docs/operational-receipt-substrate.md

Operational receipt substrate

packages/receipt-substrate is the operational Lane A receipt layer for MCP-style tool calls, Cursor agent edits, Claude subagent calls, and internal A11oy operations.

It turns a canonical tool envelope into an OperationalReceipt, links receipts with prev_receipt_hash, verifies payload and Merkle-root consistency, checks quorum signatures against configured nodes, and can append receipts to JSONL for operator handoff or UDS packaging.

Why this exists

The org already has policy receipts (packages/policy) and QEC lineage primitives (packages/qec-integrity). The receipt substrate fills the runtime handoff between agent/tool execution and those integrity surfaces:

flowchart LR
  Tool[MCP / Cursor / Claude operation] --> Env[ToolEnvelope]
  Env --> Rec[OperationalReceipt]
  Rec --> Chain[Hash-chain verification]
  Chain --> Jsonl[JSONL receipt ledger]
  Jsonl --> UDS[UDS / operator handoff]

Run tests

npm test --prefix packages/receipt-substrate

Emit an operational receipt

node --experimental-strip-types packages/receipt-substrate/src/cli.ts   --out /tmp/a11oy-receipts.jsonl   --actor did:example:operator   --tool receipted_retrieval   --payload-json '{"query":"status","limit":3}'

The CLI reads the existing JSONL file if present, links the new receipt to the last receipt, verifies the next chain, appends one canonical JSON line, and prints the receipt id, Merkle root, and sequence.

Controls implemented

• Deterministic canonical JSON with sorted object keys and NFC string normalization.
• SHA3-256 hashing when Node exposes it, with SHA-256 fallback for runtimes that do not expose SHA3.
• TAI64N-style monotonic timestamp field plus ISO-8601 timestamp.
• Payload hash verification from the stored envelope.
• Merkle-root verification from the receipt body.
• Duplicate receipt-id, chain-link, timestamp-regression, and quorum checks.
• QEC witness fields for Shor repetition and CSS parity consistency.

Non-goals

• This package does not replace packages/policy; policy YAML validation stays there.
• This package does not modify web/packages/a11oy-core; doctrine math remains a separate Lane B surface.
• This package does not claim external attestation. JSONL output is a local ledger input for downstream signing, UDS packaging, or external witness services.
• quorum_signatures are deterministic local quorum labels checked against the configured node set. They are not cryptographic signer verification until a COSE/DSSE/cosign verifier is wired into the receipt path.

UDS package handoff

The Replit/platform UDS payload now lives in artifacts/a11oy-uds/. To stage the payload, write MANIFEST.json, write ATTESTATIONS.json, verify both, and produce a local fallback archive in environments without Zarf, run:

A11OY_UDS_ALLOW_SOURCE_FALLBACK=1 bash artifacts/a11oy-uds/scripts/build.sh

Release builds should run without A11OY_UDS_ALLOW_SOURCE_FALLBACK, after installing workspace dependencies and Zarf. The fallback archive is intentionally written under dist/a11oy-uds-fallback/ and is not a deployable Zarf package.

Generated UDS outputs

artifacts/a11oy-uds/build/, artifacts/a11oy-uds/build-attestations/, and dist/ are generated by the build script and intentionally ignored by git. Run scripts/validate-operational.sh to regenerate and verify them from source.