Receipt Reference - MeshQu Developer Docs

This is the authoritative reference for the Decision Receipt and every feature attached to it. It is intended as a working spec when writing or reviewing public surfaces (homepage, /spec, /verify, sales/regulatory copy) so that what is presented externally aligns with what the technology actually does. If a property is not listed here as Implemented, do not claim it. Statuses use: Implemented, Partial (real but limited), Stub (wired but currently no-op), Planned. This page describes the receipt as it appears on the wire — the shapes the API returns and what each field binds. It is a working spec for public surfaces, not an implementation guide. For the design-level view of the same object — envelope, verification semantics, replay rules and trust boundaries, without the field-by-field contract — see the public Decision Receipt specification. Where the two disagree, this page is correct and that one is wrong.

1. The Receipt Envelope

A Decision Receipt on the wire is exposed as { context, result, chain_id, chain_step }. The cryptographic centre of gravity is result (the EvaluationResult).

1.1 v1 vs v2 — which fields exist

Field	v1	v2
`decision` ∈ `ALLOW \| DENY \| REVIEW \| ALERT`	✓	✓
`violations[]` (rule_code, severity, reason_code, reason, optional field/actual_value/expected_value/details/policy_id/is_shadow)	✓	✓
`rules_evaluated`, `rules_na`, `na_rules[]`	✓	✓
`evaluation_time_ms`	✓	✓
`timestamp` (ISO 8601, evaluation time)	✓	✓
`policy_snapshot_id` (UUID)	✓	✓
`evaluated_rules_hash` (SHA-256 hex; legacy alias `policy_snapshot_hash`)	✓	✓
`integrity_hash` (SHA-256 hex)	✓	✓
`signature` (Ed25519, base64url)	✓	✓
`signature_kid` (e.g. `msk_v1`)	✓	✓
`signature_algorithm` = `ed25519`	✓	✓
`action` (ReceiptAction, optional)	✓	✓
`transparency_anchor` (optional)	✓	✓
`is_shadow` (boolean; written only as `true`, absent otherwise — see §1.6; distinct from `violations[].is_shadow`)	✓	✓
`shadow_converted` (boolean; written only as `true`, absent otherwise — see §1.6)	✓	✓
`original_decision` (`Decision \| null`; written together with `shadow_converted` — see §1.6)	✓	✓
`receipt_schema_version` ∈ `1 \| 2`	optional/absent	required = 2
`policy_snapshot_digest` (SHA-256 hex)	—	required
`evidence_manifest_digest` (SHA-256 hex \| null)	—	optional (null when absent)

Top-level (alongside the receipt, not inside result): id (UUID), tenant_id, actor (DecisionActor JSON), chain_id, chain_step, parent_decision_id, created_at (recorded-at, distinct from result.timestamp). Migration semantics. v1 receipts continue to verify forever. There is no cut-over date. Cross-version fallback is rejected — a v2 receipt must verify under the v2 path; a v1 receipt must verify under the v1 path. The same discipline governs the three shadow-mode fields, which joined the hash payload after both schema versions had shipped: a receipt is hashed over the keys it actually carries, so receipts minted before a field existed keep verifying unchanged (§1.6, §2.2).

1.2 Decision Context (the input)

Type: DecisionContext.

decision_type         string                      selects applicable policies
fields                Record<string, unknown>     evaluation inputs (dot-notated)
evidence              Evidence[]                  reference-only (kind, ref?, hash?, data?)
metadata              DecisionMetadata            actor_id, correlation_id, ip_address, user_agent, timestamp, ...
source_artifact       SourceArtifact              optional (see §1.3)

context.evidence[] is the legacy reference-only evidence list. The richer Evidence Manifest (§5) is a separate first-class concept and its digest is stored on result, not context.

1.3 Source Artifact (`context.source_artifact`)

Type: SourceArtifact. Reference-based: stores { type, hash, hash_algorithm: 'SHA-256', reference_id?, filename?, byte_size? }. Only hash is bound into integrity_hash. Type, filename and size are convenience metadata and intentionally outside the hash. This is the older single-artifact binding (“Trust Without Disclosure”). It co-exists with the Evidence Manifest in v2; deprecation is out of scope.

1.4 Actor (the `actor` field)

Type: DecisionActor.

id            string                  required
type          'human' | 'automated'   required
role          string?                 freeform (e.g. 'MLRO')
authority     string?                 freeform (e.g. 'final_disposition')
display_name  string?                 PII-bearing; optional

MeshQu does not validate actor identity — the caller attests. metadata.actor_id on context is bound into the integrity hash via context_hash; the structured actor row is stored alongside but not part of the integrity hash.

1.5 Action (`result.action`)

Type: ReceiptAction. Shape: { type, reference_id, metadata? }. The whole action object is bound into integrity_hash — metadata included. The payload binds action as a single value, not a selection of its keys (§2.2), so changing any part of it changes the hash. This is unlike context.source_artifact (§1.3), where only hash is bound.

1.6 Shadow-mode fields (`result.is_shadow`, `result.shadow_converted`, `result.original_decision`)

Three optional fields on result record how shadow-mode policies took part in the decision.

is_shadow          boolean?          true when at least one applicable rule carried a
                                     shadow-mode stamp. Written only as `true`; never
                                     written as `false`.
shadow_converted   boolean?          true when shadow mode changed the verdict. Written
                                     only as `true`; never written as `false`.
original_decision  Decision | null   the verdict before conversion. Written together
                                     with `shadow_converted`, never on its own.

