@sanning/proof 0.5.0 → 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
@@ -397,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)
@@ -489,7 +696,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();
     }
@@ -579,7 +786,7 @@ function resolveTraceEvents(bundle) {
             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 +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) {
@@ -772,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);
@@ -821,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,
@@ -894,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 {
@@ -949,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 } : {}),
@@ -959,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,
@@ -970,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;
@@ -1044,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) => {
@@ -1073,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)));
@@ -1085,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);
@@ -1154,6 +1350,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 +1370,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 = "";