@sanning/proof 0.16.0 → 0.17.0

package/src/compose.ts

@@ -105,6 +105,23 @@ function normalizeAttestation(rec: AttestationRecord): AttestationRecord {
   return cloned;
 }
 
+// True when `value` holds a number that is NaN or +-Infinity. Iterative, so a
+// deeply nested input cannot overflow the stack before `jcs` bounds it.
+function hasNonFiniteNumber(value: unknown): boolean {
+  const stack: unknown[] = [value];
+  while (stack.length > 0) {
+    const v = stack.pop();
+    if (typeof v === "number") {
+      if (!Number.isFinite(v)) return true;
+    } else if (Array.isArray(v)) {
+      for (const x of v) stack.push(x);
+    } else if (v !== null && typeof v === "object") {
+      for (const x of Object.values(v)) stack.push(x);
+    }
+  }
+  return false;
+}
+
 // Compose an attested evidence export (evidence-export.md §5).
 //
 // 1. Normalize + transcode the attestation records (boundary hex, above).
@@ -133,6 +150,22 @@ export async function composeExport(
     throw new Error("composeExport: exporterKey.privateKey (32-byte hex seed) is required");
   }
 
+  // An over-long integer reads as Infinity (proof#217), which `jcs` refuses in
+  // the runtime's own words. Say it once, in the kernel's, before any
+  // verification: both kernels write this sentence, with no function-name prefix, so the CLI line is byte-identical.
+  if (hasNonFiniteNumber(sourceBundle)) {
+    throw new Error(
+      "the source bundle carries a number that is not a finite JSON number " +
+        "(an integer past the 1.8e308 range, or too long to read)",
+    );
+  }
+  if (hasNonFiniteNumber(attestations)) {
+    throw new Error(
+      "the attestations carry a number that is not a finite JSON number " +
+        "(an integer past the 1.8e308 range, or too long to read)",
+    );
+  }
+
   if (options.generatedAt !== undefined && !isRfc3339UtcInstant(options.generatedAt)) {
     // The verifier reads this as `malformed generated_at` (evidence-bundle §2,
     // A31), so composing one would sign an export this kernel rejects.

package/src/evidence.ts

@@ -29,6 +29,7 @@ import {
   utf8,
   verifyRsaPssSha256,
 } from "./crypto.js";
+import { safeInteger, signedLeafCount } from "./grading.js";
 import { isConformantHandoffRecord, isHandoffNamespace, type HeldRecord } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import {
@@ -1316,6 +1317,7 @@ async function verifyAnchorTrace(
     const cpErrors: string[] = [];
     let envelopeOk = false;
     let merkleRootOk = false;
+    let leafCountOk = false;
 
     // Decode event_bytes first: in v2 the join key is DERIVED from it, so it
     // is an input to identity, not just to the payload binding below.
@@ -1406,6 +1408,14 @@ async function verifyAnchorTrace(
               `committed=${jsonStr(committedRoot)}`,
           );
         }
+        // §5.1, A38 (proof#197), decided by Phil 2026-10-06: fail closed. The
+        // count the record signs is what every inclusion bound to this
+        // checkpoint is held to, so a record that signs no integer count fails
+        // the checkpoint, as a record that signs no merkle_root does. Read by
+        // value through the one reader the inclusion compare and the
+        // completeness notes share, so `3.0` and `3e0` are 3.
+        leafCountOk = signedLeafCount(cp as { event_bytes?: unknown }) !== null;
+        if (!leafCountOk) cpErrors.push("checkpoint record leaf_count is not an integer");
       } catch (e) {
         cpErrors.push(`checkpoint record is not JSON${thrownDetail(e)}`);
       }
@@ -1424,7 +1434,7 @@ async function verifyAnchorTrace(
       // standing rule is that malformed is a failure while absent is
       // undetermined (the same rule disclosed `content` follows). Without
       // this term the vector `trace-v2-malformed-anchor-ref` verified GREEN.
-      ok: envelopeOk && merkleRootOk && keyed.errors.length === 0 && !duplicateKey,
+      ok: envelopeOk && merkleRootOk && leafCountOk && keyed.errors.length === 0 && !duplicateKey,
       errors: cpErrors,
     });
     if (keyed.anchorRefMalformed) {
@@ -1554,36 +1564,66 @@ async function verifyAnchorTrace(
     const checkpointBound = cp !== undefined;
 
     let inclusionOk = false;
+    // §5.1, A38 (proof#197): the tree walked must be the tree the checkpoint
+    // record signed, the same rule and the same sentence as the stamp path's
+    // rule 3. RFC 9162's walk reads one audit path as valid at more than one
+    // (leaf_index, leaf_count), so without this a real proof at (2, 3) also
+    // verified as (1, 2) or (4, 5). A signed count that cannot be read is not
+    // compared here: it has already failed its checkpoint (above), so the
+    // bundle cannot verify. One reader of the signed count, shared with the
+    // completeness notes, so the verdict and the grade never read two
+    // different numbers.
+    //
+    // Every number here is read BY VALUE (`Number.isSafeInteger`), the model
+    // JCS signs, and the Python kernel reads the same way (`_safe_integer`):
+    // JCS writes `3.0` as `3`, so a stated `3.0` is the integer 3 under the
+    // same wrapper signature. A value that is not a safe integer is malformed,
+    // with one sentence that prints no value, because the two kernels cannot
+    // print `2.5`, `1e400` or `9007199254740993` the same way.
+    const signedCount = cp ? signedLeafCount(cp as { event_bytes?: unknown }) : null;
     if (incl && checkpointBound && cp) {
-      try {
-        inclusionOk = await verifyInclusion(
-          hexToBytes(incl.leaf_hash),
-          incl.leaf_index,
-          incl.leaf_count,
-          (incl.audit_path ?? []).map((h) => hexToBytes(h)),
-          // No `?? ""` fallback. A checkpoint that claims NO root must not be
-          // handed an invented empty one: the Python kernel refuses the same
-          // value and reports the decode failure, so substituting "" here had
-          // the two kernels say different things about one bundle (TS: "the
-          // proof did not reconstruct the checkpoint root", which is not what
-          // happened: there was no claimed root to reconstruct).
-          hexToBytes(cp.merkle_root as string),
+      const statedCount = safeInteger(incl.leaf_count);
+      const statedIndex = safeInteger(incl.leaf_index);
+      if (statedCount === null) {
+        evErrors.push("inclusion leaf_count is not an integer");
+      } else if (statedIndex === null) {
+        evErrors.push("inclusion leaf_index is not an integer");
+      } else if (signedCount !== null && statedCount !== signedCount) {
+        evErrors.push(
+          `inclusion leaf_count ${statedCount} does not equal ` +
+            `the checkpoint's committed leaf_count ${signedCount}`,
         );
-        if (!inclusionOk) evErrors.push("RFC 9162 inclusion proof did not reconstruct the checkpoint root");
-
-        // Defense in depth: the claimed leaf_hash MUST be the hash of the
-        // event's own signed envelope bytes (profile §6) — otherwise a valid
-        // inclusion proof for an UNRELATED leaf could be smuggled in.
-        const expectedLeaf = await leafHash(utf8(jcs(ev.envelope)));
-        const expectedLeafHex = toHex(expectedLeaf);
-        if (expectedLeafHex !== (incl.leaf_hash ?? "").toLowerCase()) {
-          inclusionOk = false;
-          evErrors.push(
-            `inclusion leaf_hash does not match SHA-256(0x00 || JCS(event envelope))`,
+      } else {
+        try {
+          inclusionOk = await verifyInclusion(
+            hexToBytes(incl.leaf_hash),
+            statedIndex,
+            statedCount,
+            (incl.audit_path ?? []).map((h) => hexToBytes(h)),
+            // No `?? ""` fallback. A checkpoint that claims NO root must not be
+            // handed an invented empty one: the Python kernel refuses the same
+            // value and reports the decode failure, so substituting "" here had
+            // the two kernels say different things about one bundle (TS: "the
+            // proof did not reconstruct the checkpoint root", which is not what
+            // happened: there was no claimed root to reconstruct).
+            hexToBytes(cp.merkle_root as string),
           );
+          if (!inclusionOk) evErrors.push("RFC 9162 inclusion proof did not reconstruct the checkpoint root");
+
+          // Defense in depth: the claimed leaf_hash MUST be the hash of the
+          // event's own signed envelope bytes (profile §6) — otherwise a valid
+          // inclusion proof for an UNRELATED leaf could be smuggled in.
+          const expectedLeaf = await leafHash(utf8(jcs(ev.envelope)));
+          const expectedLeafHex = toHex(expectedLeaf);
+          if (expectedLeafHex !== (incl.leaf_hash ?? "").toLowerCase()) {
+            inclusionOk = false;
+            evErrors.push(
+              `inclusion leaf_hash does not match SHA-256(0x00 || JCS(event envelope))`,
+            );
+          }
+        } catch (e) {
+          evErrors.push(`inclusion verify error${thrownDetail(e)}`);
         }
-      } catch (e) {
-        evErrors.push(`inclusion verify error${thrownDetail(e)}`);
       }
     }
 
@@ -1784,8 +1824,16 @@ function isLowerHex(s: unknown, nibbles?: number): s is string {
   return /^[0-9a-f]+$/.test(s);
 }
 
-function isNonNegInt(n: unknown): n is number {
-  return typeof n === "number" && Number.isInteger(n) && n >= 0;
+/**
+ * A JSON number read BY VALUE as a non-negative safe integer, or null.
+ * `safeInteger`, the reader every leaf count and leaf index in this kernel
+ * goes through (A38), mirrored by `_non_neg_integer` in
+ * `src/sanning_proof/evidence.py`. `Number.isInteger` alone accepted `1e+21`,
+ * JCS's own spelling of a count past 2**53 - 1, which Python refused.
+ */
+function nonNegInteger(n: unknown): number | null {
+  const v = safeInteger(n);
+  return v !== null && v >= 0 ? v : null;
 }
 
 /**
@@ -2060,11 +2108,12 @@ async function verifyStampEntry(
   } else {
     base.merkleRoot = body.merkle_root;
   }
-  if (!isNonNegInt(body.leaf_count)) {
+  const stampCount = nonNegInteger(body.leaf_count);
+  if (stampCount === null) {
     errors.push("stamp body leaf_count is not a non-negative integer");
     base.bodyOk = false;
   } else {
-    base.leafCount = body.leaf_count;
+    base.leafCount = stampCount;
   }
 
   // --- the sub-tree ranges --------------------------------------------------
@@ -2108,14 +2157,16 @@ function checkSubtrees(body: StampBody, out: StampResult, errors: string[]): boo
       continue;
     }
     const s = v as Partial<StampSubtree>;
-    if (!isNonNegInt(s.first_leaf)) {
+    const firstLeaf = nonNegInteger(s.first_leaf);
+    const subCount = nonNegInteger(s.leaf_count);
+    if (firstLeaf === null) {
       errors.push(`sub-tree ${ref} first_leaf is not a non-negative integer`);
       shapeOk = false;
     }
     // A zero-leaf sub-tree is not a slice of anything, and admitting one lets
     // an arbitrary number of empty ranges sit inside a tiling that still adds
     // up.
-    if (!isNonNegInt(s.leaf_count) || s.leaf_count === 0) {
+    if (subCount === null || subCount === 0) {
       errors.push(`sub-tree ${ref} leaf_count is not a positive integer`);
       shapeOk = false;
     }
@@ -2126,8 +2177,8 @@ function checkSubtrees(body: StampBody, out: StampResult, errors: string[]): boo
     if (!shapeOk) continue;
     subtrees.push({
       ref,
-      firstLeaf: s.first_leaf as number,
-      leafCount: s.leaf_count as number,
+      firstLeaf: firstLeaf as number,
+      leafCount: subCount as number,
       root: s.root as string,
     });
   }
@@ -2135,11 +2186,14 @@ function checkSubtrees(body: StampBody, out: StampResult, errors: string[]): boo
   out.subtrees = subtrees;
   if (!shapeOk) return false;
 
-  const total = body.leaf_count;
-  if (!isNonNegInt(total)) return false; // already reported by the caller
+  const total = out.leafCount;
+  if (total === null) return false; // already reported by the caller
 
-  const sum = subtrees.reduce((n, s) => n + s.leafCount, 0);
-  if (sum !== total) {
+  // Summed exactly. Each count is a safe integer but their sum need not be,
+  // and a float sum past 2**53 prints a different number than Python's
+  // unbounded one in the sentence below.
+  const sum = subtrees.reduce((n, s) => n + BigInt(s.leafCount), 0n);
+  if (sum !== BigInt(total)) {
     errors.push(
       `sub-tree leaf_count sum ${sum} does not equal the stamp's leaf_count ${total}`,
     );
@@ -2428,17 +2482,29 @@ async function verifyStampEvidence(
       // Rule 3: the tree walked must be the tree the stamp committed to. A
       // proof walked against a different leaf_count is a proof about a
       // different tree, and RFC 9162's path shape depends on the size.
-      if (st.leafCount !== null && incl.leaf_count !== st.leafCount) {
+      //
+      // Read BY VALUE, as the anchor-trace path reads them (A38), and as the
+      // Python kernel does (`_safe_integer`): the wrapper signs JCS(body),
+      // which writes `3.0` as `3`, so a stated `3.0` is 3 under the same
+      // signature. Anything that is not a safe integer is malformed, with a
+      // sentence that prints no value.
+      const statedCount = safeInteger(incl.leaf_count);
+      const statedIndex = safeInteger(incl.leaf_index);
+      if (statedCount === null) {
+        evErrors.push("inclusion leaf_count is not an integer");
+      } else if (statedIndex === null) {
+        evErrors.push("inclusion leaf_index is not an integer");
+      } else if (st.leafCount !== null && statedCount !== st.leafCount) {
         evErrors.push(
-          `inclusion leaf_count ${incl.leaf_count} does not equal the stamp's committed ` +
+          `inclusion leaf_count ${statedCount} does not equal the stamp's committed ` +
             `leaf_count ${st.leafCount}`,
         );
       } else {
         try {
           inclusionOk = await verifyInclusion(
             hexToBytes(incl.leaf_hash),
-            incl.leaf_index,
-            incl.leaf_count,
+            statedIndex,
+            statedCount,
             (incl.audit_path ?? []).map((h) => hexToBytes(h)),
             hexToBytes(st.merkleRoot ?? ""),
           );

package/src/file-match.ts

@@ -70,6 +70,30 @@ export const NOT_READ_REASONS = [
 
 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".
+ */
+export const SKIPPED_REASONS = [
+  "symbolic_link",
+  "not_regular",
+  "unreadable",
+  "too_large",
+  "refused",
+] as const;
+
+export type SkippedReason = (typeof SKIPPED_REASONS)[number];
+
+const SKIPPED_TEXT: Record<SkippedReason, string> = {
+  symbolic_link: "a symbolic link: not followed, not read",
+  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: Record<NotReadReason, string> = {
   no_records: "this bundle carries no records this reading can read",
   record_unreadable: "its record bytes cannot be read",
@@ -94,6 +118,14 @@ 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).
+   */
+  packIndex: number | null;
+  /** The record, by its position in the events the pack presents (A43). */
+  recordIndex: number;
 }
 
 export interface MatchedFile {
@@ -107,10 +139,25 @@ export interface UnmatchedFile {
   sha256: string;
 }
 
+/** A file a command found and did not hash, named with the reason. */
+export interface SkippedFile {
+  name: string;
+  reason: SkippedReason;
+  /** The reader's own words, for a `.zip` entry it refused (`refused`). */
+  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`).
+   */
+  recordIndex: number | null;
 }
 
 export interface FileMatchReading {
@@ -120,13 +167,22 @@ 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.
+   */
+  skipped?: SkippedFile[];
 }
 
-/** A file handed in beside a pack. `name` is a label and is never compared. */
-export interface OfferedFile {
-  name: string;
-  bytes: Uint8Array;
-}
+/**
+ * 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.
+ */
+export type OfferedFile =
+  | { name: string; bytes: Uint8Array; sha256?: undefined }
+  | { name: string; sha256: string; bytes?: undefined };
 
 /** One pack of a case, for `matchCaseFiles`. */
 export interface FileMatchPack {
@@ -197,17 +253,18 @@ async function readPack(
   bundle: unknown,
   content: SideContentMap | null | undefined,
   packRef: string | null,
+  packIndex: number | 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" });
+    notRead.push({ packRef, eventId: null, reason: "no_records", packIndex, recordIndex: null });
     return { commitments, notRead };
   }
-  for (const ev of events) {
+  for (const [recordIndex, ev] of events.entries()) {
     if (!isObject(ev)) {
-      notRead.push({ packRef, eventId: null, reason: "record_unreadable" });
+      notRead.push({ packRef, eventId: null, reason: "record_unreadable", packIndex, recordIndex });
       continue;
     }
     const envelope = own(ev, "envelope");
@@ -218,7 +275,7 @@ async function readPack(
     if (rawBytes !== undefined && rawBytes !== null) {
       eventBytes = typeof rawBytes === "string" ? decode(rawBytes) : undefined;
       if (eventBytes === undefined) {
-        notRead.push({ packRef, eventId, reason: "record_unreadable" });
+        notRead.push({ packRef, eventId, reason: "record_unreadable", packIndex, recordIndex });
         continue;
       }
     }
@@ -228,15 +285,15 @@ async function readPack(
       acceptedSpecMajors: RECORD_PROFILES,
     });
     if (!result.ok || !isObject(envelope) || !envelopeSpelled(envelope)) {
-      notRead.push({ packRef, eventId, reason: "record_not_verified" });
+      notRead.push({ packRef, eventId, reason: "record_not_verified", packIndex, recordIndex });
       continue;
     }
     if (eventBytes === undefined) {
-      notRead.push({ packRef, eventId, reason: "record_withheld" });
+      notRead.push({ packRef, eventId, reason: "record_withheld", packIndex, recordIndex });
       continue;
     }
     if (result.payloadHashOk !== true) {
-      notRead.push({ packRef, eventId, reason: "record_not_verified" });
+      notRead.push({ packRef, eventId, reason: "record_not_verified", packIndex, recordIndex });
       continue;
     }
     let record: unknown;
@@ -246,7 +303,7 @@ async function readPack(
       record = undefined;
     }
     if (!isObject(record)) {
-      notRead.push({ packRef, eventId, reason: "record_unreadable" });
+      notRead.push({ packRef, eventId, reason: "record_unreadable", packIndex, recordIndex });
       continue;
     }
 
@@ -264,12 +321,12 @@ async function readPack(
     if (isHandoffNamespace(held)) {
       const messageHash = own(event, "message_hash");
       if (!isConformantHandoffRecord(held) || !isHexField(messageHash, 64, true)) {
-        notRead.push({ packRef, eventId, reason: "handoff_record_malformed" });
+        notRead.push({ packRef, eventId, reason: "handoff_record_malformed", packIndex, recordIndex });
         continue;
       }
       const message = await messageOf(ev, eventId, messageHash, content);
       if (message === ABSENT) {
-        notRead.push({ packRef, eventId, reason: "message_withheld" });
+        notRead.push({ packRef, eventId, reason: "message_withheld", packIndex, recordIndex });
         continue;
       }
       const parts = isObject(message) ? own(message, "parts") : undefined;
@@ -284,6 +341,8 @@ async function readPack(
             contentHash: ((part as { content_hash: string }).content_hash).toLowerCase(),
             signer,
             signedAt,
+            packIndex,
+            recordIndex,
           });
         });
       }
@@ -292,7 +351,7 @@ async function readPack(
 
     const contentHash = own(event, "content_hash");
     if (!isHexField(contentHash, 64)) {
-      notRead.push({ packRef, eventId, reason: "no_content_hash" });
+      notRead.push({ packRef, eventId, reason: "no_content_hash", packIndex, recordIndex });
       continue;
     }
     commitments.push({
@@ -303,6 +362,8 @@ async function readPack(
       contentHash: contentHash.toLowerCase(),
       signer,
       signedAt,
+      packIndex,
+      recordIndex,
     });
   }
   return { commitments, notRead };
@@ -314,8 +375,17 @@ async function offeredDigests(files: readonly OfferedFile[]): Promise<[string, s
   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 };
+    const { name, bytes, sha256 } = entry as { name?: unknown; bytes?: unknown; sha256?: unknown };
     if (typeof name !== "string") throw new TypeError("matchFiles: a file's name is a string");
+    if (sha256 !== undefined && sha256 !== null) {
+      if ((bytes !== undefined && bytes !== null) || !isHexField(sha256, 64, true)) {
+        throw new TypeError(
+          "matchFiles: a file is {name, bytes} or {name, sha256}, and a sha256 is 64 lowercase hex characters",
+        );
+      }
+      out.push([name, sha256]);
+      continue;
+    }
     if (!(bytes instanceof Uint8Array)) {
       throw new TypeError("matchFiles: a file's bytes are a Uint8Array");
     }
@@ -352,6 +422,7 @@ async function match(
     notOffered: commitments.filter((_, i) => !used.has(i)),
     notRead,
     scope: FILE_MATCH_SCOPE,
+    skipped: [],
   };
 }
 
@@ -366,7 +437,7 @@ export async function matchFiles(
   files: readonly OfferedFile[],
   content?: SideContentMap | null,
 ): Promise<FileMatchReading> {
-  const { commitments, notRead } = await readPack(bundle, content, null);
+  const { commitments, notRead } = await readPack(bundle, content, null, null);
   return match(commitments, notRead, files);
 }
 
@@ -377,10 +448,10 @@ export async function matchCaseFiles(
 ): Promise<FileMatchReading> {
   const commitments: FileCommitment[] = [];
   const notRead: NotRead[] = [];
-  for (const pack of packs) {
+  for (const [packIndex, pack] of packs.entries()) {
     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);
+    const r = await readPack(pack.bundle, pack.content, pack.ref, packIndex);
     commitments.push(...r.commitments);
     notRead.push(...r.notRead);
   }
@@ -390,7 +461,9 @@ export async function matchCaseFiles(
 function commitmentJson(c: FileCommitment): Record<string, unknown> {
   return {
     pack_ref: c.packRef,
+    pack_index: c.packIndex,
     event_id: c.eventId,
+    record_index: c.recordIndex,
     kind: c.kind,
     part_index: c.partIndex,
     content_hash: c.contentHash,
@@ -401,6 +474,7 @@ function commitmentJson(c: FileCommitment): Record<string, unknown> {
 
 /** The reading as the `files` member of `--json`, identical in both kernels. */
 export function fileMatchToJson(reading: FileMatchReading): Record<string, unknown> {
+  const skipped = reading.skipped ?? [];
   return {
     offered: reading.offered,
     matched: reading.matched.map((m) => ({
@@ -412,14 +486,33 @@ export function fileMatchToJson(reading: FileMatchReading): Record<string, unkno
     not_offered: reading.notOffered.map(commitmentJson),
     not_read: reading.notRead.map((n) => ({
       pack_ref: n.packRef,
+      pack_index: n.packIndex,
       event_id: n.eventId,
+      record_index: n.recordIndex,
       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).
+    ...(skipped.length > 0
+      ? {
+          skipped: skipped.map((k) => ({
+            name: k.name,
+            reason: k.reason,
+            ...(k.detail !== undefined ? { detail: k.detail } : {}),
+            rendered: renderSkipped(k),
+          })),
+        }
+      : {}),
     scope: reading.scope,
   };
 }
 
+function renderSkipped(k: SkippedFile): string {
+  if (k.detail !== undefined) return `${k.name}  (${SKIPPED_TEXT[k.reason]}: ${k.detail}; not read)`;
+  return `${k.name}  (${SKIPPED_TEXT[k.reason]})`;
+}
+
 function recordName(eventId: string | null): string {
   return eventId !== null ? `record ${eventId}` : "a record with no event_id";
 }
@@ -440,20 +533,61 @@ function renderNotRead(n: NotRead): string {
   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[] {
+/**
+ * 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.
+ */
+export async function notAccountedFor(
+  reading: FileMatchReading,
+  contents: ReadonlyMap<string, SideContentMap | null | undefined>,
+): Promise<FileCommitment[]> {
+  const out: FileCommitment[] = [];
+  for (const c of reading.notOffered) {
+    const held = c.packRef !== null ? contents.get(c.packRef) : undefined;
+    const raw =
+      c.kind === "record" && held !== undefined && held !== null && c.eventId !== null
+        ? decode(sideContentEntry(held, c.eventId).value)
+        : undefined;
+    if (raw !== undefined && (await sha256Hex(raw)) === c.contentHash) continue;
+    out.push(c);
+  }
+  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).
+ */
+export function renderFileMatch(reading: FileMatchReading, notAmong?: number): string[] {
+  const skipped = reading.skipped ?? [];
   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`,
+      `${reading.unmatched.length} match no record` +
+      (notAmong === undefined ? `; ${reading.notOffered.length} commitment(s) had no file offered` : "") +
+      (skipped.length > 0 ? `; ${skipped.length} skipped, not read` : ""),
   ];
   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 k of skipped) lines.push(`  skipped      ${renderSkipped(k)}`);
+  if (notAmong === undefined) {
+    for (const c of reading.notOffered) {
+      lines.push(`  not offered  ${c.contentHash}, ${renderCommitment(c)}`);
+    }
+  } else if (notAmong > 0) {
+    lines.push(
+      `  ${notAmong} recorded commitment(s) matched no loose file and no log in their own pack ` +
+        "(--json lists every commitment no file matched, these included)",
+    );
   }
   for (const n of reading.notRead) lines.push(`  not read     ${renderNotRead(n)}`);
   lines.push(`  ${reading.scope}`);