Conversion rule. A DENY with at least one violation, where every violation carries is_shadow: true, is recorded as ALERT; shadow_converted: true and original_decision: 'DENY' are written alongside it. DENY is the only convertible verdict — an all-shadow REVIEW stays REVIEW. The conversion happens inside the evaluator, before the hash is computed, so the suppressed verdict is part of the signed surface rather than a note attached afterwards. Participation is not suppression. is_shadow says a shadow-mode rule was applicable; shadow_converted says a shadow-mode rule changed the verdict. A receipt can carry is_shadow on its own — a shadow rule ran, but the outcome was not an all-shadow DENY. violations[i].is_shadow (§1.1) is a third, separate field: it marks one violation as coming from a shadow-mode policy, and it is bound because the whole violations array is bound. Where the stamp comes from. Shadow status reaches the evaluator on the rules of the frozen policy snapshot, not from live policy state. Replaying a receipt against its own snapshot therefore re-derives the same conversion, and a snapshot whose shadow stamps were altered no longer reproduces the receipt. Binding. All three are bound into integrity_hash when present, on the v1 and v2 paths alike (§2.2). None of them is named in the v2 signing envelope; the signature covers them transitively, because the envelope binds integrity_hash (§2.3).

2. Cryptographic Model

2.1 Canonicalisation profile

meshqu-canonical/v0 — frozen. Alphabetic key order, JS Array.sort. RFC 8785 alignment is a planned P1 follow-up that will introduce meshqu-canonical/v1.

2.2 Integrity hash — exact payloads

v1 input — sha256(canonicalJson(payload)) where payload is, alphabetised:

{
  action,                           // the whole ReceiptAction (metadata included), or null
  context_hash,                     // sha256(canonicalJson(context minus source_artifact))
  decision,
  policy_snapshot_hash,             // == result.evaluated_rules_hash (key kept for stability)
  policy_snapshot_id,
  source_artifact_hash,             // context.source_artifact.hash or null
  timestamp,
  violations,
}

v2 input — extends v1 with:

{
  action, context_hash, decision,
  evidence_manifest_digest,         // null when no manifest
  policy_snapshot_digest,           // required
  policy_snapshot_hash, policy_snapshot_id,
  receipt_schema_version: 2,
  source_artifact_hash, timestamp, violations,
}

Shadow-mode fields — presence-dispatched, identical on both paths. Up to three further keys join the payload above, and the v1 and v2 builders dispatch them the same way (§1.6):

is_shadow,                          // included iff result.is_shadow !== undefined
shadow_converted,                   // included iff result.shadow_converted !== undefined
original_decision,                  // included with shadow_converted; undefined → null

Dispatch is on presence, not value: a key is included whenever its field is not undefined, and the value is then bound verbatim. shadow_converted and original_decision are a pair — the payload carries both keys or neither, and original_decision is coerced to null if the pair is written without it. is_shadow dispatches independently of that pair, because the two joined the payload at different times; a receipt may bind one, the other, both or neither. Where a field is absent, its key is absent. Receipts minted before a field joined the payload — and every receipt where MeshQu had nothing to write — therefore hash over the payloads exactly as listed above, unchanged, and go on verifying. Stripping a field from a receipt that carries it, or adding one to a receipt that does not, changes the recomputed hash and fails verification. There is no cross-epoch fallback. Key order stays alphabetic however these keys are added (§2.1). Not in the integrity hash: transparency_anchor (computed after signing), chain fields, evaluation_time_ms, rules_evaluated / rules_na / na_rules, the actor row, source artifact metadata.

2.3 Signing — what is signed

v1 signs the bare 64-char hex integrity_hash string, UTF-8 encoded.
v2 signs the canonical envelope, alphabetised:

{
  "evidence_manifest_digest": "<hex|null>",
  "integrity_hash": "<hex>",
  "policy_snapshot_digest": "<hex>",
  "receipt_schema_version": 2,
  "signature_algorithm": "ed25519",
  "signature_kid": "<kid>",
  "timestamp": "<ISO>"
}

The v2 envelope binds signature_kid, signature_algorithm and receipt_schema_version into the signed bytes — closing the gap where v1 stored these alongside but not inside the signature. The verifier reconstructs envelope bytes using the receipt’s stored signature_kid / signature_algorithm (not hardcoded) so any tampering of those fields fails the signature check. Hash coverage is not envelope coverage. The v2 envelope has exactly the seven fields listed above. Every other receipt field the signature covers — including the shadow-mode fields of §1.6 — is covered transitively, through integrity_hash: the signature attests to the hash, and the hash is computed over those fields. v1, which signs the bare integrity_hash string, covers them the same way. Being inside the integrity hash and being named in the signing envelope are separate properties; §14 lists which fields have which. Algorithm: Ed25519 only in v1+v2. Other algorithms require a manifest-version bump.

2.4 Policy snapshot digest (v2)

computePolicySnapshotDigest(snapshot) = sha256(canonicalJson({ id, rules, policy_versions, created_at })). This binds the content of the policy, not just its UUID. Approval-receipt digests live on policy_versions[i].approval_receipt_digest, so approval lineage is bound transitively through this single digest — there is no separate top-level approval digest on the receipt.

2.5 Evidence manifest digest (v2, optional)

sha256(canonicalJson(manifest minus manifest_digest)). Self-describing pattern (mirrors the bundle manifest). MeshQu computes and verifies this digest as part of v2 receipt and bundle handling.

2.6 Active-rule projection (used everywhere rules are hashed)

projectActiveRules strips inactive rules and all metadata, keeping only { code, condition, severity, when? }. This single helper is used by:

computeSnapshotHash (snapshot repo + evaluator)
PolicyApprovalReceipt.policy_rules_hash
PolicySnapshot.policy_versions[i].policy_rules_hash
the bundle verifier when comparing per-version hashes

Changing the projection is a hash-migration event.

3. Policy Snapshot

A frozen, immutable copy of the rules that governed a decision. Identifies the policy run by both UUID and content digest in v2.

id (UUID, on the receipt as policy_snapshot_id)
rules[] — full PolicyRule[]. Bundled in policy_snapshot.json; not stored on the receipt itself.
policy_versions[] — list of { policy_id, version, policy_rules_hash, approval_receipt_digest? }
created_at (ISO 8601)
evaluated_rules_hash on the receipt = sha256(canonicalJson(projectActiveRules(rules)))
policy_snapshot_digest on the receipt (v2) = sha256(canonicalJson({ id, rules, policy_versions, created_at }))

