Stage records

One record per stage. Digests over exact bytes. A chain a stranger can recompute. The format behind the ten-record diagram, set out for someone who has to implement it — or check it — without asking us anything.

§0The one rule everything else serves

A digest is only meaningful if the byte recipe is stated. "The hash of the document" is not a claim. "SHA-256 over the stored bytes of artifact X, 1,482,331 bytes" is. Every recipe on this page therefore answers the same three questions: which bytes, produced how, hashed with what.

The algorithm is SHA-256 throughout — one algorithm per record set, named once in the format field, because per-record algorithm choice is an invitation to downgrade games. A digest is written as sha256: followed by 64 lowercase hex characters.

§1The record envelope — every stage, no exceptions

A stage record is a JSON object with thirteen required top-level fields. A verifier fails a record that lacks any of them. Nothing is inferred and nothing is defaulted: an absent field is absent.

Trust classes

Every input and output declares one of operator-authored, model-generated, or externally-sourced. This does not make externally-sourced content safe; it makes it visible, which is the most a record format can honestly promise to any reader downstream — human or model.

Three states that must not collapse

Absent, declared-none, and recorded are three distinct states and must round-trip distinguishably. An empty inputs list is a declaration; a missing inputs field is a defect. A failed measurement is not a measured zero.

Three different three-way splits — kept apart on purpose

Three things on this page each have exactly three outcomes, and they are not the same three. A stage's outcome.class is ok / refused / error — what the stage did. A verification stage's per-claim result is supported / contradicted / couldn't-check — what the evidence says about one claim. A verifier's report on a record is PASS / FAIL / NOT RUN, with reason — what a stranger could establish. Collapsing any of them to two is how a system ends up reporting a pass for something it never examined.

§2The canonical form — specified as runnable code

A record's digest is taken over its file bytes, so the file's bytes must be the canonical serialisation of the object they encode — not equivalent to it, identical. The canonical form, in full:

1. UTF-8, no byte-order mark.
2. JSON, object keys sorted by Unicode code point.
3. No whitespace outside string literals.
4. No JSON numbers. Every numeric value — counts, offsets, indices, scores, byte lengths — is a decimal string. A format that serialises 500.00 as a float has already lost the distinction between "500.00" and "500", and float re-serialisation is not stable across languages.
5. No NaN, no Infinity, no -0.
6. The file contains exactly the canonical bytes and nothing else — no trailing newline.
7. A record never contains its own digest. A record cannot contain the proof of its own final state; the digest lives in the chain manifest and in the next record's prev.

import hashlib, json

def canonical(obj) -> bytes:
    # refuse any JSON number, refuse a self-digest, then:
    return json.dumps(obj, sort_keys=True, ensure_ascii=False,
                      separators=(",", ":"), allow_nan=False).encode("utf-8")

def digest(obj) -> str:
    return "sha256:" + hashlib.sha256(canonical(obj)).hexdigest()

jq -S sorts keys but reformats numbers and appends a newline — use it to inspect, never to produce. The reference canonicaliser ships with the samples as a ~40-line script whose only job is to answer "is this file its own canonical form?"

§3Digest recipes — one per kind of artifact

The envelope says what is digested. These recipes say which bytes, for each kind of thing a stage can touch.

R1 · File bytes — binary artifacts (PDF, image, wheel, model weights)

Hash the file exactly as stored. No transformation of any kind.

sha256sum FrameworkAgreement_2025.pdf            # Linux / macOS
certutil -hashfile file.pdf SHA256               # Windows
python -c "import hashlib,sys; print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())" f.pdf

R2 · Text artifacts — converted text, cleaned text, prompts, answers

Normalise once at write time — UTF-8, LF line endings, no BOM — write to the store, then hash the stored bytes with R1. The record may note the normalisation so a verifier who receives the text through a lossy channel (email, copy-paste) knows how to reconstitute the exact bytes. CRLF is the first cause of false mismatches; kill it at write time, never at verify time.

R3 · Chunks and spans — parts of a digested parent

A chunk's own digest is SHA-256 over the UTF-8 bytes of the chunk text (R2 rules). Its location is a pair of offsets into the parent's stored bytes. State the offset unit in the record. This reference uses byte offsets into the parent's stored UTF-8; code-point offsets are equally valid but must be declared. A record that does not name its offset unit cannot be checked. Verify: parent_bytes[start:end] must hash to the chunk digest.

R4 · Manifests — set-valued outputs (chunk sets, ranked results, a census)

Serialise as canonical JSON (§2) and hash those bytes. Arrays stay in the stage's declared order — chunk sequence, rank order — because order is part of what the stage asserts.

R5 · Merkle root — large sets, external anchoring

Leaves are item digests in manifest order. Pair adjacent leaves, hash the concatenation of the two raw 32-byte digests, repeat to the root. State the odd-leaf rule in the record (this reference: promote the odd leaf unchanged). One published root commits to every leaf, and any single item is verifiable with a log-sized proof path.

R6 · The record itself — and therefore the chain

The record is a JSON object; serialise it in canonical form including its prev field, hash the bytes, and that digest is what the next record's prev cites and what the manifest lists. Editing any historical record changes its digest, which breaks every later record's link. Tampering surfaces as a broken chain, not as an argument.

