@sanning/proof 0.19.0 → 0.20.0

package/dist/exit-codes.d.ts

@@ -1,35 +1,19 @@
 export declare const EXIT_VERIFIED = 0;
 export declare const EXIT_FAILED = 1;
-export declare const EXIT_MALFORMED = 2;
-export declare const EXIT_UNDETERMINED = 3;
-export declare const EXIT_MIXED = 4;
+export declare const EXIT_INCOMPLETE = 2;
 /**
- * Sandbox evidence (envelope-spec §2): a run that would exit 0 over a pack or
- * case holding a record signed `environment: "dev"`, or a run over records
- * that are ALL signed `dev` whose only unsettled witnesses are simulated.
- * Not a verdict word: the verdict stays what the checks established
- * (`sandboxExit`). No flag turns 5 into 0.
- */
-export declare const EXIT_SANDBOX = 5;
-/**
- * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
- * `undetermined` is the name of 3, and never a word here.
+ * Not a verdict: the verdict is `verified` and a record is signed `environment: "dev"`
+ * (envelope-spec section 2). A failed or incomplete sandbox run keeps 1 or 2.
  */
+export declare const EXIT_SANDBOX = 3;
+/** A bad flag, a missing file, or an input that is not a pack or a case at all. */
+export declare const EXIT_COULD_NOT_RUN = 4;
+/** The exit code of each verdict (`evidence-bundle.md` section 3). */
 export declare const EXIT_CODES: Readonly<Record<string, number>>;
-/** What every verb's help prints, identical in both commands. */
+/** What every verb's help prints. */
 export declare const EXIT_CODES_HELP: string;
 /**
- * The exit code of a verdict word. A word outside the eight is a verdict
- * nothing can render, so it exits 2, never 0.
- */
-export declare function exitCodeFor(verdict: unknown): number;
-/**
- * The code a verb exits with once the environment marker is read. 5 where the
- * run would otherwise exit 0 and the pack or case holds a record signed `dev`;
- * 5 where the run is undetermined only because a simulated witness could not
- * be looked up (`onlySimulatedUnsettled`, which the caller works out) and
- * EVERY record is signed `dev`, so a production or mixed pack carrying a
- * simulated witness keeps 3; the code unchanged everywhere else. A failure
- * stays 1, malformed 2 and mixed 4.
+ * The exit code of a verdict. `verified` over a record signed `dev` is 3. A value outside
+ * the three verdicts is 4, never 0.
  */
-export declare function sandboxExit(code: number, environmentMarker: string | null, onlySimulatedUnsettled?: boolean): number;
+export declare function exitCodeFor(verdict: unknown, environmentMarker?: string | null): number;

package/dist/exit-codes.js

@@ -1,75 +1,40 @@
-// One exit-code table for every verb (0.13.0).
-//
-// Both commands, `npx @sanning/proof` and `sanning-proof`, map a verdict word to
-// an exit code through this one table, for `verify`, `case` and `export` alike,
-// and every verb's `--help` prints `EXIT_CODES_HELP` byte for byte. The twin is
-// `src/sanning_proof/exit_codes.py`; the specification is `evidence-export.md`
-// §5.
-//
-// Until 0.13.0 `verify` exited 0 on `partial` unless a gateway was unreachable,
-// while `case` exited 3 on it, so a CI gate reading `verify`'s exit code read a
-// stamp witnessed by nobody as verified. Every word that means "could not be
-// settled" now exits 3, which is the code's name: undetermined.
+// One exit-code table for every verb (`verify`, `case`, `export`), shared by both
+// commands. Every verb's `--help` prints `EXIT_CODES_HELP` byte for byte
+// (evidence-export.md section 5).
 export const EXIT_VERIFIED = 0;
 export const EXIT_FAILED = 1;