Replay = re-run the snapshot’s rules against the original context and check the verdict matches. The bundle verifier sub-claim is snapshot_replay.

4. Approval Receipts (lineage)

Status: Implemented end-to-end (APR-008 / APR-009 / APR-010, May 2026). Issuance, storage, bundle export, Node verifier and browser verifier all verify approval lineage. Pinned by golden fixtures, an 18-row mutation matrix and Node ↔ browser parity tests.

Policy approval receipts are a first-class artifact. Each receipt holds a ratifier_signature (Ed25519, kid + algorithm), policy_rules_hash (via projectActiveRules) and a self-describing approval_receipt_digest.
A bundle ships these in policy_approval_receipts.json.
The verifier sub-claim approval_lineage activates when the receipt is v2 and the bundled snapshot has at least one non-null policy_versions[i].approval_receipt_digest. For every such version the verifier checks:
1. The receipt is present in the bundled file (keyed by policy_version_id).
2. computeApprovalReceiptDigest(receipt) equals the snapshot entry’s approval_receipt_digest.
3. receipt.policy_rules_hash equals entry.policy_rules_hash by string equality (do not re-hash snapshot.rules — APR-006 precomputed per-version hashes that cover only that version’s rules, and the snapshot entry is itself bound by policy_snapshot_digest).
4. receipt.ratifier_signature.kid resolves in the caller-supplied ratifierTrustedRoots.
5. The ratifier Ed25519 signature verifies.
Reports not_applicable for v1 receipts and v2 receipts whose snapshot has no non-null approval_receipt_digest entries.
The same approval-lineage checks run in both the Node verifier and the browser verifier, kept at parity (APR-009).

5. Evidence Manifest (v2 only)

Type: EvidenceManifest. Strictly additive — does not modify v1 receipts or source_artifact.

manifest_version: '1'
items: EvidenceItem[]
manifest_digest: sha256(canonical(manifest minus manifest_digest))

Each EvidenceItem:

kind                   EvidenceItemKind   open string union; named: source_document,
                                          kyc_record, sanctions_screening_result,
                                          payment_receipt, audit_report
mime_type              string             IANA media type (caller-attested)
byte_length            number
source_system          string             opaque (e.g. 'kyc-vendor-acme')
retrieval_time         ISO 8601
custodian_id           string|null        optional attribution
normalization_profile  string|null        e.g. 'pdf-strip-metadata-v1'
content_hash           SHA-256 hex (64 lowercase chars)
signature              EvidenceItemSignature|null  optional Ed25519 over
                                                   sha256(canonical(item minus signature))

Custodian signatures are produced outside MeshQu (banks, KYC vendors, auditors). MeshQu never holds custodian private keys. Trust roots are supplied to the verifier out-of-band via custodianTrustedRoots. The manifest can carry a mix of signed and unsigned items. The manifest digest covers all items; the per-item signature is an additional, independent attestation by the custodian. Reference-based — the artifact bytes are NOT stored. Only digests, references, and metadata.

6. Transparency Anchor (Rekor)

Type: TransparencyAnchor. Stamped onto the receipt after signing, so it is not part of integrity_hash.

provider                  e.g. 'rekor.sigstore.dev'
entry_uuid                Rekor entry id
log_index                 position in the Merkle tree
inclusion_proof           { hashes[], log_index, root_hash, tree_size }
anchored_at               ISO 8601 (derived)
rekor_public_url?         convenience link
dsse_envelope?            JSON-encoded DSSE envelope we submitted (optional, post-PR-5b)
entry_body?               base64 entry body returned by Rekor (optional)
signed_entry_timestamp?   base64 ECDSA-P256 SET (optional, post-PR-5f)
integrated_time?          unix seconds (optional, post-PR-5f)
log_id?                   sha256(SPKI DER of Rekor pubkey), hex (optional)

What works today:

Anchoring. Implemented. Receipt is submitted to Rekor; anchor data captured.
Offline SET verification. Implemented. The verifier reconstructs the canonical message Rekor signed ({body, integratedTime, logID, logIndex}) and checks the SET against a trusted Rekor public key.
Offline subject-digest binding. Implemented when dsse_envelope is present. The verifier decodes the DSSE envelope, reads the in-toto Statement and asserts subject.digest.sha256 == receipt.integrity_hash.
Inclusion-proof verification. Shape-checked only. The verifier emits transparency.inclusion_proof_invalid when the bundled proof’s inclusion_proof is present and malformed. The cryptographic binding comes from the SET, so the verifier also emits the advisory transparency.inclusion_proof_unverified whenever it cannot complete SET verification — for a legacy anchor lacking the new fields, and whenever the caller supplied no Rekor trust roots, which is the default. That code is therefore not a legacy-only signal.

Every bullet above describes a bundle that actually ships transparency_proof.json. What the verifier reports when it does not is §6.1. Online Rekor access splits into three layers. Read them separately — the differences are where public copy usually goes wrong:

Online entry-existence lookup: Implemented. verifyRekorInclusion() queries the log by entry UUID and reports whether an entry exists there. It is exported from @meshqu/core and tested. The shipped browser verifier also makes live, host-allowlisted calls to Rekor when validating an anchor. This confirms an entry is present; it does not verify an inclusion proof.
Bundle-verifier wiring: Inert. BundleVerificationOptions.online exists but is documented as “reserved for future wiring”. Bundle verification is offline by default and setting the flag changes nothing today.
Co-signed-witness inclusion-proof verification: Planned. Verifying an inclusion proof against an independently co-signed log witness is not implemented. Offline SET verification against a pinned Rekor log key remains the guarantee MeshQu stands behind.

6.1 What a bundle reports for an anchor

The anchor is recorded on the receipt, not proved by it. It is written after signing and is deliberately not covered by the integrity hash (§14). What the bundle verifier reports therefore depends on what the bundle carries, and there are four distinct outcomes: The branches are tested in this order, so the more specific case wins:

