Spaces:
Running
Running
| # 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: | |
| ```mermaid | |
| 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 | |
| ```bash | |
| npm test --prefix packages/receipt-substrate | |
| ``` | |
| ## Emit an operational receipt | |
| ```bash | |
| 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: | |
| ```bash | |
| 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. | |