-export const EXIT_MALFORMED = 2;
-export const EXIT_UNDETERMINED = 3;
-export const EXIT_MIXED = 4;
+export const EXIT_INCOMPLETE = 2;
 /**
- * Sandbox evidence (envelope-spec §2): a run that would exit 0 over a pack or
- * case holding a record signed `environment: "dev"`, or a run over records
- * that are ALL signed `dev` whose only unsettled witnesses are simulated.
- * Not a verdict word: the verdict stays what the checks established
- * (`sandboxExit`). No flag turns 5 into 0.
- */
-export const EXIT_SANDBOX = 5;
-/**
- * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
- * `undetermined` is the name of 3, and never a word here.
+ * Not a verdict: the verdict is `verified` and a record is signed `environment: "dev"`
+ * (envelope-spec section 2). A failed or incomplete sandbox run keeps 1 or 2.
  */
+export const EXIT_SANDBOX = 3;
+/** A bad flag, a missing file, or an input that is not a pack or a case at all. */
+export const EXIT_COULD_NOT_RUN = 4;
+/** The exit code of each verdict (`evidence-bundle.md` section 3). */
 export const EXIT_CODES = Object.freeze({
     verified: EXIT_VERIFIED,
     failed: EXIT_FAILED,
-    malformed: EXIT_MALFORMED,
-    partial: EXIT_UNDETERMINED,
-    pending: EXIT_UNDETERMINED,
-    incomplete: EXIT_UNDETERMINED,
-    not_found: EXIT_UNDETERMINED,
-    mixed: EXIT_MIXED,
+    incomplete: EXIT_INCOMPLETE,
 });
-/** What every verb's help prints, identical in both commands. */
+/** What every verb's help prints. */
 export const EXIT_CODES_HELP = [
     "Exit codes, one table for every verb:",
-    "  0  verified, or the export was written",
-    "  1  failed",
-    "  2  usage or malformed",
-    "  3  undetermined: partial, pending, incomplete or not_found",
-    "  4  mixed: more than one outcome, none failed; read the exceptions",
-    "  5  sandbox: a record is signed environment dev; would be 0, or only a simulated witness is unchecked",
+    "  0  verified: every claim in scope is proven; export: the export was written",
+    "  1  failed: a claim is disproven",
+    "  2  incomplete: nothing is disproven and a claim is not proven",
+    "  3  sandbox: verified, and a record is signed environment dev",
+    "  4  could not run: a bad flag, a missing file, or an input that is not a pack or case",
 ].join("\n");
 /**
- * The exit code of a verdict word. A word outside the eight is a verdict
- * nothing can render, so it exits 2, never 0.
+ * The exit code of a verdict. `verified` over a record signed `dev` is 3. A value outside
+ * the three verdicts is 4, never 0.
  */
