Adaptive paper: book Alpaca FEE activities in ledger cash accounting (unblocks account 2's IOVA recovery)

[seathatflowsinourveins]

Scope

• What this PR changes. The adaptive-paper engine now reads the broker's FEE activities (REG, TAF, CAT and the other documented FEE sub-types) through one new allow-listed read. It books them into the ledger's cash, realized P&L and realized loss. The mover and adaptive lanes open each trial at a consistent fee checkpoint, so the cash reconciliation explains them.
  • Before this change, Alpaca paper's overnight fee posting (-0.47 USD for account 2's 2026-09-29 sells) made runner.reconcile fail closed with cash_mismatch_or_unmodeled_fees.
  • That blocked recovery of the IOVA 68 residual: 17 of 17 attempts on 2026-09-30, and Paper engine: #215 part 2, run-loop stall, F1, a recovery exit refused before the wire, and unmodeled FEE activities #543 tracks it.
  • The engine's README-safety.md stated that paper did not simulate regulatory fees. It carries a dated correction.
• Base commit: 1f2cdce5 (main).
• Lane: lane:trading. The manifests/evidence.json re-registration and the two generated reports follow the hot-file protocol, which does not make the PR shared.
• Owned paths touched.
  • blueprints/us-equities/adaptive-paper/: transport.py, safety.py, runner.py, mover_runner.py, README-safety.md, README-mover.md, README-transport.md, source-hashes.json.
  • tests/test_adaptive_paper_fees.py (new), tests/test_adaptive_paper_transport.py, tests/test_adaptive_paper_mover_native.py.

Design.

• Transport. One new read only: GET /v2/account/activities/FEE. after (UTC YYYY-MM-DDTHH:MM:SSZ) and direction asc are required; page_size 1-100 and an activity-id page_token are optional. Everything else is refused before the budget hook. normalize_fee_activity keeps {id, date, net_amount, sub_type} and never reads description, which carries the account number.
• Ledger schema 3. It adds a fees table. The migration is one way, and older engines refuse a migrated ledger. record_fees books each new id once, refreshes risk after each fee, and refuses a changed id.
• Checkpoint.
  • transport.fee_checkpoint reads the FEE list, then the account, then the FEE list again, and refuses a start when the two lists differ.
  • The booked fees go in before baseline = cash - cash_delta. Every later snapshot, recover and the adaptive next-trial read use the same saved window.
  • Legacy trials keep their original window. The account-2 residual's recovery reads after 2026-09-29T20:25:19Z.
• Admission. Checkpoint and next-trial GETs are admitted through the durable read budget before they are sent.

SOTA sources

• Alpaca, "Account Activities". https://docs.alpaca.markets/us/docs/account-activities.md (updatedAt 2026-05-25, fetched 2026-09-30): NonTradeActivity id "Can be sent as page_token", net_amount "The net amount of money (positive or negative)", date, and FEE "Fee denominated in USD".
• Alpaca, "Retrieve Account Activities of Specific Type". https://docs.alpaca.markets/us/reference/getaccountactivitiesbyactivitytype-1.md (updatedAt 2026-05-27): GET /v2/account/activities/{activity_type}, with after "Get activities created after this date. Both formats YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ are supported." It also documents direction, page_size 1-100, page_token, and the FEE ActivitySubType list REG, TAF, LCT, ORF, OCC, NRC, NRV, COM, CAT.
• Alpaca, "Regulatory Fees". https://docs.alpaca.markets/docs/regulatory-fees (updatedAt 2025-10-03): TAF on sells, CAT on buys and sells, "At EOD, we charge each account the fees for that trading day".
• Alpaca, "Paper Trading". https://docs.alpaca.markets/docs/paper-trading (updatedAt 2026-07-07): it still lists regulatory fees under "does not account for". The corrected README quotes that page and the observation that contradicts it.
• alpaca-py 0.44.0, the reviewed pin (transport.SDK_VERSION). BrokerClient._get_account_activities_iterator keeps its request fields and sets page_token to the last result's id; _collect_fee_pages follows the same pagination.

Evidence-class table

