@sanning/proof 0.6.0 → 0.8.0

package/README.md

@@ -203,7 +203,7 @@ The primary signature covers `JCS(envelope minus signature minus co_signatures)`
 
 ## 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.0`), 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 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.
 
 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.
 

package/dist/chain.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The one sentence a surface should print beside these findings, so the reader
+ * is never left to infer that "no findings" means "nothing is missing".
+ *
+ * Lifted from the profile (§5) rather than reworded, because a paraphrase of a
+ * scope limit is how a scope limit turns into a claim.
+ */
+export declare const CHAIN_READING_SCOPE = "Chain links are deletion/reorder-evidence for the events present; they are not a completeness proof.";
+/** Where the linkage was read from. */
+export type ChainSource = "record" | "adapter";
+/**
+ * The adapter metadata namespaces that carry a chain when the record does not.
+ *
+ * VERIFIED AGAINST `sanning-io/anchor` @ main, 2026-09-07. `run` is NOT a typo
+ * for `langchain`: anchor#68 promoted the LangChain linkage out of a
+ * framework-named namespace into a shared one, so the same fact has one path in
+ * every SDK. A table pinned on the old name would find no chains, report
+ * nothing, and look exactly like a clean bundle — the rename trap, in the
+ * direction that fails silently.
+ *
+ * Exported so a test can assert the table itself, and so a consumer can see
+ * what this reader knows about rather than guessing.
+ */
+export declare const ADAPTER_CHAIN_NAMESPACES: readonly {
+    namespace: string;
+    keyField: string;
+}[];
+export type ChainFindingKind = 
+/** A record points at a predecessor no record in this bundle presents. */
+"chain-link-dangling"
+/** A `seq` slot between two records this bundle presents has no record. */
+ | "chain-gap"
+/** More than one record claims to begin the chain. */
+ | "chain-second-root";
+/**
+ * One link that does not resolve, as data.
+ *
+ * Structured for the same reason `PackGradeCause` is: prose is the part that
+ * drifts hardest between surfaces and matters least. `renderChainFinding`
+ * produces the house wording; a surface with its own voice reads the fields.
+ */
+export interface ChainFinding {
+    kind: ChainFindingKind;
+    /** The chain this is about, as the records spell it. */
+    chainKey: string;
+    /** Whether the linkage came from the record core or an adapter namespace. */
+    source: ChainSource;
+    /** The adapter metadata namespace, when `source` is `"adapter"`. */
+    namespace?: string;
+    /** The producing key, since a chain is one head per (public_key, chain_key). */
+    publicKey: string;
+    /** How many links, slots or roots the finding is about. */
+    count: number;
+    /** How many records this bundle presents for the chain, framing `count`. */
+    of: number;
+    /** The affected `event_id`s, so a reader has somewhere to look. */
+    eventIds: string[];
+    /** The pointer that resolved to no record here (`chain-link-dangling`). */
+    unresolvedPointer?: string;
+    /** The first sequence slot with no record here (`chain-gap`). */
+    firstMissingSeq?: number;
+}
+/**
+ * One chain this bundle presents records for.
+ *
+ * `events` is HOW MANY RECORDS ARE HERE — never how many the chain has. The
+ * summary exists so a surface can say "read 3 chains, nothing to report"
+ * instead of "nothing to report", which is also what a reader that silently
+ * matched no records would say.
+ */
+export interface ChainSummary {
+    chainKey: string;
+    source: ChainSource;
+    namespace?: string;
+    publicKey: string;
+    events: number;
+}
+export interface ChainReading {
+    chains: ChainSummary[];
+    findings: ChainFinding[];
+}
+/**
+ * Follow every chain the bundle's records describe, and report the links that
+ * do not resolve within it.
+ *
+ * Reports NOTHING for an intact chain, and nothing for a chain whose records
+ * are withheld — a link we could not read is unknown, never an accusation.
+ * `chains` is what makes that distinguishable from having read nothing at all.
+ */
+export declare function readChains(bundle: unknown): Promise<ChainReading>;
+/**
+ * The house wording for one finding.
+ *
+ * Deliberately free of verdict vocabulary. Every sentence says what does not
+ * resolve IN THIS BUNDLE, because that is the whole of what was checked; none
+ * of them says failed, invalid, tampered or complete. A surface with its own
+ * voice should read the fields instead — but it must not upgrade the claim.
+ */
+export declare function renderChainFinding(finding: ChainFinding, subject?: string): string;

