@sanning/proof 0.8.0 → 0.8.1

package/dist/cli.js

@@ -610,6 +610,31 @@ function reportEvidence(result, path, gateways, io, chains) {
                 io.out(paint(`        - ${e}`, R));
         }
     }
+    // Stamps (evidence-bundle.md §5.2 / §5.3). Printed rather than summarised,
+    // because for a stamp body the WITNESS is the entire independent part
+    // (§5.2.4) — and until now this reporter showed nothing about it at all, so a
+    // §5.3 pack printed a rollup line claiming an on-chain scope with no visible
+    // on-chain result anywhere above it.
+    //
+    // The on-chain column distinguishes all four states in the same three
+    // characters the checkpoint block uses, plus its absence: `✓` confirmed,
+    // `✗` mismatched, `~` asked and unreachable, and NO COLUMN AT ALL when
+    // nothing was checked. A reader must never have to infer "not checked" from
+    // a symbol that also means "could not be reached".
+    if (result.stamps && result.stamps.length > 0) {
+        io.out("");
+        io.out(paint("  Stamps", DIM));
+        for (const st of result.stamps) {
+            const witness = st.anchorRef === null
+                ? paint("~ no witness", Y)
+                : `witness ${st.anchorRef.kind}:${shortTx(st.anchorRef.id)}`;
+            const onChain = st.onChain === null ? "" : `  on-chain ${mark(st.onChainOk)} (${st.onChain.rollup})`;
+            io.out(`    ${mark(st.ok)} ${shortTx(st.stampRef)}  bytes ${mark(st.stampRefOk && st.bodyOk)}` +
+                `  ranges ${mark(st.subtreesOk)}  ${witness}${onChain}`);
+            for (const e of st.errors)
+                io.out(paint(`        - ${e}`, R));
+        }
+    }
     if (result.events.length > 0) {
         io.out("");
         io.out(paint("  Events", DIM));

package/dist/evidence.d.ts

@@ -292,6 +292,35 @@ export interface StampResult {
      * carries it.
      */
     anchorRef: AnchorRef | null;
+    /**
+     * Per-gateway on-chain outcomes for this stamp's `anchor_ref` (§4.2's shape,
+     * `checkpoints[]`'s vocabulary), or `null` when NOTHING WAS CHECKED.
+     *
+     * ── The four states, and why none of them collapses ──
+     *
+     * `null` means not checked — no gateways were supplied, or this stamp names
+     * no witness to check. It is a statement about the RUN, never about the
+     * stamp. The other three are statements about the stamp and live in
+     * `onChain.rollup`: `confirm` (a gateway returned the witnessed bytes),
+     * `mismatch` (a gateway returned DIFFERENT bytes — a finding, and the only
+     * one of the four that fails anything), `unreachable` (we asked and nobody
+     * answered — an availability gap, never an accusation).
+     *
+     * Keeping "not checked" distinct from "unreachable" is the whole point. A
+     * surface handed a collapsed boolean cannot tell "no gateway could be
+     * reached" from "no gateway was tried", and reported the first when the
+     * second was true — a false accusation manufactured by a missing state.
+     */
+    onChain: OnChainResult | null;
+    /**
+     * Derived collapse of `onChain`, mirroring `CheckpointResult.onChainOk` so a
+     * consumer reads one field the same way on both: `false` on mismatch, `true`
+     * on confirm, `null` on unreachable AND on not-checked.
+     *
+     * It is deliberately the LOSSY view — `null` is three-quarters of the state
+     * space here. Anything that needs to tell those apart reads `onChain`.
+     */
+    onChainOk: boolean | null;
     ok: boolean;
     errors: string[];
 }

package/dist/evidence.js

@@ -194,7 +194,7 @@ export async function verifyEvidenceBundle(bundle, options = {}) {
     // 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);
+        return verifyStampTrace(b, specVersionOk, assertedStatus, errors, options);
     }
     // The DL-52 hand-over body (§5.3): stamps AND the customer's events, joined.
     if (bodyType === STAMP_EVIDENCE_BODY_TYPE) {
@@ -768,18 +768,20 @@ async function verifyStampEntry(raw, seen) {
         subtreesOk: false,
         subtrees: [],
         anchorRef: null,
+        onChain: null,
+        onChainOk: null,
         ok: false,
         errors,
     };
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
         errors.push("stamp entry is not an object");
-        return base;
+        return { result: 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;
+        return { result: base };
     }
     let bytes;
     try {
@@ -787,8 +789,11 @@ async function verifyStampEntry(raw, seen) {
     }
     catch (err) {
         errors.push(`stamp_bytes is not hex: ${stringifyErr(err)}`);
-        return base;
+        return { result: base };
     }
+    // Gated by `isLowerHex` above, so this is already the exact lowercase hex of
+    // the exact witnessed bytes — §5.2.2's "one authority in this body".
+    const witnessedHex = e.stamp_bytes;
     // --- the derived identity -------------------------------------------------
     const derived = await sha256Hex(bytes);
     if (typeof e.stamp_ref !== "string" || e.stamp_ref === "") {
@@ -818,7 +823,7 @@ async function verifyStampEntry(raw, seen) {
         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;
+            return { result: base, witnessedHex };
         }
         body = parsed;
         // Re-canonicalize and compare. The plane replays these bytes verbatim on
@@ -827,12 +832,12 @@ async function verifyStampEntry(raw, seen) {
         // 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;
+            return { result: base, witnessedHex };
         }
     }
     catch (err) {
         errors.push(`stamp body is not JSON: ${stringifyErr(err)}`);
-        return base;
+        return { result: base, witnessedHex };
     }
     if (body.stamp_version !== STAMP_BODY_VERSION) {
         // A `sanning.stamp.trace/v1` body whose inner version is something else is
@@ -841,7 +846,7 @@ async function verifyStampEntry(raw, seen) {
         // 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;
+        return { result: base, witnessedHex };
     }
     base.stampVersion = body.stamp_version;
     base.bodyOk = true;
@@ -872,7 +877,7 @@ async function verifyStampEntry(raw, seen) {
     base.anchorRef = parseAnchorRef(e.anchor_ref, errors);
     base.ok =
         base.stampRefOk && base.bodyOk && base.subtreesOk && errors.length === 0;
-    return base;
+    return { result: base, witnessedHex };
 }
 /**
  * The range arithmetic (§5.2), and the reason it is a hard check.
@@ -948,16 +953,27 @@ function checkSubtrees(body, out, errors) {
     }
     return true;
 }
-async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
+async function verifyStampTrace(b, specVersionOk, assertedStatus, errors, options) {
     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 = [];
+    const witnessed = [];
     for (const entry of body.stamps) {
-        stamps.push(await verifyStampEntry(entry, seen));
+        const outcome = await verifyStampEntry(entry, seen);
+        stamps.push(outcome.result);
+        witnessed.push(outcome.witnessedHex);
     }
+    // --- The optional on-chain re-fetch (§5.2.4's "online act") ---------------
+    //
+    // The SAME stamps[] array §5.3 carries, so it gets the same capability. The
+    // alternative — a stamp that can be re-fetched inside one body and not the
+    // other — asks every consumer to remember which wrapper it is holding before
+    // it can trust `onChain: null`, and that is exactly the kind of per-body
+    // exception a reader eventually gets wrong.
+    const { onChainChecked, gatewayUnavailable } = await refetchStamps(stamps, witnessed, options, errors);
     // --- Rollup ----------------------------------------------------------------
     const anyHardFailure = stamps.some((s) => !s.ok);
     const anyUnwitnessed = stamps.some((s) => s.anchorRef === null);
@@ -972,15 +988,23 @@ async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
         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.
+    else if (gatewayUnavailable || anyUnwitnessed) {
+        // Both hold the bundle at `partial`, and both get said — see §5.3's rollup
+        // for why one note is not enough when there are two different gaps.
         status = "partial";
-        errors.push("one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody");
+        if (gatewayUnavailable) {
+            errors.push("one or more stamps could not be re-fetched from the supplied gateways");
+        }
+        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.
+            errors.push("one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody");
+        }
     }
     else {
         status = "verified";
@@ -991,7 +1015,7 @@ async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
         bodyHashOk: true,
         signatureOk: true,
         bodyType: STAMP_TRACE_BODY_TYPE,
-        onChainChecked: false,
+        onChainChecked,
         checkpoints: [],
         events: [],
         assertedStatus,
@@ -1022,8 +1046,12 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
     // --- The stamp half: §5.2's rules, §5.2's code ----------------------------
     const seen = new Set();
     const stamps = [];
-    for (const entry of body.stamps)
-        stamps.push(await verifyStampEntry(entry, seen));
+    const witnessed = [];
+    for (const entry of body.stamps) {
+        const outcome = await verifyStampEntry(entry, seen);
+        stamps.push(outcome.result);
+        witnessed.push(outcome.witnessedHex);
+    }
     // The join table. ONLY a stamp whose derived ref and witnessed bytes both
     // checked out is joinable: a root read out of bytes that failed their own
     // verification is not a root anyone should walk a proof to, and admitting one
@@ -1153,6 +1181,8 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
             errors: evErrors,
         });
     }
+    // --- The optional on-chain re-fetch (§5.2.4's "online act") ---------------
+    const { onChainChecked, gatewayUnavailable } = await refetchStamps(stamps, witnessed, options, errors);
     // --- Rollup ---------------------------------------------------------------
     // Rule 4: a declared event MUST be checked. `events[]` present and unverified
     // is the false green this body exists to prevent, so an event that did not
@@ -1167,11 +1197,21 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
         status = "partial";
         errors.push(`${STAMP_EVIDENCE_BODY_TYPE} body carries no stamps and no events`);
     }
-    else if (anyUnwitnessed) {
-        // §5.3.3 rule 6, inherited whole from §5.2.4: for a stamp the witness IS
-        // the independent part, so the events resting on it inherit `partial`.
+    else if (gatewayUnavailable || anyUnwitnessed) {
+        // Both hold the bundle at `partial`, and BOTH get said. A stamp nobody
+        // witnessed and a witness we could not reach are different gaps with
+        // different fixes — one waits for the interval, the other for the network —
+        // and an auditor told only about the second would read the first as fine.
+        // The order is fixed so the two kernels emit the same list.
         status = "partial";
-        errors.push("one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody");
+        if (gatewayUnavailable) {
+            errors.push("one or more stamps could not be re-fetched from the supplied gateways");
+        }
+        if (anyUnwitnessed) {
+            // §5.3.3 rule 6, inherited whole from §5.2.4: for a stamp the witness IS
+            // the independent part, so the events resting on it inherit `partial`.
+            errors.push("one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody");
+        }
     }
     else {
         status = "verified";
@@ -1182,7 +1222,7 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
         bodyHashOk: true,
         signatureOk: true,
         bodyType: STAMP_EVIDENCE_BODY_TYPE,
-        onChainChecked: false,
+        onChainChecked,
         checkpoints: [],
         events: eventResults,
         assertedStatus,
@@ -1190,6 +1230,78 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
         errors,
     };
 }
+/**
+ * The optional on-chain re-fetch over `stamps[]`, shared by §5.2 and §5.3.
+ *
+ * ── Why the results land on `stamps[]` and `checkpoints` stays empty ──
+ *
+ * A stamp body carries no checkpoints. Synthesising `CheckpointResult`s to
+ * carry these outcomes would make a stamp indistinguishable from a checkpoint
+ * in every consumer that reads `checkpoints[]` — the exact conflation §5.2.1
+ * and §5.3.1 refused twice, most sharply in "a Sanning attestation
+ * indistinguishable on the wire from a producer's". They are different
+ * artifacts with different signers and different meanings when absent, and a
+ * reader must never have to guess which one it is holding. So the stamp
+ * results go on the stamps, and `checkpoints: []` keeps saying the true thing:
+ * this body has none.
+ *
+ * ── Why an unwitnessed stamp gets `onChain: null` and NOT all-unreachable ──
+ *
+ * The anchor-trace path synthesises an all-`unreachable` result for a
+ * checkpoint with no `anchor_ref`. That is not copied here, for two reasons.
+ *
+ * It would be untrue: nothing was asked of any gateway, so reporting that
+ * every gateway failed to answer invents a network event. "Not checked" and
+ * "we asked and nobody answered" are different facts, and collapsing them is
+ * precisely the defect that had a surface reporting an unreachable gateway
+ * when it had contacted none.
+ *
+ * And it would be load-bearing in the wrong direction. Over there the
+ * synthesis exists to drive `gatewayUnavailable`, which is what downgrades that
+ * run to `partial`. Here §5.2.4 already downgrades an unwitnessed stamp to
+ * `partial` on its own, with a better error. Copying the synthesis would add
+ * nothing to the status and would silently move the CLI exit code from 0 to 3
+ * for an unwitnessed stamp — changing what an auditor's script does, based on
+ * nothing but whether the caller happened to pass a gateway list.
+ */
+async function refetchStamps(stamps, witnessed, options, errors) {
+    const gateways = options.gateways ?? [];
+    const onChainChecked = gateways.length > 0;
+    if (!onChainChecked)
+        return { onChainChecked, gatewayUnavailable: false };
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        errors.push("on-chain re-fetch requested but no fetch implementation is available");
+        return { onChainChecked, gatewayUnavailable: true };
+    }
+    let gatewayUnavailable = false;
+    for (let i = 0; i < stamps.length; i++) {
+        const st = stamps[i];
+        const witnessedHex = witnessed[i];
+        // No witness named, or bytes we could not read: nothing to re-fetch, and
+        // nothing a gateway could confirm or deny. Left as `onChain: null`.
+        if (st.anchorRef === null || witnessedHex === undefined)
+            continue;
+        const outcome = await refetchStamp(witnessedHex, st.anchorRef, gateways, fetchImpl);
+        st.onChain = outcome.onChain;
+        st.onChainOk = outcome.onChain.onChainOk;
+        if (outcome.unavailable)
+            gatewayUnavailable = true;
+        if (outcome.error)
+            st.errors.push(outcome.error);
+        // Fold the on-chain dimension in exactly as a checkpoint does: a MISMATCH
+        // (false) fails the stamp — the chain does not hold what the bundle says
+        // was witnessed. UNREACHABLE (null) leaves an offline-sound stamp ok and
+        // downgrades the run to `partial` via gatewayUnavailable. A confirm (true)
+        // changes nothing that was not already true offline.
+        //
+        // `st.ok` is kept and narrowed rather than recomputed: its offline form
+        // includes `errors.length === 0`, and re-evaluating that AFTER pushing an
+        // unreachable note would fail a stamp for a gateway being down.
+        st.ok = st.ok && st.onChainOk !== false;
+    }
+    return { onChainChecked, gatewayUnavailable };
+}
 // 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
@@ -1802,6 +1914,10 @@ function summarizeExport(status, source, attestations) {
 async function refetchCheckpoint(cp, anchorRef, gateways, fetchImpl) {
     let expectedHex;
     try {
+        // A checkpoint's witnessed bytes are its envelope RE-CANONICALIZED. The
+        // bundle carries the envelope as a JSON object, not as bytes, so what was
+        // uploaded has to be recomputed from it. See `refetchStamp` for the case
+        // where this step is not merely unnecessary but WRONG.
         expectedHex = toHex(utf8(jcs(cp.envelope)));
     }
     catch {
@@ -1809,6 +1925,41 @@ async function refetchCheckpoint(cp, anchorRef, gateways, fetchImpl) {
         // (we can never confirm bytes we cannot compute).
         expectedHex = undefined;
     }
+    return refetchAnchored("checkpoint", expectedHex, anchorRef, gateways, fetchImpl);
+}
+// Re-fetch a STAMP's witnessed bytes (evidence-bundle.md §5.2.2 / §5.3.2).
+//
+// ── The one step this path must NOT copy from the checkpoint path ──
+//
+// `refetchCheckpoint` recomputes `JCS(envelope)` because a checkpoint's
+// witnessed bytes are not in the bundle — only the object they were derived
+// from is. A stamp is the opposite case: §5.2.2 defines `stamp_bytes` as
+// "lowercase hex of the exact JCS bytes that were handed to the witness", and
+// §5.3.2 repeats it — *"the EXACT bytes that were witnessed, verbatim"*. They
+// are already the bytes, already hex, already lowercase (`isLowerHex` gated
+// them), and `stamp_ref` is their SHA-256.
+//
+// So the expected hex IS `stamp_bytes`, and re-canonicalizing would be a
+// defect, not a redundancy: it would compare the chain against bytes NOBODY
+// SIGNED. On a canonical body the two agree and the bug hides; on a body that
+// is not canonical — the exact case §5.2.2 makes the kernel check for, because
+// the plane replays these bytes as text precisely so a normalizing serializer
+// cannot alter them — a re-canonicalizing verifier reports `mismatch` against
+// a chain that faithfully holds what it was given. A false accusation, from
+// the verifier, about untampered evidence.
+//
+// The bytes handed here are the SAME value `verifyStampEntry` hashed to derive
+// `stamp_ref`, threaded through rather than re-read from the body, so the bytes
+// graded and the bytes compared cannot drift apart.
+async function refetchStamp(witnessedHex, anchorRef, gateways, fetchImpl) {
+    return refetchAnchored("stamp", witnessedHex, anchorRef, gateways, fetchImpl);
+}
+// The part both paths share: probe every gateway, roll the outcomes up under
+// the ONE rule (`rollupOnChain`), and phrase the finding. Extracted rather than
+// copied — a second rollup rule is a second place for "mismatch beats confirm
+// beats unreachable" to drift, and the drifted copy is the one nobody reads.
+// The subject only ever selects wording; it never changes a verdict.
+async function refetchAnchored(subject, expectedHex, anchorRef, gateways, fetchImpl) {
     const perGateway = [];
     for (const gw of gateways) {
         perGateway.push({
@@ -1819,10 +1970,13 @@ async function refetchCheckpoint(cp, anchorRef, gateways, fetchImpl) {
     const onChain = rollupOnChain(perGateway);
     let error;
     if (onChain.rollup === "mismatch") {
-        error = `on-chain bytes at ${anchorRef.id} do not match the bundle's checkpoint envelope`;
+        error =
+            subject === "checkpoint"
+                ? `on-chain bytes at ${anchorRef.id} do not match the bundle's checkpoint envelope`
+                : `on-chain bytes at ${anchorRef.id} do not match the stamp's witnessed bytes`;
     }
     else if (onChain.rollup === "unreachable") {
-        error = `checkpoint ${anchorRef.id} unreachable on all gateways`;
+        error = `${subject} ${anchorRef.id} unreachable on all gateways`;
     }
     return { onChain, unavailable: onChain.rollup === "unreachable", error };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1, sanning.mlflow/v1, sanning.events/v1. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -697,6 +697,35 @@ function reportEvidence(
     }
   }
 
+  // Stamps (evidence-bundle.md §5.2 / §5.3). Printed rather than summarised,
+  // because for a stamp body the WITNESS is the entire independent part
+  // (§5.2.4) — and until now this reporter showed nothing about it at all, so a
+  // §5.3 pack printed a rollup line claiming an on-chain scope with no visible
+  // on-chain result anywhere above it.
+  //
+  // The on-chain column distinguishes all four states in the same three
+  // characters the checkpoint block uses, plus its absence: `✓` confirmed,
+  // `✗` mismatched, `~` asked and unreachable, and NO COLUMN AT ALL when
+  // nothing was checked. A reader must never have to infer "not checked" from
+  // a symbol that also means "could not be reached".
+  if (result.stamps && result.stamps.length > 0) {
+    io.out("");
+    io.out(paint("  Stamps", DIM));
+    for (const st of result.stamps) {
+      const witness =
+        st.anchorRef === null
+          ? paint("~ no witness", Y)
+          : `witness ${st.anchorRef.kind}:${shortTx(st.anchorRef.id)}`;
+      const onChain =
+        st.onChain === null ? "" : `  on-chain ${mark(st.onChainOk)} (${st.onChain.rollup})`;
+      io.out(
+        `    ${mark(st.ok)} ${shortTx(st.stampRef)}  bytes ${mark(st.stampRefOk && st.bodyOk)}` +
+          `  ranges ${mark(st.subtreesOk)}  ${witness}${onChain}`,
+      );
+      for (const e of st.errors) io.out(paint(`        - ${e}`, R));
+    }
+  }
+
   if (result.events.length > 0) {
     io.out("");
     io.out(paint("  Events", DIM));

package/src/evidence.ts

@@ -428,6 +428,35 @@ export interface StampResult {
    * carries it.
    */
   anchorRef: AnchorRef | null;
+  /**
+   * Per-gateway on-chain outcomes for this stamp's `anchor_ref` (§4.2's shape,
+   * `checkpoints[]`'s vocabulary), or `null` when NOTHING WAS CHECKED.
+   *
+   * ── The four states, and why none of them collapses ──
+   *
+   * `null` means not checked — no gateways were supplied, or this stamp names
+   * no witness to check. It is a statement about the RUN, never about the
+   * stamp. The other three are statements about the stamp and live in
+   * `onChain.rollup`: `confirm` (a gateway returned the witnessed bytes),
+   * `mismatch` (a gateway returned DIFFERENT bytes — a finding, and the only
+   * one of the four that fails anything), `unreachable` (we asked and nobody
+   * answered — an availability gap, never an accusation).
+   *
+   * Keeping "not checked" distinct from "unreachable" is the whole point. A
+   * surface handed a collapsed boolean cannot tell "no gateway could be
+   * reached" from "no gateway was tried", and reported the first when the
+   * second was true — a false accusation manufactured by a missing state.
+   */
+  onChain: OnChainResult | null;
+  /**
+   * Derived collapse of `onChain`, mirroring `CheckpointResult.onChainOk` so a
+   * consumer reads one field the same way on both: `false` on mismatch, `true`
+   * on confirm, `null` on unreachable AND on not-checked.
+   *
+   * It is deliberately the LOSSY view — `null` is three-quarters of the state
+   * space here. Anything that needs to tell those apart reads `onChain`.
+   */
+  onChainOk: boolean | null;
   ok: boolean;
   errors: string[];
 }
@@ -749,7 +778,7 @@ export async function verifyEvidenceBundle(
   // 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);
+    return verifyStampTrace(b, specVersionOk, assertedStatus, errors, options);
   }
 
   // The DL-52 hand-over body (§5.3): stamps AND the customer's events, joined.
@@ -1365,10 +1394,29 @@ async function verifyDisclosedContent(
   return { contentOk, errors: evErrors };
 }
 
+/**
+ * One `stamps[]` entry's result, plus the witnessed bytes it was graded on.
+ *
+ * `witnessedHex` is internal and never surfaces on `StampResult`: it is the
+ * whole stamp body again, and putting it back on the result would double every
+ * serialized verdict to carry a copy of what the bundle already holds. It
+ * exists so the optional on-chain re-fetch compares the chain against THE SAME
+ * BYTES this function hashed to derive `stamp_ref`, rather than re-reading
+ * `stamp_bytes` out of the body a second time — one value, so the graded bytes
+ * and the compared bytes cannot come apart.
+ *
+ * Undefined exactly when `stamp_bytes` was unusable, in which case the entry
+ * has already failed and there is nothing a gateway could confirm.
+ */
+interface StampEntryOutcome {
+  result: StampResult;
+  witnessedHex?: string;
+}
+
 async function verifyStampEntry(
   raw: unknown,
   seen: Set<string>,
-): Promise<StampResult> {
+): Promise<StampEntryOutcome> {
   const errors: string[] = [];
   const base: StampResult = {
     stampRef: "",
@@ -1382,28 +1430,33 @@ async function verifyStampEntry(
     subtreesOk: false,
     subtrees: [],
     anchorRef: null,
+    onChain: null,
+    onChainOk: null,
     ok: false,
     errors,
   };
 
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
     errors.push("stamp entry is not an object");
-    return base;
+    return { result: base };
   }
   const e = raw as Partial<StampEntry> & Record<string, unknown>;
 
   // --- 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;
+    return { result: base };
   }
   let bytes: Uint8Array;
   try {
     bytes = hexToBytes(e.stamp_bytes);
   } catch (err) {
     errors.push(`stamp_bytes is not hex: ${stringifyErr(err)}`);
-    return base;
+    return { result: base };
   }
+  // Gated by `isLowerHex` above, so this is already the exact lowercase hex of
+  // the exact witnessed bytes — §5.2.2's "one authority in this body".
+  const witnessedHex: string = e.stamp_bytes;
 
   // --- the derived identity -------------------------------------------------
   const derived = await sha256Hex(bytes);
@@ -1434,7 +1487,7 @@ async function verifyStampEntry(
     const parsed: unknown = 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;
+      return { result: base, witnessedHex };
     }
     body = parsed as StampBody;
     // Re-canonicalize and compare. The plane replays these bytes verbatim on
@@ -1443,11 +1496,11 @@ async function verifyStampEntry(
     // of the stamp disagree with the one that was witnessed.
     if (jcs(body as unknown as Record<string, unknown>) !== new TextDecoder().decode(bytes)) {
       errors.push("stamp_bytes are not JCS-canonical (RFC 8785)");
-      return base;
+      return { result: base, witnessedHex };
     }
   } catch (err) {
     errors.push(`stamp body is not JSON: ${stringifyErr(err)}`);
-    return base;
+    return { result: base, witnessedHex };
   }
 
   if (body.stamp_version !== STAMP_BODY_VERSION) {
@@ -1459,7 +1512,7 @@ async function verifyStampEntry(
       `unsupported stamp_version ${JSON.stringify(body.stamp_version)} in a ` +
         `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`,
     );
-    return base;
+    return { result: base, witnessedHex };
   }
   base.stampVersion = body.stamp_version;
   base.bodyOk = true;
@@ -1493,7 +1546,7 @@ async function verifyStampEntry(
 
   base.ok =
     base.stampRefOk && base.bodyOk && base.subtreesOk && errors.length === 0;
-  return base;
+  return { result: base, witnessedHex };
 }
 
 /**
@@ -1581,6 +1634,7 @@ async function verifyStampTrace(
   specVersionOk: boolean,
   assertedStatus: string | null,
   errors: string[],
+  options: VerifyEvidenceOptions,
 ): Promise<EvidenceBundleResult> {
   const body = b.body as StampTraceBody;
   if (!Array.isArray(body?.stamps)) {
@@ -1589,10 +1643,27 @@ async function verifyStampTrace(
 
   const seen = new Set<string>();
   const stamps: StampResult[] = [];
+  const witnessed: (string | undefined)[] = [];
   for (const entry of body.stamps) {
-    stamps.push(await verifyStampEntry(entry, seen));
+    const outcome = await verifyStampEntry(entry, seen);
+    stamps.push(outcome.result);
+    witnessed.push(outcome.witnessedHex);
   }
 
+  // --- The optional on-chain re-fetch (§5.2.4's "online act") ---------------
+  //
+  // The SAME stamps[] array §5.3 carries, so it gets the same capability. The
+  // alternative — a stamp that can be re-fetched inside one body and not the
+  // other — asks every consumer to remember which wrapper it is holding before
+  // it can trust `onChain: null`, and that is exactly the kind of per-body
+  // exception a reader eventually gets wrong.
+  const { onChainChecked, gatewayUnavailable } = await refetchStamps(
+    stamps,
+    witnessed,
+    options,
+    errors,
+  );
+
   // --- Rollup ----------------------------------------------------------------
   const anyHardFailure = stamps.some((s) => !s.ok);
   const anyUnwitnessed = stamps.some((s) => s.anchorRef === null);
@@ -1606,17 +1677,25 @@ async function verifyStampTrace(
     // 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.
+  } else if (gatewayUnavailable || anyUnwitnessed) {
+    // Both hold the bundle at `partial`, and both get said — see §5.3's rollup
+    // for why one note is not enough when there are two different gaps.
     status = "partial";
-    errors.push(
-      "one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody",
-    );
+    if (gatewayUnavailable) {
+      errors.push("one or more stamps could not be re-fetched from the supplied gateways");
+    }
+    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.
+      errors.push(
+        "one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody",
+      );
+    }
   } else {
     status = "verified";
   }
@@ -1627,7 +1706,7 @@ async function verifyStampTrace(
     bodyHashOk: true,
     signatureOk: true,
     bodyType: STAMP_TRACE_BODY_TYPE,
-    onChainChecked: false,
+    onChainChecked,
     checkpoints: [],
     events: [],
     assertedStatus,
@@ -1666,7 +1745,12 @@ async function verifyStampEvidence(
   // --- The stamp half: §5.2's rules, §5.2's code ----------------------------
   const seen = new Set<string>();
   const stamps: StampResult[] = [];
-  for (const entry of body.stamps) stamps.push(await verifyStampEntry(entry, seen));
+  const witnessed: (string | undefined)[] = [];
+  for (const entry of body.stamps) {
+    const outcome = await verifyStampEntry(entry, seen);
+    stamps.push(outcome.result);
+    witnessed.push(outcome.witnessedHex);
+  }
 
   // The join table. ONLY a stamp whose derived ref and witnessed bytes both
   // checked out is joinable: a root read out of bytes that failed their own
@@ -1811,6 +1895,14 @@ async function verifyStampEvidence(
     });
   }
 
+  // --- The optional on-chain re-fetch (§5.2.4's "online act") ---------------
+  const { onChainChecked, gatewayUnavailable } = await refetchStamps(
+    stamps,
+    witnessed,
+    options,
+    errors,
+  );
+
   // --- Rollup ---------------------------------------------------------------
   // Rule 4: a declared event MUST be checked. `events[]` present and unverified
   // is the false green this body exists to prevent, so an event that did not
@@ -1824,13 +1916,23 @@ async function verifyStampEvidence(
   } else if (stamps.length === 0 && eventResults.length === 0) {
     status = "partial";
     errors.push(`${STAMP_EVIDENCE_BODY_TYPE} body carries no stamps and no events`);
-  } else if (anyUnwitnessed) {
-    // §5.3.3 rule 6, inherited whole from §5.2.4: for a stamp the witness IS
-    // the independent part, so the events resting on it inherit `partial`.
+  } else if (gatewayUnavailable || anyUnwitnessed) {
+    // Both hold the bundle at `partial`, and BOTH get said. A stamp nobody
+    // witnessed and a witness we could not reach are different gaps with
+    // different fixes — one waits for the interval, the other for the network —
+    // and an auditor told only about the second would read the first as fine.
+    // The order is fixed so the two kernels emit the same list.
     status = "partial";
-    errors.push(
-      "one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody",
-    );
+    if (gatewayUnavailable) {
+      errors.push("one or more stamps could not be re-fetched from the supplied gateways");
+    }
+    if (anyUnwitnessed) {
+      // §5.3.3 rule 6, inherited whole from §5.2.4: for a stamp the witness IS
+      // the independent part, so the events resting on it inherit `partial`.
+      errors.push(
+        "one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody",
+      );
+    }
   } else {
     status = "verified";
   }
@@ -1841,7 +1943,7 @@ async function verifyStampEvidence(
     bodyHashOk: true,
     signatureOk: true,
     bodyType: STAMP_EVIDENCE_BODY_TYPE,
-    onChainChecked: false,
+    onChainChecked,
     checkpoints: [],
     events: eventResults,
     assertedStatus,
@@ -1850,6 +1952,83 @@ async function verifyStampEvidence(
   };
 }
 
+/**
+ * The optional on-chain re-fetch over `stamps[]`, shared by §5.2 and §5.3.
+ *
+ * ── Why the results land on `stamps[]` and `checkpoints` stays empty ──
+ *
+ * A stamp body carries no checkpoints. Synthesising `CheckpointResult`s to
+ * carry these outcomes would make a stamp indistinguishable from a checkpoint
+ * in every consumer that reads `checkpoints[]` — the exact conflation §5.2.1
+ * and §5.3.1 refused twice, most sharply in "a Sanning attestation
+ * indistinguishable on the wire from a producer's". They are different
+ * artifacts with different signers and different meanings when absent, and a
+ * reader must never have to guess which one it is holding. So the stamp
+ * results go on the stamps, and `checkpoints: []` keeps saying the true thing:
+ * this body has none.
+ *
+ * ── Why an unwitnessed stamp gets `onChain: null` and NOT all-unreachable ──
+ *
+ * The anchor-trace path synthesises an all-`unreachable` result for a
+ * checkpoint with no `anchor_ref`. That is not copied here, for two reasons.
+ *
+ * It would be untrue: nothing was asked of any gateway, so reporting that
+ * every gateway failed to answer invents a network event. "Not checked" and
+ * "we asked and nobody answered" are different facts, and collapsing them is
+ * precisely the defect that had a surface reporting an unreachable gateway
+ * when it had contacted none.
+ *
+ * And it would be load-bearing in the wrong direction. Over there the
+ * synthesis exists to drive `gatewayUnavailable`, which is what downgrades that
+ * run to `partial`. Here §5.2.4 already downgrades an unwitnessed stamp to
+ * `partial` on its own, with a better error. Copying the synthesis would add
+ * nothing to the status and would silently move the CLI exit code from 0 to 3
+ * for an unwitnessed stamp — changing what an auditor's script does, based on
+ * nothing but whether the caller happened to pass a gateway list.
+ */
+async function refetchStamps(
+  stamps: StampResult[],
+  witnessed: (string | undefined)[],
+  options: VerifyEvidenceOptions,
+  errors: string[],
+): Promise<{ onChainChecked: boolean; gatewayUnavailable: boolean }> {
+  const gateways = options.gateways ?? [];
+  const onChainChecked = gateways.length > 0;
+  if (!onChainChecked) return { onChainChecked, gatewayUnavailable: false };
+
+  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as typeof fetch | undefined);
+  if (typeof fetchImpl !== "function") {
+    errors.push("on-chain re-fetch requested but no fetch implementation is available");
+    return { onChainChecked, gatewayUnavailable: true };
+  }
+
+  let gatewayUnavailable = false;
+  for (let i = 0; i < stamps.length; i++) {
+    const st = stamps[i]!;
+    const witnessedHex = witnessed[i];
+    // No witness named, or bytes we could not read: nothing to re-fetch, and
+    // nothing a gateway could confirm or deny. Left as `onChain: null`.
+    if (st.anchorRef === null || witnessedHex === undefined) continue;
+
+    const outcome = await refetchStamp(witnessedHex, st.anchorRef, gateways, fetchImpl);
+    st.onChain = outcome.onChain;
+    st.onChainOk = outcome.onChain.onChainOk;
+    if (outcome.unavailable) gatewayUnavailable = true;
+    if (outcome.error) st.errors.push(outcome.error);
+    // Fold the on-chain dimension in exactly as a checkpoint does: a MISMATCH
+    // (false) fails the stamp — the chain does not hold what the bundle says
+    // was witnessed. UNREACHABLE (null) leaves an offline-sound stamp ok and
+    // downgrades the run to `partial` via gatewayUnavailable. A confirm (true)
+    // changes nothing that was not already true offline.
+    //
+    // `st.ok` is kept and narrowed rather than recomputed: its offline form
+    // includes `errors.length === 0`, and re-evaluating that AFTER pushing an
+    // unreachable note would fail a stamp for a gateway being down.
+    st.ok = st.ok && st.onChainOk !== false;
+  }
+  return { onChainChecked, gatewayUnavailable };
+}
+
 // ===========================================================================
 // Ingest: materializing the disclosed raw bytes (evidence-bundle.md §5.1).
 //
@@ -2621,6 +2800,10 @@ async function refetchCheckpoint(
 ): Promise<{ onChain: OnChainResult; unavailable: boolean; error?: string }> {
   let expectedHex: string | undefined;
   try {
+    // A checkpoint's witnessed bytes are its envelope RE-CANONICALIZED. The
+    // bundle carries the envelope as a JSON object, not as bytes, so what was
+    // uploaded has to be recomputed from it. See `refetchStamp` for the case
+    // where this step is not merely unnecessary but WRONG.
     expectedHex = toHex(utf8(jcs(cp.envelope)));
   } catch {
     // Cannot canonicalize the checkpoint envelope — every gateway is a mismatch
@@ -2628,6 +2811,54 @@ async function refetchCheckpoint(
     expectedHex = undefined;
   }
 
+  return refetchAnchored("checkpoint", expectedHex, anchorRef, gateways, fetchImpl);
+}
+
+// Re-fetch a STAMP's witnessed bytes (evidence-bundle.md §5.2.2 / §5.3.2).
+//
+// ── The one step this path must NOT copy from the checkpoint path ──
+//
+// `refetchCheckpoint` recomputes `JCS(envelope)` because a checkpoint's
+// witnessed bytes are not in the bundle — only the object they were derived
+// from is. A stamp is the opposite case: §5.2.2 defines `stamp_bytes` as
+// "lowercase hex of the exact JCS bytes that were handed to the witness", and
+// §5.3.2 repeats it — *"the EXACT bytes that were witnessed, verbatim"*. They
+// are already the bytes, already hex, already lowercase (`isLowerHex` gated
+// them), and `stamp_ref` is their SHA-256.
+//
+// So the expected hex IS `stamp_bytes`, and re-canonicalizing would be a
+// defect, not a redundancy: it would compare the chain against bytes NOBODY
+// SIGNED. On a canonical body the two agree and the bug hides; on a body that
+// is not canonical — the exact case §5.2.2 makes the kernel check for, because
+// the plane replays these bytes as text precisely so a normalizing serializer
+// cannot alter them — a re-canonicalizing verifier reports `mismatch` against
+// a chain that faithfully holds what it was given. A false accusation, from
+// the verifier, about untampered evidence.
+//
+// The bytes handed here are the SAME value `verifyStampEntry` hashed to derive
+// `stamp_ref`, threaded through rather than re-read from the body, so the bytes
+// graded and the bytes compared cannot drift apart.
+async function refetchStamp(
+  witnessedHex: string,
+  anchorRef: AnchorRef,
+  gateways: string[],
+  fetchImpl: typeof fetch,
+): Promise<{ onChain: OnChainResult; unavailable: boolean; error?: string }> {
+  return refetchAnchored("stamp", witnessedHex, anchorRef, gateways, fetchImpl);
+}
+
+// The part both paths share: probe every gateway, roll the outcomes up under
+// the ONE rule (`rollupOnChain`), and phrase the finding. Extracted rather than
+// copied — a second rollup rule is a second place for "mismatch beats confirm
+// beats unreachable" to drift, and the drifted copy is the one nobody reads.
+// The subject only ever selects wording; it never changes a verdict.
+async function refetchAnchored(
+  subject: "checkpoint" | "stamp",
+  expectedHex: string | undefined,
+  anchorRef: AnchorRef,
+  gateways: string[],
+  fetchImpl: typeof fetch,
+): Promise<{ onChain: OnChainResult; unavailable: boolean; error?: string }> {
   const perGateway: PerGatewayOutcome[] = [];
   for (const gw of gateways) {
     perGateway.push({
@@ -2639,9 +2870,12 @@ async function refetchCheckpoint(
   const onChain = rollupOnChain(perGateway);
   let error: string | undefined;
   if (onChain.rollup === "mismatch") {
-    error = `on-chain bytes at ${anchorRef.id} do not match the bundle's checkpoint envelope`;
+    error =
+      subject === "checkpoint"
+        ? `on-chain bytes at ${anchorRef.id} do not match the bundle's checkpoint envelope`
+        : `on-chain bytes at ${anchorRef.id} do not match the stamp's witnessed bytes`;
   } else if (onChain.rollup === "unreachable") {
-    error = `checkpoint ${anchorRef.id} unreachable on all gateways`;
+    error = `${subject} ${anchorRef.id} unreachable on all gateways`;
   }
   return { onChain, unavailable: onChain.rollup === "unreachable", error };
 }

package/vectors/README.md

@@ -8,6 +8,24 @@ That distinction is the whole point. A rule that consumers must agree with needs
 a statement they can *fetch*, not one they have to be trusted to have copied
 correctly.
 
+## `stamp-on-chain.json`
+
+The rule that decides what re-fetching a **stamp's witness** from a gateway does
+and does not settle — the optional, online half of `sanning.stamp.trace/v1` and
+`sanning.stamp.evidence/v1` (`evidence-bundle.md` §5.2.4 / §5.3.4). Implemented
+by [`../src/evidence.ts`](../src/evidence.ts) and asserted against this table by
+[`../test/stamp-on-chain-vectors.test.ts`](../test/stamp-on-chain-vectors.test.ts)
+— **and by the Python kernel against the same bytes**, in
+`tests/test_stamp_on_chain_vectors.py`, so neither kernel can pass by agreeing
+with the other.
+
+**The one thing a consumer must not do with it: collapse the four states into a
+boolean.** `not checked` · `confirm` · `mismatch` · `unreachable`. A reader that
+cannot tell the first from the last will report that no gateway could be reached
+on a run that contacted none — a false accusation manufactured by a missing
+state, and the defect this table was written after. Vendoring rules are the same
+three steps as below, against `vectors/stamp-on-chain.json`.
+
 ## `pack-grading.json`
 
 The rule that decides whether a **pack** — a signed bundle plus whatever

package/vectors/stamp-on-chain.json

@@ -0,0 +1,229 @@
+{
+  "rule": "stamp-on-chain",
+  "ruleVersion": 1,
+  "statement": "What re-fetching a stamp's witness from a gateway DOES and DOES NOT settle. A stamp body carries no producer signature and no inclusion proof of its own, so the witness is the entire independent part of it (evidence-bundle.md §5.2.4): confirming that a gateway holds the exact bytes named by anchor_ref is the only check that turns Sanning's own assertion into evidence. It is an ONLINE act and always optional — an offline verdict is unchanged by it and never claims it happened. Four states, never three: not-checked (no gateway was asked, or the stamp names no witness), confirm (a gateway returned the witnessed bytes), mismatch (a gateway returned DIFFERENT bytes — the only outcome that fails anything), unreachable (we asked and nobody answered — an availability gap, never an accusation). The expected bytes are stamps[].stamp_bytes VERBATIM, because §5.2.2 defines that field as the exact bytes handed to the witness; re-canonicalizing them would compare the chain against bytes nobody signed.",
+  "home": "@sanning/proof — ts/vectors/stamp-on-chain.json. This file is the RULE, not a test fixture of one implementation. The TypeScript kernel implements it in ts/src/evidence.ts (refetchStamps / refetchStamp / probeGateway / rollupOnChain) and is held to it by ts/test/stamp-on-chain-vectors.test.ts; the Python kernel implements it in src/sanning_proof/evidence.py (_refetch_stamps / _refetch_stamp / _probe_gateway / _rollup_on_chain) and is held to the SAME file by tests/test_stamp_on_chain_vectors.py. Neither kernel can pass by agreeing with the other.",
+  "consumers": "A surface that re-fetches a stamp witness SHOULD call the kernel's verifyEvidenceBundle with `gateways` rather than derive the rule again. A surface that cannot yet (an older pinned kernel, another language) vendors this file byte-for-byte, asserts its own derivation against it, and runs a drift check against the copy shipped in the @sanning/proof tarball at vectors/stamp-on-chain.json — failing when it cannot find a copy to compare against. A vendored copy that is not byte-identical to this one is a defect, not a variant. In particular: a surface MUST NOT collapse the four states into a boolean. A reader that cannot distinguish not-checked from unreachable will report that no gateway could be reached when none was tried, which is a false accusation manufactured by a missing state, and is the defect this table was written after.",
+  "howToUse": "Each case describes one sanning.stamp.evidence/v1 pack and one set of scripted gateway responses. Build the pack from `packScaffold`: for each entry of `stamps` (index i, 0-based) sign ONE sanning.events/v1 envelope over the record {\"event\":{\"content_hash\":\"<64×a>\"},\"i\":i} with event_id `ev-<i>` and the fixed seed, take its leaf under RFC 9162 (SHA-256(0x00 ‖ JCS(envelope))), make a one-leaf tree, and build the stamp body from `stampBodyScaffold` with merkle_root = that root, leaf_count = 1 and one sub-tree covering [0,1). stamp_bytes is JCS(stamp body) hex-encoded; stamp_ref is SHA-256 of the DECODED bytes. When the entry's `witnessed` is true attach anchor_ref = {kind: \"arweave\", id: `<anchorIdPrefix><i>`}, otherwise omit anchor_ref entirely. Give each stamp one event whose inclusion is {stamp_ref, leaf_index: 0, leaf_count: 1, leaf_hash, audit_path: []}. Wrap the body per `wrapperScaffold`, set body_hash = SHA-256(JCS(body)) and sign the wrapper (minus `signature`) with the same seed. Then call the kernel with the case's `gateways` and a fetch seam that answers `{gateway}/{anchor id}` per the `returns` entry for that stamp at that gateway's index, and assert `expect`. A case with an empty `gateways` list is called with no gateway list at all — that is the not-checked state and it must be reachable without a fetch seam.",
+  "responseKinds": {
+    "witnessed": "The exact decoded stamp_bytes. The honest chain.",
+    "altered": "JCS of the same stamp body with interval_end changed to 2026-09-09T13:00:00.000Z — a well-formed, canonical, semantically different stamp. This is the forgery shape that matters: a pack built on it is fully self-consistent OFFLINE and lies only about what was witnessed.",
+    "reserialized": "The same JSON object re-serialized with 2-space indentation. Semantically identical, byte-different. MUST confirm: a gateway that pretty-prints is a delivery quirk, not a finding.",
+    "notJson": "The bytes `not json at all`. Neither byte-equal nor parseable, so there is nothing to compare structurally — a mismatch.",
+    "unreachable": "The fetch fails: a network error, a timeout, a non-ok response, or no such transaction. Never a mismatch."
+  },
+  "alsoAppliesTo": "sanning.stamp.trace/v1 — the same case, with body_type changed and events[] dropped. Every case's `expect` holds UNCHANGED for that body, and a grader MUST run all of them twice. §5.2 and §5.3 carry the same stamps[] array under the same §5.2.2 definition, so they must give the same on-chain answer: a stamp that can be re-fetched inside one wrapper and not the other forces every consumer to know which wrapper it is holding before it can read `onChain: null`, and that is the kind of per-body exception a reader eventually gets wrong. The one case-level difference is outside this rule: a §5.2 body with no stamps at all is `partial` for carrying nothing, which no case here exercises.",
+  "anchorIdPrefix": "stampOnChainFixtureAnchorId0000000000-",
+  "packScaffold": {
+    "seedHex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "eventIdPrefix": "ev-",
+    "contentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "signedAt": "2026-09-09T12:00:00Z",
+    "environment": "production"
+  },
+  "stampBodyScaffold": {
+    "stamp_version": "sanning.stamp/v1",
+    "org_ref": "9999999999999999999999999999999999999999999999999999999999999999",
+    "interval_start": "2026-09-09T12:00:00.000Z",
+    "interval_end": "2026-09-09T12:10:00.000Z",
+    "subtreeRef": "1111111111111111111111111111111111111111111111111111111111111111"
+  },
+  "wrapperScaffold": {
+    "spec_version": "sanning.evidence/v1",
+    "body_type": "sanning.stamp.evidence/v1",
+    "issuer": { "kind": "sanning" },
+    "generated_at": "2026-09-09T12:20:00.000Z",
+    "gateway": null,
+    "previous_hash": "GENESIS",
+    "signature_alg": "ed25519"
+  },
+  "cases": [
+    {
+      "id": "not-checked-when-no-gateways",
+      "why": "The default, and the state the other three are defined against. No gateway list means no gateway was asked, so onChain is null — NOT an unreachable result over an empty list. An implementation that reported unreachable here would tell every offline auditor that the chain could not be reached, on a run that never intended to touch it.",
+      "gateways": [],
+      "stamps": [{ "witnessed": true, "returns": [] }],
+      "expect": {
+        "onChainChecked": false,
+        "status": "verified",
+        "exit": 0,
+        "stamps": [{ "rollup": null, "onChainOk": null, "ok": true }],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "confirm-single-gateway",
+      "why": "The gateway holds exactly the bytes the bundle says were witnessed. This is the only case in which a stamp bundle has been shown to be more than Sanning's own assertion, and it must still read `verified` — confirming a witness adds evidence, it does not change a verdict that was already sound offline.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["witnessed"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "verified",
+        "exit": 0,
+        "stamps": [
+          { "rollup": "confirm", "onChainOk": true, "ok": true, "perGateway": ["confirm"] }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "mismatch-fails-the-stamp",
+      "why": "THE case this capability exists for. The pack is internally perfect — wrapper signed, stamp_ref derived from its own bytes, those bytes JCS-canonical, the event's RFC 9162 path reconstructing the committed root — and verifies `verified` offline. The chain holds different bytes. Only a re-fetch can tell, and it must fail the stamp rather than note it: a stamp whose witness contradicts it is not partially witnessed, it is contradicted. An implementation whose byte comparison cannot fail passes every other case in this table and this one alone.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["altered"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "failed",
+        "exit": 1,
+        "stamps": [
+          {
+            "rollup": "mismatch",
+            "onChainOk": false,
+            "ok": false,
+            "perGateway": ["mismatch"],
+            "errorContains": "do not match the stamp's witnessed bytes"
+          }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "unreachable-is-undetermined-not-failed",
+      "why": "A gateway that does not answer has told us NOTHING about the evidence, and a verifier that turns silence into an accusation is the exact failure the anchor_ref vocabulary was designed around. Undetermined: the offline-sound stamp stays ok, the run drops to `partial`, and the exit code is 3 — a retry, not a finding.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["unreachable"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "partial",
+        "exit": 3,
+        "stamps": [
+          {
+            "rollup": "unreachable",
+            "onChainOk": null,
+            "ok": true,
+            "perGateway": ["unreachable"],
+            "errorContains": "unreachable on all gateways"
+          }
+        ],
+        "bundleErrorsContain": ["could not be re-fetched from the supplied gateways"]
+      }
+    },
+    {
+      "id": "mismatch-beats-confirm",
+      "why": "Worst-finding-wins. One gateway serving the right bytes does not answer the other one serving different bytes — a disagreement between gateways about a permanent record is itself the finding, and the honest reading is the accusing one. The per-gateway array is retained so a reader can see WHICH gateway disagreed rather than only that one did.",
+      "gateways": ["https://g1.example", "https://g2.example"],
+      "stamps": [{ "witnessed": true, "returns": ["altered", "witnessed"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "failed",
+        "exit": 1,
+        "stamps": [
+          {
+            "rollup": "mismatch",
+            "onChainOk": false,
+            "ok": false,
+            "perGateway": ["mismatch", "confirm"]
+          }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "confirm-beats-unreachable",
+      "why": "Best-evidence, once nothing has contradicted anything. One gateway being down is an availability fact about that gateway; another gateway returning the witnessed bytes is a fact about the record. The record wins, and the run is not downgraded for the outage — otherwise every auditor with one stale gateway in their list would read `partial` on fully witnessed evidence.",
+      "gateways": ["https://g1.example", "https://g2.example"],
+      "stamps": [{ "witnessed": true, "returns": ["unreachable", "witnessed"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "verified",
+        "exit": 0,
+        "stamps": [
+          {
+            "rollup": "confirm",
+            "onChainOk": true,
+            "ok": true,
+            "perGateway": ["unreachable", "confirm"]
+          }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "unwitnessed-stamp-is-not-checked-never-unreachable",
+      "why": "A stamp with no anchor_ref names no witness, so there is nothing to ask any gateway for. onChain stays null — not-checked — even though gateways were supplied and every one of them is reachable. Reporting all-unreachable here would invent a network event that did not occur, and would move this pack's exit code from 0 to 3 purely because the caller passed a gateway list. The bundle is already `partial` for the right reason, said in the right words, by §5.2.4.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": false, "returns": ["witnessed"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "partial",
+        "exit": 0,
+        "stamps": [{ "rollup": null, "onChainOk": null, "ok": true }],
+        "bundleErrorsContain": ["sealed by Sanning, witnessed by nobody"]
+      }
+    },
+    {
+      "id": "reserialized-body-still-confirms",
+      "why": "A gateway that re-serializes JSON on the way out has changed the delivery, not the record. The byte compare fails and the structural compare — JCS of what came back against the witnessed bytes — succeeds, so this is a confirm. Without the structural fallback every pretty-printing gateway would read as a tampered record, which is a false accusation with an operational cause.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["reserialized"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "verified",
+        "exit": 0,
+        "stamps": [
+          { "rollup": "confirm", "onChainOk": true, "ok": true, "perGateway": ["confirm"] }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "not-json-is-mismatch-not-unreachable",
+      "why": "The gateway answered — so this is not an availability gap — and what it returned is neither the witnessed bytes nor anything that canonicalizes to them. The structural fallback must not swallow the failure to parse into a shrug: a witness id that resolves to something which is not this stamp is a finding, and filing it as unreachable would let a substituted record read as a temporary outage.",
+      "gateways": ["https://g1.example"],
+      "stamps": [{ "witnessed": true, "returns": ["notJson"] }],
+      "expect": {
+        "onChainChecked": true,
+        "status": "failed",
+        "exit": 1,
+        "stamps": [
+          {
+            "rollup": "mismatch",
+            "onChainOk": false,
+            "ok": false,
+            "perGateway": ["mismatch"],
+            "errorContains": "do not match the stamp's witnessed bytes"
+          }
+        ],
+        "bundleErrorsContain": []
+      }
+    },
+    {
+      "id": "two-gaps-are-two-notes",
+      "why": "One stamp witnessed but unreachable, one stamp never witnessed. Both hold the bundle at `partial` and both get SAID. They have different causes and different fixes — one waits for the network, the other for the interval to close — and an auditor told only about the gateway would read the unwitnessed stamp as fine. The per-stamp results keep them apart too: the first carries an unreachable rollup, the second carries null.",
+      "gateways": ["https://g1.example"],
+      "stamps": [
+        { "witnessed": true, "returns": ["unreachable"] },
+        { "witnessed": false, "returns": ["witnessed"] }
+      ],
+      "expect": {
+        "onChainChecked": true,
+        "status": "partial",
+        "exit": 3,
+        "stamps": [
+          {
+            "rollup": "unreachable",
+            "onChainOk": null,
+            "ok": true,
+            "perGateway": ["unreachable"],
+            "errorContains": "unreachable on all gateways"
+          },
+          { "rollup": null, "onChainOk": null, "ok": true }
+        ],
+        "bundleErrorsContain": [
+          "could not be re-fetched from the supplied gateways",
+          "sealed by Sanning, witnessed by nobody"
+        ]
+      }
+    }
+  ]
+}