@sanning/proof 0.19.1 → 0.20.0

package/src/chain.ts

@@ -1,70 +1,33 @@
-// Chain reading — following the pointer every anchored event carries to the
-// event before it, and reporting what does not line up.
+// Chain reading: follow the pointer each anchored event carries to the one
+// before it, and report what does not resolve. A pure rule over the records a
+// bundle presents, separate from envelope verification and pack grading.
 //
-// WHY THIS LIVES IN THE KERNEL, BESIDE PACK GRADING.
-// `sanning.events/v2` records carry `previous_hash`, and until now nothing we
-// shipped read it. The envelope verifier hashes each event's `event_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).
+// This is not a completeness statement. Drop the last N events of a chain and
+// nothing here dangles (`anchor/docs/profile-sanning.events-v2.md` §5);
+// completeness is the checkpoint `leaf_count` in `grading.ts`. So nothing here
+// returns a verdict: only findings, and a count of the chains read so a surface
+// can tell "nothing to report" from "read nothing".
 //
-// 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.
+// A chain is one head per `(public_key, chain_key)` (profile §3.2): two
+// producers that share a chain name are two chains. The linkage is read two
+// ways:
 //
-// ---- 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-v2.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 read through it feeds a
-// verdict, a claimed chain included (rule 11 reads linkage (1) only). 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.
+//   1. The record's own chain (`previous_hash` + `context.chain_key`), resolved
+//      in payload-hash space. The profile's mechanism.
+//   2. Adapter metadata (`metadata.<namespace>.prev_event_id` + `seq`),
+//      resolved in event-id space, read only when the record carries no chain
+//      of its own. `metadata` is caller-owned and the profile forbids
+//      verifying from it, so nothing read through it feeds a verdict, a claimed
+//      chain included (rule 11 reads linkage 1 only).
 
 import { hexToBytes, sha256Hex } from "./crypto.js";
 import { inlinePayloadBytes, jcsParse } from "./verifier.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.
+ * The sentence a surface prints beside these findings, so "no findings" is
+ * never read as "nothing is missing". Quoted from the profile (§5), because a
+ * paraphrased 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.";
@@ -74,25 +37,15 @@ 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.
+ * The names must match the `@sanning/anchor` SDKs exactly: a stale name finds no
+ * chains and reads like a clean bundle.
  */
 export const ADAPTER_CHAIN_NAMESPACES: readonly { namespace: string; keyField: string }[] = [
-  // @sanning/anchor LangChain callbacks, TS + Python (anchor#68). One chain per
-  // root run, so the root run id is the chain.
+  // LangChain callbacks: one chain per root run.
   { namespace: "run", keyField: "root_run_id" },
-  // @sanning/anchor Vercel AI SDK middleware. A flat sequence per correlation key.
+  // 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.
+  // Interchange: one chain per session; `seq` is Interchange's own.
   { namespace: "interchange", keyField: "session_id" },
 ];
 
@@ -105,11 +58,8 @@ export type ChainFindingKind =
   | "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.
