@sanning/proof 0.5.0 → 0.7.0

package/dist/evidence.js

@@ -18,6 +18,7 @@
 import { deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import { MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, jcs, verifyEnvelope, } from "./verifier.js";
+import { inBodyContentOffered, sideContentEntry, } from "./side-content.js";
 // Only the evidence-bundle major(s) this kernel verifies. A new major is a
 // deliberate one-entry addition HERE — same fail-closed discipline as the
 // envelope verifier's ACCEPTED_SPEC_MAJORS.
@@ -26,13 +27,52 @@ const ACCEPTED_EVIDENCE_MAJORS = ["sanning.evidence/v1"];
 // body_type is not a hard failure of the WRAPPER (the signature + body_hash
 // still verify), but its body cannot be re-derived, so the per-body verdict is
 // "undetermined" rather than "verified".
-export const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v1";
+export const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v2";
+/**
+ * The frozen pre-`anchor_ref` body (evidence-bundle.md §5.1.3).
+ *
+ * Accepted PERMANENTLY, not for a deprecation window. Every bundle emitted
+ * before 2026-09-03 carries this shape, and those bundles are evidence — a
+ * reader that stopped accepting them would destroy the record it exists to
+ * defend (DL-30). Nothing new emits it.
+ */
+export const ANCHOR_TRACE_BODY_TYPE_V1 = "sanning.anchor.trace/v1";
+/** Every anchor-trace body this kernel verifies. Order is newest-first. */
+export const ANCHOR_TRACE_BODY_TYPES = [
+    ANCHOR_TRACE_BODY_TYPE,
+    ANCHOR_TRACE_BODY_TYPE_V1,
+];
 // The issuer-composed attested-evidence-export body (specs/evidence-export.md
 // §2). The wrapper is unchanged (`sanning.evidence/v1`, Ed25519-signed); this body
 // carries a cached verdict + the inline source bundle + embedded RSA-PSS
 // operator attestations. verifyEvidenceBundle dispatches on it to
 // verifyExportBody (§5).
 export const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
+/**
+ * The Sanning-signed interval stamp body (evidence-bundle.md §5.2, DL-58).
+ *
+ * Its own `body_type` rather than a widened anchor-trace body, and the reason
+ * is the whole decision: an anchor-trace checkpoint carries a PRODUCER-signed
+ * `sanning.events/v1` envelope, and a stamp has no producer signature at all —
+ * Sanning places it, under DL-52, for a customer who holds no chain identity.
+ * The two rejected options were making `envelope` optional and synthesising an
+ * envelope that Sanning signs; the second would have made a Sanning
+ * attestation indistinguishable ON THE WIRE from a producer's, which is
+ * unrecoverable once witnessed.
+ */
+export const STAMP_TRACE_BODY_TYPE = "sanning.stamp.trace/v1";
+/**
+ * The version string INSIDE a witnessed stamp body — a different string from
+ * the `body_type` above, and the two are easy to confuse.
+ *
+ * `sanning.stamp.trace/v1` discriminates the BUNDLE BODY: it is the reader's
+ * dispatch key. `sanning.stamp/v1` is the control plane's own version of the
+ * bytes it hands a witness (`control-plane/src/stamp-tree.ts`,
+ * `STAMP_BODY_VERSION`). A `sanning.stamp.trace/v1` body pins the inner
+ * version to exactly this value: two answers to one question inside one
+ * signature is the §5.1.2 mixed-vocabulary reject, one layer down.
+ */
+export const STAMP_BODY_VERSION = "sanning.stamp/v1";
 function isEvidenceMajorAccepted(specVersion) {
     if (typeof specVersion !== "string" || specVersion === "")
         return false;
@@ -149,12 +189,18 @@ export async function verifyEvidenceBundle(bundle, options = {}) {
     if (bodyType === EXPORT_BODY_TYPE) {
         return verifyExportBody(b, specVersionOk, assertedStatus, errors, options);
     }
-    if (bodyType !== ANCHOR_TRACE_BODY_TYPE) {
+    // The Sanning-signed interval stamp body (evidence-bundle.md §5.2). The
+    // wrapper is authentic — and for this body that IS "Sanning signed it", since
+    // a stamp carries no second signature of its own inside the bundle.
+    if (bodyType === STAMP_TRACE_BODY_TYPE) {
+        return verifyStampTrace(b, specVersionOk, assertedStatus, errors);
+    }
+    if (bodyType !== ANCHOR_TRACE_BODY_TYPE && bodyType !== ANCHOR_TRACE_BODY_TYPE_V1) {
         // The wrapper is authentic but we don't know this body's structure. Per
         // wrap-don't-merge, that is "partial" (cryptographically sound wrapper,
         // body verdict undetermined) — not a failure.
         errors.push(`body_type ${JSON.stringify(bodyType)} is not verifiable by this kernel ` +
-            `(only ${ANCHOR_TRACE_BODY_TYPE}); wrapper verified, body undetermined`);
+            `(only ${ANCHOR_TRACE_BODY_TYPES.join(", ")}); wrapper verified, body undetermined`);
         return {
             status: "partial",
             specVersionOk,
@@ -170,31 +216,168 @@ export async function verifyEvidenceBundle(bundle, options = {}) {
     }
     return verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, errors, options);
 }
+/**
+ * Index a source bundle's checkpoints by the key its attestations will use.
+ *
+ * The attestation join key follows the SOURCE bundle's own vocabulary — a
+ * v2 source is keyed by `checkpoint_ref`, a frozen v1 source by `tx_id`. The
+ * alternative (always deriving a v2-style key) would silently un-resolve every
+ * attestation ever written against a v1 export: `data_hash_bound` would go
+ * false, the export would stop reaching `verified`, and nothing would say why.
+ */
+async function indexSourceCheckpoints(bundle) {
+    const out = new Map();
+    const sb = bundle.body;
+    const isV1 = bundle.body_type === ANCHOR_TRACE_BODY_TYPE_V1;
+    if (!sb || typeof sb !== "object" || !Array.isArray(sb.checkpoints))
+        return out;
+    for (const cp of sb.checkpoints) {
+        if (!cp || typeof cp !== "object")
+            continue;
+        let recordBytes;
+        try {
+            if (typeof cp.record_bytes === "string")
+                recordBytes = hexToBytes(cp.record_bytes);
+        }
+        catch {
+            recordBytes = undefined;
+        }
+        const keyed = await resolveCheckpointKey(cp, recordBytes, isV1);
+        if (keyed.key !== null && !out.has(keyed.key))
+            out.set(keyed.key, cp);
+    }
+    return out;
+}
+/**
+ * Resolve a checkpoint's join key and its witness reference, for whichever
+ * body form we are reading.
+ *
+ * ── The rule that matters, and why it is a reject rather than a preference ──
+ *
+ * A checkpoint carrying BOTH vocabularies is two answers to one question
+ * inside one signature. A reader that silently prefers one gives a different
+ * answer from a reader that prefers the other, over the same signed bytes —
+ * and both look like they verified. So a v2 body carrying `tx_id`, or a v1
+ * body carrying `anchor_ref`/`checkpoint_ref`, is rejected rather than
+ * resolved. This is cheap to enforce here and impossible to enforce later.
+ *
+ * ── Why v2's key is recomputed ──
+ *
+ * In v1 the key was an asserted label matched against another asserted label;
+ * nothing tied either to the bytes, so relabelling a checkpoint and every
+ * event pointing at it left a bundle that still verified. In v2 the key IS the
+ * bytes, so the same relabel fails here. v1's behaviour is preserved exactly
+ * as it was — deliberately, because those bundles are already signed and
+ * re-interpreting them is not backwards compatibility.
+ */
+async function resolveCheckpointKey(cp, recordBytes, isV1) {
+    const errors = [];
+    if (isV1) {
+        if (cp.checkpoint_ref !== undefined || cp.anchor_ref !== undefined) {
+            errors.push("sanning.anchor.trace/v1 checkpoint carries v2 fields (checkpoint_ref/anchor_ref) — " +
+                "one bundle speaks one vocabulary");
+            return { key: null, anchorRef: null, errors };
+        }
+        if (typeof cp.tx_id !== "string" || cp.tx_id === "") {
+            errors.push("checkpoint missing tx_id");
+            return { key: null, anchorRef: null, errors };
+        }
+        // v1's tx_id IS an Arweave transaction — its own spec said so. Surfacing it
+        // through the same shape as v2 gives ONE reader-side vocabulary without
+        // touching a byte of the signed bundle.
+        return { key: cp.tx_id, anchorRef: { kind: "arweave", id: cp.tx_id }, errors };
+    }
+    if (cp.tx_id !== undefined) {
+        errors.push("sanning.anchor.trace/v2 checkpoint carries legacy tx_id — one bundle speaks one vocabulary");
+        return { key: null, anchorRef: null, errors };
+    }
+    if (typeof cp.checkpoint_ref !== "string" || cp.checkpoint_ref === "") {
+        errors.push("checkpoint missing checkpoint_ref");
+        return { key: null, anchorRef: null, errors };
+    }
+    if (recordBytes === undefined) {
+        // Without the bytes the key cannot be recomputed, so it cannot be trusted.
+        errors.push("checkpoint_ref cannot be verified — record_bytes missing or not hex");
+        return { key: null, anchorRef: null, errors };
+    }
+    const derived = await sha256Hex(recordBytes);
+    if (derived !== cp.checkpoint_ref.toLowerCase()) {
+        errors.push(`checkpoint_ref does not match SHA-256(record_bytes): claimed=${cp.checkpoint_ref} derived=${derived}`);
+        return { key: null, anchorRef: null, errors };
+    }
+    const anchorRef = parseAnchorRef(cp.anchor_ref, errors);
+    return { key: derived, anchorRef, errors };
+}
+/**
+ * Validate an optional `anchor_ref` (§5.1.1).
+ *
+ * ── An unrecognised `kind` is NOT a failure, and that is the point ──
+ *
+ * The offline verdict — signatures, payload binding, Merkle inclusion — is
+ * computed with no witness access at all. A reader that cannot resolve a
+ * witness has therefore learned NOTHING about whether the evidence was
+ * altered, and must not say otherwise. The shipped issuer did the opposite:
+ * an unrecognised signature type returned `false` rather than `null`, mapped
+ * to `tampered`, and was cached as permanent — a false accusation, produced
+ * by a coverage gap, for a company whose product is telling people whether
+ * records were altered.
+ *
+ * So this validates the SHAPE and never the vocabulary. A malformed
+ * `anchor_ref` is a defect in the bundle; an unknown `kind` is a defect in
+ * the reader, and only the first is the bundle's fault.
+ */
+function parseAnchorRef(raw, errors) {
+    if (raw === undefined || raw === null)
+        return null; // placed, not yet witnessed
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push("anchor_ref must be an object");
+        return null;
+    }
+    const o = raw;
+    if (typeof o.kind !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(o.kind)) {
+        errors.push(`anchor_ref.kind is missing or malformed: ${JSON.stringify(o.kind)}`);
+        return null;
+    }
+    if (typeof o.id !== "string" || o.id === "") {
+        errors.push("anchor_ref.id is missing or empty");
+        return null;
+    }
+    const ref = o.ref;
+    if (ref !== undefined && (typeof ref !== "object" || ref === null || Array.isArray(ref))) {
+        errors.push("anchor_ref.ref must be an object when present");
+        return null;
+    }
+    return {
+        kind: o.kind,
+        id: o.id,
+        ...(ref === undefined ? {} : { ref: ref }),
+    };
+}
 async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, errors, options) {
     const body = b.body;
+    const isV1 = bodyType === ANCHOR_TRACE_BODY_TYPE_V1;
     if (!Array.isArray(body.checkpoints) || !Array.isArray(body.events)) {
-        return malformed("sanning.anchor.trace/v1 body must have checkpoints[] and events[]", true);
+        return malformed(`${bodyType} body must have checkpoints[] and events[]`, true);
     }
     const gateways = options.gateways ?? [];
     const onChainChecked = gateways.length > 0;
     // --- Step 3: per-checkpoint -------------------------------------------------
-    const byTxId = new Map();
+    //
+    // ── Why the join key is resolved BEFORE anything else ──
+    //
+    // `byKey` is what binds an event to the root its inclusion proof is checked
+    // against. Get it wrong and an event proves inclusion in a tree it was never
+    // in — the one failure in this file that produces a WRONG VERIFIED, not a
+    // failed verify. Everything below is downstream of it.
+    const byKey = new Map();
+    const anchorByKey = new Map();
     const checkpointResults = [];
     for (const cp of body.checkpoints) {
         const cpErrors = [];
         let envelopeOk = false;
         let merkleRootOk = false;
-        if (typeof cp.tx_id !== "string") {
-            cpErrors.push("checkpoint missing tx_id");
-        }
-        else if (byTxId.has(cp.tx_id)) {
-            cpErrors.push(`duplicate checkpoint tx_id ${cp.tx_id}`);
-        }
-        else {
-            byTxId.set(cp.tx_id, cp);
-        }
-        // Verify the checkpoint envelope against its committed record (external
-        // commitment — the record is the payload these external envelopes bind to).
+        // Decode record_bytes first: in v2 the join key is DERIVED from it, so it
+        // is an input to identity, not just to the payload binding below.
         let recordBytes;
         try {
             if (typeof cp.record_bytes === "string")
@@ -203,6 +386,19 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
         catch (e) {
             cpErrors.push(`checkpoint record_bytes is not hex: ${stringifyErr(e)}`);
         }
+        const keyed = await resolveCheckpointKey(cp, recordBytes, isV1);
+        cpErrors.push(...keyed.errors);
+        if (keyed.key !== null) {
+            if (byKey.has(keyed.key)) {
+                cpErrors.push(`duplicate checkpoint ${isV1 ? "tx_id" : "checkpoint_ref"} ${keyed.key}`);
+            }
+            else {
+                byKey.set(keyed.key, cp);
+                anchorByKey.set(keyed.key, keyed.anchorRef);
+            }
+        }
+        // Verify the checkpoint envelope against its committed record (external
+        // commitment — the record is the payload these external envelopes bind to).
         try {
             const res = await verifyEnvelope(cp.envelope, recordBytes !== undefined ? { payloadBytes: recordBytes } : {});
             // A checkpoint must fully bind: signature + the committed record matching
@@ -235,12 +431,19 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
             }
         }
         checkpointResults.push({
-            txId: typeof cp.tx_id === "string" ? cp.tx_id : "",
+            checkpointRef: keyed.key ?? "",
+            anchorRef: keyed.anchorRef,
             envelopeOk,
             merkleRootOk,
             onChainOk: null, // filled in step 5 if a gateway re-fetch was requested
             onChain: null, // per-gateway (§4.2), filled in step 5
-            ok: envelopeOk && merkleRootOk,
+            // `keyed.errors` is load-bearing here, not decorative. A structurally
+            // invalid anchor_ref rides INSIDE the signature, so it is a defect we
+            // can see rather than a coverage gap we cannot — and this kernel's
+            // standing rule is that malformed is a failure while absent is
+            // undetermined (the same rule disclosed `content` follows). Without
+            // this term the vector `trace-v2-malformed-anchor-ref` verified GREEN.
+            ok: envelopeOk && merkleRootOk && keyed.errors.length === 0,
             errors: cpErrors,
         });
     }
@@ -274,18 +477,36 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
         // Bind the event to exactly one checkpoint in the bundle, then verify
         // RFC 9162 inclusion against THAT checkpoint's merkle_root.
         const incl = ev.inclusion;
-        const cp = incl && typeof incl.checkpoint_tx_id === "string" ? byTxId.get(incl.checkpoint_tx_id) : undefined;
-        const checkpointBound = cp !== undefined;
+        // The join key is spelled differently in the two forms and MUST NOT be read
+        // from the other one: an inclusion carrying v1's spelling inside a v2 body
+        // is a mixed bundle, and resolving it anyway is how an event silently binds
+        // to a checkpoint nobody meant.
+        const keyField = isV1 ? "checkpoint_tx_id" : "checkpoint_ref";
+        const wrongField = isV1 ? "checkpoint_ref" : "checkpoint_tx_id";
+        const inclAsRecord = incl;
+        const rawKey = inclAsRecord ? inclAsRecord[keyField] : undefined;
+        const strayKey = inclAsRecord ? inclAsRecord[wrongField] : undefined;
+        let cp;
         if (!incl || typeof incl !== "object") {
             evErrors.push("event missing inclusion proof");
         }
-        else if (!checkpointBound) {
-            evErrors.push(`event inclusion.checkpoint_tx_id ${JSON.stringify(incl.checkpoint_tx_id)} resolves to no checkpoint`);
+        else if (strayKey !== undefined) {
+            evErrors.push(`event inclusion carries ${wrongField} in a ${bodyType} body — one bundle speaks one vocabulary`);
+        }
+        else if (typeof rawKey !== "string") {
+            evErrors.push(`event inclusion missing ${keyField}`);
+        }
+        else {
+            cp = byKey.get(rawKey);
+            if (cp === undefined) {
+                evErrors.push(`event inclusion.${keyField} ${JSON.stringify(rawKey)} resolves to no checkpoint`);
+            }
         }
+        const checkpointBound = cp !== undefined;
         let inclusionOk = false;
         if (incl && checkpointBound && cp) {
             try {
-                inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), incl.leaf_index, incl.leaf_count, (incl.audit_path ?? []).map((h) => hexToBytes(h)), hexToBytes(cp.merkle_root));
+                inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), incl.leaf_index, incl.leaf_count, (incl.audit_path ?? []).map((h) => hexToBytes(h)), hexToBytes(cp.merkle_root ?? ""));
                 if (!inclusionOk)
                     evErrors.push("RFC 9162 inclusion proof did not reconstruct the checkpoint root");
                 // Defense in depth: the claimed leaf_hash MUST be the hash of the
@@ -397,10 +618,27 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
         }
         else {
             for (const cpr of checkpointResults) {
-                const cp = byTxId.get(cpr.txId);
+                const cp = byKey.get(cpr.checkpointRef);
                 if (!cp)
                     continue;
-                const outcome = await refetchCheckpoint(cp, gateways, fetchImpl);
+                // A checkpoint with no anchor_ref has NOTHING to re-fetch. Under DL-52
+                // that is the normal state inside a stamp interval — placed, readable,
+                // not yet witnessed — so it reports as unreachable (which downgrades
+                // the run to partial) and NEVER as a mismatch. Treating "we never
+                // anchored it yet" as "the chain disagrees" would be the same false
+                // accusation this whole change is removing.
+                if (cpr.anchorRef === null) {
+                    gatewayUnavailable = true;
+                    cpr.onChain = {
+                        perGateway: gateways.map((gw) => ({ gateway: gw, outcome: "unreachable" })),
+                        rollup: "unreachable",
+                        onChainOk: null,
+                    };
+                    cpr.onChainOk = null;
+                    cpr.errors.push("checkpoint has no anchor_ref — not yet witnessed, nothing to re-fetch");
+                    continue;
+                }
+                const outcome = await refetchCheckpoint(cp, cpr.anchorRef, gateways, fetchImpl);
                 cpr.onChain = outcome.onChain;
                 cpr.onChainOk = outcome.onChain.onChainOk;
                 if (outcome.unavailable)
@@ -456,6 +694,305 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
         errors,
     };
 }