R7 · Wire bytes — external calls, request and response

Hash the raw bytes as sent and as received — before parsing, before re-serialisation, before pretty-printing. The JSON you parsed is not the JSON you received; only the received bytes are evidence. Capture at the transport boundary.

R8 · Anchoring — what makes the timestamps testify

The chain head (or a Merkle root over many) is published somewhere the operator does not control the history of, on a cadence: a commit or tag in a public repository, an OpenTimestamps attestation, a transparency-log entry. The anchor proves the record existed by that moment — which is what turns "our clock said 14:02" into "the world can bound when this record was made." §6 states what anchoring does and does not establish.

R9 · What never gets digested into anything — secrets

Keys, credentials, personal data. The record carries digests of artifacts, and artifacts must be reviewed as publishable before their digests are anchored — because an anchored digest of a secret is a commitment you can never unwind. A value inside a published preimage is frozen the moment the first hash is published.

§4Receipts and declarations

Not every stage can be replayed, and the format refuses to pretend otherwise. The instrument carries rederivable, and the diagram carries the same fact as two badges:

RECEIPT · re-derivable   The stage can be run again from its recorded inputs under its pinned instrument and must produce the same output bytes. Conversion with a pinned tool, chunking under a declared rule, retrieval against a frozen index, prompt assembly, a verification pass — these are receipts.

DECLARED · bytes frozen   The stage cannot be replayed — a call to a vendor-hosted model, an external API answering from world-state, a non-deterministic generation — so the record freezes exactly what went in and what came out, digests both, and says on its face that it cannot promise repeatability. A declaration is weaker than a receipt and is labelled as weaker. A record that quietly implies replayability it does not have is the defect this distinction exists to prevent.

§5Per stage — the worked example

The format is stage-agnostic: any pipeline declares its own stages in coverage.declared_stages. The table below is the ten-stage retrieval pipeline of the home-page diagram — one worked example, not a required shape. The sample chain published beside this page is a four-stage subset of it.

§6The chain, the manifest, and the limit of a green chain

A run publishes its records beside a manifest: the ordered list of { index, stage, file, digest }, a chain_head equal to the digest of the last record, the run identifier, and the manifest's own anchor state. A verifier checks that each record's prev equals the digest of the preceding record's exact bytes and that the head matches the last one.

That is why the format requires the anchor state to be declared on every record, and why a conforming verifier, on any record marked unanchored, must emit NOT RUN — originality with the reason stated. A verifier that lets a green chain imply originality is lying by omission. The reference verifier prints, for every unanchored sample:

[NOT-RUN] originality -- record is declared unanchored;
          this verifier can establish consistency, not originality

Anchoring, chaining, and signing are each opt-in and off by default in any implementation of this format. A record that declares itself unanchored is conforming; a record that omits the declaration is not.

§7The five classic ways a digest lies

1. CRLF / BOM drift. A Windows checkout rewrites line endings; the hash mismatches on text that looks identical. Fix at write time (R2). Verifiers clone with git clone -c core.longpaths=true and autocrlf off.
2. JSON re-serialisation. Same data, different bytes — key order, whitespace, 1.0842 becoming 1.08420000000000005. Only canonical bytes (§2) are hashable; only wire bytes (R7) are evidence.
3. Hashing the parsed, not the received. A pretty-printed API response digests differently from what arrived. Capture at the boundary.
4. Unstated offset units. Bytes, code points, and UTF-16 units silently disagree the moment text leaves ASCII. Name the unit in the record.
5. Self-reported time. A timestamp without an anchor is testimony. Anchor the chain head; let the batch bound the clock.

§8What this format does not yet do

§9Check it yourself — standard tools, no network, no key

A sample chain, its manifest, the reference canonicaliser, a ~140-line reference verifier, and ten rejection vectors a conforming verifier must refuse — each with the reason it must be refused — are published at oneproof.dev/samples/ (11 September 2026). Three commands check the whole thing:

sha256sum receipts/*.json MANIFEST.json   # our digests, your tool
python3 canonicalize.py receipts/*.json   # is each file its own canonical form?
python3 verify.py MANIFEST.json           # the chain, offline

A conforming verifier requires no network, no key, no account, no licence, and no live third party; is implementable from the specification and the vectors alone; and never mutates what it checks. A format with no rejection vectors has not specified anything — it has described a happy path and left every implementer to guess at the edges. An implementation claiming conformance must refuse all ten, and must refuse them for the stated reason; refusing the right file for the wrong reason is a failing test that happens to look green.

One verifier checking one format is a claim. Two independent verifiers agreeing on the same records is evidence. If you write one, publish your results against the samples and the vectors — including every place where you and the reference disagree. A disagreement between two verifiers is the most valuable bug report this format can receive, because it means the specification is ambiguous and the ambiguity was found before anyone depended on it.

The toolbox — nothing bespoke

sha256sum / certutil for R1–R3 · python hashlib + json.dumps(sort_keys=True, separators=(',',':')) for §2 and R4–R6 · transport-level capture for R7 · a public repository, OpenTimestamps, or a transparency log for R8. No new cryptography anywhere. The method is the discipline of which bytes, not new primitives.