-export function exitCodeFor(verdict) {
-    if (typeof verdict === "string" && Object.prototype.hasOwnProperty.call(EXIT_CODES, verdict)) {
-        return EXIT_CODES[verdict];
+export function exitCodeFor(verdict, environmentMarker = null) {
+    if (typeof verdict !== "string" || !Object.prototype.hasOwnProperty.call(EXIT_CODES, verdict)) {
+        return EXIT_COULD_NOT_RUN;
     }
-    return EXIT_MALFORMED;
-}
-/**
- * The code a verb exits with once the environment marker is read. 5 where the
- * run would otherwise exit 0 and the pack or case holds a record signed `dev`;
- * 5 where the run is undetermined only because a simulated witness could not
- * be looked up (`onlySimulatedUnsettled`, which the caller works out) and
- * EVERY record is signed `dev`, so a production or mixed pack carrying a
- * simulated witness keeps 3; the code unchanged everywhere else. A failure
- * stays 1, malformed 2 and mixed 4.
- */
-export function sandboxExit(code, environmentMarker, onlySimulatedUnsettled = false) {
-    if (code === EXIT_VERIFIED && environmentMarker !== null)
-        return EXIT_SANDBOX;
-    if (code === EXIT_UNDETERMINED && environmentMarker === "dev" && onlySimulatedUnsettled)
+    if (verdict === "verified" && environmentMarker !== null)
         return EXIT_SANDBOX;
-    return code;
+    return EXIT_CODES[verdict];
 }

package/dist/file-match.d.ts

@@ -1,56 +1,30 @@
 /**
- * Files handed in beside a pack, matched against what its records signed (A29).
+ * Matches files handed in beside a pack against the commitments its signed
+ * records make (evidence-bundle.md §5.7). Conformance: `vectors/file-match.json`.
  *
- * 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.
+ * - Matching is by SHA-256 of the exact bytes only. A file's name is a label
+ *   and is never compared with an `event_id`, a part name or a path.
+ * - Unmatched is reported, never guessed.
+ * - Only what a record's own key signed counts: 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 (`FILE_MATCH_SCOPE`).
  *
- * 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.
+ * A record outside envelope-spec.md §4.1 commits through `event.content_hash`.
+ * A hand-off record commits to its message through `event.message_hash`, and,
+ * where the message bytes are in hand and bind, each file part of that message
+ * commits by its `content_hash`. Side content is read only to find such a
+ * message; it is never an offered file.
  */
 import type { SideContentMap } from "./side-content.js";
-/** The one sentence every surface prints with the reading (5.7). */
+/** The scope 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];
 /**
- * Why a file was named in the report and never hashed (5.7.5). A skipped file
- * is listed, never dropped: every file a command found is matched, unmatched or
- * skipped, so "no match" is never read as "no file was there".
+ * Why a found file was not hashed (§5.7.5). A skipped file is listed, never
+ * dropped, so "no match" is never read as "no file was there".
  */
 export declare const SKIPPED_REASONS: readonly ["symbolic_link", "not_regular", "unreadable", "too_large", "refused"];
 export type SkippedReason = (typeof SKIPPED_REASONS)[number];
@@ -63,13 +37,9 @@ export interface FileCommitment {
     contentHash: string;
     signer: string;
     signedAt: string | null;
-    /**
-     * The pack, by its position in the packs `matchCaseFiles` was handed (the
-     * same position the case reading's `packIndex` names), or `null` from
-     * `matchFiles`, which reads one pack (A43).
-     */
+    /** Position in the packs `matchCaseFiles` was handed, or `null` from `matchFiles`. */
     packIndex: number | null;
-    /** The record, by its position in the events the pack presents (A43). */
+    /** Position in the events the pack presents. */
     recordIndex: number;
 }
 export interface MatchedFile {
@@ -85,19 +55,15 @@ export interface UnmatchedFile {
 export interface SkippedFile {
     name: string;
     reason: SkippedReason;
-    /** The reader's own words, for a `.zip` entry it refused (`refused`). */
+    /** The reader's own words, for a refused `.zip` entry. */
     detail?: string;
 }
 export interface NotRead {
     packRef: string | null;
     eventId: string | null;
     reason: NotReadReason;
-    /** As on `FileCommitment` (A43). */
     packIndex: number | null;
-    /**
-     * As on `FileCommitment`, or `null` where the pack presents no events at all
-     * (`no_records`).
-     */
+    /** `null` where the pack presents no events (`no_records`). */
     recordIndex: number | null;
 }
 export interface FileMatchReading {
@@ -107,17 +73,12 @@ export interface FileMatchReading {
     notOffered: FileCommitment[];
     notRead: NotRead[];
     scope: string;
-    /**
-     * Files found and not hashed. The matching functions leave it empty: it is
-     * the caller's, because only a caller that reads a folder knows a link.
-     */
+    /** Files found and not hashed. Filled by the caller, which alone reads folders. */
     skipped?: SkippedFile[];
 }
 /**
- * A file handed in beside a pack. `name` is a label and is never compared. The
- * file is its `bytes`, or its `sha256` (64 lowercase hex characters) where the
- * caller has already hashed it: a command streams a file of any size rather
- * than hold it.
+ * A file handed in beside a pack. `name` is a label, never compared. Give
+ * `bytes`, or `sha256` (64 lowercase hex) when the caller streamed the file.
  */
 export type OfferedFile = {
     name: string;
@@ -135,30 +96,23 @@ export interface FileMatchPack {
     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.
+ * Matches each offered file against one pack's signed commitments. `content`
+ * is the pack's side content, read only to bind hand-off messages.
  */
 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`. */
+/** `matchFiles` over every pack of a case. */
 export declare function matchCaseFiles(packs: readonly FileMatchPack[], files: readonly OfferedFile[]): Promise<FileMatchReading>;
-/** The reading as the `files` member of `--json`, identical in both kernels. */
+/** The reading as the `files` member of `--json`. */
 export declare function fileMatchToJson(reading: FileMatchReading): Record<string, unknown>;
 /**
  * The commitments no offered file matched and no disclosed log answers.
- *
- * `contents` is each pack's side content by `pack_ref`. A record whose own pack
- * discloses bytes that hash to its `content_hash` is accounted for by the pack,
- * and is not returned. Only the text report's count reads this; the reading, and
- * `--json`, still list every commitment no file matched.
+ * A record whose own pack discloses bytes hashing to its `content_hash` is
+ * accounted for. Only the text report's count reads this; `--json` still lists
+ * every unmatched commitment.
  */
 export declare function notAccountedFor(reading: FileMatchReading, contents: ReadonlyMap<string, SideContentMap | null | undefined>): Promise<FileCommitment[]>;
 /**
- * The text report's lines for the reading, identical in both kernels.
- *
- * By default every commitment no file matched is a line. `notAmong` is the case
- * command's report when no `--files` was given: one count line for the recorded
- * files no loose file matched, and no line for each (A41).
+ * The text report's lines for the reading. With `notAmong` (the case command
+ * with no `--files`), unmatched commitments collapse to one count line.
  */
 export declare function renderFileMatch(reading: FileMatchReading, notAmong?: number): string[];

package/dist/file-match.js

@@ -1,45 +1,20 @@
 /**
- * Files handed in beside a pack, matched against what its records signed (A29).
+ * Matches files handed in beside a pack against the commitments its signed
+ * records make (evidence-bundle.md §5.7). Conformance: `vectors/file-match.json`.
  *
- * 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.
+ * - Matching is by SHA-256 of the exact bytes only. A file's name is a label
+ *   and is never compared with an `event_id`, a part name or a path.
+ * - Unmatched is reported, never guessed.
+ * - Only what a record's own key signed counts: 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 (`FILE_MATCH_SCOPE`).
  *
- * 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.
+ * A record outside envelope-spec.md §4.1 commits through `event.content_hash`.
+ * A hand-off record commits to its message through `event.message_hash`, and,
+ * where the message bytes are in hand and bind, each file part of that message
+ * commits by its `content_hash`. Side content is read only to find such a
+ * message; it is never an offered file.
  */
 import { hexToBytes, isHexField, sha256Hex } from "./crypto.js";
 import { resolveTraceEvents } from "./evidence.js";
@@ -47,7 +22,7 @@ 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). */
+/** The scope 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. */
@@ -61,9 +36,8 @@ export const NOT_READ_REASONS = [
     "message_withheld",
 ];
 /**
- * Why a file was named in the report and never hashed (5.7.5). A skipped file
- * is listed, never dropped: every file a command found is matched, unmatched or
- * skipped, so "no match" is never read as "no file was there".
+ * Why a found file was not hashed (§5.7.5). A skipped file is listed, never
+ * dropped, so "no match" is never read as "no file was there".
  */
 export const SKIPPED_REASONS = [
     "symbolic_link",
@@ -77,7 +51,6 @@ const SKIPPED_TEXT = {
     not_regular: "not a regular file: not read",
     unreadable: "could not be read",
     too_large: "past the 1 GiB read from folders in one run: not read",
-    // Followed by the reader's own words, `renderSkipped`.
     refused: "a .zip entry the reader refused",
 };
 const REASON_TEXT = {
@@ -89,9 +62,8 @@ const REASON_TEXT = {
     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"];
+// The accepted profiles minus the quarantined `sanning.mlflow/v1`.
+const RECORD_PROFILES = ["sanning.events/v2"];
 function isObject(v) {
     return v !== null && typeof v === "object" && !Array.isArray(v);
 }
@@ -101,8 +73,8 @@ function strOrNull(v) {
 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).
+// The key and signature must be hex at their lengths, as every body verifier
+// requires inside a bundle.
 function envelopeSpelled(envelope) {
     for (const [name, nibbles] of [
         ["public_key", 64],
@@ -255,8 +227,8 @@ async function readPack(bundle, content, packRef, packIndex) {
     }
     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.
+// A malformed entry is the caller's mistake, not the evidence's, so it throws
+// rather than reading as an unmatched file.
 async function offeredDigests(files) {
     const out = [];
     for (const entry of files) {
@@ -310,16 +282,14 @@ async function match(commitments, notRead, files) {
     };
 }
 /**
- * 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.
+ * Matches each offered file against one pack's signed commitments. `content`
+ * is the pack's side content, read only to bind hand-off messages.
  */
 export async function matchFiles(bundle, files, content) {
     const { commitments, notRead } = await readPack(bundle, content, null, null);
     return match(commitments, notRead, files);
 }
-/** The same reading over every pack of a case, each commitment naming its pack's `ref`. */
+/** `matchFiles` over every pack of a case. */
 export async function matchCaseFiles(packs, files) {
     const commitments = [];
     const notRead = [];
@@ -347,7 +317,7 @@ function commitmentJson(c) {
         signed_at: c.signedAt,
     };
 }
-/** The reading as the `files` member of `--json`, identical in both kernels. */
+/** The reading as the `files` member of `--json`. */
 export function fileMatchToJson(reading) {
     const skipped = reading.skipped ?? [];
     return {
@@ -367,8 +337,7 @@ export function fileMatchToJson(reading) {
             reason: n.reason,
             rendered: renderNotRead(n),
         })),
-        // Present only when something was skipped, so a reading with no skipped
-        // file is the object it was before a folder could be offered (A40).
+        // Omitted when empty, so a reading with nothing skipped keeps its shape.
         ...(skipped.length > 0
             ? {
                 skipped: skipped.map((k) => ({
@@ -406,11 +375,9 @@ function renderNotRead(n) {
 }
 /**
  * The commitments no offered file matched and no disclosed log answers.
- *
- * `contents` is each pack's side content by `pack_ref`. A record whose own pack
- * discloses bytes that hash to its `content_hash` is accounted for by the pack,
- * and is not returned. Only the text report's count reads this; the reading, and
- * `--json`, still list every commitment no file matched.
+ * A record whose own pack discloses bytes hashing to its `content_hash` is
+ * accounted for. Only the text report's count reads this; `--json` still lists
+ * every unmatched commitment.
  */
 export async function notAccountedFor(reading, contents) {
     const out = [];
@@ -426,11 +393,8 @@ export async function notAccountedFor(reading, contents) {
     return out;
 }
 /**
- * The text report's lines for the reading, identical in both kernels.
- *
- * By default every commitment no file matched is a line. `notAmong` is the case
- * command's report when no `--files` was given: one count line for the recorded
- * files no loose file matched, and no line for each (A41).
+ * The text report's lines for the reading. With `notAmong` (the case command
+ * with no `--files`), unmatched commitments collapse to one count line.
  */
 export function renderFileMatch(reading, notAmong) {
     const skipped = reading.skipped ?? [];