On the receipt, and in the bundle	`transparency` status	Failure code	Verdict contribution
A. Anchor names a proof-bearing shape — `dsse_envelope` and `entry_body` both captured — and `transparency_proof.json` is absent	`invalid`	`transparency.proof_missing`	`invalid`; exit 5
B. Any other anchor is present, and `transparency_proof.json` is absent	`not_checked`	`transparency.anchor_unproven`	`indeterminate`; exit 7
C. No anchor at all — `transparency_anchor` absent or `null`	`not_applicable`	none	none; exit 0
D. Anchor present and `transparency_proof.json` shipped	the checks in §6 above	as listed in §10.4	per §10.5

Verdicts and exit codes are §10.5. A pre-PR-5b/5f anchor (no dsse_envelope / entry_body) falls in B: the exporter deliberately ships no proof for it, so the verifier has nothing to check the claim against. B changed on 2026-08-28 (CCR-302c). It previously reported not_applicable with no failure code, verdict valid, exit 0. not_applicable asserts that no check was required; not_checked states that one was not performed. When the verifier lacks the inputs to determine anything, the second is true and the first is a claim that cannot be supported. Note the shape of D in the default configuration: with no Rekor trust roots supplied, a correctly anchored bundle reports transparency: invalid carrying only the advisory transparency.inclusion_proof_unverified, which rolls up to warn and exit 0. A sub-claim reading invalid is not by itself a failed bundle — the failure codes decide (§10.5). Two consequences to state plainly on any public surface:

An anchor displayed on a receipt is a claim recorded, not a claim verified. provider, log_index, entry_uuid and anchored_at render as facts on every surface that displays a receipt. Only A and D involve the verifier checking anything about them.
The verifier cannot distinguish “never anchored” from “anchor removed”. Because the anchor is not bound by the integrity hash, a receipt whose anchor was stripped to null presents the same claim as one that was never anchored, and transparency_anchor: null is a legitimate state that unanchored runs export on purpose. Do not read C as evidence that no anchoring took place.

7. Decision Chains

A chain is an ordered group of receipts that together prove a workflow.

7.1 Linkage on the receipt

ChainLinkage — top-level fields on the receipt:

chain_id (UUID, caller-provided)
chain_step (1-based, auto-assigned if omitted)
parent_decision_id (UUID, optional — explicit causal lineage)

7.2 Chain proofs

The chain-proof artifact (chain_proof.json in a bundle). Each non-first step gets:

chain_integrity_hash = sha256 over { chain_id, step, decision_integrity_hash, previous_chain_hash }
chain_signature (Ed25519 over the chain integrity hash)

This makes the chain hash-linked: edit any step’s receipt and every later step’s chain_integrity_hash changes.

7.3 Chain seal

The chain-seal artifact (chain_seal.json in a bundle):

seal_hash = sha256 over { chain_id, sealed_at, steps_count, ALL receipt_hashes (ordered) }
seal_signature (Ed25519 over seal hash)
sealed_at (ISO 8601)

The seal is a completeness proof — adding, removing or reordering steps breaks the seal. A sealed chain is a closed proof of the entire workflow.

7.4 Verification result type

ChainVerificationResult exposes chain_proof: 'full' | 'partial' | 'none' | 'failed', per-step status, warnings (gap, parent_not_in_chain, parent_step_not_lower, chain_id_mismatch, proof_boundary) and seal status.

8. Decision Outcomes (post-decision tracking)

Separate from the receipt itself. A decision-outcome record carries:

status              'accepted' | 'overridden' | 'escalated' | 'expired' | 'abandoned'
final_action        'ALLOW' | 'DENY' | 'NO_ACTION' | null   (only meaningful on override)
source_type         'human' | 'external_system' | 'agent'
reported_by         string
reported_at         ISO 8601
resolution_reason   string?
notes               string?

Use on UI / detail surfaces. Do not market as part of the receipt; it is an audit-grade post-hoc annotation.

9. Audit Trail

Append-only, hash-chained. Each event carries:

previous_hash
per-event integrity_hash = sha256 over { action, entity_type, entity_id, actor_id, tenant_id, changes, timestamp, previous_hash }

UPDATE / DELETE on audit rows are denied at the row level by DB triggers. A decision_recorded audit event is written on every record.

10. Verification Bundle

A self-describing tar / JSON archive that lets a third party verify a receipt offline. See also the standalone Verification Bundle page; this section focuses on the contract relevant to the receipt.

10.1 Manifest (`bundle_manifest.json`)

version                        '1'   (locked; v2+ additive)
canonicalization_profile       'meshqu-canonical/v0'
signature_alg                  'ed25519'
evaluator_version              string (stamped)
exported_at                    ISO 8601
decision_id                    UUID
chain_id                       UUID | null
files[]                        BundleFileEntry[]   { path, sha256, required, size? }
manifest_digest                sha256(canonical(manifest minus manifest_digest))

10.2 Files in a bundle

File	Required	Purpose
`bundle_manifest.json`	✓	Top-level integrity descriptor
`receipt.json`	✓	`{ context, result }`
`policy_snapshot.json`	✓	`{ id, rules, policy_versions, created_at }`
`trusted_keys.json`	✓	Public keys at export time (no private material)
`transparency_proof.json`	optional	Present if anchored
`chain_proof.json`	optional	Present if part of a chain
`chain_seal.json`	optional	Present if chain is sealed
`evidence_manifest.json`	optional	Present if v2 receipt with evidence
`policy_approval_receipts.json`	optional	Present when snapshot has approval-receipt digests

trusted_keys.json is pinned at export time. Rotating signing keys does not retroactively invalidate already-issued bundles.

10.3 Verifier sub-claims

Every relevant sub-claim is reported (not just the first failure). Each has a status and a failure_codes: string[]. There are four statuses:

