@sanning/proof 0.5.0 → 0.7.0

package/README.md

@@ -92,23 +92,48 @@ A bundle a producer built with disclosure carries the bytes **in the signed body
 npx @sanning/proof verify trace-bundle.json          # in-body content verified inline
 ```
 
-If the logs travel **alongside** a minimal bundle instead, pass them with `--logs` — a JSON object mapping `event_id` → bytes, where an even-length lowercase-hex string is read as hex and anything else as UTF-8 text:
+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:
+
+```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.
+
+**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
 ```
 
+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:
+
+| 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 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.
 
-Programmatically the same side input is `content`, keyed by `event_id` — a `Uint8Array` is used as-is, a `string` is hex:
+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, {
-  content: { [eventId]: rawLogBytes }, // Uint8Array, or a hex string
+  content: new Map([[eventId, rawLogBytes]]), // Uint8Array, or a hex string
 });
 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.
+
 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)
@@ -161,6 +186,7 @@ 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. |
 | `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. |
 | `specVersionSupported(v)` | Fail-closed accept-check: `sanning.agent/v1` and additive minors (`sanning.agent/v1.<n>`). Unknown majors/profiles are rejected. |
@@ -177,12 +203,13 @@ 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-v2.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.
 
 ## 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."
 - **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.

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,351 @@
+// 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;
+        const seq = Number.isInteger(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;
+}
+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);
+        const missing = [];
+        for (let s = low; s <= high; s++)
+            if (!present.has(s))
+                missing.push(s);
+        if (missing.length > 0) {
+            const after = sequenced.filter((m) => m.seq > missing[0]).sort(byChainOrder)[0];
+            findings.push({
+                kind: "chain-gap",
+                ...base,
+                count: missing.length,
+                eventIds: after === undefined ? [] : [after.eventId],
+                firstMissingSeq: missing[0],
+            });
+        }
+    }
+    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}`;
+    groups.sort((a, b) => order(a).localeCompare(order(b)));
+    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(", ")})`);
+    }
+}