Skip to content

feat(receipts): evidence levels — separate signature authenticity from durable inclusion - #236

Merged
tcconnally merged 1 commit into
mainfrom
feat/235-evidence-levels
Aug 13, 2026
Merged

feat(receipts): evidence levels — separate signature authenticity from durable inclusion#236
tcconnally merged 1 commit into
mainfrom
feat/235-evidence-levels

Conversation

@tcconnally

Copy link
Copy Markdown
Contributor

Summary

Receipts now state what they prove. Introduces the four calibrated evidence levels from arXiv:2608.11632 §3.3 / Table 4, so a signed receipt is never conflated with a durably committed one.

Levels

  • structural — canonical syntax, typed bindings, valid receipt signature under the declared key. Malformed receipts fail with stable structural:<code> reasons.
  • attested — a trusted key attests the first terminal stage + reason (does NOT independently establish correct evaluation).
  • replay — retained prebind inputs + pinned versions reproduce the recorded decision/transition.
  • inclusion — the org chain verifies AND a retained checkpoint anchors a head covering the receipt's events (durable across restart).

Behavior

  • verification.evidence reports the highest level achieved with the objects actually retained, per-level reason codes, downgrades vs a claimed level, and the inclusion anchor.
  • Commit receipts require inclusion: a receipt with action_status: executed reports inclusion_required: true; a sign-then-abort receipt verifies at attested but NOT inclusion.
  • Watermark reclamation strips replay inputs (re-issued receipt) → Replay downgrades, Inclusion stays verifiable via the checkpoint anchor.
  • Optional HMAC-SHA256 receipt signature + trusted-key attestation blocks (declared-key registry, key_registry / sign_key_id on audit_json).

Verification

  • 9 new tests in tests/test_evidence_levels.py — one per level + sign-then-abort + restart durability + reclamation.
  • Full suite: 720 passed, 71.46% coverage (gate 65% green).
  • tools/json_smoke.py PASS.
  • Docs: docs/evidence-receipts.md → "Evidence levels"; CHANGELOG entry.

Closes #235

…m durable inclusion

Receipts now state what they prove. Four calibrated levels borrowed from
arXiv:2608.11632 §3.3 / Table 4 ("a signature is not evidence that its
transaction committed"):

- structural — canonical syntax, typed bindings, valid receipt signature
  under the declared key; malformed receipts fail with stable reason codes.
- attested — a trusted key attests the first terminal stage + reason
  (does not independently establish correct evaluation).
- replay — retained prebind inputs + pinned versions reproduce the
  recorded decision/transition; watermark reclamation downgrades it.
- inclusion — the org chain verifies and a retained checkpoint anchors a
  head covering the receipt's events; survives restart. Commit receipts
  (executed actions) require this anchor: sign-then-abort receipts verify
  at attested but NOT inclusion.

verification.evidence reports the highest level achieved with the objects
actually retained, per-level reasons, downgrades vs a claimed level, and
the inclusion anchor. Optional HMAC-SHA256 receipt signatures + trusted-
key attestations; audit_json gains key_registry/sign_key_id. 9 new tests;
full suite 720 passed, 71.46% coverage (gate 65).

Closes #235
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.

feat(receipts): evidence levels — separate signature authenticity from durable inclusion

1 participant