`status`	Meaning	Contribution to the verdict
`valid`	The check ran and the claim holds	passing
`not_applicable`	The artefact makes no claim of this kind; there is nothing to check	passing
`not_checked`	A claim was made and could not be established	`indeterminate` (§10.5)
`invalid`	The check ran and the claim is refuted	`invalid` if any code on it is non-advisory, otherwise `warn` (§10.5)

not_applicable and not_checked are not interchangeable, and the distinction is load-bearing rather than stylistic: the first asserts that no check was required, the second that one was not performed. Only the second carries verification debt.

Sub-claim	What it checks	Today’s status
`bundle_manifest`	Version/profile/file digests + manifest self-digest	Implemented
`integrity`	`integrity_hash` recomputes correctly (v1 or v2 path by `receipt_schema_version`)	Implemented
`signature`	Ed25519 signature valid against trusted key (v1: bare hash; v2: canonical envelope)	Implemented
`snapshot_replay`	`evaluated_rules_hash` + `policy_snapshot_id` match; v2 also checks `policy_snapshot_digest`	Implemented
`transparency`	DSSE subject digest binding + offline SET when a proof is bundled; `not_checked` when the receipt claims an anchor and no proof is bundled; `not_applicable` only when the receipt claims no anchor (§6.1)	Implemented (offline)
`chain_link`	Hash-linked parent receipt → chain integrity hash	Implemented
`chain_seal`	Seal hash + signature; receipt binding	Implemented
`canonicalization`	Profile match + canonical-form vector tests	Implemented
`evidence`	v2: `evidence_manifest_digest` matches bundled `evidence_manifest.json`; `not_applicable` for v1 or null	Implemented
`approval_lineage`	Per-version approval-receipt digest + ratifier signature + `policy_rules_hash` (string equality)	Implemented (APR-008 / APR-009)

Shadow-mode fields and the two hash-comparing sub-claims. integrity and snapshot_replay both recompute a hash, so both have to account for the presence dispatch of §2.2. A fresh replay re-derives shadow conversion from the shadow stamps on the bundled snapshot’s rules, and the replay result is then normalised to the fields the stored receipt actually carries before the hashes are compared. The normalisation removes the shadow keys only — never the verdict — so a stored decision that disagrees with what the bundled snapshot produces still fails snapshot_replay.hash_mismatch, and a receipt whose shadow fields were stripped or added after signing fails integrity.mismatch.

10.4 Failure codes

These are the codes this page describes. It is not the complete set. The gap is stated here rather than left to be discovered:

@meshqu/types declares 55 BundleFailureCode members. 40 are listed below. The other 15 are emitted by the shipped verifier and are not yet described on any public surface; they belong to legs that have not reached step 4 of §18.
@meshqu/verify-lib — the browser verifier, a deliberately independent re-implementation — declares its own union carrying 17 further codes. One of them, snapshot_replay.skipped_in_browser, is an advisory recording that the browser has no evaluator and skipped that sub-claim there. The other 16 belong to a separate verifier leg (CCR-403) whose capability §15 does not list; until §15 lists it, no public surface may claim it.
Across both packages the union is 72 codes, of which 32 are not listed below.

These five numbers are no longer prose. docs-parity.invariant.test.ts in the tradequ repository parses them out of this section and compares them with the declared unions, so a code added to either package and not reflected here turns that check red. Its limits are stated in the test itself. A code’s absence from this list is a documentation gap, not evidence that the verifier cannot emit it. Do not treat the list as an exhaustive contract, and do not build a public claim on a code being missing from it.

bundle.unknown_version
bundle.unknown_profile
bundle.file_missing
bundle.file_digest_mismatch
bundle.manifest_digest_mismatch

integrity.mismatch

signature.unknown_kid
signature.invalid
signature.not_signed
signature.no_external_trust_root

snapshot_replay.hash_mismatch
snapshot_replay.evaluator_unavailable
snapshot_replay.snapshot_id_mismatch
snapshot_replay.policy_snapshot_digest_mismatch     (v2 only)

transparency.body_subject_mismatch
transparency.inclusion_proof_invalid
transparency.inclusion_proof_unverified
transparency.set_invalid
transparency.unknown_log_id
transparency.envelope_decode_failed
transparency.envelope_body_hash_mismatch
transparency.proof_missing
transparency.anchor_unproven

chain_link.hash_mismatch
chain_link.signature_invalid
chain_link.receipt_binding_mismatch

chain_seal.hash_mismatch
chain_seal.signature_invalid
chain_seal.receipt_binding_mismatch

canonicalization.profile_mismatch
canonicalization.vector_failure

evidence.digest_mismatch
evidence.bundled_manifest_invalid
evidence.custodian_unknown_kid
evidence.custodian_signature_invalid
evidence.custodian_signature_malformed

approval_lineage.digest_mismatch
approval_lineage.signature_invalid
approval_lineage.unknown_ratifier
approval_lineage.policy_rules_hash_mismatch

10.5 Verdict roll-up and exit codes

The ten sub-claims roll up to one headline verdict, with precedence invalid > indeterminate > warn > valid:

Verdict	When	Exit code
`invalid`	Any sub-claim has `status: 'invalid'` and at least one non-advisory failure code	5
`indeterminate`	No hard failure, but at least one sub-claim is `not_checked`	7
`warn`	No hard failure and nothing unchecked, but at least one sub-claim carries an advisory code	0
`valid`	Every sub-claim passes cleanly	0

An advisory code is one the verifier emits to disclose a scope limit rather than to report a cryptographic failure. transparency.inclusion_proof_unverified and snapshot_replay.skipped_in_browser are the two this page names; the set is not fully documented here (§10.4). A sub-claim is downgraded only when every code on it is advisory — a real failure alongside an advisory one always wins, so “we could not check X” can never launder “X failed”. 5 and 7 answer deliberately different questions. Exit 5 says a check ran and the claim is refuted. Exit 7 says a claim was made and could not be established: the artefact is not accused of anything, and it has not passed either. Automation gating on verification should pick the question it means:

-eq 0 — nothing is wrong. Rejects unchecked claims.
-ne 5 — nothing is proven wrong. Accepts unchecked claims.

