Skip to content

0009: receipt, epoch and proof-container contracts

Date: 2026-10-20. Implements W06 / issue #7 under the autonomous backlog request. These are structural contracts and checks of declared references. No signature, quote or proof is accepted, no backend is qualified, and no old experiment is reused.

Records and structural invariants

hallmark.receipts adds frozen records with required schema IDs, including when nested: ProofInputs (hallmark/proof-inputs/1), ReceiptBody (hallmark/receipt/1), SignedReceipt (hallmark/signed-receipt/1), EpochRecord (hallmark/epoch/1) and ProofArtifact (hallmark/proof-artifact/1). All fields, including nullable ones, are required. Checked CBOR methods revalidate nested records and reject extra fields and unchecked-copy corruption.

ProofInputs names context, classifier, input digest, original unit count, chunk count, signed int32 threshold and boolean verdict. Unit count is 0..32768 and chunk count 1..32768, no greater than max(1, unit_count). The explicit validate_profile(classifier, profile) checks classifier/profile identities, encoding kind, exact threshold, the lower profile unit cap and chunk_count=max(1, ceil(unit_count/content_capacity)). Content capacity subtracts the fixed prefix/suffix from chunk size. This checks counts, not actual chunks, masks, input opening or execution.

ReceiptBody requires exactly three distinct classifier inputs. Every input context must equal H("context", [expected, transcript]). Sequence zero has a null predecessor; later sequences require a digest. Nonnull continuity must match the body exactly; null continuity makes no history claim. released requires all three declared verdicts true, and blocked requires at least one false. A storage, classifier or epoch failure is not a native policy block and releases nothing; these records do not model such failures as a successful policy verdict.

Decoding cannot determine kinds from opaque identities. The explicit validate_policy(policy, classifiers, profiles) resolves the policy's exact rule/MLP/encoder order, checks its identity against the expectation, and checks each input's threshold/count/profile. validate_expectation(expected, now=...) requires independently supplied expectations and compares every field. Reusing the receipt's own expectations as trust defeats that boundary.

Public-input layout

ProofInputs.to_fields() returns exactly 100 mathematical integers:

Positions Meaning Range
0–31 context bytes, original order 0..255 each
32–63 classifier bytes, original order 0..255 each
64–95 input-digest bytes, original order 0..255 each
96 original unit count 0..32768, further bounded by profile
97 chunk count 1..32768, exact profile relation
98 signed threshold plus 2^31 0..2^32−1
99 verdict false=0, true=1

from_fields requires an exact 100-element tuple of exact integers, rejects out-of-range aliases/booleans and reconstructs the record. Digests are never reduced modulo a scalar field. Negative thresholds use the specified offset, not two's complement or a signed field residue. The schema ID is fixed by this layout and is not another field. The machine-readable layout must be pinned as a backend artifact, with a field modulus greater than 2^32−1 and circuit constraints for every bound and relation. Packing is not a proof adapter.

Epoch, receipt identity and signature message

Epochs have raw 32-byte IDs/keys, model/measurement digests, two required opaque evidence payloads and 1..256 collateral references sorted by unique path. References remain logical names; validation performs no file access. issued_at < expires_at, with an epoch lifetime of at most 3600 seconds.

epoch.challenge() is exactly the RFC-0006 list preimage: H("epoch", [epoch_id, key, model, measurement, issued_at, expires_at]). epoch.identity() hashes the entire epoch record in the same domain. The list and map are distinct encodings; the challenge excludes quotes/collateral to avoid a cycle, while the record identity includes them. A receipt's epoch field references the complete record identity. epoch.key_id() is H("key", key).

body.identity() is H("receipt", complete_body). body.signing_bytes() returns u32be(len(tag)) || tag || encode(body) for tag=ASCII("hallmark/v1/sign/receipt"). It neither signs nor verifies. A SignedReceipt carries that body, a key digest and exactly 64 opaque signature bytes. Key/signature size is checked here; Ed25519 point/encoding/signature validity requires the later pinned crypto verifier.

signed.validate_epoch(epoch, now=...) compares epoch identity, model and key ID, checks receipt issuance within the epoch and checks both intervals at the explicit caller clock. Current means issued_at <= now < expires_at, with no hidden clock or skew allowance. Receipt expiry need not equal epoch expiry; either expired interval fails. The clock itself must be a strict U64. These checks do not authenticate time, enforce caller max-age policy, or examine collateral validity.

Opaque payload and trust boundaries

Each proof and each CPU/accelerator evidence field is nonempty and at most 16 MiB. These implementation hard caps keep individual containers bounded; aggregate wire/bundle limits still apply. ProofArtifact.validate_inputs requires external ProofInputs, classifier/profile records and an explicit max_proof_bytes in 1..16 MiB. It checks equality, backend/verifier-key references and the lower byte budget. Classifier identity also binds its program and setup declarations. It never invokes a verifier or treats arbitrary nonempty bytes as a valid proof.

Malformed structures use sanitized INPUT_INVALID; payload budgets use LIMIT_EXCEEDED. External request mismatch uses REQUEST_MISMATCH; declared reference mismatch uses INPUT_BINDING_FAILED; outside-clock intervals use STALE_EVIDENCE, all at bind for these comparison methods. No accepted/verified flag, signature verifier, attestation verifier or proof verifier is supplied.

Opaque evidence, proof and signature bytes are omitted from repr, but serialization still includes them. Use authorized channels and never log raw Pydantic error objects. Fixtures use explicit synthetic non-signatures, non-proofs and non-attestations; their successful parsing and reference matching cannot establish claims A/B. Authenticated enrollment, qualified cryptographic/hardware adapters and independent verification remain gates.