Claim	Evidence class	Command / receipt
The fee tests fail before the implementation (35 of 38 at 4ea5372f, the failing-first commit)	synthetic	Claude Opus verifier, round 1: Ran 38 tests ... FAILED (failures=7, errors=93); 3 regression guards pass
Offline gate, 9 modules, pinned venv (NautilusTrader 2.0.0rc5, alpaca-py 0.44.0)	synthetic	Ran 462 tests ... OK (coordinator, and independently by the Opus re-check)
Every other tests/test_adaptive_paper_* module plus test_adaptive_market_research	synthetic	Ran 820 tests ... OK (skipped=2) (Opus re-check; the skips need exchange_calendars)
12 named mutants plus 3 variants each killed by a named test	synthetic	Opus re-check (the mutant table in its report)
The checkpoint timelines reconcile or refuse and never double-count or miss a fee	synthetic	Opus re-check (10 timelines through the real fee_checkpoint with a patched session) and gpt-6.1-sol re-check (synchronous probes)
Account 2's measured -0.47 USD gap is exactly three FEE activities, and this change's read returns them for the residual's window	local_integration	read-only GET through transport.fee_activities on the paper account, 2026-09-30 ~17:35Z: after 2026-09-29T20:25:19Z returns REG -0.19, CAT -0.01, TAF -0.27; after 2026-09-30T10:48:39Z returns 0
The base engine refuses a migrated (schema 3) ledger without changing it	synthetic	base 11227bfd safety.Ledger opening a ledger this change created: unsupported_ledger_schema, ledger unchanged

Local commands run

$ TMPDIR=/var/tmp PYTHONDONTWRITEBYTECODE=1 <pinned venv>/bin/python -B -m unittest tests.test_adaptive_paper_mover tests.test_adaptive_paper_mover_native tests.test_adaptive_paper_safety tests.test_adaptive_paper_recovery tests.test_mover_early_entry_scan tests.test_mover_early_entry_rules tests.test_adaptive_paper_transport tests.test_adaptive_paper_native tests.test_adaptive_paper_fees
Ran 462 tests in 198.293s
OK
$ <pinned venv>/bin/python -B -m unittest tests.test_adaptive_paper_fees tests.test_adaptive_paper_source_hashes_manifest   # at this head
Ran 68 tests in 31.111s
OK
$ python3 scripts/validate.py
{"components": 69, "hashed_files": 8547, "profiles": 4, "receipts": 177, "status": "passed"}
$ python3 scripts/evidence_manifest.py --check
{"files": 8547, "status": "passed"}

Reviews

Round 1, at 7f9e12f2 (the same content as 8eeaa9b0 here):

• gpt-6.1-sol, two lenses at effort ultra, through native Codex 0.159.2, read-only. Lens A reported 3 high and 3 medium findings. Lens B timed out at 3600 s; its four delegated sub-reviewers each duplicated a lens-A finding.
• Claude Opus evidence-reviewer and stack-verifier: 1 medium and 5 low findings. All 10 mutants were killed.
• Agreement. Both families independently found the same defect: the fee window and the cash baseline were taken at different moments.

Repair (3b367efd): R1-R7, built test-first by gpt-6.1-sol at ultra in the owned worktree, then gated by the coordinator.

Re-check at the repair head:

• gpt-6.1-sol ultra: every repair confirmed; one medium documentation overstatement, fixed in b6dc55df.
• Claude Opus: pass with 5 low findings. Four are fixed or documented in b6dc55df, including a new test for the recovery halt semantics.

Residuals.

• A fee booked at a start that begin_next_trial then refuses appears in the ledger and its fee_recorded event, but in no receipt (documented in Limits).
• One timing-flaky runner test also flakes at the base (1 of 24).

Both are tracked in #543.

Decision record

No separate record. The design, its assumption (a FEE activity is visible in the list exactly when its amount is in account cash) and its limits are in blueprints/us-equities/adaptive-paper/README-safety.md, "Broker FEE activities".

It is overturned by either of these:

• a broker statement or observation that FEE visibility and the cash effect are not simultaneous (for example, intraday accruals deducted before the activity posts);
• a new FEE sub-type outside the documented list, which fails closed today.

Checklist

• No GitHub Actions changes.
• No workflow changes.
• No secrets printed, logged or committed. The FEE description (account number) is never read, and the privacy tests capture stdout, stderr and logs.
• No paid hosting or billing surface.
• Peer-owned files and worktrees preserved.

🤖 Generated with Claude Code