Neither is the right default for every caller, which is why the verifier reports them separately rather than collapsing 7 into either neighbour. A CI gate written as “exit 0 or fail” is a stricter policy than one written as “not exit 5”, and the difference is exactly the set of claims the artefact makes that the verifier could not settle. The verdict is the shipped verifier’s own output, in both the Node and browser implementations. The exit codes are the mapping the command-line verifier applies to it; that verifier is not published yet — see Trust Model for its status.

11. Public API Surface

The endpoints exposed by the MeshQu API:

Endpoint	Auth	Rate limit	Status
`POST /v1/decisions/evaluate`	API key + tenant	tenant-tier	Implemented
`POST /v1/decisions/record`	API key + tenant	tenant-tier; `idempotency_key` required	Implemented
`POST /v1/decisions/replay`	API key + tenant	tenant-tier	Implemented
`GET /v1/receipts/:decisionId`	Public, unauth	300 req/min per IP	Implemented. Also resolves approval-receipt and agent-licence ids (§19)
`GET /v1/receipts/:decisionId/bundle?format=json\|tar`	Public, unauth	60 req/min per IP	Implemented; may be disabled by the operator
`POST /v1/agent-licences` (issue) · `POST /v1/agent-licences/:id/revoke`	Human session only (`humanGovernanceAct` — an API key receives 403)	tenant-tier	Implemented
`GET /v1/agent-licences` (list) · `GET /v1/agent-licences/:id`	API key + tenant	tenant-tier	Implemented
`GET /v1/chains/:chainId/bundle?format=json\|tar`	Public, unauth	30 req/min per IP	Implemented
`GET /v1/chains/:chainId/verify`	Public, unauth	100 req/min per IP	Implemented
`GET /v1/chains/:chainId/seal`	Public, unauth	300 req/min per IP	Implemented
`GET /v1/forms/:formId/schema`	Public, unauth	60 req/min	Implemented
`GET /v1/forms/:formId/api-contract`	Public, unauth	60 req/min	Implemented
`GET /v1/forms/:formId/receipts/:decisionId`	Public, unauth	300 req/min	Implemented
`POST /v1/forms/:formId/submit`	Public, unauth — and a write	100 req/min per (form, IP)	Implemented. Evaluates and mints a signed receipt with no API key presented

Fourteen path patterns are reachable with no API key and no tenant header — eighteen when the operator enables the OpenAPI document and docs UI. Nine of them reach tenant data: the eight reads in the table above plus one write, the form submit. The remaining five are infrastructure, with one caveat worth stating — /metrics exposes per-tenant time series and is guarded by a bearer token rather than by the API key. All of them are listed, with what “unauthenticated” does and does not mean, under Authentication → Public paths. Public receipt response shape: { context, result, chain_id, chain_step }. The API normalises legacy policy_snapshot_hash → evaluated_rules_hash on the way out.

12. Persistence Model (summary)

MeshQu persists each of these as a distinct artifact, surfaced through the REST API and verification bundles:

Receipts — immutable once written; hash, signature and timestamp fields cannot be updated or deleted after they are recorded.
Chain proofs — per-step chain integrity hashes and signatures.
Chain seals — a completeness seal per chain.
Decision outcomes — post-decision status (override / escalate / etc).
Policy snapshots — frozen policy bundles.
Policy approval receipts — ratifier-signed approval records.
Audit events — an append-only, hash-chained audit log.

Tenant isolation is enforced in four layers — the request’s tenant header, an application-level tenant predicate on every query, a per-transaction SET LOCAL of the tenant id, and Postgres row-level security with FORCE — so a request carrying a tenant header can only ever reach that tenant’s data. What that does not say. Of the fourteen path patterns reachable with no tenant header and no API key (§11), nine reach tenant data — and they read and write it, addressed by an unguessable identifier rather than by an authenticated principal. A receipt id, chain id or form id is therefore a capability: whoever holds one can read what it names, and in the case of POST /v1/forms/:formId/submit cause a signed receipt to be minted under that form’s tenant. On those paths the four layers are not what separates one tenant from another, because they are not in the request at all — GET /v1/receipts/:decisionId resolves through a SECURITY DEFINER lookup that takes a receipt id and no tenant predicate. What keeps one tenant’s receipts out of another’s reach there is the unguessability of the identifier, and nothing else. Publish an id and you have published what it names.

13. Key Management

Signing key kid format: msk_v{N} (e.g. msk_v1).
Algorithm: Ed25519 only.
trusted_keys.json inside a bundle is informational only and is never used as a trust root. Treating it as one would let a self-signed bundle — operator-controlled keys listed in the bundle as “trusted” — verify against itself. The verifier refuses instead: with no external roots supplied it emits signature.no_external_trust_root (§10.4) rather than falling back to the bundled listing.
Production verification requires trust roots supplied out-of-band. The verifier resolves a receipt’s signature_kid only against roots its caller passes in; with none supplied it emits signature.no_external_trust_root rather than falling back to anything. How a verifying party obtains and pins those roots is that party’s own policy — it is not something the issuer’s own API can settle, and this page does not tell you to fetch them from one. GET /v1/.well-known/signing-keys in particular is deprecated and self-asserted — the producer vouching for itself — and must not be treated as a trust root.
The /verify demo is not an exception to that rule so much as a demonstration of it: it verifies against a bundled demo key (msk_demo_v2) and makes no trust-rooted claim.
Key rotation does not retroactively invalidate bundles — a rotated-out key still verifies a receipt it signed, provided the verifier’s out-of-band root set still carries it. The bundle’s trusted_keys.json records which keys were current at export time, which is useful for a fingerprint UI; it is not what makes the old signature verify.
Custodian (evidence) keys and ratifier (approval) keys are supplied to the verifier out-of-band via custodianTrustedRoots / ratifierTrustedRoots. MeshQu never holds them.

14. What Is and Isn’t Bound — quick reference