+// ===========================================================================
+// `sanning.stamp.trace/v1` — the Sanning-signed interval stamp (§5.2, DL-58)
+//
+// ── What this can prove, and what it deliberately does not claim ──
+//
+// A stamp is not a producer artifact. Under DL-52 the customer signs an
+// envelope and POSTs it; the commitment is witnessed later, on an interval, by
+// a stamp the customer never sees and holds no key for. So there is no
+// producer signature inside this body to check, and — this is the part worth
+// being precise about — there is no SECOND Sanning signature either. The
+// control plane stores the stamp's canonical bytes and hands them to a witness
+// as a signed chain data item; the signature lives on the chain, not in the
+// `stamps` table and not in this body.
+//
+// What "Sanning signed this" means for a stamp bundle is therefore exactly the
+// WRAPPER signature, verified generically before this function is reached. And
+// what makes the stamp evidence rather than an assertion is the witness, which
+// is on a chain and not checkable offline. Hence the rollup below: a stamp we
+// can read but nobody has witnessed holds the bundle at `partial`.
+//
+// So the checkable surface here is the stamp's INTERNAL consistency against
+// the one authority in the bundle — the witnessed bytes:
+//
+//   1. `stamp_ref` is SHA-256 of the DECODED bytes (derived, not asserted).
+//   2. Those bytes parse and re-canonicalize to themselves under JCS.
+//   3. Their `stamp_version` is the one this body_type pins.
+//   4. Every sub-tree range accounts for exactly one leaf of the stamp.
+//
+// (4) is the one that carries customer weight. R-8's whole per-agent story is
+// "prove this agent was under evidence over window W", answered by a
+// contiguous `first_leaf`/`leaf_count` slice of the org tree. Ranges that do
+// not tile `[0, leaf_count)` describe a partition that does not exist, so a
+// slice claim resting on them is unfounded — and unlike a bad signature,
+// nothing else in the stack would ever notice.
+// ===========================================================================
+/** Lowercase hex, even length, non-empty. The family's serialization rule. */
+function isLowerHex(s, nibbles) {
+    if (typeof s !== "string" || s.length === 0 || s.length % 2 !== 0)
+        return false;
+    if (nibbles !== undefined && s.length !== nibbles)
+        return false;
+    return /^[0-9a-f]+$/.test(s);
+}
+function isNonNegInt(n) {
+    return typeof n === "number" && Number.isInteger(n) && n >= 0;
+}
+/**
+ * Parse and check one stamp's witnessed bytes.
+ *
+ * Errors accumulate rather than short-circuit wherever a later check is still
+ * meaningful, so a bundle with two independent defects reports two — a
+ * verifier that stops at the first one turns a second fix into a second
+ * round-trip.
+ */
+async function verifyStampEntry(raw, seen) {
+    const errors = [];
+    const base = {
+        stampRef: "",
+        stampRefOk: false,
+        bodyOk: false,
+        stampVersion: null,
+        intervalStart: null,
+        intervalEnd: null,
+        merkleRoot: null,
+        leafCount: null,
+        subtreesOk: false,
+        subtrees: [],
+        anchorRef: null,
+        ok: false,
+        errors,
+    };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push("stamp entry is not an object");
+        return base;
+    }
+    const e = raw;
+    // --- the witnessed bytes, which are the only authority in this body -------
+    if (!isLowerHex(e.stamp_bytes)) {
+        errors.push("stamp_bytes is missing or not lowercase hex");
+        return base;
+    }
+    let bytes;
+    try {
+        bytes = hexToBytes(e.stamp_bytes);
+    }
+    catch (err) {
+        errors.push(`stamp_bytes is not hex: ${stringifyErr(err)}`);
+        return base;
+    }
+    // --- the derived identity -------------------------------------------------
+    const derived = await sha256Hex(bytes);
+    if (typeof e.stamp_ref !== "string" || e.stamp_ref === "") {
+        errors.push("stamp entry missing stamp_ref");
+    }
+    else if (e.stamp_ref.toLowerCase() !== derived) {
+        // The bytes were edited and the label was not — or the label was edited
+        // and the bytes were not. Either way the bundle names a stamp it is not
+        // carrying, and quoting that name to a witness would resolve to something
+        // else entirely.
+        errors.push(`stamp_ref does not match SHA-256(stamp_bytes): claimed=${e.stamp_ref} derived=${derived}`);
+    }
+    else {
+        base.stampRefOk = true;
+        base.stampRef = derived;
+        if (seen.has(derived)) {
+            errors.push(`duplicate stamp_ref ${derived}`);
+            base.stampRefOk = false;
+        }
+        else {
+            seen.add(derived);
+        }
+    }
+    // --- the body itself ------------------------------------------------------
+    let body;
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            errors.push("stamp body is not a JSON object");
+            return base;
+        }
+        body = parsed;
+        // Re-canonicalize and compare. The plane replays these bytes verbatim on
+        // every submit attempt for exactly this reason: a non-canonical body makes
+        // a retry a DIFFERENT submission, and makes every independent re-derivation
+        // of the stamp disagree with the one that was witnessed.
+        if (jcs(body) !== new TextDecoder().decode(bytes)) {
+            errors.push("stamp_bytes are not JCS-canonical (RFC 8785)");
+            return base;
+        }
+    }
+    catch (err) {
+        errors.push(`stamp body is not JSON: ${stringifyErr(err)}`);
+        return base;
+    }
+    if (body.stamp_version !== STAMP_BODY_VERSION) {
+        // A `sanning.stamp.trace/v1` body whose inner version is something else is
+        // two answers to one question inside one signature. The body_type is the
+        // reader's dispatch key and it said v1; honouring the other spelling is
+        // how a reader half-parses a shape it does not know.
+        errors.push(`unsupported stamp_version ${JSON.stringify(body.stamp_version)} in a ` +
+            `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`);
+        return base;
+    }
+    base.stampVersion = body.stamp_version;
+    base.bodyOk = true;
+    for (const f of ["org_ref", "interval_start", "interval_end"]) {
+        if (typeof body[f] !== "string" || body[f] === "") {
+            errors.push(`stamp body ${f} is missing or not a non-empty string`);
+            base.bodyOk = false;
+        }
+    }
+    base.intervalStart = typeof body.interval_start === "string" ? body.interval_start : null;
+    base.intervalEnd = typeof body.interval_end === "string" ? body.interval_end : null;
+    if (!isLowerHex(body.merkle_root, 64)) {
+        errors.push("stamp body merkle_root is not 64 lowercase hex characters");
+        base.bodyOk = false;
+    }
+    else {
+        base.merkleRoot = body.merkle_root;
+    }
+    if (!isNonNegInt(body.leaf_count)) {
+        errors.push("stamp body leaf_count is not a non-negative integer");
+        base.bodyOk = false;
+    }
+    else {
+        base.leafCount = body.leaf_count;
+    }
+    // --- the sub-tree ranges --------------------------------------------------
+    base.subtreesOk = checkSubtrees(body, base, errors);
+    base.anchorRef = parseAnchorRef(e.anchor_ref, errors);
+    base.ok =
+        base.stampRefOk && base.bodyOk && base.subtreesOk && errors.length === 0;
+    return base;
+}
+/**
+ * The range arithmetic (§5.2), and the reason it is a hard check.
+ *
+ * `buildStampTree` orders a stamp's leaves agent-major, which is the only
+ * reason `first_leaf` + `leaf_count` can describe an agent's slice at all: the
+ * ranges partition `[0, leaf_count)` exactly, by construction. A body whose
+ * ranges do not is either not a stamp this stack built or one built wrong, and
+ * in both cases the per-agent claim the ranges exist to support is unfounded.
+ *
+ * The sum is checked BEFORE the tiling and reports its own message, so a body
+ * that is merely short does not get filed under a gap it does not have.
+ */
+function checkSubtrees(body, out, errors) {
+    const raw = body.subtrees;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push("stamp body subtrees is not an object");
+        return false;
+    }
+    let shapeOk = true;
+    const subtrees = [];
+    for (const [ref, v] of Object.entries(raw)) {
+        if (v === null || typeof v !== "object" || Array.isArray(v)) {
+            errors.push(`sub-tree ${ref} is not an object`);
+            shapeOk = false;
+            continue;
+        }
+        const s = v;
+        if (!isNonNegInt(s.first_leaf)) {
+            errors.push(`sub-tree ${ref} first_leaf is not a non-negative integer`);
+            shapeOk = false;
+        }
+        // A zero-leaf sub-tree is not a slice of anything, and admitting one lets
+        // an arbitrary number of empty ranges sit inside a tiling that still adds
+        // up.
+        if (!isNonNegInt(s.leaf_count) || s.leaf_count === 0) {
+            errors.push(`sub-tree ${ref} leaf_count is not a positive integer`);
+            shapeOk = false;
+        }
+        if (!isLowerHex(s.root, 64)) {
+            errors.push(`sub-tree ${ref} root is not 64 lowercase hex characters`);
+            shapeOk = false;
+        }
+        if (!shapeOk)
+            continue;
+        subtrees.push({
+            ref,
+            firstLeaf: s.first_leaf,
+            leafCount: s.leaf_count,
+            root: s.root,
+        });
+    }
+    subtrees.sort((a, b) => a.firstLeaf - b.firstLeaf);
+    out.subtrees = subtrees;
+    if (!shapeOk)
+        return false;
+    const total = body.leaf_count;
+    if (!isNonNegInt(total))
+        return false; // already reported by the caller
+    const sum = subtrees.reduce((n, s) => n + s.leafCount, 0);
+    if (sum !== total) {
+        errors.push(`sub-tree leaf_count sum ${sum} does not equal the stamp's leaf_count ${total}`);
+        return false;
+    }
+    let next = 0;
+    for (const s of subtrees) {
+        if (s.firstLeaf !== next) {
+            errors.push(`sub-tree ranges do not tile [0, ${total}): expected a range at leaf ` +
+                `${next}, found one at ${s.firstLeaf}`);
+            return false;
+        }
+        next += s.leafCount;
+    }
+    return true;
+}
+async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
+    const body = b.body;
+    if (!Array.isArray(body?.stamps)) {
+        return malformed(`${STAMP_TRACE_BODY_TYPE} body must have stamps[]`, true);
+    }
+    const seen = new Set();
+    const stamps = [];
+    for (const entry of body.stamps) {
+        stamps.push(await verifyStampEntry(entry, seen));
+    }
+    // --- Rollup ----------------------------------------------------------------
+    const anyHardFailure = stamps.some((s) => !s.ok);
+    const anyUnwitnessed = stamps.some((s) => s.anchorRef === null);
+    let status;
+    if (anyHardFailure) {
+        status = "failed";
+    }
+    else if (stamps.length === 0) {
+        // A bundle asserting nothing. Not a failure — nothing here is wrong — but
+        // it must never read `verified`, which a caller would take as a witness it
+        // does not have.
+        status = "partial";
+        errors.push(`${STAMP_TRACE_BODY_TYPE} body carries no stamps`);
+    }
+    else if (anyUnwitnessed) {
+        // The honest half of P-10, one layer up. A stamp with no `anchor_ref` is
+        // sealed and unwitnessed: `retained-by-sanning`, which is a statement about
+        // our coverage and never an accusation about their evidence. It is also not
+        // `verified`, because for a stamp the witness is the entire independent
+        // part — unlike an anchor-trace checkpoint, which still carries a producer
+        // signature and an inclusion proof that stand on their own offline.
+        status = "partial";
+        errors.push("one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody");
+    }
+    else {
+        status = "verified";
+    }
+    return {
+        status,
+        specVersionOk,
+        bodyHashOk: true,
+        signatureOk: true,
+        bodyType: STAMP_TRACE_BODY_TYPE,
+        onChainChecked: false,
+        checkpoints: [],
+        events: [],
+        assertedStatus,
+        stamps,
+        errors,
+    };
+}
 // How many `sanning.evidence.export/v1` wrappers deep the source bundle may be
 // nested before this path gives up. verifyEvidenceBundle's canonicalization
 // depth bound already rejects a pathological bundle, but the unwrap must be
