@sanning/proof 0.17.0 → 0.19.0

package/src/crypto.ts

@@ -8,8 +8,10 @@ import * as ed from "@noble/ed25519";
 // @noble/ed25519 needs SHA-512 to verify. Wire it to WebCrypto rather than
 // pulling in @noble/hashes. globalThis.crypto.subtle exists in every modern
 // browser and in Node >= 19, so the same code path runs in the app and in tests.
-ed.etc.sha512Async = async (...msgs: Uint8Array[]): Promise<Uint8Array> =>
-  new Uint8Array(await crypto.subtle.digest("SHA-512", asBufferSource(ed.etc.concatBytes(...msgs))));
+// noble 3 ships this provider as its default; it is set here so the kernel
+// says what it hashes with rather than inheriting it.
+ed.hashes.sha512Async = async (message) =>
+  new Uint8Array(await crypto.subtle.digest("SHA-512", asBufferSource(message)));
 
 // WebCrypto's digest() wants a BufferSource backed by a (non-shared) ArrayBuffer.
 // Our byte arrays always are; this keeps TS 5.7's stricter Uint8Array<ArrayBufferLike>
@@ -76,10 +78,125 @@ export async function sha256Hex(bytes: Uint8Array): Promise<string> {
   return bytesToHex(await sha256Bytes(bytes));
 }
 
