Skip to content

feat(governance): receipt ledger, pluggable signing, ds verify CLI, MCP receipt tools - #68

Open
Ian-Tharp wants to merge 2 commits into
developfrom
claude/dynamic-subgraphs-receipt-tools-sjlxhx
Open

Ian-Tharp wants to merge 2 commits into
developfrom
claude/dynamic-subgraphs-receipt-tools-sjlxhx

Conversation

@Ian-Tharp

Copy link
Copy Markdown
Owner

Summary

Receipts could already prove they hadn't been edited, but anyone able to rewrite runs/<run_id>/ could also rewrite receipt.json and recompute its hash. This PR closes that gap (see docs/governance.md §4).

  • Receipt ledger (app/governance/ledger.py): an append-only log at <runs_dir>/.ledger/receipts.jsonl with one entry per saved receipt.
    • Each entry includes the previous entry's hash (prev_entry_hash).
    • supersedes links a run's new receipt to the one it replaced, so a resumed run keeps its paused receipt in its history.
    • verify() catches edited, deleted, reordered or re-linked entries. It also catches unsigned entries (require_signatures) and a cut-off tail (expect_head).
    • Appends are locked within a process and, on POSIX, across processes (flock).
  • Pluggable signing (app/governance/signing.py): ReceiptSigner and SignatureVerifier protocols.
    • HmacSigner uses the stdlib and refuses keys under 32 bytes.
    • Ed25519Signer / Ed25519Verifier need the new signing extra (cryptography).
    • KeyRing handles key rotation.
    • Signed messages are domain-separated, so a receipt signature can't be reused as a ledger-entry signature.
    • sign_receipt / verify_receipt_signature give a standalone signature for a single receipt.
  • audit_run (app/governance/audit.py): runs verify_receipt on the stored receipt, then requires it to be anchored in the ledger and to be the run's latest entry. This catches a resealed receipt.json and an older receipt restored over a newer one.
  • Wiring, off by default for the SDK:
    • EngineConfig(receipt_ledger=...). The SDK anchors one entry per run: the final receipt with token usage filled in.
    • Supervisor(receipt_ledger=...) and build_supervisor(..., receipt_ledger=...).
    • A ledger error is logged and never changes the run's outcome.
  • ds CLI (app/cli.py, [project.scripts]): ds verify, ds ledger, ds keygen.
    • ds verify options: --hmac-key-env, --public-key, --require-signatures, --policy-hash, --expect-head, --json.
    • Exit codes are 0 (all verified), 1 (problem found), 2 (usage error).
  • MCP: new read-only tools get_receipt, verify_receipt and verify_ledger.
    • The ledger is on by default (DS_RECEIPT_LEDGER; off turns it off).
    • Entries are signed when DS_RECEIPT_HMAC_KEY or DS_RECEIPT_ED25519_KEY_FILE is set; a bad key stops the server at startup.
    • server_info reports the ledger path and signing key id.
    • Run ids starting with . are refused.
  • Docs: governance.md, mcp.md, README, CHANGELOG, AGENTS, ARCHITECTURE.

Type of change

  • Bug fix
  • New feature
  • Docs
  • Refactor / chore

Checklist

  • uv run ruff format . and uv run ruff check . pass
  • uv run mypy passes (app/cli.py added to the mypy file set)
  • uv run pytest passes: 797 passed, 6 skipped. New test files: test_receipt_ledger.py, test_receipt_signing.py and test_cli.py. MCP tests were extended in test_mcp_service.py and test_mcp_server.py.
  • Updated docs / CHANGELOG.md
  • Respects the layer boundaries in ARCHITECTURE.md: governance imports only models/policy/registry, and the CLI imports only governance.

Notes

  • Receipt format is unchanged (receipt_version: 1). The task brief mentioned "receipts v2 with resume chaining", but no branch had it, so resume chaining lives in the ledger (supersedes) instead. A v2 receipt with a previous_receipt_hash field would change v1 hashes and could be a follow-up.
  • Tamper detection, not prevention. Whoever can write the ledger file can cut off its tail, and anyone holding the HMAC key can re-sign it. To guard against that, store head somewhere you control and check it with --expect-head. When the auditor isn't the host, use Ed25519.
  • A receipt is only anchored once it's saved, so a refused resume and an SDK engine_failed run are never anchored.
  • uv.lock changes only for the new signing extra.
  • I also checked a wheel install with no extras: import dynamic_subgraphs and ds verify both work.

Generated by Claude Code

claude and others added 2 commits November 4, 2026 20:02
…erify CLI, MCP receipt tools

- app.governance.ledger: append-only, hash-chained JSONL ledger
  (<runs_dir>/.ledger/receipts.jsonl). One entry per persisted receipt;
  prev_entry_hash chains entries, `supersedes` links a run's new receipt to
  the one it replaced (resume keeps the paused receipt in history).
  verify() catches edits, gaps, reorders, forged links, unsigned entries
  (require_signatures) and truncation (expect_head). Process + flock locking.
- app.governance.signing: ReceiptSigner / SignatureVerifier protocols,
  HmacSigner (stdlib), Ed25519Signer/Verifier (new `signing` extra), KeyRing,
  domain-separated messages, detached sign_receipt/verify_receipt_signature.
- app.governance.audit: audit_run() = verify_receipt + "anchored and latest"
  ledger check + entry signature, catching resealed or rolled-back receipts.
- Supervisor/build_supervisor/EngineConfig accept receipt_ledger (off by
  default); the SDK anchors one entry per run (the final, usage-filled receipt).
- `ds` CLI (app/cli.py): ds verify / ds ledger / ds keygen, exit 0/1/2.
- MCP: get_receipt, verify_receipt, verify_ledger tools; ledger on by default
  (DS_RECEIPT_LEDGER), signing via DS_RECEIPT_HMAC_KEY or
  DS_RECEIPT_ED25519_KEY_FILE (bad keys fail at startup); dot-prefixed run
  ids refused.
- Docs: governance.md section 4, mcp.md, README, CHANGELOG, AGENTS, ARCHITECTURE.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019KQ4WiPnTbxYH119mnxPiX
mypy on Windows rejected fcntl.flock (attr-defined) because the import was a
try/except; gate it on sys.platform so mypy narrows on every OS. The keygen
test asserted POSIX 0o600 mode bits, which Windows does not have.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants