@sanning/proof 0.8.0 → 0.8.2

package/README.md

@@ -1,6 +1,6 @@
 # @sanning/proof
 
-Verify Sanning evidence-plane provenance records — **with no Sanning code or service in the trust path**.
+Verify Sanning evidence-plane provenance records, **with no Sanning code or service in the trust path**.
 
 This is the TypeScript verification kernel for the *Verifiable Event Envelope* family: the signed JSON records that producers such as the verification agent daemon and the MLflow plugin anchor permanently to Arweave. Given an envelope (fetched from any Arweave gateway), this package answers: *is it authentic, and does it commit to the bytes I'm holding?*
 
@@ -29,10 +29,10 @@ const result = await verifyEnvelope(env);
 result.ok;            // spec_version + payload_hash + Ed25519 all passed
 result.signatureOk;   // Ed25519 over the signed scope, against env.public_key
 result.payloadHashOk; // SHA-256(JCS(payload)) === env.payload_hash
-result.errors;        // [] when ok — machine-readable reasons otherwise
+result.errors;        // [] when ok: machine-readable reasons otherwise
 ```
 
-`verifyEnvelope` never throws on hostile input — a malformed envelope (or a lying gateway) yields `ok: false` with reasons, not an exception.
+`verifyEnvelope` never throws on hostile input: a malformed envelope (or a lying gateway) yields `ok: false` with reasons, not an exception.
 
 ## Bind an envelope to bytes you hold (reverse provenance)
 
@@ -51,9 +51,9 @@ result.contentRole;   // how it commits: e.g. the registered baseline,
 contentHashes(env);   // all content hashes an envelope commits to, by event type
 ```
 
-## Verify a whole trace bundle — one command
+## Verify a whole trace bundle: one command
 
