@sanning/proof 0.4.1 → 0.6.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,7 +27,21 @@ 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
@@ -149,12 +164,12 @@ export async function verifyEvidenceBundle(bundle, options = {}) {
     if (bodyType === EXPORT_BODY_TYPE) {
         return verifyExportBody(b, specVersionOk, assertedStatus, errors, options);
     }
-    if (bodyType !== ANCHOR_TRACE_BODY_TYPE) {
+    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 +185,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 +355,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 +400,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 +446,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
@@ -341,29 +531,12 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
                     committed.push(c.hash.toLowerCase());
             }
             // Disclosed bytes, precedence: in-body (signed) → side input. A string
-            // side input is hex; a Uint8Array is used as-is.
-            let inBody;
-            if (typeof ev.content === "string") {
-                try {
-                    inBody = hexToBytes(ev.content);
-                }
-                catch (e) {
-                    evErrors.push(`event content is not hex: ${stringifyErr(e)}`);
-                }
-            }
-            let side;
-            const sideRaw = options.content?.[eventId];
-            if (sideRaw instanceof Uint8Array) {
-                side = sideRaw;
-            }
-            else if (typeof sideRaw === "string") {
-                try {
-                    side = hexToBytes(sideRaw);
-                }
-                catch (e) {
-                    evErrors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
-                }
-            }
+            // side input is hex; a Uint8Array is used as-is. Resolved by the SHARED
+            // selector so `disclosedContent` hands a consumer the very bytes bound
+            // here — one decode, not two that can drift apart.
+            const selection = selectDisclosedBytes(ev, eventId, options.content);
+            const { inBody, side } = selection;
+            evErrors.push(...selection.errors);
             if (inBody !== undefined && side !== undefined && !bytesEqual(inBody, side)) {
                 // Two disclosures that disagree: a genuine conflict, not undetermined.
                 contentOk = false;
@@ -414,10 +587,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)
@@ -473,6 +663,144 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
         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
+// independently bounded rather than trusting that it ran first.
+const MAX_EXPORT_UNWRAP = 4;
+/**
+ * Materialize the disclosed raw bytes of a received bundle (evidence-bundle §5.1).
+ *
+ * Verify-then-return: the bundle is verified with {@link verifyEvidenceBundle}
+ * (same options — gateways, out-of-band `content`, `fetchImpl`), and an event's
+ * bytes are returned ONLY when that verification bound them to the committed
+ * `content_hash`. There is no path through this function that yields bytes
+ * whose SHA-256 is not the commitment.
+ *
+ * Returns `Uint8Array`, never a string: the spec commits to raw bytes, and a
+ * UTF-8 decode is lossy for any payload that is not valid UTF-8 — re-encoding
+ * such a string would produce different bytes and a different hash. Callers who
+ * know their payload is text decode it themselves and own that assumption.
+ */
+export async function disclosedContent(bundle, options = {}) {
+    const verification = await verifyEvidenceBundle(bundle, options);
+    const events = [];
+    const content = new Map();
+    const errors = [];
+    const empty = () => ({
+        status: verification.status,
+        verification,
+        events: [],
+        content: new Map(),
+        errors: [...errors, ...verification.errors],
+    });
+    const traceEvents = resolveTraceEvents(bundle);
+    if (traceEvents === undefined) {
+        errors.push(`no ${ANCHOR_TRACE_BODY_TYPES.join(" / ")} body to materialize content from ` +
+            `(body_type ${JSON.stringify(verification.bodyType)})`);
+        return empty();
+    }
+    // Fail closed on any drift between the body we are decoding and the results
+    // we are trusting. Both must be the same events in the same order, or the
+    // "these bytes are the bytes that verified" guarantee is void — which is the
+    // only guarantee this function makes. A broken wrapper lands here too:
+    // verifyEvidenceBundle returns zero event results, so nothing is emitted.
+    if (traceEvents.length !== verification.events.length) {
+        errors.push("the bundle did not verify far enough to materialize content: " +
+            `${verification.events.length} verified event result(s) for ${traceEvents.length} body event(s)`);
+        return empty();
+    }
+    for (let i = 0; i < traceEvents.length; i++) {
+        const te = traceEvents[i];
+        const envelope = te !== null && typeof te === "object" ? te.envelope : undefined;
+        if (getEventId(envelope) !== verification.events[i].eventId) {
+            errors.push(`event alignment drift at index ${i}: the body event and its verification result ` +
+                "are not the same event; refusing to hand back any content");
+            return empty();
+        }
+    }
+    for (let i = 0; i < traceEvents.length; i++) {
+        const ev = traceEvents[i];
+        const res = verification.events[i];
+        const selection = selectDisclosedBytes(ev, res.eventId, options.content);
+        const bytes = selection.inBody ?? selection.side;
+        const evErrors = [];
+        let status;
+        if (!res.ok || res.contentOk === false) {
+            // The event itself is not trustworthy (bad signature, broken inclusion,
+            // unbound checkpoint) or its disclosure contradicts the commitment.
+            status = "failed";
+            evErrors.push(res.contentOk === false
+                ? "disclosed content does not bind to the committed content_hash — withheld"
+                : "the event's own proof chain did not verify — nothing here is safe to materialize");
+            evErrors.push(...res.errors);
+        }
+        else if (!selection.offered) {
+            // Minimal disclosure: the committed hash is there, the bytes are not.
+            // Distinct from empty bytes, and never an error.
+            status = "not_disclosed";
+        }
+        else if (bytes === undefined) {
+            status = "failed";
+            evErrors.push("content was disclosed for this event but is not a decodable lowercase-hex string");
+            evErrors.push(...selection.errors);
+        }
+        else if (res.contentOk !== true) {
+            // Disclosed and decodable, but there is no commitment to check it against
+            // (withheld record, or a record committing no content_hash). Unbound
+            // bytes are exactly what a consumer must not silently write out.
+            status = "undetermined";
+            evErrors.push("disclosed bytes are not bound to any committed content_hash — withheld rather than returned");
+            evErrors.push(...res.errors);
+        }
+        else {
+            status = "verified";
+        }
+        const verified = status === "verified" && bytes !== undefined;
+        if (verified) {
+            if (content.has(res.eventId)) {
+                errors.push(`duplicate event_id ${JSON.stringify(res.eventId)}: the content map keeps the first ` +
+                    "occurrence — read events[] for every event");
+            }
+            else {
+                content.set(res.eventId, bytes);
+            }
+        }
+        events.push({
+            eventId: res.eventId,
+            status,
+            bytes: verified ? bytes : null,
+            errors: evErrors,
+        });
+    }
+    return { status: verification.status, verification, events, content, errors };
+}
+// The anchor-trace events a bundle carries, unwrapping any evidence-export
+// 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) {
+    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 || bodyType === ANCHOR_TRACE_BODY_TYPE_V1) {
+            const body = b.body;
+            if (body === null || typeof body !== "object" || !Array.isArray(body.events))
+                return undefined;
+            return body.events;
+        }
+        if (bodyType !== EXPORT_BODY_TYPE)
+            return undefined;
+        const body = b.body;
+        if (body === null || typeof body !== "object")
+            return undefined;
+        cur = body.source_bundle;
+    }
+    return undefined;
+}
 // ===========================================================================
 // Attested-evidence-export verification (evidence-export.md §5, steps 3–9).
 // Reached from verifyEvidenceBundle AFTER the wrapper (Ed25519 issuer signature
@@ -551,15 +879,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) {
@@ -651,16 +972,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);
@@ -700,7 +1014,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,
@@ -773,10 +1087,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 {
@@ -828,7 +1142,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 } : {}),
@@ -838,7 +1152,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,
@@ -849,10 +1163,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;
@@ -923,7 +1237,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) => {
@@ -952,7 +1266,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)));
@@ -964,22 +1278,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);
@@ -1033,6 +1350,54 @@ 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;
+    if (typeof ev.content === "string") {
+        try {
+            inBody = hexToBytes(ev.content);
+        }
+        catch (e) {
+            errors.push(`event content is not hex: ${stringifyErr(e)}`);
+        }
+    }
+    let side;
+    const sideEntry = sideContentEntry(sideContent, eventId);
+    if (sideEntry.value instanceof Uint8Array) {
+        side = sideEntry.value;
+    }
+    else if (typeof sideEntry.value === "string") {
+        try {
+            side = hexToBytes(sideEntry.value);
+        }
+        catch (e) {
+            errors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
+        }
+    }
+    // `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 = "";
     for (const x of bytes)