@sanning/proof 0.16.0 → 0.18.0

package/src/cli.ts

@@ -44,8 +44,8 @@
 
 import { lstat, open, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { constants as fsConstants, realpathSync } from "node:fs";
-import { randomBytes } from "node:crypto";
-import { basename, join, resolve } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { basename, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
@@ -67,18 +67,26 @@ import {
 } from "./case.js";
 import {
   CASE_FILE_INDEX_NAME,
+  caseFileListedPaths,
   jsonDepthExceeds,
   readCaseFileIndex,
   renderCaseFileFinding,
+  unreadableCaseFileIndex,
 } from "./case-file.js";
-import { ZipReadError, readZip } from "./zip-reader.js";
+import { MAX_ZIP_ARCHIVE_BYTES, MAX_ZIP_BYTES, ZipReadError, readZip } from "./zip-reader.js";
 import { composeExport } from "./compose.js";
 import type { ComposeExportOptions } from "./compose.js";
 import { isHexField, sha256Hex, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
 import { DuplicateKeyError, parseRefusingDuplicates } from "./verifier.js";
-import { fileMatchToJson, matchCaseFiles, matchFiles, renderFileMatch } from "./file-match.js";
-import type { OfferedFile } from "./file-match.js";
+import {
+  fileMatchToJson,
+  matchCaseFiles,
+  matchFiles,
+  notAccountedFor,
+  renderFileMatch,
+} from "./file-match.js";
+import type { OfferedFile, SkippedFile } from "./file-match.js";
 import {
   type CachedWitnessTime,
   WITNESS_CACHE_NAME,
@@ -354,13 +362,15 @@ async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promis
   const content = logs?.content;
 
   let offered: OfferedFile[] | undefined;
+  let skipped: SkippedFile[] = [];
   if (filePaths !== undefined) {
     const read = await readOfferedFiles(filePaths);
     if (typeof read === "string") {
       io.err(`verify: ${read}`);
       return EXIT_MALFORMED;
     }
-    offered = read;
+    offered = read.offered;
+    skipped = read.skipped;
   }
 
   let raw: Uint8Array;
@@ -439,7 +449,7 @@ async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promis
   // Files handed in beside the pack (evidence-bundle.md 5.7, A29): findings
   // beside the verdict, never inside it, so `exit` is untouched.
   if (offered !== undefined) {
-    const reading = await matchFiles(parsed, offered, content);
+    const reading = { ...(await matchFiles(parsed, offered, content)), skipped };
     for (const line of renderFileMatch(reading)) io.out(line);
     if (sink !== null && sink.data !== null) sink.data.files = fileMatchToJson(reading);
   }
@@ -459,20 +469,188 @@ function takeFilePaths(args: readonly string[], start: number): string[] {
   return out;
 }
 
-// Each `--files` path as `{ name, bytes }`, the name exactly as typed, or the
-// one error line when a path is not a readable regular file. The line names the
-// path and not the operating system's words, which differ by kernel.
-async function readOfferedFiles(paths: readonly string[]): Promise<OfferedFile[] | string> {
-  const out: OfferedFile[] = [];
+// A file is hashed in pieces this big, so a file is read without being held.
+const HASH_CHUNK = 1 << 20;
+
+// The most a command reads from the files it finds in folders it was handed, in
+// all: the cap the zip reader puts on an archive. A file that would push the
+// total past it is skipped as `too_large` and never read past it, so a sparse
+// file of a terabyte cannot hold a command for hours (A41). A file a person
+// names on the command line is the person's choice and is read at any size.
+export const MAX_FOLDER_BYTES = MAX_ZIP_BYTES;
+
+// What `hashFile` returns for a file that would push the total past the cap.
+export const TOO_LARGE = "too_large";
+
+// A child of a folder, by concatenation. `path.join` collapses `link/..`
+// lexically, where the operating system, and the Python command, resolve it
+// on disk: the same typed path then names two different folders (proof#219).
+function childPath(directory: string, name: string): string {
+  return directory.endsWith("/") ? `${directory}${name}` : `${directory}/${name}`;
+}
+
+// The SHA-256 of a regular file, read in pieces, or null when it cannot be
+// read. Inside a folder the file is opened without following a link and
+// without blocking, then checked again, so a file swapped for a link or a pipe
+// after the walk listed it is skipped and never followed or waited on. A path a
+// person typed (`follow`) is opened as the shell would.
+//
+// `budget` is the bytes still allowed across the folders of a run. A file
+// larger than it returns TOO_LARGE before a byte is read, and so does a file
+// that grows past it while it is read; only a file read whole is charged.
+export async function hashFile(
+  path: string,
+  follow: boolean,
+  budget?: { n: number },
+): Promise<string | null> {
+  const flags =
+    fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK ?? 0) | (follow ? 0 : (fsConstants.O_NOFOLLOW ?? 0));
+  let handle;
+  try {
+    handle = await open(path, flags);
+  } catch {
+    return null;
+  }
+  try {
+    const st = await handle.stat();
+    if (!st.isFile()) return null;
+    if (budget !== undefined && st.size > budget.n) return TOO_LARGE;
+    const h = createHash("sha256");
+    const buf = Buffer.allocUnsafe(HASH_CHUNK);
+    let total = 0;
+    for (;;) {
+      const { bytesRead } = await handle.read(buf, 0, HASH_CHUNK, null);
+      if (bytesRead === 0) {
+        if (budget !== undefined) budget.n -= total;
+        return h.digest("hex");
+      }
+      total += bytesRead;
+      if (budget !== undefined && total > budget.n) return TOO_LARGE;
+      h.update(buf.subarray(0, bytesRead));
+    }
+  } catch {
+    return null;
+  } finally {
+    await handle.close();
+  }
+}
+
+// The regular files under a `--files` folder, recursively, hidden files
+// included, into `offered` as `<folder>/<path inside>` in UTF-16 code unit
+// order of that path; a link or anything that is not a regular file, and a
+// file or folder that cannot be read, into `skipped`. Returns the one error
+// line, or null. Iterative, bounded as the case walk is.
+//
+// The files are hashed once the walk is done, in the order they are listed, so
+// which file a full `budget` turns away does not depend on how the walk
+// happened to reach it.
+async function walkOfferedFolder(
+  typed: string,
+  offered: OfferedFile[],
+  skipped: SkippedFile[],
+  seen: { n: number },
+  budget: { n: number },
+): Promise<string | null> {
+  let base = typed;
+  while (base.length > 0 && (base.endsWith("/") || base.endsWith(sep))) base = base.slice(0, -1);
+  const found: { key: string; path?: string; skip?: SkippedFile }[] = [];
+  const queue: [string, string, number][] = [[typed, "", 0]];
+  for (let head = 0; head < queue.length; head++) {
+    const [directory, rel, depth] = queue[head]!;
+    let names: Buffer[];
+    try {
+      names = await readdir(directory, { encoding: "buffer" });
+    } catch {
+      if (head === 0) return `--files ${typed} is not a readable folder`;
+      found.push({ key: rel.slice(0, -1), skip: { name: `${base}/${rel.slice(0, -1)}`, reason: "unreadable" } });
+      continue;
+    }
+    names.sort(Buffer.compare);
+    for (const raw of names) {
+      seen.n++;
+      if (seen.n > MAX_WALK_ENTRIES) {
+        return `--files ${typed} holds more than ${MAX_WALK_ENTRIES} files and folders; refusing to read it`;
+      }
+      let name: string;
+      try {
+        name = nameDecoder.decode(raw);
+      } catch {
+        return `--files ${typed} holds a name that is not valid UTF-8; rename it, then run again`;
+      }
+      const key = `${rel}${name}`;
+      const label = `${base}/${key}`;
+      const path = childPath(directory, name);
+      let st;
+      try {
+        st = await lstat(path);
+      } catch {
+        found.push({ key, skip: { name: label, reason: "unreadable" } });
+        continue;
+      }
+      if (st.isDirectory()) {
+        if (depth + 1 > MAX_WALK_DEPTH) {
+          return `--files ${typed} is nested more than ${MAX_WALK_DEPTH} folders deep; refusing to read it`;
+        }
+        queue.push([path, `${key}/`, depth + 1]);
+      } else if (st.isSymbolicLink()) {
+        found.push({ key, skip: { name: label, reason: "symbolic_link" } });
+      } else if (!st.isFile()) {
+        found.push({ key, skip: { name: label, reason: "not_regular" } });
+      } else {
+        found.push({ key, path });
+      }
+    }
+  }
+  found.sort((x, y) => (x.key < y.key ? -1 : x.key > y.key ? 1 : 0));
+  for (const f of found) {
+    if (f.skip !== undefined) {
+      skipped.push(f.skip);
+      continue;
+    }
+    const label = `${base}/${f.key}`;
+    const digest = await hashFile(f.path!, false, budget);
+    if (digest === TOO_LARGE) skipped.push({ name: label, reason: "too_large" });
+    else if (digest === null) skipped.push({ name: label, reason: "unreadable" });
+    else offered.push({ name: label, sha256: digest });
+  }
+  return null;
+}
+
+// Each `--files` path as `{ name, sha256 }`, or the one error line.
+//
+// A path that is a regular file is one file, its name exactly as typed. A path
+// that is a folder stands for the regular files inside it, recursively and
+// hidden files included, each named `<folder as typed>/<path inside>` (A40,
+// proof#214). The rest is returned as `skipped`, named, never dropped. A path
+// that is neither a readable file nor a readable folder is the one error line,
+// which names the path and not the operating system's words, which differ by
+// kernel. A path typed is followed as a shell would; a link found inside a
+// folder is not.
+export async function readOfferedFiles(
+  paths: readonly string[],
+  cap: number = MAX_FOLDER_BYTES,
+): Promise<{ offered: OfferedFile[]; skipped: SkippedFile[] } | string> {
+  const offered: OfferedFile[] = [];
+  const skipped: SkippedFile[] = [];
+  const seen = { n: 0 };
+  const budget = { n: cap };
   for (const path of paths) {
+    let st;
     try {
-      if (!(await stat(path)).isFile()) return `--files ${path} is not a readable file`;
-      out.push({ name: path, bytes: new Uint8Array(await readFile(path)) });
+      st = await stat(path);
     } catch {
       return `--files ${path} is not a readable file`;
     }
+    if (st.isDirectory()) {
+      const err = await walkOfferedFolder(path, offered, skipped, seen, budget);
+      if (err !== null) return err;
+      continue;
+    }
+    const digest = st.isFile() ? await hashFile(path, true) : null;
+    if (digest === null) return `--files ${path} is not a readable file`;
+    offered.push({ name: path, sha256: digest });
   }
-  return out;
+  return { offered, skipped };
 }
 
 // `proof export <source-bundle.json> --attestations <f> --key <f> [--out <out>]`
@@ -734,7 +912,7 @@ async function readExporterKey(path: string, io: Cli): Promise<string | undefine
 // uses as-is; only the map form's *strings* go through `decodeLogValue`. That
 // is the invariant this feature exists to hold, and it is what makes the CLI
 // and the verify page agree about one pack.
-interface LoadedLogs {
+export interface LoadedLogs {
   // Keyed by event id. A `Uint8Array` is raw bytes (directory form); a `string`
   // is hex in either case (map form). Those are exactly the two the verifier
   // distinguishes.
@@ -772,7 +950,7 @@ async function loadLogs(logsPath: string, io: Cli): Promise<LoadedLogs | undefin
   try {
     isDirectory = (await stat(logsPath)).isDirectory();
   } catch (e) {
-    io.err(`cannot read --logs ${logsPath}: ${errMsg(e)}`);
+    io.err(`cannot read --logs ${logsPath}`);
     return undefined;
   }
   return isDirectory ? loadLogsDirectory(logsPath, io) : loadLogsMap(logsPath, io);
@@ -783,8 +961,8 @@ async function loadLogsMap(logsPath: string, io: Cli): Promise<LoadedLogs | unde
   let logsRaw: string;
   try {
     logsRaw = await readFile(logsPath, "utf8");
-  } catch (e) {
-    io.err(`cannot read --logs ${logsPath}: ${errMsg(e)}`);
+  } catch {
+    io.err(`cannot read --logs ${logsPath}`);
     return undefined;
   }
   let logsParsed: unknown;
@@ -797,7 +975,8 @@ async function loadLogsMap(logsPath: string, io: Cli): Promise<LoadedLogs | unde
       io.err(`--logs ${logsPath} ${NOT_I_JSON}: ${e.message}`);
       return undefined;
     }
-    io.err(`--logs ${logsPath} is not valid JSON: ${errMsg(e)}`);
+    // The parser's own words differ by kernel, so the sentence is ours.
+    io.err(`--logs ${logsPath} is not valid JSON`);
     return undefined;
   }
   if (logsParsed === null || typeof logsParsed !== "object" || Array.isArray(logsParsed)) {
@@ -809,97 +988,213 @@ async function loadLogsMap(logsPath: string, io: Cli): Promise<LoadedLogs | unde
   }
   const content = new Map<string, Uint8Array | string>();
   const suppliedIds: string[] = [];
+  const notStrings: string[] = [];
   for (const [k, v] of Object.entries(logsParsed as Record<string, unknown>)) {
-    if (typeof v !== "string") continue;
+    if (typeof v !== "string") {
+      notStrings.push(k);
+      continue;
+    }
     content.set(k, decodeLogValue(v));
     suppliedIds.push(k);
   }
-  return { content, suppliedIds, notes: [] };
+  // Named, every name, in the one sentence the Python command writes (A42): a
+  // value that is not a string is never coerced and never dropped unnamed.
+  const notes =
+    notStrings.length === 0
+      ? []
+      : [
+          `--logs ${logsPath}: skipped ${count(notStrings.length, "entry", "entries")} whose ` +
+            `value is not a string (${quoted(notStrings.sort())})`,
+        ];
+  return { content, suppliedIds, notes };
 }
 
-// The directory form. Flat, one file per event, `<event_id>.json`.
+// The directory form, read by the one rule both kernels apply
+// (evidence-bundle.md §5.1.4, A42). The twin is `_load_logs_directory` in
+// `src/sanning_proof/cli.py`, and `cross-kernel/logs_folder_cli_leg.py` holds
+// the two commands to the same stdout, stderr and exit code.
 //
-// The decisions this pins, none of which is a verification failure — an absent
-// or unusable disclosure is UNDISCLOSED, and absence is not evidence of
-// tampering (evidence-bundle.md §5.1):
+// A regular file named `<event_id>.json` is that record's disclosed bytes, and
+// nothing else in the folder is read. None of the following is a verification
+// failure, because an absent or unusable disclosure is UNDISCLOSED and absence
+// is not evidence of tampering (evidence-bundle.md §5.1), and every one of them
+// is NAMED in a note, every name, so no file is dropped without being named:
 //
 //   - a file whose name is not a known event id  → loaded, binds to nothing,
-//     named in a post-verify note (silence is how a typo'd filename becomes a
-//     mysteriously undisclosed event)
+//     named in a post-verify note
 //   - an event with no corresponding file        → undetermined (`~`), noted
 //   - an empty directory                         → valid; discloses nothing,
 //     noted, exit code unchanged
-//   - a subdirectory                             → skipped, never recursed,
-//     noted (this is the "you pointed at the pack root, not its logs/" case)
-//   - anything not named `<event_id>.json`, and anything that is not a regular
-//     file                                       → skipped, noted
+//   - a subdirectory                             → never entered, noted (the
+//     "you pointed at the pack root, not its logs/" case)
+//   - a symbolic link                            → never followed, whatever it
+//     points at, noted; `case` never follows one under a pack's `logs/` and
+//     `--files` never follows one in a folder (A40), so a link named
+//     `<event_id>.json` discloses nothing here either
+//   - anything that is not a regular file        → never opened, noted
+//   - anything else not named `<event_id>.json`  → never read, noted
+//
+// The Python command read every regular file by its STEM until 0.17.0, so a
+// forged `<id>.txt` beside a genuine `<id>.json` failed the pack there and was
+// never read here, and the forged-`.json` direction read clean there and
+// failed here: whoever assembled the folder chose the verdict.
 //
-// The one hard stop is a file we SELECTED but cannot read: we were pointed at
-// it, so a permissions error must not read as minimal disclosure. That exits 2.
-async function loadLogsDirectory(dirPath: string, io: Cli): Promise<LoadedLogs | undefined> {
-  let names: string[];
+// The hard stops (exit 2): a `<event_id>.json` file that cannot be read (we were
+// pointed at it, so a permissions error must not read as minimal disclosure),
+// more than MAX_WALK_ENTRIES names, a name that is not valid UTF-8 (escaping it
+// would let two names read as one), and `<event_id>.json` files holding more
+// than MAX_LOGS_BYTES in all.
+export const MAX_LOGS_BYTES = MAX_ZIP_BYTES;
+
+export class LogsTooLarge extends Error {}
+
+// A `<event_id>.json` file's bytes. Opened without following a link and without
+// blocking, then checked again, so a file swapped for a link or a pipe after the
+// folder was listed is refused rather than followed or waited on; and read no
+// further than `budget` allows. Two checks, and each is reachable without the
+// other: the size `fstat` reports refuses a sparse file before a byte is read,
+// and the count of bytes read refuses a file that reports less than it holds
+// (a file in /proc reports 0) or grows while it is read. `opener` is for the
+// tests, which must reach the second check with the first one passing.
+export async function readLogFile(
+  path: string,
+  budget: { n: number },
+  opener: typeof open = open,
+): Promise<Uint8Array> {
+  const flags =
+    fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+  const handle = await opener(path, flags);
   try {
-    names = await readdir(dirPath);
-  } catch (e) {
-    io.err(`cannot read --logs directory ${dirPath}: ${errMsg(e)}`);
+    const st = await handle.stat();
+    if (!st.isFile()) throw new Error("not a regular file");
+    if (st.size > budget.n) throw new LogsTooLarge();
+    const chunks: Buffer[] = [];
+    let total = 0;
+    for (;;) {
+      const buf = Buffer.allocUnsafe(HASH_CHUNK);
+      const { bytesRead } = await handle.read(buf, 0, HASH_CHUNK, null);
+      if (bytesRead === 0) break;
+      total += bytesRead;
+      if (total > budget.n) throw new LogsTooLarge();
+      chunks.push(buf.subarray(0, bytesRead));
+    }
+    budget.n -= total;
+    // Copied into one array the verifier owns, never a window onto a pooled block.
+    return new Uint8Array(Buffer.concat(chunks, total));
+  } finally {
+    await handle.close();
+  }
+}
+
+// `limits` is for the tests, which cannot write a gigabyte or fifty thousand
+// names per case; the command always passes the defaults.
+export async function loadLogsDirectory(
+  dirPath: string,
+  io: Cli,
+  limits: { bytes: number; entries: number } = { bytes: MAX_LOGS_BYTES, entries: MAX_WALK_ENTRIES },
+): Promise<LoadedLogs | undefined> {
+  let raws: Buffer[];
+  try {
+    raws = await readdir(dirPath, { encoding: "buffer" });
+  } catch {
+    io.err(`cannot read --logs directory ${dirPath}`);
     return undefined;
   }
+  if (raws.length > limits.entries) {
+    io.err(`--logs ${dirPath} holds more than ${limits.entries} entries; refusing to read it`);
+    return undefined;
+  }
+  const names: string[] = [];
+  for (const raw of raws) {
+    try {
+      names.push(nameDecoder.decode(raw));
+    } catch {
+      io.err(`--logs ${dirPath} holds a name that is not valid UTF-8; rename it, then run verify again`);
+      return undefined;
+    }
+  }
 
   const content = new Map<string, Uint8Array | string>();
   const suppliedIds: string[] = [];
-  const skippedDirs: string[] = [];
-  const skippedNames: string[] = [];
+  const dirs: string[] = [];
+  const links: string[] = [];
+  const notRegular: string[] = [];
+  const notNamed: string[] = [];
+  const budget = { n: limits.bytes };
 
-  for (const name of [...names].sort()) {
-    const p = join(dirPath, name);
-    let isDirectory: boolean;
-    let isFile: boolean;
+  for (const name of names.sort()) {
+    const p = childPath(dirPath, name);
+    let s;
     try {
-      // `stat`, not the dirent kind: a symlinked log file is a log file, and a
-      // symlink to a directory is a directory.
-      const s = await stat(p);
-      isDirectory = s.isDirectory();
-      isFile = s.isFile();
-    } catch (e) {
-      io.err(`cannot read --logs entry ${p}: ${errMsg(e)}`);
+      // `lstat`, never `stat`: a link in the folder is never followed.
+      s = await lstat(p);
+    } catch {
+      io.err(`cannot read --logs entry ${p}`);
       return undefined;
     }
-    if (isDirectory) {
-      skippedDirs.push(name);
+    if (s.isSymbolicLink()) {
+      links.push(name);
+      continue;
+    }
+    if (s.isDirectory()) {
+      dirs.push(name);
+      continue;
+    }
+    if (!s.isFile()) {
+      notRegular.push(name);
       continue;
     }
-    // Not a regular file (device, fifo, socket), or not named
-    // `<event_id>.json` — including a file named exactly `.json`, whose event
-    // id would be the empty string.
-    if (!isFile || !name.endsWith(LOG_SUFFIX) || name.length === LOG_SUFFIX.length) {
-      skippedNames.push(name);
+    // Not named `<event_id>.json`, including a file named exactly `.json`,
+    // whose event id would be the empty string.
+    if (!name.endsWith(LOG_SUFFIX) || name.length === LOG_SUFFIX.length) {
+      notNamed.push(name);
       continue;
     }
     const eventId = name.slice(0, -LOG_SUFFIX.length);
     try {
-      // No encoding argument: bytes, exactly as they sit on disk. Copied out of
-      // Buffer's shared pool so the array handed to the verifier owns its own
-      // memory rather than a window onto a reused block.
-      content.set(eventId, new Uint8Array(await readFile(p)));
+      // Bytes, exactly as they sit on disk.
+      content.set(eventId, await readLogFile(p, budget));
     } catch (e) {
-      io.err(`cannot read --logs file ${p}: ${errMsg(e)}`);
+      if (e instanceof LogsTooLarge) {
+        io.err(
+          `--logs ${dirPath}: the <event_id>${LOG_SUFFIX} files hold more than ${limits.bytes} ` +
+            `bytes in all, at ${p}; refusing to read them`,
+        );
+      } else {
+        io.err(`cannot read --logs file ${p}`);
+      }
       return undefined;
     }
     suppliedIds.push(eventId);
   }
 
   const notes: string[] = [];
-  if (skippedDirs.length > 0) {
+  if (dirs.length > 0) {
     notes.push(
-      `--logs ${dirPath}: skipped ${count(skippedDirs.length, "subdirectory", "subdirectories")} ` +
-        `(${sample(skippedDirs)}) — the directory form reads <event_id>${LOG_SUFFIX} files ` +
+      `--logs ${dirPath}: skipped ${count(dirs.length, "subdirectory", "subdirectories")} ` +
+        `(${quoted(dirs)}) — the directory form reads <event_id>${LOG_SUFFIX} files ` +
         `and does not recurse`,
     );
   }
-  if (skippedNames.length > 0) {
+  if (links.length > 0) {
     notes.push(
-      `--logs ${dirPath}: skipped ${count(skippedNames.length, "entry", "entries")} ` +
-        `not named <event_id>${LOG_SUFFIX} (${sample(skippedNames)})`,
+      `--logs ${dirPath}: skipped ${count(links.length, "symbolic link", "symbolic links")}, ` +
+        `never followed (${quoted(links)})`,
+    );
+  }
+  if (notRegular.length > 0) {
+    notes.push(
+      `--logs ${dirPath}: skipped ` +
+        (notRegular.length === 1
+          ? "1 entry that is not a regular file"
+          : `${notRegular.length} entries that are not regular files`) +
+        ` (${quoted(notRegular)})`,
+    );
+  }
+  if (notNamed.length > 0) {
+    notes.push(
+      `--logs ${dirPath}: skipped ${count(notNamed.length, "entry", "entries")} ` +
+        `not named <event_id>${LOG_SUFFIX} (${quoted(notNamed)})`,
     );
   }
   if (suppliedIds.length === 0) {
@@ -924,11 +1219,11 @@ async function loadLogsDirectory(dirPath: string, io: Cli): Promise<LoadedLogs |
 //     of a disclosure is not evidence of tampering.
 function reportLogsCoverage(logs: LoadedLogs, result: EvidenceBundleResult, io: Cli): void {
   const eventIds = new Set(result.events.map((e) => e.eventId));
-  const unmatched = logs.suppliedIds.filter((id) => !eventIds.has(id));
+  const unmatched = logs.suppliedIds.filter((id) => !eventIds.has(id)).sort();
   if (unmatched.length > 0) {
     io.err(
       `note: --logs supplied ${count(unmatched.length, "entry", "entries")} matching no event ` +
-        `in the bundle, ignored: ${sample(unmatched)}`,
+        `in the bundle, ignored: ${quoted(unmatched)}`,
     );
   }
   const undetermined = result.events.filter((e) => e.contentOk === null);
@@ -950,6 +1245,12 @@ function count(n: number, one: string, many: string): string {
   return `${n} ${n === 1 ? one : many}`;
 }
 
+// Every name, quoted. Every one, not the first few: a file left out of a note
+// is a file dropped without being named.
+function quoted(names: string[]): string {
+  return names.map((n) => JSON.stringify(n)).join(", ");
+}
+
 // First few names, quoted, with a tail count — enough to recognise the mistake
 // without pasting a whole directory into the terminal.
 function sample(names: string[], max = 3): string {
@@ -992,7 +1293,7 @@ function printUsage(io: Cli): void {
   io.out("                                                          Verify a bundle");
   io.out("  export <source.json> --attestations <f> --key <f> [--out <f>] [--json]");
   io.out("                                                          Create an attested export");
-  io.out("  case <folder>... [--gateways <urls>] [--files <path>...] [--json]");
+  io.out("  case <folder or .zip>... [--gateways <urls>] [--files <path>...] [--json]");
   io.out("                                                          Read several packs as one case");
   io.out("                                                          (`case --help` for its exit codes)");
   io.out("");
@@ -1012,7 +1313,15 @@ function printUsage(io: Cli): void {
   io.out("                    to; the report lists the files the pack vouches for,");
   io.out("                    the files that match no record, and the commitments");
   io.out("                    no file was offered for. Names and folders are never");
-  io.out("                    compared, and the verdict never moves.");
+  io.out("                    compared, and the verdict never moves. A folder");
+  io.out("                    stands for the regular files inside it, found");
+  io.out("                    recursively, hidden files included, so one folder");
+  io.out("                    covers a whole download in any shell (a wildcard like");
+  io.out("                    evidence/* is not expanded here). A symbolic link");
+  io.out("                    inside a folder is never followed and is listed as");
+  io.out("                    skipped, as is anything that is not a regular file or");
+  io.out("                    cannot be read: no file is dropped without being");
+  io.out("                    named. Two files with one hash are both listed.");
   io.out("");
   io.out("--logs <path>       Bind disclosed raw logs to each event's committed");
   io.out("                    content_hash, or message_hash for a hand-off record.");
@@ -1023,6 +1332,9 @@ function printUsage(io: Cli): void {
   io.out("                      raw bytes ARE the content, nothing is decoded.");
   io.out("                      This is a materialized pack's logs/ directory:");
   io.out("                        sanning-proof verify <pack>/bundle.json --logs <pack>/logs");
+  io.out("                      Nothing else in it is read: a link is never");
+  io.out("                      followed, a subdirectory never entered, and any");
+  io.out("                      other name is not a disclosure. Each is named.");
   io.out("");
   io.out("                      a JSON FILE mapping event_id → bytes (an");
   io.out("                      even-length hex value, in either case, ⇒ hex,");
@@ -1459,11 +1771,12 @@ function mapGradeToExit(grade: PackGrade): number {
 //
 // ── Directories only ──
 //
-// `case` reads no archive. A `.zip` argument exits 2 with one line that says to
-// unzip it first and pass the folder, and a `.zip` inside a directory is a file
-// like any other: outside every pack, and never opened. Reading archives in the
-// kernel brought zip bombs, two zip libraries that disagree, and entry names
-// that are not file names, and `unzip` already does that job.
+// A `.zip` named on the command line is read as the folder `unzip` would make,
+// by the reader in `zip-reader.ts` and nothing else, one reader restated in both
+// kernels because two zip libraries disagree on the edges. A `.zip` INSIDE a
+// folder is a file like any other: outside every pack, hashed like any other
+// file and never unzipped, because a reader does not open a zip inside a zip
+// (§5.6.1).
 //
 // ── The walk ──
 //
@@ -1492,7 +1805,8 @@ function mapGradeToExit(grade: PackGrade): number {
 //      at the directory that holds it.
 //   2. A file belongs to the pack with the LONGEST root it sits under, and only
 //      if it is that root's `bundle.json` or under that root's `logs/`.
-//   3. A file under no pack is OUTSIDE: listed, and never opened.
+//   3. A file under no pack is OUTSIDE: listed, never read as part of a pack, and
+//      hashed to be matched against the records (§5.7.6, A41).
 //   4. Roots and outside paths are sorted by UTF-16 code unit (the default
 //      `Array.prototype.sort`).
 //   5. Inside a pack, `logs/<event_id>.json` (one level) is disclosed content,
@@ -1505,8 +1819,7 @@ function mapGradeToExit(grade: PackGrade): number {
 // holding them, each under its own name, and two that would land at one name
 // refuse.
 //
-// Known differences from the page: the page opens a dropped `.zip` and this
-// command does not; the page drops a leading byte-order mark from
+// Known differences from the page: the page drops a leading byte-order mark from
 // `bundle.json` and `verify`'s reader refuses one; the page reads whatever the
 // browser hands it for a link, a name that is not UTF-8 or a very deep tree,
 // where this command applies the walk's rules above; and the page keys
@@ -1549,6 +1862,14 @@ export class CaseInputError extends Error {
   }
 }
 
+/**
+ * A file `case` reads whole that does not fit in what is left of the run's
+ * 1 GiB. Always a `CaseInputError`; the type lets a caller that can carry on
+ * without the file (`contents.json`, `witness-cache.json`) tell this refusal
+ * from an unreadable file.
+ */
+export class WholeReadRefused extends CaseInputError {}
+
 /**
  * `bundle.json` bytes that `readBundleBytes` will not read. `tooDeep` separates
  * the one refusal that is not a parse error; `detail` is the parser's own words,
@@ -1615,7 +1936,7 @@ export interface SplitPack {
 
 export interface SplitCase {
   packs: SplitPack[];
-  /** Paths that belong to no pack, sorted. Never opened. */
+  /** Paths that belong to no pack, sorted. Never read as part of a pack; a regular one is hashed, and nothing else is read of it (A41). */
   outside: string[];
   /** The part of `outside` that is not a regular file. Never followed, never opened. */
   notRegular: string[];
@@ -1632,6 +1953,13 @@ export interface TreeEntry {
   regular: boolean;
   /** The bytes of an entry read out of a case-file `.zip`. */
   data?: Uint8Array | null;
+  /**
+   * `true` for a symbolic link, on disk or an entry of a `.zip`: the one reason
+   * a link is skipped under, here and under `--files`.
+   */
+  link?: boolean;
+  /** The `.zip` reader's own words for an entry it refused (not a link). */
+  refused?: string;
 }
 
 /**
@@ -1705,22 +2033,30 @@ export async function splitCase(
  * (evidence-bundle 5.6.6, v1.25, A30), or `null`.
  *
  * The split rule is not changed for it: the file stays outside every pack,
- * listed as such, and is opened here and nowhere else. It is read only where it
- * is a regular file the split left outside every pack, so a file under another
+ * listed as such, and is read here, for its contents, and hashed with the other
+ * outside files (A41). It is read as a cache only where it is a regular file the split left outside every pack, so a file under another
  * pack's `logs/` is that pack's, and a link is never followed. A file that
- * cannot be read is no cache, never a refusal of the drop.
+ * cannot be read is no cache, never a refusal of the drop. One the run's
+ * whole-read total has no room for is pushed onto `refused` when it is given,
+ * so the output says so.
  */
-async function witnessCacheBytes(
+export async function witnessCacheBytes(
   tree: Map<string, TreeEntry>,
   split: SplitCase,
   pack: SplitPack,
+  budget?: { n: number },
+  refused?: string[],
 ): Promise<Uint8Array | null> {
   const path = pack.bundlePath.slice(0, -"bundle.json".length) + WITNESS_CACHE_NAME;
   const entry = tree.get(path);
   if (entry === undefined || !entry.regular || !split.outside.includes(path)) return null;
   try {
-    return await readFileEntry(entry, path);
+    return await readFileEntry(entry, path, budget);
   } catch (e) {
+    if (e instanceof WholeReadRefused) {
+      refused?.push(path);
+      return null;
+    }
     if (e instanceof CaseInputError) return null;
     throw e;
   }
@@ -1741,12 +2077,46 @@ export function loadBundle(pack: SplitPack): unknown {
   }
 }
 
+/**
+ * The refusal for a file `case` would hold whole that does not fit in what is
+ * left of the 1 GiB a run reads whole. The same words in both kernels.
+ */
+export const wholeReadRefusal = (key: string): string =>
+  `${key} cannot be read: it would take case past the 1 GiB it reads whole in one run; refusing to read it`;
+
+/**
+ * Why `contents.json` reads as an unreadable index when the run's whole-read
+ * total has no room for it, and when it cannot be read. The same words in both
+ * kernels.
+ */
+export const INDEX_OVER_BUDGET =
+  "it would take case past the 1 GiB it reads whole in one run, so it was not read";
+export const INDEX_NOT_READ = "it could not be read";
+
+/** The note for a `witness-cache.json` the whole-read total had no room for. */
+export const witnessCacheRefusedNote = (path: string): string =>
+  `${path} was not read as a witness cache: it would take case past the 1 GiB it reads whole in one run`;
+
+/** The refusal for an archive file larger than MAX_ZIP_ARCHIVE_BYTES. */
+export const zipFileRefusal = (arg: string): string =>
+  `${arg} is larger than 1.25 GiB on disk; refusing to read it`;
+
 /**
  * A regular file's bytes. Opened without following a link and without
  * blocking, then checked again, so a file swapped for a link or a pipe after
  * the walk listed it is refused rather than followed or waited on.
+ *
+ * `budget` is the bytes a run may still hold whole from files on disk
+ * (MAX_FOLDER_BYTES at the start). A file larger than what is left, or that
+ * grows past it while it is read, is refused before it is held, so a file of a
+ * terabyte under a pack's own names cannot exhaust memory. A `.zip` entry is
+ * already in memory, inside the archive's own cap, and is not charged.
  */
-export async function readFileEntry(entry: TreeEntry, key: string): Promise<Uint8Array> {
+export async function readFileEntry(
+  entry: TreeEntry,
+  key: string,
+  budget?: { n: number },
+): Promise<Uint8Array> {
   if (entry.data !== undefined && entry.data !== null) return entry.data;
   const flags =
     fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
@@ -1757,9 +2127,42 @@ export async function readFileEntry(entry: TreeEntry, key: string): Promise<Uint
     throw new CaseInputError(`cannot read ${key}`);
   }
   try {
-    if (!(await handle.stat()).isFile()) throw new CaseInputError(`cannot read ${key}`);
-    return new Uint8Array(await handle.readFile());
-  } catch {
+    const st = await handle.stat();
+    if (!st.isFile()) throw new CaseInputError(`cannot read ${key}`);
+    if (budget === undefined) return new Uint8Array(await handle.readFile());
+    if (st.size > budget.n) throw new WholeReadRefused(wholeReadRefusal(key));
+    // Once, at what the file says it holds and one byte more to see it grow:
+    // the bytes are read into the buffer the result is a view of, never copied.
+    const want = Math.min(st.size, budget.n) + 1;
+    const buf = Buffer.allocUnsafeSlow(want);
+    let total = 0;
+    while (total < want) {
+      const { bytesRead } = await handle.read(buf, total, want - total, null);
+      if (bytesRead === 0) break;
+      total += bytesRead;
+    }
+    if (total > st.size) {
+      // The file grew since it was measured: take the rest in pieces, never
+      // past the budget.
+      const rest: Buffer[] = [];
+      let all = total;
+      while (all <= budget.n) {
+        const chunk = Buffer.allocUnsafe(Math.min(HASH_CHUNK, budget.n - all + 1));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+        if (bytesRead === 0) break;
+        all += bytesRead;
+        rest.push(chunk.subarray(0, bytesRead));
+      }
+      if (all > budget.n) throw new WholeReadRefused(wholeReadRefusal(key));
+      budget.n -= all;
+      const joined = Buffer.concat([buf.subarray(0, total), ...rest], all);
+      return new Uint8Array(joined.buffer, joined.byteOffset, all);
+    }
+    if (total > budget.n) throw new WholeReadRefused(wholeReadRefusal(key));
+    budget.n -= total;
+    return new Uint8Array(buf.buffer, buf.byteOffset, total);
+  } catch (e) {
+    if (e instanceof CaseInputError) throw e;
     throw new CaseInputError(`cannot read ${key}`);
   } finally {
     await handle.close();
@@ -1803,7 +2206,7 @@ async function walk(
           `${rel.slice(0, -1)} holds a name that is not valid UTF-8; rename it, then run case again`,
         );
       }
-      const path = join(directory, name);
+      const path = childPath(directory, name);
       const key = `${rel}${name}`;
       let s;
       try {
@@ -1819,7 +2222,7 @@ async function walk(
         }
         queue.push([path, `${key}/`, depth + 1]);
       } else {
-        tree.set(key, { fsPath: path, regular: s.isFile() });
+        tree.set(key, { fsPath: path, regular: s.isFile(), link: s.isSymbolicLink() });
       }
     }
   }
@@ -1902,11 +2305,33 @@ async function unzip(
   seen: { n: number },
 ): Promise<void> {
   let data: Uint8Array;
+  let handle;
   try {
-    data = new Uint8Array(await readFile(arg));
+    handle = await open(arg, fsConstants.O_RDONLY);
   } catch {
     throw new CaseInputError(`cannot read ${arg}`);
   }
+  try {
+    const size = (await handle.stat()).size;
+    if (size > MAX_ZIP_ARCHIVE_BYTES) throw new CaseInputError(zipFileRefusal(arg));
+    // One more byte than the size on disk, so a file that grew is noticed; the
+    // archive is read straight into this buffer, once, and never copied.
+    const buf = Buffer.allocUnsafe(size + 1);
+    let have = 0;
+    for (;;) {
+      const { bytesRead } = await handle.read(buf, have, buf.length - have, null);
+      if (bytesRead === 0) break;
+      have += bytesRead;
+      if (have === buf.length) break;
+    }
+    if (have > size) throw new CaseInputError(`cannot read ${arg}`);
+    data = new Uint8Array(buf.buffer, buf.byteOffset, have);
+  } catch (e) {
+    if (e instanceof CaseInputError) throw e;
+    throw new CaseInputError(`cannot read ${arg}`);
+  } finally {
+    await handle.close();
+  }
   let entries;
   try {
     entries = readZip(data);
@@ -1925,6 +2350,8 @@ async function unzip(
       fsPath: "",
       regular: entry.refused === null,
       data: entry.data,
+      link: entry.refused === "a symbolic link",
+      ...(entry.refused !== null && entry.refused !== "a symbolic link" ? { refused: entry.refused } : {}),
     });
   }
 }
@@ -1959,7 +2386,8 @@ export const CASE_USAGE = `sanning-proof case -- a case reading: one verdict ove
               verify page's splitting rule: every bundle.json is a pack, a file
               belongs to the deepest pack whose bundle.json or logs/ it sits
               in, and every other file is listed as outside every pack and
-              never opened. A .zip inside a folder is a file like any other. A
+              matched by hash (see below), never read as part of a pack. A
+              .zip inside a folder is a file like any other. A
               symbolic link is never followed: it is listed as outside and not
               read, even under a pack's logs/. Several arguments are read as
               one folder holding them, each under its own name. A folder
@@ -1978,12 +2406,25 @@ export const CASE_USAGE = `sanning-proof case -- a case reading: one verdict ove
               the witness line. The lookup never changes the verdict word.
   --files     files handed in beside the packs, every path up to the next
               option, matched by SHA-256 alone against what every pack's
-              signed records commit to. A file under a pack's logs/ is
-              offered only when it is named here. The verdict never moves.
+              signed records commit to. A folder stands for the regular files
+              inside it, found recursively, hidden files included; a link
+              inside it is listed as skipped and never followed. A file under
+              a pack's logs/ is offered only when it is named here. The
+              verdict never moves.
   --json      the full reading as JSON: the verdict, every exception and note
-              with its rendered line, every record, every contribution, the
-              packs, the files outside them, the case file index comparison,
-              the witness line and the on-chain half.
+              with its rendered line, every record of every pack with its
+              status (read clean, read flagged, or not read and why), every
+              contribution, the packs, each with its index, the files outside
+              them, the case file index comparison, the witness line and the
+              on-chain half.
+
+Files outside every pack are matched too, always, so
+sanning-proof case audit-file.zip checks a whole download in one command: each
+is hashed and listed as vouched for by a record in a named pack, or as matching
+no record, by SHA-256 alone, as --files does. Names and folders are never
+compared, and neither the verdict nor the exit code moves. A link, a pipe or an
+entry or file that cannot be read is listed as skipped. Nothing is printed for
+this when no file sits outside every pack and --files is not given.
 
 Each pack's bundle.json is read as verify reads it, so the two commands
 classify one bundle the same way.
@@ -2046,7 +2487,7 @@ export function caseExitCode(verdict: string, onChainVerdict: string): number {
   return code;
 }
 
-interface CaseFileData {
+export interface CaseFileData {
   root: string;
   index: string;
   case_id: string | null;
@@ -2061,16 +2502,19 @@ interface CaseData {
   exceptions: { rendered: string }[];
   notes: { rendered: string }[];
   packs: {
+    index: number;
     ref: string;
     log_files: number;
     unaccounted: string[];
     signing_key: string | null;
     grade: string | null;
   }[];
+  records: { pack_index: number; status: string }[];
   outside: string[];
   not_regular: string[];
   case_file: CaseFileData[];
   on_chain: OnChainHalf;
+  witness_cache_not_read?: string[];
 }
 
 const titleOf = (word: string): string =>
@@ -2096,7 +2540,15 @@ function caseReport(data: CaseData): string[] {
   for (const p of data.packs) {
     const key = p.signing_key !== null ? p.signing_key : "a key this reader cannot read";
     const grade = p.grade !== null ? titleOf(p.grade) : "not graded";
-    let line = `  ${p.ref}  signed by ${key}; ${grade}; ${p.log_files} record file(s) under logs/`;
+    // Each record's status, counted per pack (A43): the JSON lists every one.
+    const mine = data.records.filter((r) => r.pack_index === p.index);
+    const count = (status: string) => mine.filter((r) => r.status === status).length;
+    const records =
+      `records: ${count("read_clean")} read clean, ${count("read_flagged")} read flagged, ` +
+      `${count("not_read")} not read`;
+    let line =
+      `  ${p.ref}  signed by ${key}; ${grade}; ${records}; ` +
+      `${p.log_files} record file(s) under logs/`;
     if (p.unaccounted.length > 0) {
       line +=
         `; ${p.unaccounted.length} file(s) under logs/ that cannot be a ` +
@@ -2114,6 +2566,9 @@ function caseReport(data: CaseData): string[] {
       lines.push(links.has(path) ? `  - ${path} (not a regular file: not followed, not read)` : `  - ${path}`);
     }
   }
+  for (const path of data.witness_cache_not_read ?? []) {
+    lines.push(`note          ${witnessCacheRefusedNote(path)}`);
+  }
   for (const c of data.case_file) {
     if (c.index === "absent") continue;
     const label = c.case_id !== null ? `, which says it is about ${c.case_id}` : "";
@@ -2145,34 +2600,67 @@ function caseReport(data: CaseData): string[] {
 /**
  * The index comparison, once per argument (5.6.3): each folder or case file
  * whose root holds `contents.json`. Every file under `packs/` and `report/` is
- * hashed for it, as bytes, and nothing is parsed but the index. It is never an
- * input to the reading.
+ * hashed for it, in pieces, as bytes, and nothing is parsed but the index. The
+ * files share one total of 1 GiB across the run, charged in path order; a file
+ * larger than what is left is reported as too large to hash, never as a match
+ * and never as absent. It is never an input to the reading.
  */
-async function caseFileReadings(tree: Map<string, TreeEntry>): Promise<CaseFileData[]> {
+export async function caseFileReadings(
+  tree: Map<string, TreeEntry>,
+  whole?: { n: number },
+  cap: number = MAX_FOLDER_BYTES,
+): Promise<CaseFileData[]> {
   const out: (CaseFileData & { findings: Record<string, unknown>[] })[] = [];
+  const budget = { n: cap };
   const roots = [...new Set([...tree.keys()].map((k) => k.split("/", 1)[0] as string))].sort();
   const keys = [...tree.keys()].sort();
   for (const root of roots) {
     const prefix = `${root}/`;
     const indexKey = `${prefix}${CASE_FILE_INDEX_NAME}`;
     const indexEntry = tree.get(indexKey);
-    const indexBytes =
-      indexEntry !== undefined && indexEntry.regular ? await readFileEntry(indexEntry, indexKey) : null;
-    const files: { path: string; sha256: string }[] = [];
-    if (indexBytes !== null) {
-      for (const key of keys) {
+    let indexBytes: Uint8Array | null = null;
+    let refused: string | null = null;
+    if (indexEntry !== undefined && indexEntry.regular) {
+      try {
+        indexBytes = await readFileEntry(indexEntry, indexKey, whole);
+      } catch (e) {
+        if (e instanceof WholeReadRefused) refused = INDEX_OVER_BUDGET;
+        else if (e instanceof CaseInputError) refused = INDEX_NOT_READ;
+        else throw e;
+      }
+    }
+    const files: { path: string; sha256?: string; too_large?: boolean }[] = [];
+    const listed = indexBytes !== null ? caseFileListedPaths(indexBytes) : null;
+    if (listed !== null) {
+      const candidates = keys
+        .filter((key) => key.startsWith(prefix) && tree.get(key)!.regular)
+        .map((key) => [key, key.slice(prefix.length)] as const)
+        .filter(([, rel]) => rel.startsWith("packs/") || rel.startsWith("report/"));
+      // The files the index lists are charged first, then the rest, each group
+      // in UTF-16 order, so a file it does not list cannot use up the total and
+      // turn a real mismatch into `too_large`.
+      for (const [key, rel] of [
+        ...candidates.filter(([, rel]) => listed.has(rel)),
+        ...candidates.filter(([, rel]) => !listed.has(rel)),
+      ]) {
         const entry = tree.get(key)!;
-        const rel = key.slice(prefix.length);
-        if (
-          key.startsWith(prefix) &&
-          entry.regular &&
-          (rel.startsWith("packs/") || rel.startsWith("report/"))
-        ) {
-          files.push({ path: rel, sha256: await sha256Hex(await readFileEntry(entry, key)) });
+        let digest: string | null;
+        if (entry.data !== undefined && entry.data !== null) {
+          if (entry.data.length > budget.n) digest = TOO_LARGE;
+          else {
+            budget.n -= entry.data.length;
+            digest = await sha256Hex(entry.data);
+          }
+        } else {
+          digest = await hashFile(entry.fsPath, false, budget);
         }
+        if (digest === TOO_LARGE) files.push({ path: rel, too_large: true });
+        else if (digest === null) throw new CaseInputError(`cannot read ${key}`);
+        else files.push({ path: rel, sha256: digest });
       }
     }
-    const reading = readCaseFileIndex(indexBytes, files);
+    const reading =
+      refused !== null ? unreadableCaseFileIndex(refused) : readCaseFileIndex(indexBytes, files);
     const nil = <T>(v: T | undefined): T | null => (v === undefined ? null : v);
     out.push({
       root,
@@ -2227,6 +2715,60 @@ export async function runCase(argv: readonly string[], stream: Cli): Promise<num
   }
 }
 
+// The files that sit outside every pack, as files offered (A41, proof#215).
+//
+// Every regular file the split left outside, in the split's order, hashed
+// exactly as a `--files` file is (a folder's file in pieces, a `.zip` entry
+// from the bytes the reader already holds) and named by its path in the tree,
+// `<case name>/<path inside>`, so a `.zip` and the folder `unzip` makes of it
+// name each file alike. A link, a pipe, an entry the zip reader refused (with
+// its own words) and a file that cannot be read are returned as skipped, named
+// and never opened as a pack file. A pack's own files, `bundle.json` and what
+// is under `logs/`, are not outside and are not offered.
+//
+// The files share one total of 1 GiB, the cap the zip reader puts on an
+// archive, charged in that order. A file larger than what is left is skipped as
+// `too_large` and read no further, so a sparse file of a terabyte in a
+// downloaded folder cannot keep `case` from reaching its verdict.
+export async function looseFiles(
+  tree: Map<string, TreeEntry>,
+  split: SplitCase,
+  cap: number = MAX_FOLDER_BYTES,
+): Promise<{ offered: OfferedFile[]; skipped: SkippedFile[] }> {
+  const offered: OfferedFile[] = [];
+  const skipped: SkippedFile[] = [];
+  const budget = { n: cap };
+  for (const path of split.outside) {
+    const entry = tree.get(path)!;
+    if (entry.link === true) {
+      skipped.push({ name: path, reason: "symbolic_link" });
+      continue;
+    }
+    if (entry.refused !== undefined) {
+      skipped.push({ name: path, reason: "refused", detail: entry.refused });
+      continue;
+    }
+    if (!entry.regular) {
+      skipped.push({ name: path, reason: "not_regular" });
+      continue;
+    }
+    let digest: string | null;
+    if (entry.data !== undefined && entry.data !== null) {
+      if (entry.data.length > budget.n) digest = TOO_LARGE;
+      else {
+        budget.n -= entry.data.length;
+        digest = await sha256Hex(entry.data);
+      }
+    } else {
+      digest = await hashFile(entry.fsPath, false, budget);
+    }
+    if (digest === TOO_LARGE) skipped.push({ name: path, reason: "too_large" });
+    else if (digest === null) skipped.push({ name: path, reason: "unreadable" });
+    else offered.push({ name: path, sha256: digest });
+  }
+  return { offered, skipped };
+}
+
 async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
   let asJson = false;
   let gateways: string[] = [];
@@ -2276,18 +2818,21 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
   }
 
   let offered: OfferedFile[] | undefined;
+  let skipped: SkippedFile[] = [];
   if (filePaths !== undefined) {
     const read = await readOfferedFiles(filePaths);
     if (typeof read === "string") return caseError(new CaseInputError(read), asJson, io);
-    offered = read;
+    offered = read.offered;
+    skipped = read.skipped;
   }
 
+  const whole = { n: MAX_FOLDER_BYTES };
   let split;
   let tree: Map<string, TreeEntry>;
   let bundles: [SplitPack, unknown][];
   try {
     tree = await treeFromArguments(paths);
-    split = await splitCase(tree, readFileEntry);
+    split = await splitCase(tree, (entry, key) => readFileEntry(entry, key, whole));
     bundles = split.packs.map((p): [SplitPack, unknown] => [p, loadBundle(p)]);
   } catch (e) {
     if (e instanceof CaseInputError) return caseError(e, asJson, io);
@@ -2299,14 +2844,15 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
   );
   let caseFile: CaseFileData[];
   try {
-    caseFile = await caseFileReadings(tree);
+    caseFile = await caseFileReadings(tree, whole);
   } catch (e) {
     if (e instanceof CaseInputError) return caseError(e, asJson, io);
     throw e;
   }
   const caches: CachedWitnessTime[][] = [];
+  const cacheRefused: string[] = [];
   for (const [p, bundle] of bundles) {
-    caches.push(readWitnessCache(bundle, await witnessCacheBytes(tree, split, p)));
+    caches.push(readWitnessCache(bundle, await witnessCacheBytes(tree, split, p, whole, cacheRefused)));
   }
   const onChain = await onChainHalf(
     bundles.map(([p, bundle], i): [string, unknown, CachedWitnessTime[]] => [p.ref, bundle, caches[i]!]),
@@ -2336,7 +2882,9 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
     exceptions: reading.exceptions.map((e) => ({
       kind: e.kind,
       pack_ref: nil(e.packRef),
+      pack_index: nil(e.packIndex),
       event_id: nil(e.eventId),
+      record_index: nil(e.recordIndex),
       counterparty_key: nil(e.counterpartyKey),
       failed_checks: e.failedChecks ?? [],
       count: nil(e.count),
@@ -2348,12 +2896,18 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
     notes: reading.notes.map((n) => ({
       kind: n.kind,
       pack_ref: n.packRef,
+      pack_index: n.packIndex,
       count: nil(n.count),
       rendered: renderCaseNote(n),
     })),
     records: reading.records.map((r) => ({
       pack_ref: r.packRef,
+      pack_index: r.packIndex,
       event_id: r.eventId,
+      record_index: r.recordIndex,
+      status: r.status,
+      reason: r.reason,
+      declaration_findings: [...r.declarationFindings],
       verdict: nil(r.verdict),
       role: r.role,
       findings: r.findings,
@@ -2362,6 +2916,7 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
     })),
     contributions: reading.contributions.map(([who, verdict]) => [who, verdict]),
     packs: bundles.map(([p], i) => ({
+      index: reading.packs[i]!.index,
       ref: p.ref,
       bundle_path: p.bundlePath,
       log_files: p.content.size,
@@ -2375,19 +2930,35 @@ async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
     not_regular: split.notRegular,
     case_file: caseFile,
     on_chain: onChain,
+    ...(cacheRefused.length > 0 ? { witness_cache_not_read: cacheRefused } : {}),
   };
-  // Files handed in beside the packs (evidence-bundle.md 5.7, A29). A pack's
-  // logs/ is its side content and is never an offered file; only the paths
-  // after --files are. Nothing here moves `code`.
+  // The files outside every pack (evidence-bundle.md 5.7, A29, A41), always,
+  // then the files after --files. A pack's logs/ is its side content and is
+  // never an offered file; only the paths after --files are. Both are matched
+  // by SHA-256 alone and nothing here moves `code`. The section is printed when
+  // there is a file to say something about, so a case with nothing outside
+  // every pack and no --files prints what it always did.
+  const loose = await looseFiles(tree, split);
   let fileLines: string[] = [];
   const out: Record<string, unknown> = data;
-  if (offered !== undefined) {
-    const fileReading = await matchCaseFiles(
-      bundles.map(([p, bundle]) => ({ ref: p.ref, bundle, content: p.content })),
-      offered,
-    );
+  if (offered !== undefined || loose.offered.length > 0 || loose.skipped.length > 0) {
+    const fileReading = {
+      ...(await matchCaseFiles(
+        bundles.map(([p, bundle]) => ({ ref: p.ref, bundle, content: p.content })),
+        [...loose.offered, ...(offered ?? [])],
+      )),
+      skipped: [...loose.skipped, ...skipped],
+    };
     out.files = fileMatchToJson(fileReading);
-    fileLines = renderFileMatch(fileReading);
+    // No --files: one count line for the recorded files no loose file matched,
+    // not a line for each of them, and none for a record the pack's own logs
+    // disclose and bind. With --files, and in --json, every one is listed.
+    fileLines = renderFileMatch(
+      fileReading,
+      offered !== undefined
+        ? undefined
+        : (await notAccountedFor(fileReading, new Map(bundles.map(([p]) => [p.ref, p.content])))).length,
+    );
   }
   if (asJson) outJson(io, jsonText(out));
   else for (const line of [...caseReport(data), ...fileLines]) io.out(noLoneSurrogates(line));