in reviewhumanPR #343Identity

ActionLedger: Track sellers (deterministic and Claude) with ledger-backed external writes under Town's faults

[ActionLedger](https://github.com/Cecilia1220/actionledger) is a small service an agent calls instead of calling a side-effecting tool directly.

Author

chrischenhub avatar

@chrischenhub

github profile →
Status
In review
Opened on
Nov 11
Branch
integration/actionledger-side-effects

Description

The pitch.

## Summary

[ActionLedger](https://github.com/Cecilia1220/actionledger) is a small service an agent calls instead of calling a side-effecting tool directly. It persists the request, makes the downstream write once, and when the outcome is uncertain (lost acknowledgement, timeout) verifies it by tag and payload hash before answering `CONFIRMED_SUCCESS`, `RECOVERED_SUCCESS`, `SAFE_TO_RETRY`, `FAILED` or `AMBIGUOUS` (do not retry blindly).

Town's Track keeps *messages* idempotent under at-least-once delivery, and its README says a run does not prove exactly-once external side effects. This PR puts one external write into a Track run and measures it from outside, with two sellers: a deterministic adapter and a **model-driven seller in which Claude (Opus 5.5) makes the seller's decisions while a harness carries out Town's protocol**. It adds `examples/actionledger/` (both sellers, a direct-to-tracker negative control, `run_check.py` over 9 cases, recorded evidence and model transcripts) and `tests/test_actionledger_integration.py`.

## Integration

- **Where the project runs:** separately, from its own checkout: ActionLedger's ledger and its non-idempotent mock tracker as two uvicorn processes, fresh data directory and free ports per run. No ActionLedger code is in this PR.
- **How Town connects:** each seller is a `cmd:` participant. For a new quote request it places a stock hold through ActionLedger's `POST /execute`, quotes only once the hold is known to exist, and acknowledges; the hold id, ledger status and action id travel in its ack note. Identity mapping: `action_id = town:{RUN_ID}:{message_id}`, which Town keeps stable across redelivery, fencing and restart. Town's lost-ack and duplicate faults come from the coordinator, its crash and amnesia faults die where the stock seller wrappers die, and tracker faults come from ActionLedger's `/faults`.
- **Claude seller (`claude_seller.py`):** the split follows Town's tier-two harness. Claude decides the total, whether to call `place_hold`, what ActionLedger's raw response means (quote, retry once, stop), whether and what to quote, and the ack status and reason. The harness claims work and hands it to Claude, holds the lease, fence and journal, applies Town's faults (a restart is a new conversation), and, when Claude's ack arrives after the fence expired, re-claims the redelivery and records Claude's own decision. For model runs Town's stock buyer joins as `buyer=external` (same module, started by `run_check.py`), because the runner otherwise stops the seller 8 s after a spawned buyer exits.
- **Independent checks per run:** Town verdict and stages, `verify_bundle`, the tracker's SQLite file read directly (ground truth for holds), the ledger's SQLite file, and the services' own log lines.

## Reproduce

Town: this branch on `projnanda/nandatown` main at `6f9a7c0` (nandatown 0.2.0, evaluator 0.5.0). ActionLedger: `main` at `725ea40`. Both are recorded in each `summary.json`. Python 3.13 on macOS; the live deterministic tests also pass with Town on Python 3.11. The Claude seller additionally needs `anthropic` 2.x and `ANTHROPIC_API_KEY` (read from the environment or `ACTIONLEDGER_HOME/.env`, never printed or recorded).

```bash
git clone https://github.com/Cecilia1220/actionledger
(cd actionledger && git checkout 725ea40 && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt)

python3 -m venv .venv && source .venv/bin/activate && python -m pip install -e '.[dev]'
export ACTIONLEDGER_HOME=$PWD/../actionledger
python examples/actionledger/run_check.py                                  # deterministic, 9 cases, ~70 s, no key
python -m pytest -q tests/test_actionledger_integration.py                  # 69 passed live; 60 offline without ACTIONLEDGER_HOME

pip install 'anthropic>=2,<3'
python examples/actionledger/run_check.py --seller claude --harness v2 --reps 3   # Opus 5.5, ~$0.6
python examples/actionledger/run_check.py --seller claude --harness v1 --reps 2   # the bas

…

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/343/head:pr-343
git checkout pr-343