@sanning/proof 0.13.0 → 0.15.0

package/dist/evidence.js

@@ -23,7 +23,7 @@ import { deriveOperatorAddress, ed25519Verify, hexToBytes,
 isHexField, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
-import { MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, jcs, jcsParse, verifyEnvelope, } from "./verifier.js";
+import { DuplicateKeyError, MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, isRfc3339UtcInstant, jcs, jcsParse, verifyEnvelope, } from "./verifier.js";
 import { inBodyContentOffered, sideContentEntry, } from "./side-content.js";
 // Only the evidence-bundle major(s) this kernel verifies. A new major is a
 // deliberate one-entry addition HERE — same fail-closed discipline as the
@@ -108,6 +108,41 @@ export const STAMP_EVIDENCE_BODY_TYPE = "sanning.stamp.evidence/v2";
  * signature is the §5.1.2 mixed-vocabulary reject, one layer down.
  */
 export const STAMP_BODY_VERSION = "sanning.stamp/v1";
+/**
+ * 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) {
+    if (b === null || typeof b !== "object" || Array.isArray(b))
+        return false;
+    const value = b.co_signatures;
+    if (!("co_signatures" in b) || value === null || value === undefined) {
+        return false;
+    }
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+function coSignaturesNote(bundle) {
+    return coSignaturesPresent(bundle) ? CO_SIGNATURES_NOTE : undefined;
+}
 function isEvidenceMajorAccepted(specVersion) {
     if (typeof specVersion !== "string" || specVersion === "")
         return false;
@@ -131,6 +166,8 @@ function isEvidenceMajorAccepted(specVersion) {
  * (`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, specVersionOk = false, wrapperOk = false) {
     return {
         status: "malformed",
@@ -150,7 +187,9 @@ function malformed(error, specVersionOk = false, wrapperOk = false) {
  * 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.
  *
@@ -167,6 +206,29 @@ 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) {
+    if (eventBytes === undefined)
+        return undefined;
+    try {
+        jcsParse(eventBytes);
+    }
+    catch (e) {
+        if (e instanceof DuplicateKeyError)
+            return e.message;
+    }
+    return undefined;
+}
 function thrownDetail(e) {
     const text = e instanceof Error ? e.message : String(e);
     return KERNEL_WORDING.some((w) => text.startsWith(w)) ? `: ${text}` : "";
@@ -237,7 +299,17 @@ function jsonStr(value) {
 // (`assertedStatus`) but NEVER trusted — the displayed status is the one this
 // function recomputes (evidence-bundle §1 principle 3 / §4 step 4).
 export async function verifyEvidenceBundle(bundle, options = {}) {
-    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
 // §2.4), where the only recognised body is `sanning.anchor.trace/v3`.
@@ -339,6 +411,16 @@ async function verifyBundle(bundle, options, exportSource) {
             errors,
         };
     }
+    // --- 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.generated_at)) {
+        return malformed(GENERATED_AT_MALFORMED, specVersionOk, true);
+    }
     // --- Body dispatch ---------------------------------------------------------
     const bodyType = typeof b.body_type === "string" ? b.body_type : null;
     // Read as an export's source (evidence-export.md §2.4), the only body this
@@ -767,6 +849,11 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
             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, eventBytes !== undefined ? { payloadBytes: eventBytes } : {});
             const hexError = envelopeHexError("event", ev.envelope);
@@ -1280,6 +1367,11 @@ async function verifyStampEntry(raw, seen) {
             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;
     base.intervalEnd = typeof body.interval_end === "string" ? body.interval_end : null;
@@ -1553,6 +1645,11 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
             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, eventBytes !== undefined ? { payloadBytes: eventBytes } : {});
             const hexError = envelopeHexError("event", ev.envelope);
@@ -2220,6 +2317,10 @@ function payloadFieldError(payload) {
         }
         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/dist/file-match.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 type { SideContentMap } from "./side-content.js";
+/** The one sentence every surface prints with the reading (5.7). */
+export declare const FILE_MATCH_SCOPE: string;
+/** Why a record's commitments could not be read, in the order they are tested. */
+export declare const NOT_READ_REASONS: readonly ["no_records", "record_unreadable", "record_not_verified", "record_withheld", "no_content_hash", "handoff_record_malformed", "message_withheld"];
+export type NotReadReason = (typeof NOT_READ_REASONS)[number];
+/** 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;
+}
+/**
+ * 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 declare function matchFiles(bundle: unknown, files: readonly OfferedFile[], content?: SideContentMap | null): Promise<FileMatchReading>;
+/** The same reading over every pack of a case, each commitment naming its pack's `ref`. */
+export declare function matchCaseFiles(packs: readonly FileMatchPack[], files: readonly OfferedFile[]): Promise<FileMatchReading>;
+/** The reading as the `files` member of `--json`, identical in both kernels. */
+export declare function fileMatchToJson(reading: FileMatchReading): Record<string, unknown>;
+/** The text report's lines for the reading, identical in both kernels. */
+export declare function renderFileMatch(reading: FileMatchReading): string[];

package/dist/file-match.js

@@ -0,0 +1,374 @@
+/**
+ * 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 { isFilePart } from "./message-parts.js";
+import { sideContentEntry } from "./side-content.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",
+];
+const REASON_TEXT = {
+    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"];
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function strOrNull(v) {
+    return typeof v === "string" ? v : null;
+}
+function own(o, key) {
+    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) {
+    for (const [name, nibbles] of [
+        ["public_key", 64],
+        ["signature", 128],
+    ]) {
+        const value = own(envelope, name);
+        if (typeof value === "string" && !isHexField(value, nibbles))
+            return false;
+    }
+    return true;
+}
+function decode(value) {
+    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, eventId, messageHash, content) {
+    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, content, packRef) {
+    const commitments = [];
+    const notRead = [];
+    const events = resolveTraceEvents(bundle);
+    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;
+        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, {
+            ...(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;
+        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 = {
+            publicKey: signer,
+            record: 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.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) {
+    const out = [];
+    for (const entry of files) {
+        if (!isObject(entry))
+            throw new TypeError("matchFiles: each file is an object {name, bytes}");
+        const { name, bytes } = entry;
+        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, notRead, files) {
+    const offered = await offeredDigests(files);
+    const matched = [];
+    const unmatched = [];
+    const used = new Set();
+    for (const [name, digest] of offered) {
+        const hits = [];
+        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, files, content) {
+    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, files) {
+    const commitments = [];
+    const 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) {
+    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) {
+    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) {
+    return eventId !== null ? `record ${eventId}` : "a record with no event_id";
+}
+function renderCommitment(c) {
+    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) {
+    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) {
+    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;
+}