Bound into v1 integrity_hash: decision, violations, context (minus source_artifact, which is stripped whole), source_artifact.hash, action in full — metadata included (§1.5) — policy_snapshot_id, evaluated_rules_hash, timestamp. Additionally bound into v2 integrity_hash: receipt_schema_version, policy_snapshot_digest, evidence_manifest_digest (or null). Conditionally bound into integrity_hash — v1 and v2 alike — when the field is present on result: is_shadow, shadow_converted, original_decision (§1.6). Presence-dispatched: absent field, absent key, unchanged legacy payload (§2.2). In the v2 signed envelope (§2.3) — seven fields exactly, in two groups:

Envelope only, not in the integrity hash: signature_kid, signature_algorithm.
In the envelope and in the integrity hash: timestamp (bound by the v1 and v2 hash alike), receipt_schema_version, policy_snapshot_digest, evidence_manifest_digest.

The seventh field is integrity_hash itself, which is what makes the signature’s coverage of every other field transitive (§2.3). Stored on the receipt but NOT hashed: transparency_anchor, chain linkage, evaluation_time_ms, rules_evaluated, rules_na, na_rules, source artifact metadata (type / filename / byte_size / reference_id), the structured actor row, decision outcomes. Bound transitively via policy_snapshot_digest: all policy_versions[i].approval_receipt_digest entries (when present), all policy_versions[i].policy_rules_hash entries — therefore approval lineage.

15. Status Matrix

Capability	Status	Public-claim guidance
Ed25519 signing of receipts	Implemented	”Signed against published keys” — safe
Offline integrity + signature verification	Implemented	”Verifiable offline / no MeshQu API” — safe
Snapshot replay (deterministic re-evaluation)	Implemented	”Replayable: same inputs and snapshot → same result” — safe
Self-contained verification bundle	Implemented	”Portable” / “self-contained proof” — safe
Chain linkage + chain integrity hash	Implemented	”Chainable” — safe
Chain seal	Implemented	”Sealed chain” / “completeness proof” — safe
Evidence manifest (digest + custodian sigs)	Implemented (v2)	“Evidence digest / evidence references” — safe. Never imply MeshQu stores evidence content.
Source artifact hash binding	Implemented	”Document binding” — safe
Rekor anchoring	Implemented	”Anchored to a public transparency log” — safe with footnote
Offline SET verification	Implemented	”Verifiable without contacting the log” — safe
Online Rekor entry-existence lookup	Implemented (primitive; inert in the bundle verifier)	“We can check the log still has the entry” — safe. Not an inclusion proof
Online inclusion-proof verification against a co-signed witness	Planned	Don’t claim live witness verification
Approval lineage verified by bundle (per-version digest + ratifier signature + rules-hash)	Implemented (APR-008 / APR-009 / APR-010)	“Approval lineage verified” — safe. Requires `ratifierTrustedRoots` supplied out-of-band.
Agent licence record — signed grant + superseding revocation (§19)	Implemented (AGD-003)	“A named person granted this credential a scoped, expiring, revocable licence” — safe. Never “discharges/transfers accountability”, never “proves which model acted”.
Licence admissibility on receipt-minting calls (`off` / `record_only` / `enforce`)	Implemented (AGD-003)	Claims must name the mode. `record_only` deployments claim issue/display/verify only — the enforcement claim is per-deployment, not a product property.
Licence page in the public verifier (`/l/:id`)	Implemented, behind a release flag	Do not claim or link until the flag is flipped (AGD-007 release gate).
Recursive governance (`governance_source.level > 0`)	Planned (`level` always 0)	Don’t market hierarchical / tiered governance
RFC 8785 canonical JSON	Planned (`v1` profile)	Today the spec is `meshqu-canonical/v0`
Decision outcome tracking	Implemented	Safe on detail UIs; not part of the signed receipt
Audit trail (hash-chained, immutable)	Implemented	Safe

16. Glossary — safe public terms (and what to avoid)

Use	Avoid	Why
Decision Receipt	”Decision token”	Receipt is the canonical product noun
Signed	”Tamper-proof”	We claim tamper-evident (any change is detected), not impossible-to-tamper
Verifiable offline	”Trustless”	We still trust the bundled public keys
Replayable	”Reversible”	Replay reproduces the verdict; nothing is undone
Portable	”Decentralised”	Self-contained bundle ≠ decentralisation
Independently verifiable	”Permissionless”	We provide a verifier and a bundle format; no permission, but not permissionless infra
Chainable / Sealed chain	”Workflow ledger”	Chain is hash-linked; “ledger” implies more than we ship
Evidence references / Evidence digest	”Evidence stored”	We do not store evidence content
Anchored to a public transparency log	”Notarised on-chain”	Rekor ≠ blockchain
Snapshot of policy	”Frozen ledger”	Snapshot is the right primitive
Actor (human / automated)	“Approver”	Receipt records who acted, not necessarily who approved
Ratifier (in approval receipts)	“Auditor”	Auditor is the wrong role
Custodian (in evidence manifests)	“Issuer”	Custodian = external system attesting to evidence
`receipt_schema_version` v1 / v2	”Receipt protocol v2”	Not a protocol; just envelope schema
`integrity_hash`	”Fingerprint”	OK casually but not in /spec
Verification bundle	”Proof package”	Use the canonical product noun
Approval lineage verified	”Policy provenance proven”	Lineage is verified per-version, but “provenance proven” overstates the claim
Governance	”Tiered governance”	Recursive governance is planned

17. The two highest-risk public-copy traps

Implying evidence content custody. The product is reference-based. Any public surface that says “MeshQu stores the policy, context, evidence and outcome” overshoots. Use evidence references / evidence digests. The single artefact on the receipt that binds content (source_artifact.hash) binds only the hash — type, filename and size are not bound.
Implying live transparency-log verification. Anchoring to Rekor and offline SET verification are real. Online inclusion-proof lookup against a live witness is not implemented yet. Don’t say “checked against the live transparency log” or “live witness verification”. “Anchored to a public transparency log; verifiable offline against a pinned log key” is accurate.