+ * One link that does not resolve, as data. `renderChainFinding` gives the house
+ * wording.
  */
 export interface ChainFinding {
   kind: ChainFindingKind;
@@ -134,12 +84,8 @@ export interface ChainFinding {
 }
 
 /**
- * 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.
+ * One chain this bundle presents records for. `events` counts the records
+ * here, never the chain's length.
  */
 export interface ChainSummary {
   chainKey: string;
@@ -154,8 +100,6 @@ export interface ChainReading {
   findings: ChainFinding[];
 }
 
-// ---- Reading the records -----------------------------------------------------
-
 interface EventRecord {
   previous_hash?: unknown;
   context?: { chain_key?: unknown };
@@ -165,7 +109,7 @@ interface EventRecord {
 /** One record's place in one chain, normalised across the two linkage forms. */
 interface Member {
   eventId: string;
-  /** What the NEXT record's pointer must equal: payload hash, or event id. */
+  /** What the next record's pointer must equal: payload hash, or event id. */
   selfId: string;
   /** The pointer this record carries, or `null` when it claims to begin the chain. */
   prev: string | null;
@@ -183,46 +127,23 @@ interface Group {
 }
 
 /**
- * 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.
+ * The events this bundle is about, through the same descent
+ * `verifyEvidenceBundle` uses, so the reader walks the events the verifier
+ * reported on.
  */
 const eventsOf = (bundle: unknown) => 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.
+ * Decode one event record from its committed bytes, or `null`. A withheld or
+ * unreadable record takes no part in a chain: the bundle verifier already
+ * reports its binding as undetermined.
  */
 function decodeRecord(hex: unknown): { record: EventRecord; bytes: Uint8Array } | null {
   if (typeof hex !== "string" || hex.length === 0) return null;
   try {
     const bytes = hexToBytes(hex);
-    // PINNED STRICT via `jcsParse`, and the twin at
-    // `src/sanning_proof/chain.py` is `jcs_loads` (proof#149). This was the
-    // LAST lenient decode pair in either kernel, and it was lenient on BOTH
-    // sides in different directions, so it agreed nowhere while looking like
-    // it agreed everywhere:
-    //
-    //   * A bare `new TextDecoder()` here eats a leading byte-order mark and
-    //     substitutes U+FFFD for every invalid sequence, so `BOM + JCS(r)`, a
-    //     raw `0x80`, a CESU-8 surrogate pair and a truncated UTF-8 sequence
-    //     each joined a chain HERE and joined none there.
-    //   * Python's `json.loads` accepted `NaN`, `Infinity` and `-Infinity`,
-    //     which RFC 8785 cannot emit and this kernel's `JSON.parse` rejects,
-    //     so a record carrying one joined a chain THERE and none here.
-    //
-    // Five split readings on one pair, in two directions, and no test in
-    // either kernel could see them: each kernel agreed with itself. That is
-    // why agreement between two lenient readers is not evidence of anything,
-    // and why the comparison has to run on the same bytes.
+    // Strict, matching Python's `jcs_loads`: a lenient decoder on either side
+    // (BOM, invalid UTF-8, non-finite literals) splits the two kernels.
     const record = jcsParse(bytes) as EventRecord;
     if (record === null || typeof record !== "object") return null;
     return { record, bytes };
@@ -234,10 +155,8 @@ function decodeRecord(hex: unknown): { record: EventRecord; bytes: Uint8Array }
 const str = (v: unknown): string | null => (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.
+ * The adapter linkage, if the record carries a known one. The first namespace
+ * in table order wins.
  */
 function adapterLinkage(
   record: EventRecord,
@@ -250,20 +169,11 @@ function adapterLinkage(
     const fields = ns as Record<string, unknown>;
     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.
+    // Adapters write `null` at the head; absent reads the same: 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.
+    // Safe integers only: beyond 2^53 `JSON.parse` loses precision where Python
+    // does not, and the kernels would report different gaps on the same bytes.
     const seq = Number.isSafeInteger(seqRaw) ? (seqRaw as number) : null;
     return { namespace, chainKey, prev, seq };
   }
@@ -271,21 +181,9 @@ function adapterLinkage(
 }
 
 /**
- * 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.
- */
-/**
- * The record an envelope binds, for rule 11's links: `event_bytes` where the
- * entry carries them, else the inline `payload` read through
- * `inlinePayloadBytes`, the bytes `payload_hash` binds. Its identity is the
- * SHA-256 of whichever bytes it is read from. Python's `_bound_record`.
+ * The record an envelope binds, for rule 11: `event_bytes` where present, else
+ * the inline `payload`. Its identity is the SHA-256 of those bytes. Python's
+ * twin is `_bound_record`.
  */
 function boundRecord(
   entry: { event_bytes?: unknown; envelope?: unknown } | undefined,
@@ -305,6 +203,11 @@ function boundRecord(
   }
 }
 
+/**
+ * Group the bundle's records into chains. Self-ids are derived by hashing the
+ * bytes, never read off the envelope, so a relabelled record dangles instead of
+ * resolving.
+ */
 async function groupChains(bundle: unknown, inline = false): Promise<Group[]> {
   const groups = new Map<string, Group>();
   const events = eventsOf(bundle);
@@ -313,22 +216,17 @@ async function groupChains(bundle: unknown, inline = false): Promise<Group[]> {
     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.
+    // No producing key, no chain identity; no event id, nothing to resolve to.
     if (eventId === null || publicKey === null) continue;
 
-    // `inline` (rule 11's links only): a record carried as the envelope's
-    // inline `payload` with no `event_bytes` is read too. The chain reading
-    // itself keeps reading `event_bytes` alone, so its findings and its rule
-    // table do not move.
+    // `inline` is for rule 11 only; the chain reading itself reads
+    // `event_bytes` alone.
     const decoded = inline ? boundRecord(entry) : decodeRecord(entry?.event_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.
+    // 1. `context.chain_key` is present only on chained records, which keeps
+    //    unchained `GENESIS` singletons out of one fictional chain.
     const recordChainKey = str(record.context?.chain_key);
     let member: Member;
     let key: string;
@@ -346,10 +244,7 @@ async function groupChains(bundle: unknown, inline = false): Promise<Group[]> {
       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.
+      // 2. Fallback only: one record must not land in two chains.
       const linkage = adapterLinkage(record);
       if (linkage === null) continue;
       member = { eventId, selfId: eventId, prev: linkage.prev, seq: linkage.seq, order };
@@ -370,8 +265,6 @@ async function groupChains(bundle: unknown, inline = false): Promise<Group[]> {
   return [...groups.values()];
 }
 
-// ---- The rule ----------------------------------------------------------------
-
 /** By `seq` where both have one, else by position in the bundle. */
 function byChainOrder(a: Member, b: Member): number {
   if (a.seq !== null && b.seq !== null && a.seq !== b.seq) return a.seq - b.seq;
@@ -379,10 +272,8 @@ function byChainOrder(a: Member, b: Member): number {
 }
 
 /**
- * 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.
+ * The smallest unoccupied slot between the lowest and highest occupied ones,
+ * found by walking the sorted occupants: the range width is attacker-chosen.
  */
 function firstMissingSlot(present: Set<number>): number | null {
   const ordered = [...present].sort((a, b) => a - b);
@@ -410,11 +301,8 @@ function findingsFor(group: Group): ChainFinding[] {
     .filter((m): m is Member & { prev: string } => 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.
+  // Two GENESIS records under one key: a fork, which a link-walk alone reports
+  // as clean. Typically a crash that lost the chain head.
   if (roots.length > 1) {
     findings.push({
       kind: "chain-second-root",
@@ -424,12 +312,8 @@ function findingsFor(group: Group): ChainFinding[] {
     });
   }
 
-  // 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.
+  // One pointer out of the bundle is the window's edge, not a finding, unless
+  // the chain already has its GENESIS root here.
   const unexplained = roots.length === 0 ? dangling.slice(1) : dangling;
   if (unexplained.length > 0) {
     const first = unexplained[0]!;
@@ -442,24 +326,15 @@ function findingsFor(group: Group): ChainFinding[] {
     });
   }
 
-  // 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.
+  // Interior holes only: a window starting at seq 7 is not a deletion. The
+  // present-set is duplicate-safe so a repeated seq is not 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 as number));
     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.
+    // Counted, never walked: `seq` is attacker-chosen, and a loop over
+    // [low, high] hangs on 0 and 1e15.
     const missingCount = high - low + 1 - present.size;
     const firstMissing = missingCount > 0 ? firstMissingSlot(present) : null;
     if (firstMissing !== null) {
@@ -478,10 +353,8 @@ function findingsFor(group: Group): ChainFinding[] {
 }
 
 /**
- * One record's place in a chain, as the reader grouped it, for a check that
- * needs the links themselves rather than the findings: rule 11 of
- * evidence-bundle.md 5.4.2, which holds a claimed chain to every link. The
- * twin of Python's `ChainLink`.
+ * One record's place in a chain, for rule 11 of evidence-bundle.md §5.4.2.
+ * Python's twin is `ChainLink`.
  */
 export interface ChainLink {
   eventId: string;
@@ -499,11 +372,8 @@ export interface ChainLink {
 }
 
 /**
- * Every record the chain reader places in a chain, in bundle order, with the
- * identity and pointer it read: the grouping `readChains` reads, over every
- * record an envelope binds, `event_bytes` or the inline `payload` where no
- * `event_bytes` travel, with the identity the SHA-256 of those bytes, exactly
- * as the envelope verifier binds `payload_hash`.
+ * Every record placed in a chain, in bundle order, with its identity and
+ * pointer. Reads `event_bytes`, or the inline `payload` where none travel.
  */
 export async function readChainLinks(bundle: unknown): Promise<ChainLink[]> {
   const links: ChainLink[] = [];
@@ -526,23 +396,15 @@ export async function readChainLinks(bundle: unknown): Promise<ChainLink[]> {
 }
 
 /**
- * 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.
+ * Report the links that do not resolve within the bundle. An intact chain, and
+ * one whose records are withheld, report nothing: an unreadable link is
+ * unknown, never an accusation.
  */
 export async function readChains(bundle: unknown): Promise<ChainReading> {
   const groups = await groupChains(bundle);
   const order = (g: Group) => `${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).
+  // By UTF-16 code unit, not `localeCompare` (host-dependent ICU collation).
+  // Python sorts the key as `utf-16-be`, so both kernels emit one order.
   groups.sort((a, b) => {
     const x = order(a);
     const y = order(b);
@@ -562,12 +424,9 @@ export async 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.
+ * The house wording for one finding. Says only what does not resolve in this
+ * bundle, never failed, tampered or complete; a surface rewording it must not
+ * upgrade the claim.
  */
 export function renderChainFinding(finding: ChainFinding, subject = "this bundle"): string {
   const where =
@@ -577,14 +436,16 @@ export function renderChainFinding(finding: ChainFinding, subject = "this bundle
   switch (finding.kind) {
     case "chain-link-dangling":
       return (
-        `${where}: ${finding.count} of ${finding.of} record(s) point at a predecessor ` +
+        `${where}: ${finding.count} of ${finding.of} ` +
+        `${finding.of === 1 ? "record points" : "records 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}` +
+        `${where}: ${finding.count} sequence ` +
+        `${finding.count === 1 ? "slot" : "slots"} between the records ${subject} presents ` +
+        `${finding.count === 1 ? "carries" : "carry"} no record (first missing seq ${finding.firstMissingSeq}` +
         `${finding.eventIds[0] === undefined ? "" : `, next present: ${finding.eventIds[0]}`})`
       );
     case "chain-second-root":