package/dist/chain.js

@@ -0,0 +1,389 @@
+// Chain reading — following the pointer every anchored event carries to the
+// event before it, and reporting what does not line up.
+//
+// WHY THIS LIVES IN THE KERNEL, BESIDE PACK GRADING.
+// `sanning.events/v1` records carry `previous_hash`, and until now nothing we
+// shipped read it. The envelope verifier hashes each event's `record_bytes`
+// and stops — `evidence.ts` says following the link is "consumer-layer logic
+// above it", and it was right that a SINGLE-envelope verifier should not do
+// it. But the consumer layer never did it either, so a bundle with an event
+// removed, and a chain that restarted after a crash and now asserts two
+// beginnings, both passed every shipped check (proof#43).
+//
+// Reading the link is not envelope verification and it is not pack grading: it
+// is a third, pure rule over the records a bundle presents. Same seam as
+// grading — data in, data out, no `fs`, no `fetch` — so the kernel's scope
+// boundary (`specs/architecture.md` §3) is unchanged.
+//
+// ---- WHAT THIS IS NOT ------------------------------------------------------
+//
+// It is not a completeness statement and it must never be read as one. The
+// profile says so in its own words (`anchor/docs/profile-sanning.events-v1.md`
+// §5): chain semantics are "deletion/reorder-evidence for the events present
+// ... not a completeness proof." Drop the last N events of a chain and nothing
+// here dangles; the record that would have pointed at them was never written.
+// Completeness is the checkpoint `leaf_count` mechanism, which lives in
+// `grading.ts` and answers a different question.
+//
+// So nothing in this module returns a verdict, a status, an `ok`, or the word
+// "complete". It returns FINDINGS — each one a specific link that does not
+// resolve within the bundle in front of us — and a count of the chains it read,
+// so a surface can tell "nothing to report" apart from "read nothing".
+//
+// ---- HOW A CHAIN IS IDENTIFIED ---------------------------------------------
+//
+// A chain is one head per `(public_key, chain_key)` — profile §3.2, and the
+// reason `public_key` is part of every group key below. Two producers using the
+// chain name "session-1" are two chains; merging them would manufacture a
+// second root out of a naming coincidence.
+//
+// The linkage is written two ways today, and this reads both:
+//
+//   1. THE RECORD'S OWN CHAIN (`previous_hash` + `context.chain_key`). The
+//      profile's mechanism, and the one a third party can walk from the spec
+//      alone. Links resolve in PAYLOAD-HASH space.
+//   2. THE ADAPTER'S METADATA (`metadata.<namespace>.prev_event_id` + `seq`).
+//      The batched paths write the linkage only here; their records say
+//      GENESIS. Links resolve in EVENT-ID space. Read as a FALLBACK, only when
+//      the record carries no chain of its own.
+//
+// (2) is a transitional accommodation, not the design. `metadata` is
+// caller-owned and the profile says a verifier MUST NOT read it for
+// verification — which is exactly why nothing here feeds a verdict. The fix is
+// for every adapter to set the record's own `previous_hash` (filed separately
+// against `anchor`); when it lands, the namespace table below stops mattering
+// and can go.
+import { hexToBytes, sha256Hex } from "./crypto.js";
+import { resolveTraceEvents } from "./evidence.js";
+/**
+ * The one sentence a surface should print beside these findings, so the reader
+ * is never left to infer that "no findings" means "nothing is missing".
+ *
+ * Lifted from the profile (§5) rather than reworded, because a paraphrase of a
+ * scope limit is how a scope limit turns into a claim.
+ */
+export const CHAIN_READING_SCOPE = "Chain links are deletion/reorder-evidence for the events present; they are not a completeness proof.";
+/**
+ * The adapter metadata namespaces that carry a chain when the record does not.
+ *
+ * VERIFIED AGAINST `sanning-io/anchor` @ main, 2026-09-07. `run` is NOT a typo
+ * for `langchain`: anchor#68 promoted the LangChain linkage out of a
+ * framework-named namespace into a shared one, so the same fact has one path in
+ * every SDK. A table pinned on the old name would find no chains, report
+ * nothing, and look exactly like a clean bundle — the rename trap, in the
+ * direction that fails silently.
+ *
+ * Exported so a test can assert the table itself, and so a consumer can see
+ * what this reader knows about rather than guessing.
+ */
+export const ADAPTER_CHAIN_NAMESPACES = [
+    // @sanning/anchor LangChain callbacks, TS + Python (anchor#68). One chain per
+    // root run, so the root run id is the chain.
+    { namespace: "run", keyField: "root_run_id" },
+    // @sanning/anchor Vercel AI SDK middleware. A flat sequence per correlation key.
+    { namespace: "vercel_ai", keyField: "chain_key" },
+    // @sanning/anchor Interchange adapter. One chain per session; `seq` is
+    // Interchange's own reactor-owned sequence, passed through.
+    { namespace: "interchange", keyField: "session_id" },
+];
+/**
+ * The events this bundle is about, unwrapping any evidence-export wrapper to
+ * the inline source bundle. DEFERRED to `evidence.ts`, which is the same
+ * descent `verifyEvidenceBundle` and `disclosedContent` already use — a second
+ * answer to "which events" inside one kernel is a second implementation of one
+ * rule, and it is how a reader ends up walking a different set of events than
+ * the verifier reported on.
+ */
+const eventsOf = (bundle) => resolveTraceEvents(bundle) ?? [];
+/**
+ * Decode one event record from its committed bytes.
+ *
+ * Same discipline as `signedLeafCount`: hex, UTF-8, JSON, and an undecodable
+ * record is `null` rather than a throw or a guess. A withheld or unreadable
+ * record simply takes no part in a chain — `verifyEvidenceBundle` already
+ * reports its binding as undetermined, and inventing a second accusation here
+ * would say the same thing twice in a harsher voice.
+ */
+function decodeRecord(hex) {
+    if (typeof hex !== "string" || hex.length === 0)
+        return null;
+    try {
+        const bytes = hexToBytes(hex);
+        const record = JSON.parse(new TextDecoder().decode(bytes));
+        if (record === null || typeof record !== "object")
+            return null;
+        return { record, bytes };
+    }
+    catch {
+        return null;
+    }
+}
+const str = (v) => (typeof v === "string" && v.length > 0 ? v : null);
+/**
+ * The adapter linkage, if this record carries one this reader knows about.
+ *
+ * Order is the table's order and the first match wins; a record carrying two
+ * adapter namespaces is not a shape any SDK emits.
+ */
+function adapterLinkage(record) {
+    const metadata = record.metadata;
+    if (metadata === null || typeof metadata !== "object")
+        return null;
+    for (const { namespace, keyField } of ADAPTER_CHAIN_NAMESPACES) {
+        const ns = metadata[namespace];
+        if (ns === null || typeof ns !== "object")
+            continue;
+        const fields = ns;
+        const chainKey = str(fields[keyField]);
+        if (chainKey === null)
+            continue;
+        // `prev_event_id` is explicitly null at the head of an adapter chain — the
+        // adapters write the null rather than omitting the key, because absent and
+        // null mean different things to a reader. Absent is treated the same way
+        // here: nothing to resolve is a beginning.
+        const prev = str(fields.prev_event_id);
+        const seqRaw = fields.seq;
+        // SAFE integer, not merely integral. Beyond 2^53 a JSON number does not
+        // survive `JSON.parse` intact — `9007199254740993` arrives as
+        // `...992` — while Python's parser keeps it exactly, so the two kernels
+        // read DIFFERENT sequence numbers off identical bytes and report gaps of
+        // different widths. Measured at 2^53+1: a `chain-gap` count of
+        // 9007199254740990 here against 9007199254740992 there (proof#49). A value
+        // this kernel cannot represent is one it cannot read, which is the same
+        // answer it gives every other unreadable field: no sequence, take no part.
+        const seq = Number.isSafeInteger(seqRaw) ? seqRaw : null;
+        return { namespace, chainKey, prev, seq };
+    }
+    return null;
+}
+/**
+ * Group the bundle's records into chains.
+ *
+ * Self-ids are DERIVED, never read off the envelope. A record chain's pointer
+ * is the previous record's `payload_hash`, and `payload_hash` is an asserted
+ * label sitting next to the bytes it claims to be about; matching one asserted
+ * label against another is how a relabelled checkpoint once verified cleanly
+ * (`evidence.ts`, `checkpoint_ref`). Hashing the bytes we already hold costs
+ * nothing and means a relabelled record DANGLES instead of quietly resolving.
+ * That is why this function is async.
+ */
+async function groupChains(bundle) {
+    const groups = new Map();
+    const events = eventsOf(bundle);
+    for (let order = 0; order < events.length; order++) {
+        const entry = events[order];
+        const eventId = str(entry?.envelope?.event_id);
+        const publicKey = str(entry?.envelope?.public_key);
+        // Without a producing key there is no chain identity (§3.2), and without an
+        // event id an adapter pointer has nothing to resolve against.
+        if (eventId === null || publicKey === null)
+            continue;
+        const decoded = decodeRecord(entry?.record_bytes);
+        if (decoded === null)
+            continue;
+        const { record, bytes } = decoded;
+        // 1. The record's own chain. `context.chain_key` is present IFF the record
+        //    is chained (profile §5) — which is what keeps every unchained
+        //    singleton, all of them carrying `previous_hash: "GENESIS"`, out of one
+        //    enormous fictional chain that would report a second root per pair.
+        const recordChainKey = str(record.context?.chain_key);
+        let member;
+        let key;
+        let group;
+        if (recordChainKey !== null) {
+            const previous = str(record.previous_hash);
+            member = {
+                eventId,
+                selfId: await sha256Hex(bytes),
+                prev: previous === null || previous === "GENESIS" ? null : previous,
+                seq: null,
+                order,
+            };
+            group = { chainKey: recordChainKey, source: "record", publicKey };
+            key = `record ${publicKey} ${recordChainKey}`;
+        }
+        else {
+            // 2. Fallback only. A record that carries its own chain is never read
+            //    through its adapter metadata: one record must not land in two
+            //    chains, and the profile's own field is the one a third party can
+            //    walk without knowing which SDK wrote it.
+            const linkage = adapterLinkage(record);
+            if (linkage === null)
+                continue;
+            member = { eventId, selfId: eventId, prev: linkage.prev, seq: linkage.seq, order };
+            group = {
+                chainKey: linkage.chainKey,
+                source: "adapter",
+                namespace: linkage.namespace,
+                publicKey,
+            };
+            key = `adapter ${linkage.namespace} ${publicKey} ${linkage.chainKey}`;
+        }
+        const existing = groups.get(key);
+        if (existing === undefined)
+            groups.set(key, { ...group, members: [member] });
+        else
+            existing.members.push(member);
+    }
+    return [...groups.values()];
+}
+// ---- The rule ----------------------------------------------------------------
+/** By `seq` where both have one, else by position in the bundle. */
+function byChainOrder(a, b) {
+    if (a.seq !== null && b.seq !== null && a.seq !== b.seq)
+        return a.seq - b.seq;
+    return a.order - b.order;
+}
+/**
+ * The smallest slot between the lowest and highest occupied ones that no record
+ * occupies, found by walking the SORTED occupants rather than the range they
+ * span. See the call site: the range's width is chosen by whoever wrote the
+ * bundle.
+ */
+function firstMissingSlot(present) {
+    const ordered = [...present].sort((a, b) => a - b);
+    for (let i = 0; i < ordered.length - 1; i++) {
+        if (ordered[i + 1] > ordered[i] + 1)
+            return ordered[i] + 1;
+    }
+    return null;
+}
+function findingsFor(group) {
+    const { members, chainKey, source, publicKey } = group;
+    const of = members.length;
+    const base = {
+        chainKey,
+        source,
+        publicKey,
+        of,
+        ...(group.namespace === undefined ? {} : { namespace: group.namespace }),
+    };
+    const findings = [];
+    const selfIds = new Set(members.map((m) => m.selfId));
+    const roots = members.filter((m) => m.prev === null).sort(byChainOrder);
+    const dangling = members
+        .filter((m) => m.prev !== null && !selfIds.has(m.prev))
+        .sort(byChainOrder);
+    // A SECOND BEGINNING. One chain has one head per (public_key, chain_key), so
+    // two records claiming GENESIS under one key is a fork — the case a link-walk
+    // alone reports as CLEAN, because both halves walk back to a legitimate
+    // beginning and neither dangles. It is what a crash looks like when the SDK
+    // lost its chain head and started over under the same name.
+    if (roots.length > 1) {
+        findings.push({
+            kind: "chain-second-root",
+            ...base,
+            count: roots.length,
+            eventIds: roots.map((m) => m.eventId),
+        });
+    }
+    // A POINTER THAT LEAVES THIS BUNDLE. Exactly one such pointer is expected and
+    // is NOT a finding: a bundle is a window onto a chain that may have begun
+    // before this export, so the window's earliest record necessarily points at a
+    // predecessor nobody handed us. The allowance is spent only when the chain
+    // shows no GENESIS root — a chain that already has its beginning here has no
+    // window edge left to explain the next one.
+    const unexplained = roots.length === 0 ? dangling.slice(1) : dangling;
+    if (unexplained.length > 0) {
+        const first = unexplained[0];
+        findings.push({
+            kind: "chain-link-dangling",
+            ...base,
+            count: unexplained.length,
+            eventIds: unexplained.map((m) => m.eventId),
+            unresolvedPointer: first.prev,
+        });
+    }
+    // A HOLE IN THE SEQUENCE, where an adapter numbers its events. Only INTERIOR
+    // holes count: a window that starts at seq 7 is a window, not a deletion, and
+    // reporting its first six absent slots would bury the one that matters. A
+    // repeated seq is a real defect but a different one, and the present-set below
+    // is deliberately duplicate-safe rather than count-based so it cannot be
+    // mistaken for a gap.
+    const sequenced = members.filter((m) => m.seq !== null);
+    if (sequenced.length === of && of > 0) {
+        const present = new Set(sequenced.map((m) => m.seq));
+        const low = Math.min(...present);
+        const high = Math.max(...present);
+        // Counted, never walked. `seq` is attacker-chosen, so a bundle presenting
+        // two records at seq 0 and seq 1e15 made the old `for (let s = low; s <=
+        // high; s++)` spin for days — a verifier that HANGS on adversarial input is
+        // worse than one that raises, and this reader promises neither (proof#49).
+        // The present set is a subset of [low, high], so the absent slots are the
+        // width minus the occupants, and the first of them is found by walking the
+        // occupants in order.
+        const missingCount = high - low + 1 - present.size;
+        const firstMissing = missingCount > 0 ? firstMissingSlot(present) : null;
+        if (firstMissing !== null) {
+            const after = sequenced.filter((m) => m.seq > firstMissing).sort(byChainOrder)[0];
+            findings.push({
+                kind: "chain-gap",
+                ...base,
+                count: missingCount,
+                eventIds: after === undefined ? [] : [after.eventId],
+                firstMissingSeq: firstMissing,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Follow every chain the bundle's records describe, and report the links that
+ * do not resolve within it.
+ *
+ * Reports NOTHING for an intact chain, and nothing for a chain whose records
+ * are withheld — a link we could not read is unknown, never an accusation.
+ * `chains` is what makes that distinguishable from having read nothing at all.
+ */
+export async function readChains(bundle) {
+    const groups = await groupChains(bundle);
+    const order = (g) => `${g.source} ${g.namespace ?? ""} ${g.chainKey}`;
+    // Ordered by UTF-16 code unit, NOT `localeCompare`. A chain key is caller
+    // text, and `localeCompare` with no locale argument answers from the host's
+    // ICU collation: measured here, it puts "chain-2" AFTER "chain_1" where every
+    // code-wise comparison puts it before, and it can differ between two
+    // TypeScript installs, let alone between kernels. The Python reader sorts the
+    // same key encoded as `utf-16-be`, which is exactly this comparison — so the
+    // two kernels emit findings in one order (proof#49).
+    groups.sort((a, b) => {
+        const x = order(a);
+        const y = order(b);
+        return x < y ? -1 : x > y ? 1 : 0;
+    });
+    return {
+        chains: groups.map((g) => ({
+            chainKey: g.chainKey,
+            source: g.source,
+            ...(g.namespace === undefined ? {} : { namespace: g.namespace }),
+            publicKey: g.publicKey,
+            events: g.members.length,
+        })),
+        findings: groups.flatMap(findingsFor),
+    };
+}
+/**
+ * The house wording for one finding.
+ *
+ * Deliberately free of verdict vocabulary. Every sentence says what does not
+ * resolve IN THIS BUNDLE, because that is the whole of what was checked; none
+ * of them says failed, invalid, tampered or complete. A surface with its own
+ * voice should read the fields instead — but it must not upgrade the claim.
+ */
+export function renderChainFinding(finding, subject = "this bundle") {
+    const where = finding.source === "adapter"
+        ? `chain ${finding.chainKey} (${finding.namespace} metadata)`
+        : `chain ${finding.chainKey}`;
+    switch (finding.kind) {
+        case "chain-link-dangling":
+            return (`${where}: ${finding.count} of ${finding.of} record(s) point at a predecessor ` +
+                `${subject} does not present (first: ${finding.eventIds[0]}, pointer ` +
+                `${finding.unresolvedPointer})`);
+        case "chain-gap":
+            return (`${where}: ${finding.count} sequence slot(s) between the records ${subject} presents ` +
+                `carry no record (first missing seq ${finding.firstMissingSeq}` +
+                `${finding.eventIds[0] === undefined ? "" : `, next present: ${finding.eventIds[0]}`})`);
+        case "chain-second-root":
+            return (`${where}: ${finding.count} records begin the chain where one chain has one beginning ` +
+                `(${finding.eventIds.join(", ")})`);
+    }
+}

package/dist/cli.js

@@ -18,6 +18,7 @@ import { realpathSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
+import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
 import { composeExport } from "./compose.js";
 import { utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
@@ -147,7 +148,12 @@ export async function runCli(argv, io) {
         ...(content ? { content } : {}),
         ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
     });
-    const exit = reportEvidence(result, bundlePath, gateways, io);
+    // Read the chains from the SAME parsed bundle the verifier saw. Findings are
+    // evidence about the records in front of us, not a verdict: they are printed
+    // and they never move `exit`, because a chain is not a completeness proof and
+    // an exit code is exactly the kind of thing people read as one.
+    const chains = await readChains(parsed);
+    const exit = reportEvidence(result, bundlePath, gateways, io, chains);
     // Coverage is reported only once the bundle parsed far enough to have events
     // to compare against; over a MALFORMED bundle there is nothing to say.
     if (logs && result.status !== "malformed")
@@ -584,7 +590,7 @@ function printUsage(io) {
     io.out("");
     io.out("Exit codes: 0 verified · 1 failed · 2 malformed · 3 gateway-unavailable");
 }
-function reportEvidence(result, path, gateways, io) {
+function reportEvidence(result, path, gateways, io, chains) {
     if (result.status === "malformed") {
         io.err(paint("MALFORMED", R) + `  ${path}`);
         for (const e of result.errors)
@@ -620,6 +626,7 @@ function reportEvidence(result, path, gateways, io) {
                 io.out(paint(`        - ${e}`, R));
         }
     }
+    reportChains(chains, io);
     if (result.export) {
         reportExport(result.export, io);
     }
@@ -634,6 +641,39 @@ function reportEvidence(result, path, gateways, io) {
     }
     return mapStatusToExit(result.status, result.errors);
 }
+/**
+ * The chain block: what following each record's pointer to the record before it
+ * showed, over the records THIS bundle presents.
+ *
+ * Three deliberate choices, all of them about not overclaiming.
+ *
+ * 1. It prints the chains it READ, not just the findings. "3 chains, nothing to
+ *    report" and silence are different statements, and a reader that quietly
+ *    matched no records at all would produce the second one while covering
+ *    nothing.
+ * 2. It prints the scope sentence whenever it read a chain, findings or not.
+ *    "Delete an event and the next pointer dangles" is true; "so the bundle is
+ *    complete" does not follow, and two customer-facing documents had already
+ *    made that leap. The limit travels with the result or it gets dropped.
+ * 3. It does not touch the exit code. Findings are evidence; the exit code is
+ *    the verdict surface, and the pinned 0/1/2/3 contract stays exactly what it
+ *    was. A dangling link is something for a person to look at, not a machine
+ *    decision this check is entitled to make.
+ */
+function reportChains(reading, io) {
+    if (reading.chains.length === 0)
+        return;
+    io.out("");
+    io.out(paint("  Event chains", DIM));
+    for (const c of reading.chains) {
+        const where = c.namespace === undefined ? "record" : `${c.namespace} metadata`;
+        io.out(paint(`    ${c.chainKey}  ${count(c.events, "record", "records")} present  (linked in ${where})`, DIM));
+    }
+    for (const f of reading.findings) {
+        io.out(paint(`    ! ${renderChainFinding(f, "this bundle")}`, Y));
+    }
+    io.out(paint(`    ${CHAIN_READING_SCOPE}`, DIM));
+}
 // Render the export-specific block (evidence-export.md §5): source-bundle
 // linkage, cached-vs-recomputed verdict agreement, and each embedded operator
 // attestation (RSA-PSS sig · operator-address binding · data_hash binding).