-The `@sanning/anchor` SDK hands a producer a set of `InclusionReceipt`s and can serialize them into one portable, self-verifying `sanning.evidence/v1` bundle (`body_type: sanning.anchor.trace/v1`). Verify the entire bundle — every event's signature + payload binding + Merkle inclusion, all offline — with the bundled CLI:
+The `@sanning/anchor` SDK hands a producer a set of `InclusionReceipt`s and can serialize them into one portable, self-verifying `sanning.evidence/v1` bundle (`body_type: sanning.anchor.trace/v1`). Verify the entire bundle (every event's signature + payload binding + Merkle inclusion, all offline) with the bundled CLI:
 
 ```bash
 npx @sanning/proof verify trace-bundle.json
@@ -61,9 +61,9 @@ npx @sanning/proof verify trace-bundle.json
 npx @sanning/proof verify trace-bundle.json https://arweave.net,https://permagate.io
 ```
 
-It prints a per-event + rollup verdict and exits on a pinned code — `0` verified · `1` a real failure (bad signature / tamper / broken inclusion) · `2` malformed bundle · `3` gateway-unavailable when an on-chain re-fetch was requested. The producer's asserted `verdict` is shown but **never trusted** — the displayed verdict is always recomputed from the body. The same CLI also verifies the agent's `sanning.agent.proof/v1` inclusion bundle (it sniffs `spec_version`), so one command covers anchor + agent.
+It prints a per-event + rollup verdict and exits on a pinned code: `0` verified · `1` a real failure (bad signature / tamper / broken inclusion) · `2` malformed bundle · `3` gateway-unavailable when an on-chain re-fetch was requested. The producer's asserted `verdict` is shown but **never trusted**, the displayed verdict is always recomputed from the body. The same CLI also verifies the agent's `sanning.agent.proof/v1` inclusion bundle (it sniffs `spec_version`), so one command covers anchor + agent.
 
-> The `verify` CLI is live in `@sanning/proof` ≥ 0.2.2 — `npx @sanning/proof verify <bundle> [gateways]`. `verifyEvidenceBundle` is the programmatic API.
+> The `verify` CLI is live in `@sanning/proof` ≥ 0.2.2, `npx @sanning/proof verify <bundle> [gateways]`. `verifyEvidenceBundle` is the programmatic API.
 
 Programmatically:
 
@@ -80,13 +80,13 @@ result.checkpoints;  // per-checkpoint envelope / merkle-root / on-chain results
 result.events;       // per-event signature / payload-binding / inclusion results
 ```
 
-A withheld `record_bytes` (external commitment, record not disclosed) leaves that event's payload binding **undetermined** — surfaced, never failed (the bundle stays cryptographically sound).
+A withheld `record_bytes` (external commitment, record not disclosed) leaves that event's payload binding **undetermined**, surfaced, never failed (the bundle stays cryptographically sound).
 
 ### …including the raw logs, when the holder discloses them
 
 The checks above prove the *stamps*. To also confirm a holder's **raw logs are the bytes whose hash was anchored**, the verifier closes the final `rawLog → content_hash` link: `SHA-256(disclosed bytes)` must equal the `content_hash` the event's record committed to.
 
-A bundle a producer built with disclosure carries the bytes **in the signed body** (`events[].content`), so they're checked automatically — no flag, and the disclosure is itself covered by the wrapper signature:
+A bundle a producer built with disclosure carries the bytes **in the signed body** (`events[].content`), so they're checked automatically: no flag, and the disclosure is itself covered by the wrapper signature:
 
 ```bash
 npx @sanning/proof verify trace-bundle.json          # in-body content verified inline
@@ -94,15 +94,15 @@ npx @sanning/proof verify trace-bundle.json          # in-body content verified
 
 If the logs travel **alongside** a minimal bundle instead, pass them with `--logs`. It takes either shape below, and which one you passed is decided by `stat`, never by the extension.
 
-**A materialized pack — a DIRECTORY.** `materializeBundle` (in [`@sanning/anchor`](https://github.com/sanning-io/anchor)) writes `bundle.json` + `logs/<event_id>.json`, and each file's **raw bytes are the disclosure**. Point `--logs` at that directory and the pack verifies with nothing of ours in the path:
+**A materialized pack: a DIRECTORY.** `materializeBundle` (in [`@sanning/anchor`](https://www.npmjs.com/package/@sanning/anchor)) writes `bundle.json` + `logs/<event_id>.json`, and each file's **raw bytes are the disclosure**. Point `--logs` at that directory and the pack verifies with nothing of ours in the path:
 
 ```bash
 npx @sanning/proof verify pack/bundle.json --logs pack/logs
 ```
 
-Nothing is decoded, re-parsed or re-serialised on the way in: the bytes on disk are the bytes hashed against the committed `content_hash` — the same bytes a verify page hashes from the same files. That is the whole point of the directory form. The alternative — reading the directory and hex-encoding it into a map yourself — is a step that has been got wrong twice in shipped code, once by writing the hex *text* into the log files, so `SHA-256(file)` was the hash of the encoding rather than of the bytes and genuine, untampered evidence failed.
+Nothing is decoded, re-parsed or re-serialised on the way in: the bytes on disk are the bytes hashed against the committed `content_hash`: the same bytes a verify page hashes from the same files. That is the whole point of the directory form. The alternative (reading the directory and hex-encoding it into a map yourself) is a step that has been got wrong twice in shipped code, once by writing the hex *text* into the log files, so `SHA-256(file)` was the hash of the encoding rather than of the bytes and genuine, untampered evidence failed.
 
-**A side input — a JSON FILE** mapping `event_id` → bytes, where an even-length lowercase-hex value is read as hex and anything else as UTF-8 text:
+**A side input: a JSON FILE** mapping `event_id` → bytes, where an even-length lowercase-hex value is read as hex and anything else as UTF-8 text:
 
 ```bash
 npx @sanning/proof verify trace-bundle.json --logs logs.json
@@ -110,20 +110,20 @@ npx @sanning/proof verify trace-bundle.json --logs logs.json
 
 Emit hex, not text, into that map: a UTF-8 decode is lossy for a non-text payload, and a log line that happens to *look* like hex would be decoded into something the producer never wrote. `logsSideInput` in `@sanning/anchor` builds the map correctly.
 
-The directory form's edge cases, **none of which is a verification failure** — an absent disclosure is not evidence of tampering:
+The directory form's edge cases, **none of which is a verification failure**, an absent disclosure is not evidence of tampering:
 
 | Situation | What happens |
 |---|---|
 | A record with no file | That event's content is **undetermined** (`~`) and reported as undisclosed. Exit code unchanged. |
 | An empty directory | Valid. Discloses nothing, says so, exit code unchanged. |
-| A file whose name is no event id | Read, binds to nothing, and is **named** in a note — a typo'd filename is otherwise indistinguishable from minimal disclosure. |
+| A file whose name is no event id | Read, binds to nothing, and is **named** in a note: a typo'd filename is otherwise indistinguishable from minimal disclosure. |
 | A subdirectory | Skipped, never recursed: the layout is flat. Noted. |
 | Anything not named `<event_id>.json`, or not a regular file | Skipped, noted. |
 | A file we selected but cannot read | **Exit 2.** We were pointed at it, so a permissions or broken-link problem must not read as minimal disclosure. |
 
-Either way each event gains a `contentOk`: **`true`** match · **`false`** mismatch (the event *and* the rollup fail, exit `1`) · **`null`** undetermined — nothing disclosed, or no committed `content_hash` (a withheld record); never a failure, mirroring the payload-binding rule. The CLI prints a `logs ✓/✗/~` mark per event and a `logs: N/M disclosed verified` line.
+Either way each event gains a `contentOk`: **`true`** match · **`false`** mismatch (the event *and* the rollup fail, exit `1`) · **`null`** undetermined, nothing disclosed, or no committed `content_hash` (a withheld record); never a failure, mirroring the payload-binding rule. The CLI prints a `logs ✓/✗/~` mark per event and a `logs: N/M disclosed verified` line.
 
-Programmatically the same side input is `content`, keyed by `event_id` — a `Uint8Array` is used as-is, a `string` is hex. **Prefer a `Map`:**
+Programmatically the same side input is `content`, keyed by `event_id`: a `Uint8Array` is used as-is, a `string` is hex. **Prefer a `Map`:**
 
 ```ts
 const result = await verifyEvidenceBundle(bundle, {
@@ -132,13 +132,13 @@ const result = await verifyEvidenceBundle(bundle, {
 result.events[0].contentOk; // true | false | null
 ```
 
-A plain object still works and is fully guarded on the way in. But **an `event_id` is producer-chosen**, and on a plain object the names that live on `Object.prototype` are not free: `content["__proto__"] = bytes` does not store anything — it replaces the object's prototype, and the bytes you meant to disclose are lost before the verifier ever sees them. If you are building the map from names you did not choose — a directory listing, a JSON key, an id off the wire — use a `Map` (or `Object.create(null)`). It is also what `disclosedContent` hands back, so its output feeds straight back in.
+A plain object still works and is fully guarded on the way in. But **an `event_id` is producer-chosen**, and on a plain object the names that live on `Object.prototype` are not free: `content["__proto__"] = bytes` does not store anything: it replaces the object's prototype, and the bytes you meant to disclose are lost before the verifier ever sees them. If you are building the map from names you did not choose (a directory listing, a JSON key, an id off the wire) use a `Map` (or `Object.create(null)`). It is also what `disclosedContent` hands back, so its output feeds straight back in.
 
 In-body `events[].content` (signed) takes precedence over the side input; if both are present for an event and disagree, the event fails.
 
 ### …and get those raw logs back out (ingest)
 
-`events[].content` rides as **lowercase hex** — JSON cannot carry arbitrary bytes. To *materialize* a received bundle's logs (serve them, write pack files, hand them on), use `disclosedContent` rather than decoding that field yourself:
+`events[].content` rides as **lowercase hex**, JSON cannot carry arbitrary bytes. To *materialize* a received bundle's logs (serve them, write pack files, hand them on), use `disclosedContent` rather than decoding that field yourself:
 
 ```ts
 import { disclosedContent } from "@sanning/proof";
@@ -146,26 +146,26 @@ import { disclosedContent } from "@sanning/proof";
 const result = await disclosedContent(bundle); // verifies, then decodes
 
 for (const [eventId, bytes] of result.content) {
-  await writeFile(`logs/${eventId}.json`, bytes); // Uint8Array — write it as-is
+  await writeFile(`logs/${eventId}.json`, bytes); // Uint8Array: write it as-is
 }
 ```
 
-**Verify-then-return:** `disclosedContent` runs the full `verifyEvidenceBundle` (same options) and hands back bytes **only** for events whose chain verified *and* whose disclosed bytes hash to the committed `content_hash`. There is no path through it that yields bytes that are not the committed ones — and `result.verification` carries the whole `EvidenceBundleResult`, so you verify once and render the verdict from the same call.
+**Verify-then-return:** `disclosedContent` runs the full `verifyEvidenceBundle` (same options) and hands back bytes **only** for events whose chain verified *and* whose disclosed bytes hash to the committed `content_hash`. There is no path through it that yields bytes that are not the committed ones, and `result.verification` carries the whole `EvidenceBundleResult`, so you verify once and render the verdict from the same call.
 
 Every event also appears in `result.events`, in body order, with a status that never lets "nothing was disclosed" pass for "empty":
 
 | `status` | `bytes` | Meaning |
 |---|---|---|
-| `verified` | the bytes | Decoded **and** bound to the committed `content_hash` — safe to write as-is. May be zero-length: an empty payload is real, verifiable content. |
-| `not_disclosed` | `null` | Minimal disclosure — the hash was committed, the bytes were not shared. Nothing to write, and not an error. |
+| `verified` | the bytes | Decoded **and** bound to the committed `content_hash`: safe to write as-is. May be zero-length: an empty payload is real, verifiable content. |
+| `not_disclosed` | `null` | Minimal disclosure: the hash was committed, the bytes were not shared. Nothing to write, and not an error. |
 | `undetermined` | `null` | Bytes were disclosed but there is nothing to bind them to (withheld record, or no committed `content_hash`). Withheld rather than returned. |
 | `failed` | `null` | The event's own proof chain failed, or the disclosure did not bind or did not decode. `errors` says which. |
 
-Bytes come back as `Uint8Array`, never a string: the spec commits to **raw bytes**, and a UTF-8 decode is lossy for any payload that is not valid UTF-8 — re-encoding such a string would change the bytes and break the hash. Decode to text yourself if you know your payload is text.
+Bytes come back as `Uint8Array`, never a string: the spec commits to **raw bytes**, and a UTF-8 decode is lossy for any payload that is not valid UTF-8, re-encoding such a string would change the bytes and break the hash. Decode to text yourself if you know your payload is text.
 
 ## Verify a Merkle inclusion proof
 
-Agents close daily checkpoints over per-cycle leaves (RFC 9162, §2.1 domain separation — not the Bitcoin duplicate-leaf variant). Verify a leaf's inclusion against an anchored root:
+Agents close daily checkpoints over per-cycle leaves (RFC 9162, §2.1 domain separation, not the Bitcoin duplicate-leaf variant). Verify a leaf's inclusion against an anchored root:
 
 ```ts
 import { leafHash, verifyInclusion, hexToBytes } from "@sanning/proof";
@@ -185,10 +185,10 @@ const ok = await verifyInclusion(
 |---|---|
 | `verifyEnvelope(env, optionsOrContentHash?)` | The three load-bearing checks (spec-version registry, payload-hash recompute, Ed25519 over the signed scope) + optional content bind. Pass `{ payloadBytes }` for external-commitment envelopes. Returns `VerificationResult`. |
 | `verifyEvidenceBundle(bundle, { gateways?, fetchImpl? })` | Verify a signed `sanning.evidence/v1` / `sanning.anchor.trace/v1` bundle: wrapper signature + `body_hash` + every checkpoint + every event's inclusion, offline (optional on-chain re-fetch). Returns `EvidenceBundleResult`. Powers the `npx @sanning/proof verify` CLI. |
-| `disclosedContent(bundle, { gateways?, content?, fetchImpl? })` | **Ingest:** verify a bundle, then hand back the DECODED raw bytes (`Uint8Array`) of every event whose disclosure bound to its committed `content_hash` — so materializing a received pack never means re-implementing the hex convention. Returns `DisclosedContentResult` (`content` map + per-event `verified` / `not_disclosed` / `undetermined` / `failed`, plus the full `verification`). |
-| `gradePack(result, account, notes)` + `accountDisclosure(bundle, content)` / `completenessNotes(bundle)` / `renderCause(cause)` | **Pack grading:** what a SURFACE may claim about a pack — the bundle plus whatever disclosed bytes travelled with it. Three states, never two: `verified` only when every record's own bytes bound to its own commitment and nothing is missing, unreadable, surplus or omitted; `failed` on a proven mismatch; `incomplete` when a check could not be run. Absent evidence is UNKNOWN, never an accusation. Pure — no I/O; transport stays yours. Conformance table: [`vectors/pack-grading.json`](https://github.com/sanning-io/proof/blob/main/ts/vectors/pack-grading.json), shipped in the tarball. |
+| `disclosedContent(bundle, { gateways?, content?, fetchImpl? })` | **Ingest:** verify a bundle, then hand back the DECODED raw bytes (`Uint8Array`) of every event whose disclosure bound to its committed `content_hash`, so materializing a received pack never means re-implementing the hex convention. Returns `DisclosedContentResult` (`content` map + per-event `verified` / `not_disclosed` / `undetermined` / `failed`, plus the full `verification`). |
+| `gradePack(result, account, notes)` + `accountDisclosure(bundle, content)` / `completenessNotes(bundle)` / `renderCause(cause)` | **Pack grading:** what a SURFACE may claim about a pack: the bundle plus whatever disclosed bytes travelled with it. Three states, never two: `verified` only when every record's own bytes bound to its own commitment and nothing is missing, unreadable, surplus or omitted; `failed` on a proven mismatch; `incomplete` when a check could not be run. Absent evidence is UNKNOWN, never an accusation. Pure: no I/O; transport stays yours. Conformance table: `vectors/pack-grading.json`, shipped in this tarball. |
 | `verifyAgentProofBundle(bundle, { gateways?, fetchImpl? })` / `isAgentProofSpec(v)` | Verify the agent producer's `sanning.agent.proof/v1` inclusion bundle. |
-| `contentHashes(env)` | The content hash(es) an envelope commits to, by event type — the reverse-provenance join keys. |
+| `contentHashes(env)` | The content hash(es) an envelope commits to, by event type: the reverse-provenance join keys. |
 | `specVersionSupported(v)` | Fail-closed accept-check: `sanning.agent/v1` and additive minors (`sanning.agent/v1.<n>`). Unknown majors/profiles are rejected. |
 | `jcs(value)` | RFC 8785 canonical JSON bytes. |
 | `sha256Hex(bytes)` / `sha256Bytes(bytes)` | SHA-256 via WebCrypto. |
@@ -199,19 +199,19 @@ const ok = await verifyInclusion(
 
 ### Signed scope
 
-The primary signature covers `JCS(envelope minus signature minus co_signatures)` ([envelope-spec](https://github.com/sanning-io/proof/blob/main/specs/envelope-spec.md) §2/§7.1). The reserved `co_signatures` carve-out lets countersignatures be added later without invalidating the primary signature.
+The primary signature covers `JCS(envelope minus signature minus co_signatures)` (`envelope-spec.md` §2/§7.1, in the `sanning-proof` package). The reserved `co_signatures` carve-out lets countersignatures be added later without invalidating the primary signature.
 
 ## Why you can trust it (without trusting us)
 
-Three **independent implementations** of this kernel exist — this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and the MIT-licensed Go reference, vendored into this repo under [`cross-kernel/vendor-agent/`](https://github.com/sanning-io/proof/tree/main/cross-kernel/vendor-agent) so anyone can build and run it. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against the shared [`test-vectors` corpus](https://github.com/sanning-io/proof/tree/main/test-vectors) (per-file SHA-256 pins; current cut tag `test-vectors-v3.1`), and the [cross-kernel agreement gate](https://github.com/sanning-io/proof/tree/main/cross-kernel) re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
+Three **independent implementations** of this kernel exist: this package, the Python [`sanning-proof`](https://pypi.org/project/sanning-proof/) (PyPI), and and the MIT-licensed Go reference. The TypeScript and Python kernels are conformance-gated **byte-for-byte** in CI against one shared corpus, pinned per file by SHA-256 at cut tag `test-vectors-v3.2`, and a cross-kernel agreement gate re-runs the corpus plus adversarial negatives through both, asserting identical verdicts on identical bytes. The Go reference runs as a third leg of that same gate, built at the commit its vendoring pins.
 
-That mutual gate is the point: anyone can verify these provenance records with **no Sanning code in the trust path** — write your own verifier against the [public specs](https://github.com/sanning-io/proof/tree/main/specs) and the corpus will tell you if it's conformant.
+That mutual gate is the point: anyone can verify these provenance records with **no Sanning code in the trust path**, write your own verifier against the specs that ship inside the [`sanning-proof`](https://pypi.org/project/sanning-proof/) sdist, and the corpus will tell you if it is conformant.
 
 ## What this package deliberately does NOT do
 
 - **No I/O, ever.** Including in `gradePack`: it takes an account of what was disclosed, it does not go and read a directory. How a pack reached you is yours.
 - **Single-envelope scope.** Chain walking (`previous_hash`), checkpoint reconciliation, and gateway/transport logic are consumer-layer concerns composed above the kernel.
-- **Provenance is history, not endorsement.** A verified envelope proves *these bytes have this signed, anchored history* — never "safe," "approved," or "currently in production."
+- **Provenance is history, not endorsement.** A verified envelope proves *these bytes have this signed, anchored history*, never "safe," "approved," or "currently in production."
 - **Key identity is out-of-band.** The kernel proves the signature matches `env.public_key`; binding that key to a real-world identity is yours to establish.
 
 ## Requirements
@@ -220,4 +220,4 @@ ESM-only. Needs WebCrypto (`globalThis.crypto.subtle`): any modern browser, Node
 
 ## License
 
-MIT — verification must be open.
+MIT, verification must be open.

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 };
 }