docs: Tutorial 33 — Offline-Verifiable Decision Receipts

[tomjwxf]

What this adds

A new tutorial, docs/tutorials/33-offline-verifiable-receipts.md, teaching
the decision-receipt layer that sits between the internal audit log
(Tutorial 04) and artifact signing (Tutorial 26).

The tutorial does not introduce any new APIs. It is a teaching wrapper
around the already-merged reference code in
examples/protect-mcp-governed/
(PR #1159) and examples/physical-attestation-governed/
(PR #1168). Every API call in the tutorial (CedarDecision, CedarPolicyBridge,
ReceiptVerifier, SpendingGate, scopeblind_context, AuditLog,
PolicyEvaluator) uses the exact signatures from those merged examples.

Why this belongs in the tutorial series

AGT already covers two of the three signing-adjacent pillars:

• Tutorial 04 covers internal audit logs with Merkle-chain integrity
  (operator-side).
• Tutorial 26 covers Ed25519 signing of built artifacts (SBOMs,
  releases).

What is not yet covered as a standalone tutorial: the per-tool-call decision
receipt layer. That is what an external auditor, regulator, or counterparty
actually needs: evidence of individual governance decisions that verifies
without trusting the operator.

The receipt format is standardized in
draft-farley-acta-signed-receipts
and implemented by at least four independent codebases (protect-mcp,
protect-mcp-adk for Google ADK, sb-runtime, APS governance hook). Any of
them can verify receipts produced by the others via the shared
@veritasacta/verify CLI.

Structure

Follows the pattern of Tutorial 26 (SBOM & Signing), which is the closest
conceptual neighbor:

1. Header callout block with packages / standards / reference example
2. What You'll Learn table
3. Prerequisites
4. Why section (the gap between internal audit and external accountability)
5. The Receipt Format (fields, JCS, Ed25519, hash chain)
6. Six numbered sections walking from a single receipt to CI-gated chains
7. CI/CD Integration
8. Cross-Reference table linking 7 related tutorials

478 lines, 100% Python and YAML code samples are runnable against the
existing pip install agent-governance-toolkit[full]. No new dependencies.

Files changed

File	Change
docs/tutorials/33-offline-verifiable-receipts.md	New (478 lines)
docs/tutorials/README.md	Add Tutorial 33 row to Supply Chain Security table; add to Enterprise Compliance learning path

Verification

• Every API named in the tutorial is defined in examples/protect-mcp-governed/getting_started.py
• All cross-reference links (Tutorials 01, 04, 07, 08, 12, 26, 27) resolve
• Standards cited are RFC 8032 (Ed25519), RFC 8785 (JCS), Cedar (AWS), IETF draft
• Written to match Tutorial 26 / 32 prose style and section numbering
• No new packages, no new commands, no new dependencies

Happy to iterate on scope, tone, or section ordering if the docs maintainers
want anything adjusted.

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[aeoess]

Strong tutorial framing. The positioning between Tutorial 04 (internal audit log, Merkle-chain, operator-side) and Tutorial 26 (Ed25519 artifact signing, SBOMs/releases) maps the external-auditor/regulator gap precisely — per-tool-call decision evidence that verifies without trusting the operator.

One observation from the APS side that may be worth adding as a sidebar in the tutorial, since aps-governance-hook is cited as one of the four implementations:

The four implementations listed (protect-mcp, protect-mcp-adk, sb-runtime, aps-governance-hook) verify receipts against the same @veritasacta/verify CLI but make different identity-binding choices underneath:

• protect-mcp / protect-mcp-adk / sb-runtime: receipts are signed by a supervisor-hook identity (operator-side key).
• aps-governance-hook: receipts are signed by the gateway's identity AND reference a delegation chain root proving which agent authority the tool call was made under.

Both choices are correct for different threat models. Operator-side signing is sufficient for internal audit and regulator evidence of what the operator evaluated. Authority-chain-referencing signing is additionally sufficient for cross-organization evidence where the verifier doesn't trust the operator but needs to confirm the agent was legitimately authorized (not just that the operator evaluated something).

For an enterprise reading this tutorial to decide whether to deploy receipts, that distinction matters. An operator subject to a single regulator can pick either; an operator participating in cross-org agent commerce or in a regulated multi-tenant environment needs the authority-chain variant to meet the evidentiary bar. Worth a one-paragraph callout distinguishing the two modes so readers know which fits their use case.

On the tutorial's code references to examples/protect-mcp-governed/ (PR #1159 merged) and examples/physical-attestation-governed/ (PR #1168 merged) — clean move to anchor on already-landed code rather than introducing new APIs. ScopeBlind/agent-governance-testvectors#1 ships APS's conformant driver if the tutorial wants to optionally reference authority-chain-mode receipts as a comparison; entirely optional.

Approving the framing in spirit; cannot +1 the PR as a non-maintainer, but will follow when it merges.

[tomjwxf]

Thanks @aeoess, that distinction is load-bearing and the tutorial was eliding it. Pushed 608b190 adding a new "Two identity-binding modes" sidebar to §6 (Cross-Implementation Interoperability):

• Operator-signed mode (protect-mcp, protect-mcp-adk, sb-runtime): sufficient when the operator IS the authority being audited, or when the regulator trusts the operators attestation. Single-tenant compliance covers this.
• Authority-chain-referenced mode (asqav / APS governance hook): additionally required for cross-org agent commerce, multi-tenant regulated environments, and use cases where the agents authority to act is itself a separately auditable property.

Both verify against the same @veritasacta/verify and use the same outer receipt structure; the distinction is whether the payload carries an optional delegation_chain_root field pointing at the principals delegation root.

The sidebar also cross-references arewm/refs.arewm.com#1 where youve pointed out that authority-chain attestation belongs as a sibling SLSA byproduct alongside decision receipts. That proposal and the identity-binding-mode distinction are coherent: the operator-signed mode maps to "decision-receipts only" byproducts; the authority-chain-referenced mode maps to "decision-receipts + authority-chain-attestation" byproducts together.

For the readers picking between modes at deployment time, the sidebar keeps the pick simple: single-regulator or internal audit → operator-signed; cross-org or principal-authority-sensitive → authority-chain-referenced. A concrete worked example of the authority-chain mode (with delegation_chain_root populated and a verifier walking the chain) would be worth a separate follow-up tutorial once the pattern lands on the SLSA side.

On your review in spirit: understood on the non-maintainer approval. Noted for the record that the framing held up to review from an independent implementer.

[aeoess]

The operator-signed vs authority-chain-referenced framing in §6 is the right split. Both modes landing against the same @veritasacta/verify CLI keeps the reader from having to pick a verifier at deployment time — they pick a mode and the verifier handles the dispatch.

For the follow-up worked example: the delegation_chain_root field will be populated by APS governance hook receipts as soon as in-toto/attestation#549 lands with the delegationChainRoot: DigestSet field (drafting today). Once that's merged, I can contribute a concrete cross-org agent commerce fixture — two organizations, shared compliance regulator, authority chain walking from the root delegation through a sub-delegation into the final action — that slots in as the worked example for the sidebar.

No maintainer review needed from my side. Flagging as available when it makes sense.