18. Publication order for wire-format changes

When the receipt wire format changes, the surfaces that describe it must be updated in a fixed order. Each step gates the next — nothing at a given step may describe a change until every step above it is complete.

Step	Surface
1	Implementation and tests
2	Migration and compatibility tests
3	Signed public fixture
4	Receipt Reference — this page
5	Developer guides
6	Website summaries and visuals
7	Sales and conference assets

This page is step 4, which cuts both ways:

Nothing downstream of it may run ahead. Developer guides, website copy and visuals, decks, event pages and sales collateral must not describe a wire-format change before this page describes it.
This page may not run ahead either. It may not describe a wire-format change before the signed public fixture (step 3) exists. Receipt-shaped examples are generated from, or explicitly checked against, a valid fixture; hand-authored ones are not permitted on any public surface.

Standing embargo — receipt v3. No public surface may describe receipt v3 fields, semantics or timelines until steps 1–4 are complete. That includes this page. Until then, v3 is not a public roadmap item and no date may be given for it. Today’s wire format is receipt_schema_version v1 and v2 only (§1.1). The same order is recorded as a standing rule alongside the implementation, so that engineering and documentation cannot drift apart; this section is its docs-side statement, and this page remains the authority for what public surfaces may claim.

19. Agent Licences

A first-class signed record answering: which named person authorised this API credential to act, under which ratified policy version, for which decision types, until when — and has that authorisation been withdrawn? Everything in this section is validated against the committed public fixture — a real grant issued 2026-08-25 in a purpose-made demo tenant, captured from the public lookup and verified with the open verifier: packages/meshqu-core/test-vectors/public-agent-licence-fixture/ in the platform repository. The field contract is docs/architecture/0004-agent-licence-digest-contract.md (ADR 0004).

19.1 The record

Two record types share one shape and one table: a grant, and a revocation that supersedes it. Revocation is a new signed record naming the grant — never an edit or a deletion. The store is append-only. The signed preimage is exactly 14 fields (ADR 0004 §3): id, tenant_id, record_type, key_id (the subject — an API key, not a person and not a model), revokes_licence_id, granted_by (the authenticated user id captured at issue), grant_authority (free text, stored verbatim), policy_id, policy_version_id, policy_version_number, scope (decision types, matched exactly), valid_from, valid_until, issued_at. licence_digest = SHA-256 over the canonical JSON of that preimage. grantor_signature is Ed25519 over the digest, under a ratifier key — policy-governance authority, disjoint from receipt-signing keys by construction. Verification recomputes the digest before checking the signature: a genuine signature over a stale digest proves nothing about an edited record.

19.2 Lifecycle and admissibility

Issue and revoke are human governance acts: the routes reject any API-key principal before the handler runs. A deployment resolves licence admissibility on every receipt-minting call under one of three modes — off, record_only, enforce — where the effective mode is the maximum of the deployment default and the tenant setting. In record_only, the admissibility status is stamped into the decision receipt’s hashed context and nothing is refused; in enforce, an expired, out-of-scope, revoked or missing licence fails closed with a distinct error code and no receipt is minted. The mode itself is stamped into the hashed context, so a record-only receipt is distinguishable from an enforced one from the receipt alone.

19.3 Verification and the public lookup

GET /v1/receipts/:id (public, unauthenticated) resolves a licence id and returns the grant with its superseding revocation inline (or null), so a verifier can distinguish verifiably issued from verifiably still in force. The open verifier (@meshqu/verify-lib/agent-licence) recomputes the digest from the response bytes, checks the signature against the ratifier trust roots, verifies any revocation the same way including its binding to the grant, and reports cryptographic verdict and lifecycle as two separate axes — a revoked licence is normally cryptographically perfect, and one badge would have to lie about one of the two.

19.4 What a licence does and does not establish

It evidences governed delegation by a named accountable person. It does not discharge, transfer or dilute that person’s accountability, and it is not a regulator-granted permission.
Its subject is an API credential. It does not establish which model or agent implementation acted behind that credential.
The signature is checked against the trust roots the verifier carries. The stronger claim — verification without trusting MeshQu — awaits the published signed key registry and may not be made until then.

​1. The Receipt Envelope

​1.1 v1 vs v2 — which fields exist

​1.2 Decision Context (the input)

​1.3 Source Artifact (context.source_artifact)

​1.4 Actor (the actor field)

​1.5 Action (result.action)

​1.6 Shadow-mode fields (result.is_shadow, result.shadow_converted, result.original_decision)

​2. Cryptographic Model

​2.1 Canonicalisation profile

​2.2 Integrity hash — exact payloads

​2.3 Signing — what is signed

​2.4 Policy snapshot digest (v2)

​2.5 Evidence manifest digest (v2, optional)

​2.6 Active-rule projection (used everywhere rules are hashed)

​3. Policy Snapshot

​4. Approval Receipts (lineage)

​5. Evidence Manifest (v2 only)

​6. Transparency Anchor (Rekor)

​6.1 What a bundle reports for an anchor

​7. Decision Chains

​7.1 Linkage on the receipt

​7.2 Chain proofs

​7.3 Chain seal

​7.4 Verification result type

​8. Decision Outcomes (post-decision tracking)

​9. Audit Trail

​10. Verification Bundle

​10.1 Manifest (bundle_manifest.json)

​10.2 Files in a bundle

​10.3 Verifier sub-claims

​10.4 Failure codes

​10.5 Verdict roll-up and exit codes

​11. Public API Surface

​12. Persistence Model (summary)

​13. Key Management

​14. What Is and Isn’t Bound — quick reference

​15. Status Matrix

​16. Glossary — safe public terms (and what to avoid)

​17. The two highest-risk public-copy traps

​18. Publication order for wire-format changes

​19. Agent Licences

​19.1 The record

​19.2 Lifecycle and admissibility

​19.3 Verification and the public lookup

​19.4 What a licence does and does not establish