@@ -489,7 +1026,7 @@ export async function disclosedContent(bundle, options = {}) {
     });
     const traceEvents = resolveTraceEvents(bundle);
     if (traceEvents === undefined) {
-        errors.push(`no ${ANCHOR_TRACE_BODY_TYPE} body to materialize content from ` +
+        errors.push(`no ${ANCHOR_TRACE_BODY_TYPES.join(" / ")} body to materialize content from ` +
             `(body_type ${JSON.stringify(verification.bodyType)})`);
         return empty();
     }
@@ -572,14 +1109,20 @@ export async function disclosedContent(bundle, options = {}) {
 // wrapper(s) to the inline source bundle — mirroring how verifyEvidenceBundle
 // recurses into `source_bundle`, so the events line up with its results.
 // `undefined` when there is no anchor-trace body to materialize from.
-function resolveTraceEvents(bundle) {
+//
+// Exported for `chain.ts`, which needs the same descent and must not derive it
+// again: two answers to "which events is this bundle actually about" inside one
+// kernel is two implementations of one rule, and the one that drifted would be
+// the one nobody was looking at. Deliberately NOT re-exported from `index.ts` —
+// same posture as `side-content.ts`, internal and shared.
+export function resolveTraceEvents(bundle) {
     let cur = bundle;
     for (let depth = 0; depth < MAX_EXPORT_UNWRAP; depth++) {
         if (cur === null || typeof cur !== "object" || Array.isArray(cur))
             return undefined;
         const b = cur;
         const bodyType = typeof b.body_type === "string" ? b.body_type : null;
-        if (bodyType === ANCHOR_TRACE_BODY_TYPE) {
+        if (bodyType === ANCHOR_TRACE_BODY_TYPE || bodyType === ANCHOR_TRACE_BODY_TYPE_V1) {
             const body = b.body;
             if (body === null || typeof body !== "object" || !Array.isArray(body.events))
                 return undefined;
@@ -672,15 +1215,8 @@ async function verifyExportBody(b, specVersionOk, assertedStatus, errors, option
     // (Ed25519 envelopes, payload binding, RFC 9162 inclusion, merkle roots,
     // content_ok, and the optional per-gateway on-chain re-fetch, §4.2 / step 7).
     const sourceResult = await verifyEvidenceBundle(inline, options);
-    // Map source checkpoints by tx_id for attestation data_hash binding (§5 6c).
-    const sourceCheckpoints = new Map();
-    const sb = inline.body;
-    if (sb && typeof sb === "object" && Array.isArray(sb.checkpoints)) {
-        for (const cp of sb.checkpoints) {
-            if (cp && typeof cp.tx_id === "string")
-                sourceCheckpoints.set(cp.tx_id, cp);
-        }
-    }
+    // Attestation data_hash binding (§5 6c).
+    const sourceCheckpoints = await indexSourceCheckpoints(inline);
     // --- Step 6: embedded attestation records ---------------------------------
     const attestations = [];
     for (const rec of body.attestations) {
@@ -772,16 +1308,9 @@ async function verifyExportBody(b, specVersionOk, assertedStatus, errors, option
 }
 export async function recomputeExportVerdict(sourceBundle, attestationRecords, generatedAt, options = {}) {
     const sourceResult = await verifyEvidenceBundle(sourceBundle, options);
-    // Map source checkpoints by tx_id for attestation data_hash binding (§5 6c) —
-    // identical to verifyExportBody's map construction.
-    const sourceCheckpoints = new Map();
-    const sb = sourceBundle.body;
-    if (sb && typeof sb === "object" && Array.isArray(sb.checkpoints)) {
-        for (const cp of sb.checkpoints) {
-            if (cp && typeof cp.tx_id === "string")
-                sourceCheckpoints.set(cp.tx_id, cp);
-        }
-    }
+    // Attestation data_hash binding (§5 6c) — the SAME index construction as
+    // verifyExportBody, deliberately shared rather than restated.
+    const sourceCheckpoints = await indexSourceCheckpoints(sourceBundle);
     const attestations = [];
     for (const rec of attestationRecords) {
         const r = await verifyAttestation(rec, sourceCheckpoints);
@@ -821,7 +1350,7 @@ export async function recomputeExportVerdict(sourceBundle, attestationRecords, g
 async function verifyAttestation(rec, sourceCheckpoints) {
     const errs = [];
     const result = {
-        checkpointTxId: rec && typeof rec.checkpoint_tx_id === "string" ? rec.checkpoint_tx_id : "",
+        checkpointRef: rec && typeof rec.checkpoint_ref === "string" ? rec.checkpoint_ref : "",
         operator: "",
         gateway: null,
         signatureOk: false,
@@ -894,10 +1423,10 @@ async function verifyAttestation(rec, sourceCheckpoints) {
     // uploaded JCS(envelope) bytes (the same bytes the on-chain re-fetch compares
     // against, §4.2), so the checkpoint's committed content hash is
     // SHA-256(JCS(checkpoint.envelope)).
-    const cp = sourceCheckpoints.get(result.checkpointTxId);
+    const cp = sourceCheckpoints.get(result.checkpointRef);
     result.checkpointResolved = cp !== undefined;
     if (!cp) {
-        errs.push(`attestation checkpoint_tx_id ${JSON.stringify(result.checkpointTxId)} resolves to no source checkpoint`);
+        errs.push(`attestation checkpoint_ref ${JSON.stringify(result.checkpointRef)} resolves to no source checkpoint`);
     }
     else {
         try {
@@ -949,7 +1478,7 @@ function evaluateSubjectRef(subjectRef, errs) {
 function buildVerdictObject(source, attestations) {
     const attByCheckpoint = new Map();
     for (const a of attestations) {
-        const list = attByCheckpoint.get(a.checkpointTxId) ?? [];
+        const list = attByCheckpoint.get(a.checkpointRef) ?? [];
         list.push({
             operator: a.operator,
             ...(a.gateway ? { gateway: a.gateway } : {}),
@@ -959,7 +1488,7 @@ function buildVerdictObject(source, attestations) {
             ...(a.level !== null ? { level: a.level } : {}),
             subject_ref_ok: a.subjectRefOk,
         });
-        attByCheckpoint.set(a.checkpointTxId, list);
+        attByCheckpoint.set(a.checkpointRef, list);
     }
     const events = source.events.map((e) => ({
         event_id: e.eventId,
@@ -970,10 +1499,10 @@ function buildVerdictObject(source, attestations) {
         status: eventVerdictStatus(e),
     }));
     const checkpoints = source.checkpoints.map((c) => ({
-        checkpoint_tx_id: c.txId,
+        checkpoint_ref: c.checkpointRef,
         merkle_root_ok: c.merkleRootOk,
         on_chain: c.onChain ? toVerdictOnChain(c.onChain) : null,
-        attestations: attByCheckpoint.get(c.txId) ?? [],
+        attestations: attByCheckpoint.get(c.checkpointRef) ?? [],
     }));
     let verified = 0;
     let failed = 0;
@@ -1044,7 +1573,7 @@ function projectVerdictForAgreement(v) {
             const cp = (c ?? {});
             const atts = Array.isArray(cp.attestations) ? cp.attestations : [];
             return {
-                checkpoint_tx_id: cp.checkpoint_tx_id ?? null,
+                checkpoint_ref: cp.checkpoint_ref ?? null,
                 merkle_root_ok: cp.merkle_root_ok ?? null,
                 // on_chain DELIBERATELY OMITTED — environment/time-dependent (see step 5).
                 attestations: atts.map((a) => {
@@ -1073,7 +1602,7 @@ function summarizeExport(status, source, attestations) {
 // records a per-gateway array so a confirm/mismatch/unreachable MIX across
 // gateways is preserved; the derived collapsed `onChainOk` reproduces the old
 // single-boolean exactly for a single gateway.
-async function refetchCheckpoint(cp, gateways, fetchImpl) {
+async function refetchCheckpoint(cp, anchorRef, gateways, fetchImpl) {
     let expectedHex;
     try {
         expectedHex = toHex(utf8(jcs(cp.envelope)));
@@ -1085,22 +1614,25 @@ async function refetchCheckpoint(cp, gateways, fetchImpl) {
     }
     const perGateway = [];
     for (const gw of gateways) {
-        perGateway.push({ gateway: gw, outcome: await probeGateway(cp, gw, expectedHex, fetchImpl) });
+        perGateway.push({
+            gateway: gw,
+            outcome: await probeGateway(anchorRef, gw, expectedHex, fetchImpl),
+        });
     }
     const onChain = rollupOnChain(perGateway);
     let error;
     if (onChain.rollup === "mismatch") {
-        error = `on-chain bytes at ${cp.tx_id} do not match the bundle's checkpoint envelope`;
+        error = `on-chain bytes at ${anchorRef.id} do not match the bundle's checkpoint envelope`;
     }
     else if (onChain.rollup === "unreachable") {
-        error = `checkpoint ${cp.tx_id} unreachable on all gateways`;
+        error = `checkpoint ${anchorRef.id} unreachable on all gateways`;
     }
     return { onChain, unavailable: onChain.rollup === "unreachable", error };
 }
 // One gateway's outcome for one checkpoint tx: confirm (bytes match), mismatch
 // (bytes disagree), or unreachable (no response / !ok / network error).
-async function probeGateway(cp, gateway, expectedHex, fetchImpl) {
-    const url = `${gateway.replace(/\/+$/, "")}/${cp.tx_id}`;
+async function probeGateway(anchorRef, gateway, expectedHex, fetchImpl) {
+    const url = `${gateway.replace(/\/+$/, "")}/${anchorRef.id}`;
     let resp;
     try {
         resp = await fetchImpl(url);
@@ -1154,6 +1686,14 @@ function getEventId(env) {
     }
     return "<unknown>";
 }
+// The side-input presence rule lives in `side-content.ts`, stated ONCE.
+//
+// It used to live here as a private `lookupSideContent`, and `grading.ts`
+// carried a second, laxer answer to the same question (`hasEntry`: own +
+// enumerable, nothing more). On one and the same content map the grader said
+// PRESENT while this verifier said nothing was offered, and `gradePack` then
+// returned `incomplete` with ZERO causes. Read `side-content.ts` for the rule
+// and for what each clause of it cost.
 function selectDisclosedBytes(ev, eventId, sideContent) {
     const errors = [];
     let inBody;
@@ -1166,19 +1706,33 @@ function selectDisclosedBytes(ev, eventId, sideContent) {
         }
     }
     let side;
-    const sideRaw = sideContent?.[eventId];
-    if (sideRaw instanceof Uint8Array) {
-        side = sideRaw;
+    const sideEntry = sideContentEntry(sideContent, eventId);
+    if (sideEntry.value instanceof Uint8Array) {
+        side = sideEntry.value;
     }
-    else if (typeof sideRaw === "string") {
+    else if (typeof sideEntry.value === "string") {
         try {
-            side = hexToBytes(sideRaw);
+            side = hexToBytes(sideEntry.value);
         }
         catch (e) {
             errors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
         }
     }
-    return { inBody, side, offered: ev.content !== undefined || sideRaw !== undefined, errors };
+    // `offered` comes from the SAME test that produced the value, never from
+    // `value !== undefined` — that is the conflation this whole guard exists to
+    // remove, and it was removed from ONE of the two operands. The left one
+    // carried it unchanged: an in-body `"content": null` is `!== undefined`, so
+    // the event was marked offered while no bytes were selected, and the kernel
+    // split against itself — `verifyEvidenceBundle` VERIFIED, `disclosedContent`
+    // FAILED, on one bundle. `null` is how an optional field's absence
+    // serializes; `inBodyContentOffered` states that once, beside the side-input
+    // rule it mirrors.
+    return {
+        inBody,
+        side,
+        offered: inBodyContentOffered(ev.content) || sideEntry.offered,
+        errors,
+    };
 }
 function toHex(bytes) {
     let out = "";