-// Verify an Ed25519 signature. Inputs are hex (signature, public key) as they
-// appear in the envelope; message is raw bytes. Never throws — a malformed
-// signature or key is "not verified," not an exception, so a hostile envelope
-// can't crash the checker.
+// ---------------------------------------------------------------------------
+// The Ed25519 rule (envelope-spec §7, A44, proof#230)
+//
+// Strict RFC 8032 (`zip215: false`, a frozen invariant), and more: the public
+// key A and the signature's R must each be the canonical encoding of a point
+// in the prime-order subgroup other than the identity, and S below the group
+// order L. Only then is the equation checked.
+//
+// Why more than `zip215: false`: noble checks the equation with the cofactor,
+// 8·S·B = 8·R + 8·k·A, and Go's crypto/ed25519 and libsodium without it, so on
+// their own they disagree when A or R has a small-order component. noble 2.3
+// also could not encode an identity R and hashed nothing for k, so it accepted
+// one signature from a key holder over every message. With A and R in the
+// prime-order subgroup the two equations are the same equation, and every
+// kernel accepts exactly the same signatures.
+//
+// Each clause is checked here, in this order, and named in these words: the
+// Python twin is `ed25519_rule_reason` in `src/sanning_proof/ed25519_rule.py`
+// and the Go kernel's `verifyEd25519Strict` in sanning-io/agent `pkg/proof`.
+// Several clauses are ones noble 3 refuses on its own; they are checked here
+// anyway so the refusal names the clause, which a library's `false` cannot.
+
+/** The sentence a refused signature reads in an envelope result. */
+export const SIGNATURE_FAILED = "Ed25519 signature verification failed";
+
+export const ED25519_RULE_REASONS = [
+  "the public key is not the canonical encoding of a point",
+  "the public key is a point of small order",
+  "the public key is not in the prime-order subgroup",
+  "R is not the canonical encoding of a point",
+  "R is the identity",
+  "R is a point of small order",
+  "R is not in the prime-order subgroup",
+  "S is not below the group order",
+] as const;
+
+const [
+  KEY_NOT_CANONICAL,
+  KEY_SMALL_ORDER,
+  KEY_NOT_IN_SUBGROUP,
+  R_NOT_CANONICAL,
+  R_IDENTITY,
+  R_SMALL_ORDER,
+  R_NOT_IN_SUBGROUP,
+  S_NOT_BELOW_L,
+] = ED25519_RULE_REASONS;
+
+const ED25519_L = 2n ** 252n + 27742317777372353535851937790883648493n;
+
+function bytesToNumberLE(bytes: Uint8Array): bigint {
+  let v = 0n;
+  for (let i = bytes.length - 1; i >= 0; i--) v = (v << 8n) | BigInt(bytes[i]);
+  return v;
+}
+
+// `Point.fromBytes(..., false)` is RFC 8032 decoding with its two strict
+// branches: it throws on y at or above p and on x zero with the sign bit set,
+// the two non-canonical encodings of a point, and on bytes that are no point.
+function decodeStrict(bytes: Uint8Array): ed.Point | null {
+  try {
+    return ed.Point.fromBytes(bytes, false);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The clause of the rule that (`publicKey`, `signature`) breaks, or `null`
+ * when it breaks none and the equation is what is left to check. Lengths are
+ * the caller's (32 and 64 bytes). Never throws.
+ */
+export function ed25519RuleReason(signature: Uint8Array, publicKey: Uint8Array): string | null {
+  const A = decodeStrict(publicKey);
+  if (A === null) return KEY_NOT_CANONICAL;
+  if (A.isSmallOrder()) return KEY_SMALL_ORDER;
+  if (!A.isTorsionFree()) return KEY_NOT_IN_SUBGROUP;
+  const R = decodeStrict(signature.subarray(0, 32));
+  if (R === null) return R_NOT_CANONICAL;
+  if (R.is0()) return R_IDENTITY;
+  if (R.isSmallOrder()) return R_SMALL_ORDER;
+  if (!R.isTorsionFree()) return R_NOT_IN_SUBGROUP;
+  if (bytesToNumberLE(signature.subarray(32, 64)) >= ED25519_L) return S_NOT_BELOW_L;
+  return null;
+}
+
+/**
+ * `null` iff `signatureHex` is a signature of `message` under `publicKeyHex`
+ * by the rule; otherwise the sentence the refusal reads: `SIGNATURE_FAILED`,
+ * with `": "` and the clause of the rule it broke when it broke one. A
+ * malformed field, a wrong length and an equation that does not hold read
+ * the bare sentence. Never throws. The Python twin is `ed25519_refusal`.
+ */
+export async function ed25519Refusal(
+  message: Uint8Array,
+  signatureHex: string,
+  publicKeyHex: string,
+): Promise<string | null> {
+  let signature: Uint8Array;
+  let publicKey: Uint8Array;
+  try {
+    signature = hexToBytes(signatureHex);
+    publicKey = hexToBytes(publicKeyHex);
+  } catch {
+    return SIGNATURE_FAILED;
+  }
+  if (signature.length !== 64 || publicKey.length !== 32) return SIGNATURE_FAILED;
+  const reason = ed25519RuleReason(signature, publicKey);
+  if (reason !== null) return `${SIGNATURE_FAILED}: ${reason}`;
+  try {
+    return (await ed.verifyAsync(signature, message, publicKey, { zip215: false })) ? null : SIGNATURE_FAILED;
+  } catch {
+    return SIGNATURE_FAILED;
+  }
+}
+
+// Verify an Ed25519 signature by the rule above. Inputs are hex (signature,
+// public key) as they appear in the envelope; message is raw bytes. Never
+// throws — a malformed signature or key is "not verified," not an exception,
+// so a hostile envelope can't crash the checker.
 // Arguments in the Python twin's order, `ed25519_verify(message,
 // signature_hex, public_key_hex)` (P-03, 0.13.0). The message came second
 // until 0.13.0; a caller that still passes the signature first gets a compile
@@ -89,22 +206,14 @@ export async function ed25519Verify(
   signatureHex: string,
   publicKeyHex: string,
 ): Promise<boolean> {
-  try {
-    // zip215:false → strict RFC-8032 verification, matching the Go agent's
-    // crypto/ed25519 exactly (noble defaults to the more lenient zip215:true).
-    return await ed.verifyAsync(hexToBytes(signatureHex), message, hexToBytes(publicKeyHex), {
-      zip215: false,
-    });
-  } catch {
-    return false;
-  }
+  return (await ed25519Refusal(message, signatureHex, publicKeyHex)) === null;
 }
 
 // Ed25519 SIGN the raw `message` bytes with a 32-byte private-key seed (lowercase
 // hex). Returns the signature as lowercase hex. The signing counterpart to
 // ed25519Verify — the ONE signing primitive the composer (`proof export`,
 // evidence-export.md §5) needs to Ed25519-sign the export wrapper with the
-// exporter's key ("anyone can export", P-4). The @noble sha512Async hook wired at
+// exporter's key ("anyone can export", P-4). The @noble sha512Async provider wired at
 // module load serves signing and verification alike, so this stays WebCrypto-only.
 export async function ed25519Sign(message: Uint8Array, privateKeyHex: string): Promise<string> {
   return bytesToHex(await ed.signAsync(message, hexToBytes(privateKeyHex)));

package/src/declaration.ts

@@ -131,6 +131,7 @@
 // The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
 // byte-order mark, no non-finite literal. `jcs_loads` in
 // `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
+import type { ChainLink } from "./chain.js";
 import { hexToBytes, utf8 } from "./crypto.js";
 import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace, type HandoffRecord } from "./handoff.js";
@@ -151,8 +152,23 @@ export const DECLARATION_VERSION = "sanning.declaration/v1";
  */
 export const DECLARATION_VERSION_V2 = "sanning.declaration/v2";
 
+/**
+ * v2 plus a signed `chains[]`: the `chain_key`s the holder claims are complete
+ * and in order (evidence-bundle.md 5.4.1 v1.36, A45). A reader that knows only
+ * v1 and v2 reads a v3 declaration as one it cannot read, which is the safe
+ * direction.
+ */
+export const DECLARATION_VERSION_V3 = "sanning.declaration/v3";
+
 /** Every declaration schema this reader knows, in the order they were added. */
-export const DECLARATION_VERSIONS = [DECLARATION_VERSION, DECLARATION_VERSION_V2] as const;
+export const DECLARATION_VERSIONS = [
+  DECLARATION_VERSION,
+  DECLARATION_VERSION_V2,
+  DECLARATION_VERSION_V3,
+] as const;
+
+/** The versions whose every `records[]` entry carries a signed `role`. */
+const ROLE_VERSIONS: readonly string[] = [DECLARATION_VERSION_V2, DECLARATION_VERSION_V3];
 
 /**
  * What a v2 declaration may sign a record IS, compared exactly: `handoff`, a
@@ -205,6 +221,18 @@ export const DECLARATION_DEVIATION_KINDS = [
    * read under rule 7's parser rule.
    */
   "role_step_unreadable",
+  /**
+   * Rule 11 (v1.36, A45), `sanning.declaration/v3` only. The holder signed
+   * that a chain is complete and in order, and a second record under that key,
+   * under any producing key, begins it.
+   */
+  "chain_second_root",
+  /** A record of a claimed chain is the second successor of one predecessor. */
+  "chain_fork",
+  /** A record of a claimed chain points at a predecessor its chain does not present in the pack. */
+  "chain_link_dangling",
+  /** A claimed chain of which the pack presents no record at all. */
+  "chain_claimed_absent",
 ] as const;
 export type DeclarationDeviationKind = (typeof DECLARATION_DEVIATION_KINDS)[number];
 
@@ -300,6 +328,14 @@ export const DECLARATION_NOTE_KINDS = [
    * declaration other than this pack's own is UNKNOWN.
    */
   "other_declaration_withheld",
+  /**
+   * Rule 11 (v1.36, A45). A claimed chain has a dangling link, and a record
+   * signed by the same producing key has an undetermined payload binding. That
+   * record takes no part in a chain, so whether the missing link is it is
+   * UNKNOWN. Moves nothing: the undetermined binding holds the pack at
+   * `incomplete`.
+   */
+  "chain_claim_withheld",
 ] as const;
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 
@@ -320,6 +356,8 @@ export interface DeclarationNote {
   side?: "sent" | "received";
   /** Which claimed hand-off, by position, for `pair_record_withheld`. */
   pairIndex?: number;
+  /** The claimed chain, for `chain_claim_withheld`. */
+  chainKey?: string;
 }
 
 /** One deviation, as data. A surface renders its own prose or calls `renderDeviation`. */
@@ -339,6 +377,8 @@ export interface DeclarationDeviation {
    * the first one this reader learned.
    */
   version?: string;
+  /** The claimed chain, for the four rule 11 `chain_` deviations. */
+  chainKey?: string;
 }
 
 export interface DeclarationCheck {
@@ -377,6 +417,12 @@ export interface DeclarationCheck {
    * Empty for v1, and for anything this reader could not read.
    */
   roles?: { eventId: string; role: DeclarationRole }[];
+  /**
+   * Every `chain_key` a v3 declaration claims is complete and in order, in
+   * declaration order. Empty for v1 and v2, and for anything this reader could
+   * not read.
+   */
+  chains?: string[];
 }
 
 // ---- Reading the pack --------------------------------------------------------
@@ -385,7 +431,7 @@ interface DeclarationBundleLike {
   body?: {
     declaration?: unknown;
     events?: {
-      envelope?: { event_id?: unknown; public_key?: unknown };
+      envelope?: { event_id?: unknown; public_key?: unknown; payload_hash?: unknown };
       content?: unknown;
       event_bytes?: unknown;
     }[];
@@ -504,6 +550,19 @@ export interface PackRecord {
    * two different readings and never one.
    */
   bytesSupplied: boolean;
+  /**
+   * Whether this record's payload binding is UNDETERMINED: no `event_bytes`
+   * string and no inline envelope `payload`, the two things the envelope
+   * verifier binds `payload_hash` against. Rule 11 excuses a dangling link
+   * only for such a record's producing key.
+   */
+  bindingUndetermined: boolean;
+  /**
+   * The envelope's signed `payload_hash` as written, or `""`. For a record
+   * whose binding is undetermined it is the identity a successor's pointer
+   * names: rule 11 excuses a dangling link only where the pointer equals it.
+   */
+  payloadHash: string;
 }
 
 /**
@@ -545,6 +604,8 @@ export function packRecords(
       publicKey: typeof key === "string" ? key : "",
       record: committedRecord(rawBytes),
       bytesSupplied: typeof rawBytes === "string" && rawBytes.length > 0,
+      bindingUndetermined: typeof rawBytes !== "string" && !(isObject(ev?.envelope) && "payload" in ev.envelope),
+      payloadHash: typeof ev?.envelope?.payload_hash === "string" ? ev.envelope.payload_hash : "",
     };
   });
 }
@@ -568,6 +629,7 @@ interface ReadDeclaration {
   records: { eventId: string; withheld: boolean }[];
   pairs: { sent: string | null; received: string | null }[];
   roles: { eventId: string; role: DeclarationRole }[];
+  chains: string[];
 }
 
 /**
@@ -587,7 +649,7 @@ function readDeclaration(
   // or `step` (5.4.1 v1.20, A21); under v1 the member is not read at all, so a
   // v1 declaration carrying `role` reads exactly as the same object without it.
   const roles: { eventId: string; role: DeclarationRole }[] = [];
-  const v2 = version === DECLARATION_VERSION_V2;
+  const v2 = ROLE_VERSIONS.includes(version);
   const note = (r: string) => reasons.push(r);
 
   if (!isId(declaration["case_id"])) note("case_id is not a non-empty string");
@@ -665,7 +727,31 @@ function readDeclaration(
     }
   }
 
-  return reasons.length > 0 ? { ok: false, reasons } : { ok: true, read: { records, pairs, roles } };
+  // v3 is v2 plus a required `chains[]` (5.4.1 v1.36, A45); v1 and v2 do not
+  // read the member.
+  const chains: string[] = [];
+  if (version === DECLARATION_VERSION_V3) {
+    const rawChains = declaration["chains"];
+    if (!Array.isArray(rawChains)) note("chains is not an array");
+    else {
+      for (const [i, c] of rawChains.entries()) {
+        if (!isObject(c) || !isId(c["chain_key"])) {
+          note(`chains[${i}] carries no chain_key`);
+          continue;
+        }
+        const chainKey = c["chain_key"] as string;
+        if (chains.includes(chainKey)) {
+          note(`chains[${i}] claims ${chainKey} a second time`);
+          continue;
+        }
+        chains.push(chainKey);
+      }
+    }
+  }
+
+  return reasons.length > 0
+    ? { ok: false, reasons }
+    : { ok: true, read: { records, pairs, roles, chains } };
 }
 
 // ---- The check ---------------------------------------------------------------
@@ -680,6 +766,7 @@ const noDeclaration = (): DeclarationCheck => ({
   declaredWithheld: [],
   version: null,
   roles: [],
+  chains: [],
 });
 
 /**
@@ -690,7 +777,9 @@ const noDeclaration = (): DeclarationCheck => ({
 function knownVersion(declaration: unknown): string | null {
   if (!isObject(declaration)) return null;
   const version = declaration["declaration_version"];
-  return version === DECLARATION_VERSION || version === DECLARATION_VERSION_V2 ? version : null;
+  return typeof version === "string" && (DECLARATION_VERSIONS as readonly string[]).includes(version)
+    ? version
+    : null;
 }
 
 /**
@@ -752,16 +841,19 @@ function hasExactKeys(value: unknown, keys: string[]): value is Record<string, u
 function isDeclarationShape(obj: unknown): boolean {
   if (!isObject(obj)) return false;
   const version = obj["declaration_version"];
-  if (version !== DECLARATION_VERSION && version !== DECLARATION_VERSION_V2) return false;
-  if (!hasExactKeys(obj, DECLARATION_KEYS)) return false;
+  if (typeof version !== "string" || !(DECLARATION_VERSIONS as readonly string[]).includes(version))
+    return false;
+  const v3 = version === DECLARATION_VERSION_V3;
+  if (!hasExactKeys(obj, v3 ? [...DECLARATION_KEYS, "chains"] : DECLARATION_KEYS)) return false;
   if (!isId(obj["case_id"])) return false;
   const agents = obj["agents"];
   if (!Array.isArray(agents) || !agents.every((a) => typeof a === "string")) return false;
   const period = obj["period"];
   if (!hasExactKeys(period, ["start", "end"])) return false;
   if (typeof period["start"] !== "string" || typeof period["end"] !== "string") return false;
-  const recordKeys =
-    version === DECLARATION_VERSION_V2 ? ["event_id", "disclosure", "role"] : ["event_id", "disclosure"];
+  const recordKeys = ROLE_VERSIONS.includes(version)
+    ? ["event_id", "disclosure", "role"]
+    : ["event_id", "disclosure"];
   const records = obj["records"];
   if (!Array.isArray(records)) return false;
   for (const r of records) {
@@ -769,7 +861,13 @@ function isDeclarationShape(obj: unknown): boolean {
   }
   const handoffs = obj["handoffs"];
   if (!Array.isArray(handoffs)) return false;
-  return handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"]));
+  if (!handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"]))) return false;
+  if (!v3) return true;
+  const chains = obj["chains"];
+  return (
+    Array.isArray(chains) &&
+    chains.every((c) => hasExactKeys(c, ["chain_key"]) && typeof c["chain_key"] === "string")
+  );
 }
 
 /**
@@ -871,6 +969,14 @@ function otherDeclarationNotes(
  * and a pack that discloses them beside itself passes the map a consumer
  * already built.
  *
+ * `chains` is `readChains` over the SAME bundle. Only a v3 declaration that
+ * claims a chain reads it (rule 11). It is an argument rather than computed
+ * here because `readChains` is asynchronous and this check is not, and Python's
+ * `check_declaration` takes it the same way so the two kernels share one
+ * contract. A v3 declaration that claims a chain, checked without it, reads as
+ * a reader that does not know v3 reads it: `partial`, nothing named, and the
+ * pack `incomplete`. Leaving it out can never read `verified`.
+ *
  * The verdict is this check's own. It does not restate the bundle verdict and
  * it does not read it: a declaration can match perfectly over a pack whose
  * signatures are forged, and saying so is `gradePack`'s job, which takes both.
@@ -878,6 +984,7 @@ function otherDeclarationNotes(
 export function checkDeclaration(
   bundle: unknown,
   content?: SideContentMap | null,
+  links?: readonly ChainLink[] | null,
 ): DeclarationCheck {
   // `body.declaration` as WRITTEN, not as hoped. The key being absent and the
   // key holding a string, an array or `null` are graded differently and must
@@ -922,10 +1029,12 @@ export function checkDeclaration(
       declaredWithheld: [],
       version,
       roles: [],
+      chains: [],
     };
   }
 
-  const { records, pairs, roles } = read.read;
+  const { records, pairs, roles, chains: claimedChains } = read.read;
+
   const declared = records.map((r) => r.eventId);
   const declaredSet = new Set(declared);
   const pack = packRecords(bundle, content);
@@ -1080,6 +1189,19 @@ export function checkDeclaration(
     }
   }
 
+  // Rule 11 (5.4.2 v1.36, A45), `sanning.declaration/v3` only: a chain the
+  // holder signed as complete and in order, against the chain reading of the
+  // same pack. Its deviations follow rule 9's, and its notes follow rule 9's
+  // and precede rule 10's, both in `chains[]` order.
+  // A caller that passed no links leaves the claim UNREAD: rules 1 to 10 still
+  // run, and the verdict below is never `verified`.
+  const unread = claimedChains.length > 0 && (links === undefined || links === null);
+  if (claimedChains.length > 0 && links !== undefined && links !== null) {
+    const found = chainClaimFindings(claimedChains, links, pack);
+    deviations.push(...found.deviations);
+    notes.push(...found.notes);
+  }
+
   // Rule 10 (5.4.2 v1.29, A36): content handed in for a record signed
   // `declaration` that is a declaration other than this pack's own. Notes only, in bundle order, after every other note, and
   // never a deviation: the pack holds what its own declaration says whatever
@@ -1093,7 +1215,11 @@ export function checkDeclaration(
   // only unsigned bytes could settle, which is UNDETERMINED: `partial` is
   // 3's word for that, and it adds none.
   const verdict: DeclarationVerdict =
-    deviations.length > 0 ? "failed" : contentFindings.length > 0 ? "partial" : "verified";
+    deviations.length > 0
+      ? "failed"
+      : contentFindings.length > 0 || unread
+        ? "partial"
+        : "verified";
 
   return {
     verdict,
@@ -1105,9 +1231,75 @@ export function checkDeclaration(
     declaredWithheld: records.filter((r) => r.withheld).map((r) => r.eventId),
     version,
     roles,
+    chains: claimedChains,
   };
 }
 
+/**
+ * Rule 11 over every claimed `chain_key`, in `chains[]` order. The twin of
+ * Python's `_chain_claim_findings`, which states the rule in full.
+ *
+ * A claim covers every record whose OWN signed linkage names the key
+ * (`source === "record"`), under every producing key; an adapter's metadata
+ * linkage is never read for a claim. Under a claim, in bundle order: every
+ * record after the first that begins the chain is a `chain_second_root`; a
+ * record whose predecessor already has an earlier successor in its chain is a
+ * `chain_fork`; a record whose pointer resolves to no record of its own chain
+ * (one producing key, one `chain_key`) is a `chain_link_dangling`, with no
+ * window allowance; a claimed key with no such record is
+ * `chain_claimed_absent`. Links are read from the record each envelope binds,
+ * `event_bytes` or an inline `payload`. A dangling link is the note
+ * `chain_claim_withheld` instead, once per key, only where its pointer equals
+ * the signed `payload_hash` of a same-key record whose binding is
+ * undetermined: exactly the missing link. Nothing else is excused.
+ */
+function chainClaimFindings(
+  claimed: string[],
+  links: readonly ChainLink[],
+  pack: { publicKey: string; bindingUndetermined: boolean; payloadHash: string }[],
+): { deviations: DeclarationDeviation[]; notes: DeclarationNote[] } {
+  const deviations: DeclarationDeviation[] = [];
+  const notes: DeclarationNote[] = [];
+  const withheldLinks = new Set(
+    pack
+      .filter((p) => p.bindingUndetermined && p.publicKey !== "" && p.payloadHash !== "")
+      .map((p) => JSON.stringify([p.publicKey, p.payloadHash])),
+  );
+  for (const chainKey of claimed) {
+    const members = links
+      .filter((l) => l.source === "record" && l.chainKey === chainKey)
+      .sort((a, b) => a.order - b.order);
+    if (members.length === 0) {
+      deviations.push({ kind: "chain_claimed_absent", chainKey });
+      continue;
+    }
+    const idsByKey = new Map<string, Set<string>>();
+    for (const m of members) {
+      if (!idsByKey.has(m.publicKey)) idsByKey.set(m.publicKey, new Set());
+      idsByKey.get(m.publicKey)!.add(m.selfId);
+    }
+    let roots = 0;
+    const successors = new Set<string>();
+    let excused = false;
+    for (const m of members) {
+      if (m.prev === null) {
+        roots++;
+        if (roots > 1) deviations.push({ kind: "chain_second_root", eventId: m.eventId, chainKey });
+        continue;
+      }
+      const edge = JSON.stringify([m.publicKey, m.prev]);
+      if (successors.has(edge)) deviations.push({ kind: "chain_fork", eventId: m.eventId, chainKey });
+      successors.add(edge);
+      if (!idsByKey.get(m.publicKey)!.has(m.prev)) {
+        if (withheldLinks.has(JSON.stringify([m.publicKey, m.prev]))) excused = true;
+        else deviations.push({ kind: "chain_link_dangling", eventId: m.eventId, chainKey });
+      }
+    }
+    if (excused) notes.push({ kind: "chain_claim_withheld", chainKey });
+  }
+  return { deviations, notes };
+}
+
 // ---- Presentation (optional) -------------------------------------------------
 
 /**
@@ -1257,6 +1449,15 @@ export function renderDeclarationSummary(check: DeclarationCheck): string {
       "unsigned content handed in beside it, which anyone could have supplied"
     );
   }
+  if (check.verdict === "partial" && (check.chains ?? []).length > 0) {
+    // Read before the branch below: the declaration WAS read, and its chain
+    // claim was not checked because the caller gave no reading.
+    return (
+      "this pack holds what it declares, and says its chains are complete " +
+      "and in order, which this verifier did not check, so whether they " +
+      "are is UNKNOWN"
+    );
+  }
   if (check.verdict === "partial") {
     return (
       "this pack says what it holds in a declaration this verifier cannot read, " +
@@ -1303,6 +1504,13 @@ export function renderNote(note: DeclarationNote): string {
         "reached this verifier, so whether it is a declaration other than " +
         "this pack's own is UNKNOWN"
       );
+    case "chain_claim_withheld":
+      return (
+        `this pack declares chain ${note.chainKey} complete and in order, ` +
+        "and a link in it points at a record its producer signed and this " +
+        "pack withholds: the pointer equals that record's signed " +
+        "payload_hash, and the record's bytes are not here to read"
+      );
   }
 }
 
@@ -1380,5 +1588,27 @@ export function renderDeviation(deviation: DeclarationDeviation): string {
         `${deviation.eventId} is signed as a step and this pack carries ` +
         "record bytes for it that this verifier cannot read"
       );
+    case "chain_second_root":
+      return (
+        `${deviation.eventId} begins chain ${deviation.chainKey} a second ` +
+        "time, and the declaration says that chain is complete and in order"
+      );
+    case "chain_fork":
+      return (
+        `${deviation.eventId} in chain ${deviation.chainKey} points at a ` +
+        "record another record of that chain already points at, and the " +
+        "declaration says that chain is complete and in order"
+      );
+    case "chain_link_dangling":
+      return (
+        `${deviation.eventId} in chain ${deviation.chainKey} points at a ` +
+        "record of that chain this pack does not present, and the " +
+        "declaration says that chain is complete and in order"
+      );
+    case "chain_claimed_absent":
+      return (
+        `the declaration says chain ${deviation.chainKey} is complete and ` +
+        "in order, and this pack presents no record of it"
+      );
   }
 }