@sanning/proof 0.13.0 → 0.15.0

package/src/evidence.ts

@@ -32,9 +32,11 @@ import {
 import { isConformantHandoffRecord, isHandoffNamespace, type HeldRecord } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import {
+  DuplicateKeyError,
   MAX_CANONICAL_DEPTH,
   contentHashes,
   exceedsDepth,
+  isRfc3339UtcInstant,
   jcs,
   jcsParse,
   verifyEnvelope,
@@ -516,6 +518,12 @@ export interface EvidenceBundleResult {
   // Absent for every other body — additive, backward-compatible.
   stamps?: StampResult[];
   errors: string[];
+  // Informational only: never read, never gated on, never moves `status` or
+  // the CLI exit code. Carries `CO_SIGNATURES_NOTE` where the wrapper's
+  // reserved `co_signatures` field is present with at least one entry
+  // (evidence-bundle.md §2, §7.1 decision proof#148). Absent for every
+  // bundle without it, additive and backward-compatible.
+  notes?: string[];
 }
 
 // ---- Attested-evidence-export wire + result types (evidence-export.md) -------
@@ -671,6 +679,43 @@ export interface VerifyEvidenceOptions {
   fetchImpl?: typeof fetch;
 }
 
+/**
+ * A surface MUST NOT present a wrapper's `co_signatures` as evidence
+ * (evidence-bundle.md §2, decided by Phil 2026-09-24 on proof#148): nothing
+ * in either kernel verifies the field, and it sits outside the wrapper's
+ * signed scope (`bundleForSig` below), so anyone holding a pack's bytes can
+ * append it with no key at all. This is the one sentence both kernels attach
+ * as a note, never a verdict, never an exit code.
+ */
+export const CO_SIGNATURES_NOTE =
+  "unverified co-signatures are present in this pack's wrapper and are not part of the evidence";
+
+/**
+ * True iff the wrapper's reserved `co_signatures` field carries at least one
+ * entry.
+ *
+ * Absence and an empty array read the same way here: the field asserts
+ * nothing about a second signer until it holds one, and evidence-bundle.md's
+ * own carve-out language for the analogous envelope field treats "absent"
+ * and "an empty array" as one thing (envelope-spec.md §7.1). A non-array
+ * value (malformed shape, but the field is reserved, not yet specified)
+ * still counts as present: it is not the well-formed absence either rule
+ * describes.
+ */
+export function coSignaturesPresent(b: unknown): boolean {
+  if (b === null || typeof b !== "object" || Array.isArray(b)) return false;
+  const value = (b as Record<string, unknown>).co_signatures;
+  if (!("co_signatures" in (b as Record<string, unknown>)) || value === null || value === undefined) {
+    return false;
+  }
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+
+function coSignaturesNote(bundle: unknown): string | undefined {
+  return coSignaturesPresent(bundle) ? CO_SIGNATURES_NOTE : undefined;
+}
+
 function isEvidenceMajorAccepted(specVersion: unknown): boolean {
   if (typeof specVersion !== "string" || specVersion === "") return false;
   return ACCEPTED_EVIDENCE_MAJORS.some((m) => {
@@ -692,6 +737,10 @@ function isEvidenceMajorAccepted(specVersion: unknown): boolean {
  * (`evidence-bundle.md` 5.5.1), so reporting `false` here let a holder who
  * broke its own body shape read as a forger.
  */
+/** evidence-bundle §2 (A31). Byte-identical to the Python kernel's. */
+export const GENERATED_AT_MALFORMED =
+  "malformed generated_at: not an RFC 3339 UTC date-time with Z naming a real date and time (evidence-bundle §2)";
+
 function malformed(error: string, specVersionOk = false, wrapperOk = false): EvidenceBundleResult {
   return {
     status: "malformed",
@@ -712,7 +761,9 @@ function malformed(error: string, specVersionOk = false, wrapperOk = false): Evi
  * the Python kernel writes too. Anything outside this set comes from the host:
  * a JSON parser, a codec, a crypto library. See `thrownDetail`.
  */
-const KERNEL_WORDING = ["hexToBytes: "];
+// `duplicate key ` is `DuplicateKeyError` in `verifier.ts`, which
+// `DuplicateKey` in the Python twin's `canonicalize.py` words identically.
+const KERNEL_WORDING = ["hexToBytes: ", "duplicate key "];
 
 /**
  * The detail a finding may append about a caught exception.
@@ -730,6 +781,27 @@ const KERNEL_WORDING = ["hexToBytes: "];
  * is the host's parse offset, which no reader can act on and which was never
  * the same in the two kernels.
  */
+/**
+ * The kernel's `duplicate key "<name>"` when a record repeats a member name,
+ * else `undefined` (proof#144; `_record_duplicate_key` in the Python twin).
+ *
+ * ONLY A DUPLICATE, and not every unreadable record. Every reader below this
+ * one that parses a record treats an unreadable one as absent, so the content
+ * binding reads undetermined and the pack said "1 record discloses no bytes"
+ * about a record whose bytes it had read. A record that repeats a name is
+ * a defect in the artifact, and a defect this kernel can see fails, the rule
+ * `event_bytes` that are not hex already follow.
+ */
+function recordDuplicateKey(eventBytes: Uint8Array | undefined): string | undefined {
+  if (eventBytes === undefined) return undefined;
+  try {
+    jcsParse(eventBytes);
+  } catch (e) {
+    if (e instanceof DuplicateKeyError) return e.message;
+  }
+  return undefined;
+}
+
 function thrownDetail(e: unknown): string {
   const text = e instanceof Error ? e.message : String(e);
   return KERNEL_WORDING.some((w) => text.startsWith(w)) ? `: ${text}` : "";
@@ -806,7 +878,17 @@ export async function verifyEvidenceBundle(
   bundle: unknown,
   options: VerifyEvidenceOptions = {},
 ): Promise<EvidenceBundleResult> {
-  return verifyBundle(bundle, options, false);
+  // The ONE place a present `co_signatures` becomes a note, so every caller
+  // (including `case.ts`, which calls this function directly per pack) gets
+  // it, however the wrapper otherwise verifies. Never touches `status` or
+  // the exit code: a bundle that would otherwise verify still verifies, note
+  // or not (proof#148).
+  const result = await verifyBundle(bundle, options, false);
+  const note = coSignaturesNote(bundle);
+  if (note !== undefined) {
+    result.notes = [...(result.notes ?? []), note];
+  }
+  return result;
 }
 
 // `exportSource`: read the bundle as an export's source (evidence-export.md
@@ -917,6 +999,19 @@ async function verifyBundle(
     };
   }
 
+  // --- The wrapper's own time (evidence-bundle §2, A31) ---------------------
+  // `generated_at` is copied into a recomputed verdict's `as_of` (the export
+  // reading) and printed beside every verdict, so a present value that is not
+  // the RFC 3339 form `signed_at` already pins is a wrapper this kernel cannot
+  // render, whatever its signature. It is read only once the wrapper holds: a
+  // broken wrapper is `failed` above, as it was. Absence is unchanged.
+  if (
+    Object.prototype.hasOwnProperty.call(b, "generated_at") &&
+    !isRfc3339UtcInstant((b as { generated_at?: unknown }).generated_at)
+  ) {
+    return malformed(GENERATED_AT_MALFORMED, specVersionOk, true);
+  }
+
   // --- Body dispatch ---------------------------------------------------------
   const bodyType = typeof b.body_type === "string" ? b.body_type : null;
 
@@ -1390,6 +1485,11 @@ async function verifyAnchorTrace(
       eventBytesMalformed = true;
       evErrors.push(`event event_bytes is not hex${thrownDetail(e)}`);
     }
+    const duplicate = recordDuplicateKey(eventBytes);
+    if (duplicate !== undefined) {
+      eventBytesMalformed = true;
+      evErrors.push(`event record is not JSON: ${duplicate}`);
+    }
     try {
       const res = await verifyEnvelope(
         ev.envelope,
@@ -1945,6 +2045,10 @@ async function verifyStampEntry(
     if (typeof body[f] !== "string" || body[f] === "") {
       errors.push(`stamp body ${f} is missing or not a non-empty string`);
       base.bodyOk = false;
+    } else if (f !== "org_ref" && !isRfc3339UtcInstant(body[f])) {
+      // §5.2 (A31): the promise window is the form `signed_at` pins.
+      errors.push(`stamp body ${f} is not an RFC 3339 UTC date-time with Z naming a real date and time`);
+      base.bodyOk = false;
     }
   }
   base.intervalStart = typeof body.interval_start === "string" ? body.interval_start : null;
@@ -2255,6 +2359,11 @@ async function verifyStampEvidence(
       eventBytesMalformed = true;
       evErrors.push(`event event_bytes is not hex${thrownDetail(e)}`);
     }
+    const duplicate = recordDuplicateKey(eventBytes);
+    if (duplicate !== undefined) {
+      eventBytesMalformed = true;
+      evErrors.push(`event record is not JSON: ${duplicate}`);
+    }
     try {
       const res = await verifyEnvelope(
         ev.envelope,
@@ -3084,6 +3193,10 @@ function payloadFieldError(payload: Record<string, unknown>): string | null {
       want = "1, 2 or 3";
     }
     if (!ok) return `attestation payload field ${JSON.stringify(name)} is missing or not ${want}`;
+    if (name === "attested_at" && !isRfc3339UtcInstant(v)) {
+      // evidence-export §3.1 (v3.4): the form `signed_at` pins.
+      return 'attestation payload field "attested_at" is not an RFC 3339 UTC date-time with Z naming a real date and time';
+    }
   }
   return null;
 }

package/src/file-match.ts

@@ -0,0 +1,461 @@
+/**
+ * Files handed in beside a pack, matched against what its records signed (A29).
+ *
+ * The TypeScript half of `src/sanning_proof/file_match.py`. Both kernels are
+ * held to one table, `vectors/file-match.json`, so neither can pass by agreeing
+ * with the other, and `cross-kernel/run_file_match.sh` holds the two readings,
+ * and the two commands' `--files` output, to the same bytes.
+ *
+ * WHAT THIS ANSWERS (evidence-bundle.md 5.7 v1.24, proof#92, decided by Phil
+ * 2026-09-23 as option 2). A reader holds a pack and some files beside it and
+ * asks whether the pack vouches for them. Each offered file is hashed, SHA-256
+ * over its exact bytes, and the digest is looked for among the commitments the
+ * pack's SIGNED records make. The reading says which offered files a record
+ * commits to (naming the record, its signer and its `signed_at`), which match
+ * no record, and which commitments had no file offered.
+ *
+ * THE RULES THAT CARRY THE WEIGHT:
+ *
+ *   - By hash, and by nothing else. A file's name is carried through as the
+ *     caller's label and is never compared with an `event_id`, a part's name or
+ *     a `logs/` path. There is no layout convention.
+ *   - Unmatched is reported, never guessed.
+ *   - Only what a record's own key signed: a verified envelope whose
+ *     `event_bytes` bind to its `payload_hash`, or a hand-off message whose
+ *     bytes bind to that record's `message_hash`. No wrapper field is read.
+ *   - The verdict does not move. A match proves that a signed record in the
+ *     pack committed to those exact bytes, and nothing more (`FILE_MATCH_SCOPE`).
+ *
+ * WHAT COUNTS AS A COMMITMENT, in record order and then part order:
+ *
+ *   1. `record`: a record outside envelope-spec.md 4.1 commits through
+ *      `event.content_hash`, 64 hex characters in either case.
+ *   2. `file_part`: a record 4.1 governs commits to its MESSAGE through
+ *      `event.message_hash` (5.1, A20), never through a `content_hash` it also
+ *      writes. Where the message's JCS bytes are in hand (in the body, or in
+ *      the side content) and bind to it, each file part of that message (A18)
+ *      commits by its `content_hash`.
+ *
+ * Side content is read for ONE thing, to find a hand-off message that binds to
+ * a signed `message_hash`. It is never an offered file.
+ *
+ * Pure: a bundle, the files and the optional side content in, a reading out.
+ */
+
+import { hexToBytes, isHexField, sha256Hex } from "./crypto.js";
+import { resolveTraceEvents } from "./evidence.js";
+import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
+import type { HeldRecord } from "./handoff.js";
+import { isFilePart } from "./message-parts.js";
+import { sideContentEntry } from "./side-content.js";
+import type { SideContentMap } from "./side-content.js";
+import type { Envelope } from "./types.js";
+import { jcsParse, verifyEnvelope } from "./verifier.js";
+
+/** The one sentence every surface prints with the reading (5.7). */
+export const FILE_MATCH_SCOPE =
+  "A match proves that a signed record in the pack committed to these exact " +
+  "bytes, and nothing more.";
+
+/** Why a record's commitments could not be read, in the order they are tested. */
+export const NOT_READ_REASONS = [
+  "no_records",
+  "record_unreadable",
+  "record_not_verified",
+  "record_withheld",
+  "no_content_hash",
+  "handoff_record_malformed",
+  "message_withheld",
+] as const;
+
+export type NotReadReason = (typeof NOT_READ_REASONS)[number];
+
+const REASON_TEXT: Record<NotReadReason, string> = {
+  no_records: "this bundle carries no records this reading can read",
+  record_unreadable: "its record bytes cannot be read",
+  record_not_verified: "its envelope does not verify",
+  record_withheld: "its record bytes are withheld",
+  no_content_hash: "it commits to no content_hash",
+  handoff_record_malformed:
+    "it is a hand-off record that commits to no message a reader can bind to",
+  message_withheld: "its message is not in hand, so its file parts cannot be read",
+};
+
+// The accept-set minus the quarantined `sanning.mlflow/v1` (DL-63), the set
+// both kernels read a case under.
+const RECORD_PROFILES = ["sanning.agent/v1", "sanning.events/v2"] as const;
+
+/** One commitment a signed record makes to a file's bytes. */
+export interface FileCommitment {
+  packRef: string | null;
+  eventId: string | null;
+  kind: "record" | "file_part";
+  partIndex: number | null;
+  contentHash: string;
+  signer: string;
+  signedAt: string | null;
+}
+
+export interface MatchedFile {
+  name: string;
+  sha256: string;
+  records: FileCommitment[];
+}
+
+export interface UnmatchedFile {
+  name: string;
+  sha256: string;
+}
+
+export interface NotRead {
+  packRef: string | null;
+  eventId: string | null;
+  reason: NotReadReason;
+}
+
+export interface FileMatchReading {
+  offered: number;
+  matched: MatchedFile[];
+  unmatched: UnmatchedFile[];
+  notOffered: FileCommitment[];
+  notRead: NotRead[];
+  scope: string;
+}
+
+/** A file handed in beside a pack. `name` is a label and is never compared. */
+export interface OfferedFile {
+  name: string;
+  bytes: Uint8Array;
+}
+
+/** One pack of a case, for `matchCaseFiles`. */
+export interface FileMatchPack {
+  ref: string;
+  bundle: unknown;
+  content?: SideContentMap | null;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function strOrNull(v: unknown): string | null {
+  return typeof v === "string" ? v : null;
+}
+
+function own(o: Record<string, unknown>, key: string): unknown {
+  return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
+}
+
+// The envelope's key and signature in the hex charset at their lengths, the
+// reading every body verifier applies inside a bundle (proof#142).
+function envelopeSpelled(envelope: Record<string, unknown>): boolean {
+  for (const [name, nibbles] of [
+    ["public_key", 64],
+    ["signature", 128],
+  ] as const) {
+    const value = own(envelope, name);
+    if (typeof value === "string" && !isHexField(value, nibbles)) return false;
+  }
+  return true;
+}
+
+function decode(value: unknown): Uint8Array | undefined {
+  if (value instanceof Uint8Array) return value;
+  if (typeof value === "string") {
+    try {
+      return hexToBytes(value);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+const ABSENT = Symbol("absent");
+
+async function messageOf(
+  ev: Record<string, unknown>,
+  eventId: string | null,
+  messageHash: string,
+  content: SideContentMap | null | undefined,
+): Promise<unknown> {
+  const candidates = [decode(own(ev, "content"))];
+  if (eventId !== null) candidates.push(decode(sideContentEntry(content, eventId).value));
+  for (const raw of candidates) {
+    if (raw === undefined || (await sha256Hex(raw)) !== messageHash) continue;
+    try {
+      return jcsParse(raw);
+    } catch {
+      continue;
+    }
+  }
+  return ABSENT;
+}
+
+async function readPack(
+  bundle: unknown,
+  content: SideContentMap | null | undefined,
+  packRef: string | null,
+): Promise<{ commitments: FileCommitment[]; notRead: NotRead[] }> {
+  const commitments: FileCommitment[] = [];
+  const notRead: NotRead[] = [];
+  const events = resolveTraceEvents(bundle) as unknown[] | undefined;
+  if (events === undefined) {
+    notRead.push({ packRef, eventId: null, reason: "no_records" });
+    return { commitments, notRead };
+  }
+  for (const ev of events) {
+    if (!isObject(ev)) {
+      notRead.push({ packRef, eventId: null, reason: "record_unreadable" });
+      continue;
+    }
+    const envelope = own(ev, "envelope");
+    const eventId = isObject(envelope) ? strOrNull(own(envelope, "event_id")) : null;
+
+    const rawBytes = own(ev, "event_bytes");
+    let eventBytes: Uint8Array | undefined;
+    if (rawBytes !== undefined && rawBytes !== null) {
+      eventBytes = typeof rawBytes === "string" ? decode(rawBytes) : undefined;
+      if (eventBytes === undefined) {
+        notRead.push({ packRef, eventId, reason: "record_unreadable" });
+        continue;
+      }
+    }
+
+    const result = await verifyEnvelope(envelope as Envelope, {
+      ...(eventBytes !== undefined ? { payloadBytes: eventBytes } : {}),
+      acceptedSpecMajors: RECORD_PROFILES,
+    });
+    if (!result.ok || !isObject(envelope) || !envelopeSpelled(envelope)) {
+      notRead.push({ packRef, eventId, reason: "record_not_verified" });
+      continue;
+    }
+    if (eventBytes === undefined) {
+      notRead.push({ packRef, eventId, reason: "record_withheld" });
+      continue;
+    }
+    if (result.payloadHashOk !== true) {
+      notRead.push({ packRef, eventId, reason: "record_not_verified" });
+      continue;
+    }
+    let record: unknown;
+    try {
+      record = jcsParse(eventBytes);
+    } catch {
+      record = undefined;
+    }
+    if (!isObject(record)) {
+      notRead.push({ packRef, eventId, reason: "record_unreadable" });
+      continue;
+    }
+
+    const key = own(envelope, "public_key");
+    const signer = typeof key === "string" ? key : "";
+    const signedAt = strOrNull(own(envelope, "signed_at"));
+    const section = own(record, "event");
+    const event = isObject(section) ? section : {};
+
+    const held: HeldRecord = {
+      publicKey: signer,
+      record: record as HeldRecord["record"],
+      ref: "",
+    };
+    if (isHandoffNamespace(held)) {
+      const messageHash = own(event, "message_hash");
+      if (!isConformantHandoffRecord(held) || !isHexField(messageHash, 64, true)) {
+        notRead.push({ packRef, eventId, reason: "handoff_record_malformed" });
+        continue;
+      }
+      const message = await messageOf(ev, eventId, messageHash, content);
+      if (message === ABSENT) {
+        notRead.push({ packRef, eventId, reason: "message_withheld" });
+        continue;
+      }
+      const parts = isObject(message) ? own(message, "parts") : undefined;
+      if (Array.isArray(parts)) {
+        parts.forEach((part, index) => {
+          if (!isFilePart(part)) return;
+          commitments.push({
+            packRef,
+            eventId,
+            kind: "file_part",
+            partIndex: index,
+            contentHash: ((part as { content_hash: string }).content_hash).toLowerCase(),
+            signer,
+            signedAt,
+          });
+        });
+      }
+      continue;
+    }
+
+    const contentHash = own(event, "content_hash");
+    if (!isHexField(contentHash, 64)) {
+      notRead.push({ packRef, eventId, reason: "no_content_hash" });
+      continue;
+    }
+    commitments.push({
+      packRef,
+      eventId,
+      kind: "record",
+      partIndex: null,
+      contentHash: contentHash.toLowerCase(),
+      signer,
+      signedAt,
+    });
+  }
+  return { commitments, notRead };
+}
+
+// A malformed file entry is the CALLER's mistake, not the evidence's, so it
+// throws rather than reading as a file that matched nothing.
+async function offeredDigests(files: readonly OfferedFile[]): Promise<[string, string][]> {
+  const out: [string, string][] = [];
+  for (const entry of files) {
+    if (!isObject(entry)) throw new TypeError("matchFiles: each file is an object {name, bytes}");
+    const { name, bytes } = entry as { name?: unknown; bytes?: unknown };
+    if (typeof name !== "string") throw new TypeError("matchFiles: a file's name is a string");
+    if (!(bytes instanceof Uint8Array)) {
+      throw new TypeError("matchFiles: a file's bytes are a Uint8Array");
+    }
+    out.push([name, await sha256Hex(bytes)]);
+  }
+  return out;
+}
+
+async function match(
+  commitments: FileCommitment[],
+  notRead: NotRead[],
+  files: readonly OfferedFile[],
+): Promise<FileMatchReading> {
+  const offered = await offeredDigests(files);
+  const matched: MatchedFile[] = [];
+  const unmatched: UnmatchedFile[] = [];
+  const used = new Set<number>();
+  for (const [name, digest] of offered) {
+    const hits: number[] = [];
+    commitments.forEach((c, i) => {
+      if (c.contentHash === digest) hits.push(i);
+    });
+    if (hits.length > 0) {
+      for (const i of hits) used.add(i);
+      matched.push({ name, sha256: digest, records: hits.map((i) => commitments[i]!) });
+    } else {
+      unmatched.push({ name, sha256: digest });
+    }
+  }
+  return {
+    offered: offered.length,
+    matched,
+    unmatched,
+    notOffered: commitments.filter((_, i) => !used.has(i)),
+    notRead,
+    scope: FILE_MATCH_SCOPE,
+  };
+}
+
+/**
+ * Match each offered file against the commitments one pack's signed records
+ * make. `content` is the side content handed in beside the pack, read only to
+ * find a hand-off message that binds to its record's `message_hash`; it is
+ * never an offered file.
+ */
+export async function matchFiles(
+  bundle: unknown,
+  files: readonly OfferedFile[],
+  content?: SideContentMap | null,
+): Promise<FileMatchReading> {
+  const { commitments, notRead } = await readPack(bundle, content, null);
+  return match(commitments, notRead, files);
+}
+
+/** The same reading over every pack of a case, each commitment naming its pack's `ref`. */
+export async function matchCaseFiles(
+  packs: readonly FileMatchPack[],
+  files: readonly OfferedFile[],
+): Promise<FileMatchReading> {
+  const commitments: FileCommitment[] = [];
+  const notRead: NotRead[] = [];
+  for (const pack of packs) {
+    if (!isObject(pack)) throw new TypeError("matchCaseFiles: each pack is an object {ref, bundle}");
+    if (typeof pack.ref !== "string") throw new TypeError("matchCaseFiles: a pack's ref is a string");
+    const r = await readPack(pack.bundle, pack.content, pack.ref);
+    commitments.push(...r.commitments);
+    notRead.push(...r.notRead);
+  }
+  return match(commitments, notRead, files);
+}
+
+function commitmentJson(c: FileCommitment): Record<string, unknown> {
+  return {
+    pack_ref: c.packRef,
+    event_id: c.eventId,
+    kind: c.kind,
+    part_index: c.partIndex,
+    content_hash: c.contentHash,
+    signer: c.signer,
+    signed_at: c.signedAt,
+  };
+}
+
+/** The reading as the `files` member of `--json`, identical in both kernels. */
+export function fileMatchToJson(reading: FileMatchReading): Record<string, unknown> {
+  return {
+    offered: reading.offered,
+    matched: reading.matched.map((m) => ({
+      name: m.name,
+      sha256: m.sha256,
+      records: m.records.map(commitmentJson),
+    })),
+    unmatched: reading.unmatched.map((u) => ({ name: u.name, sha256: u.sha256 })),
+    not_offered: reading.notOffered.map(commitmentJson),
+    not_read: reading.notRead.map((n) => ({
+      pack_ref: n.packRef,
+      event_id: n.eventId,
+      reason: n.reason,
+      rendered: renderNotRead(n),
+    })),
+    scope: reading.scope,
+  };
+}
+
+function recordName(eventId: string | null): string {
+  return eventId !== null ? `record ${eventId}` : "a record with no event_id";
+}
+
+function renderCommitment(c: FileCommitment): string {
+  const what =
+    c.kind === "record"
+      ? recordName(c.eventId)
+      : `file part ${c.partIndex} of the message in ${recordName(c.eventId)}`;
+  const where = c.packRef !== null ? ` in pack ${c.packRef}` : "";
+  const when = c.signedAt !== null ? c.signedAt : "no stated time";
+  return `${what}${where}, signed by ${c.signer}, signed_at ${when}`;
+}
+
+function renderNotRead(n: NotRead): string {
+  const where = n.packRef !== null ? ` in pack ${n.packRef}` : "";
+  if (n.reason === "no_records") return `no record read${where}: ${REASON_TEXT[n.reason]}`;
+  return `${recordName(n.eventId)}${where} not read: ${REASON_TEXT[n.reason]}`;
+}
+
+/** The text report's lines for the reading, identical in both kernels. */
+export function renderFileMatch(reading: FileMatchReading): string[] {
+  const lines = [
+    `files         ${reading.offered} offered: ${reading.matched.length} vouched for, ` +
+      `${reading.unmatched.length} match no record; ` +
+      `${reading.notOffered.length} commitment(s) had no file offered`,
+  ];
+  for (const m of reading.matched) {
+    lines.push(`  vouched for  ${m.name}  sha256 ${m.sha256}`);
+    for (const c of m.records) lines.push(`    by ${renderCommitment(c)}`);
+  }
+  for (const u of reading.unmatched) lines.push(`  no match     ${u.name}  sha256 ${u.sha256}`);
+  for (const c of reading.notOffered) {
+    lines.push(`  not offered  ${c.contentHash}, ${renderCommitment(c)}`);
+  }
+  for (const n of reading.notRead) lines.push(`  not read     ${renderNotRead(n)}`);
+  lines.push(`  ${reading.scope}`);
+  return lines;
+}