@sanning/proof 0.11.1 → 0.13.0

package/src/cli.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-// npx @sanning/proof verify <bundle.json> [comma,sep,gateways]
+// sanning-proof verify <bundle.json> [--gateways <url,url>]
+// (`npx @sanning/proof verify ...` without installing: npm runs a package's
+// only binary whatever it is called.)
 //
 // One turnkey verifier for both producer bundles in the stack:
 //   - sanning.evidence/v1: bodies sanning.anchor.trace/v3, sanning.stamp.trace/v1,
@@ -7,12 +9,16 @@
 //   - sanning.agent.proof/v1: the agent inclusion proof
 // Dispatch is by sniffed spec_version; no flag tells the CLI which it is.
 //
-// Pinned exit codes (mirror `sanningd verify-status`):
-//   0  verified
-//   1  a real verification failure (bad signature / tamper / broken inclusion)
-//   2  malformed bundle (unparseable, unknown spec major, body_hash mismatch)
-//   3  UNDETERMINED: a gateway was unreachable when an on-chain re-fetch was
-//      requested, or the PACK is `incomplete` (see below)
+// Exit codes: one table for every verb, `./exit-codes.ts` (0.13.0):
+//   0  verified, or the export was written
+//   1  failed (bad signature / tamper / broken inclusion / on-chain mismatch)
+//   2  usage or malformed (unparseable, unknown spec major, body_hash mismatch)
+//   3  UNDETERMINED: partial, pending, incomplete or not_found. A gateway that
+//      could not be reached reads `partial`; a pack whose records nobody hashed
+//      reads `incomplete` (see below)
+//   4  mixed
+// `sanningd verify-status` in sanning-io/agent mirrored the 0.12 table, which
+// exited 0 on `partial`; it moves with this one.
 //
 // ── The headline is the PACK verdict, not the bundle status (proof#110) ──
 //
@@ -25,9 +31,10 @@
 // terminal: two answers to one question, from one kernel, which is the exact
 // defect `grading.ts` was brought into the kernel to end.
 //
-// The two enums stay distinct, deliberately (`grading.ts` says so in its own
-// comments, and `evidence-bundle.md` §3 does not carry `incomplete`): the
-// BUNDLE status is still reported, unchanged, on its own line. What changed is
+// The two layers stay distinct, deliberately (`grading.ts` says so in its own
+// comments, and `incomplete` is a pack verdict in `evidence-bundle.md` §3,
+// never a bundle status): the BUNDLE status is still reported, unchanged, on
+// its own line. What changed is
 // which of the two is the headline and which one the exit code follows.
 //
 // `payloadHashOk === null` (a withheld record) is semantics-undetermined and
@@ -35,12 +42,13 @@
 // PACK at `incomplete`, because a record nobody hashed is a record nobody
 // checked, and exit 3 is how this command says "undetermined".
 
-import { readFile, readdir, stat, writeFile } from "node:fs/promises";
-import { realpathSync } from "node:fs";
-import { join } from "node:path";
+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 { fileURLToPath } from "node:url";
 
-import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
+import { isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
 import type { AgentProofResult } from "./agent-proof.js";
 import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
 
@@ -48,21 +56,41 @@ import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js"
 // named statement that one could not be produced. Three states, not two.
 type ChainOutcome = ChainReading | { unreadable: string };
 import type { ChainReading } from "./chain.js";
+import {
+  CASE_RELIANCE,
+  VERDICT_DISPLAY_TITLES,
+  WITNESS_NOT_LOOKED_UP,
+  type WitnessLine,
+  readCase,
+  renderCaseNote,
+  renderCaseSummary,
+  renderException,
+  renderWitnessLine,
+} from "./case.js";
+import {
+  CASE_FILE_INDEX_NAME,
+  jsonDepthExceeds,
+  readCaseFileIndex,
+  renderCaseFileFinding,
+} from "./case-file.js";
+import { ZipReadError, readZip } from "./zip-reader.js";
 import { composeExport } from "./compose.js";
 import type { ComposeExportOptions } from "./compose.js";
-import { isHexField, utf8 } from "./crypto.js";
+import { isHexField, sha256Hex, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
 import type { AttestationRecord, EvidenceBundle, EvidenceBundleResult, ExportResult } from "./evidence.js";
 import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
 import { completenessNotes, gradePack, renderCause } from "./grading.js";
 import type { DisclosureAccount, PackGrade } from "./grading.js";
 
-const EXIT_VERIFIED = 0;
-const EXIT_FAILED = 1;
-const EXIT_MALFORMED = 2;
-// One code, two undetermined outcomes: a gateway we could not reach, and a pack
-// whose records nobody hashed. Neither is an accusation, and neither is a pass.
-const EXIT_UNDETERMINED = 3;
+import {
+  EXIT_CODES_HELP,
+  EXIT_FAILED,
+  EXIT_MALFORMED,
+  EXIT_UNDETERMINED,
+  EXIT_VERIFIED,
+  exitCodeFor,
+} from "./exit-codes.js";
 
 interface Cli {
   out: (s: string) => void;
@@ -70,12 +98,78 @@ interface Cli {
   fetchImpl?: typeof fetch;
 }
 
-const G = "\x1b[32m";
-const R = "\x1b[31m";
-const Y = "\x1b[33m";
-const DIM = "\x1b[2m";
-const B = "\x1b[1m";
-const X = "\x1b[0m";
+// ── What a person reads is escaped at one choke point ──
+//
+// Every human-readable line this command prints passes through `guard`, which
+// `runCli` and `runCase` apply to the streams they are handed. It escapes each
+// control character, so a value the audited party wrote (a folder or file
+// name, a `contents.json` field, a zip entry name, an exception built from
+// one) cannot move the cursor, clear the screen or reorder the line. Before
+// this, a case file whose name carried `\x1b[2J\x1b[H` printed "Verified" over
+// a FAILED headline. `outJson` is the one way around it, and it carries JSON
+// only, which escapes its own control characters. The twin is `Io` in
+// `src/sanning_proof/cli.py`, and the two print byte-identical escapes.
+
+// C0, DEL, C1, the two Unicode line and paragraph separators, and the bidi
+// embedding, override and isolate controls.
+const CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+
+/** Each control character in `text` as a visible escape: `\x1b` for ESC,
+ * `\u202e` for RIGHT-TO-LEFT OVERRIDE. Every other character is unchanged, a
+ * backslash included, so a line with none is printed as it was. */
+export function escapeControl(text: string): string {
+  return text.replace(CONTROL_CHARACTERS, (c) => {
+    const code = c.charCodeAt(0);
+    return code < 0x100
+      ? `\\x${code.toString(16).padStart(2, "0")}`
+      : `\\u${code.toString(16).padStart(4, "0")}`;
+  });
+}
+
+// The colors this command writes on a TTY are its own control characters, and
+// the choke point would escape them with everything else. So `paint` and
+// `mark` write this marker instead, and the choke point turns it into ESC
+// after escaping. It is random per process, so no input can spell it.
+const COLOR_MARK = `sgr${randomBytes(16).toString("hex")}:`;
+const G = `${COLOR_MARK}32m`;
+const R = `${COLOR_MARK}31m`;
+const Y = `${COLOR_MARK}33m`;
+const DIM = `${COLOR_MARK}2m`;
+const B = `${COLOR_MARK}1m`;
+const X = `${COLOR_MARK}0m`;
+
+function forTerminal(text: string): string {
+  return escapeControl(text).split(COLOR_MARK).join("\x1b[");
+}
+
+const RAW = Symbol("sanning.cli.raw");
+type Guarded = Cli & { [RAW]: Cli };
+
+function guard(io: Cli): Cli {
+  if (RAW in io) return io;
+  const guarded: Guarded = {
+    out: (s) => io.out(forTerminal(s)),
+    err: (s) => io.err(forTerminal(s)),
+    [RAW]: io,
+    ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
+  };
+  return guarded;
+}
+
+function rawOf(io: Cli): Cli {
+  return (io as Partial<Guarded>)[RAW] ?? io;
+}
+
+/** JSON, printed unescaped: a script reads it, not a terminal. */
+function outJson(io: Cli, text: string): void {
+  rawOf(io).out(text);
+}
+
+/** A block this command wrote itself, such as a usage text: its own newlines
+ * are kept, and each line is escaped as `out` escapes it. */
+function outBlock(io: Cli, text: string): void {
+  rawOf(io).out(text.split("\n").map(forTerminal).join("\n"));
+}
 
 function useColor(): boolean {
   // Honor NO_COLOR; otherwise color only a TTY.
@@ -94,7 +188,8 @@ function paint(s: string, c: string): string {
   return useColor() ? `${c}${s}${X}` : s;
 }
 
-export async function runCli(argv: string[], io: Cli): Promise<number> {
+export async function runCli(argv: string[], stream: Cli): Promise<number> {
+  const io = guard(stream);
   const [command, ...rest] = argv;
 
   if (command === undefined || command === "help" || command === "--help" || command === "-h") {
@@ -105,25 +200,97 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     io.out("@sanning/proof verify CLI");
     return EXIT_VERIFIED;
   }
-  // `bundle` is the customer-facing verb (proof#19: one artifact, one word).
-  // `export` is kept working as a QUIET alias — it shipped and is published, so
-  // it is not broken abruptly; it is simply no longer taught anywhere.
-  if (command === "bundle" || command === "export") {
-    return runBundle(rest, io);
+  // `export` composes an attested export (`sanning.evidence.export/v2`). It
+  // was taught as `bundle` until 0.13.0, and `bundle` is now the one verb that
+  // builds a pack (`anchor bundle`, DL-59), so this command no longer answers
+  // to it: `proof bundle` is an unknown command and exits 2, with no alias.
+  if (command === "export") {
+    if (rest.includes("--json")) {
+      return runJson(
+        rest.filter((a) => a !== "--json"),
+        io,
+        runExport,
+      );
+    }
+    return runExport(rest, io, null);
+  }
+  if (command === "case") {
+    return runCase(rest, io);
   }
   if (command !== "verify") {
     io.err(`unknown command: ${command}`);
     printUsage(io);
     return EXIT_MALFORMED;
   }
+  if (rest.includes("--json")) {
+    return runJson(
+      rest.filter((a) => a !== "--json"),
+      io,
+      runVerify,
+    );
+  }
+  return runVerify(rest, io, null);
+}
+
+// ─── `--json` on `verify` and `export` (C-03, 0.13.0) ──────────────────────
+//
+// `case --json` printed the reading as JSON and the other two verbs had no
+// machine-readable form, so a script parsed the text. Each verb now runs as it
+// does for a person, with its text discarded, and hands this one object back
+// through `sink`: the same keys in both kernels, sorted at every depth, and
+// printed byte for byte the same (`cross-kernel/run_cli.sh`,
+// `cross-kernel/run_export_cli.sh`). A run that stops before it has anything to
+// report (a bad flag, an unreadable file) prints `{ error, exit_code }`, as
+// `case --json` does. `note:` lines still go to stderr.
+interface JsonSink {
+  data: Record<string, unknown> | null;
+}
+
+type JsonVerb = (rest: string[], io: Cli, sink: JsonSink | null) => Promise<number>;
+
+async function runJson(rest: string[], io: Cli, verb: JsonVerb): Promise<number> {
+  const errs: string[] = [];
+  const sink: JsonSink = { data: null };
+  const quiet: Cli = {
+    out: () => {},
+    err: (s) => errs.push(s),
+    ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
+  };
+  const code = await verb(rest, quiet, sink);
+  const notes = errs.filter((l) => l.startsWith("note: "));
+  for (const n of notes) io.err(n);
+  if (sink.data !== null) {
+    outJson(io, jsonText({ ...sink.data, exit_code: code }));
+  } else {
+    const error = errs.filter((l) => !l.startsWith("note: ")).join("\n");
+    outJson(io, jsonText({ error, exit_code: code }));
+  }
+  return code;
+}
+
+async function runVerify(rest: string[], io: Cli, sink: JsonSink | null): Promise<number> {
 
-  // Pull the optional `--logs <path>` flag out of the args; the rest are
-  // positional (<bundle> [gateways]). --logs feeds disclosed raw-log bytes for
-  // content verification (the evidence-bundle path only).
+  // `--logs <path>` feeds disclosed raw-log bytes for content verification
+  // (the evidence-bundle path only); `--gateways <url,url>` asks for the
+  // on-chain re-fetch, as it does on `case` (0.13.0: the gateway list was a
+  // second positional argument until then, and a second positional is now a
+  // usage error). The one positional is the bundle.
   let logsPath: string | undefined;
+  let gatewayArg: string | undefined;
   const positional: string[] = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i]!;
+    if (a === "--gateways") {
+      const next = rest[i + 1];
+      if (next === undefined) {
+        io.err("verify: --gateways requires a comma-separated list of URLs");
+        printUsage(io);
+        return EXIT_MALFORMED;
+      }
+      gatewayArg = next;
+      i++;
+      continue;
+    }
     if (a === "--logs") {
       const next = rest[i + 1];
       if (next === undefined) {
@@ -138,12 +305,17 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     positional.push(a);
   }
 
-  const [bundlePath, gatewayArg] = positional;
+  const [bundlePath] = positional;
   if (!bundlePath) {
     io.err("verify: a bundle file path is required");
     printUsage(io);
     return EXIT_MALFORMED;
   }
+  if (positional.length > 1) {
+    io.err("verify: takes one bundle; pass gateways as --gateways <url,url>");
+    printUsage(io);
+    return EXIT_MALFORMED;
+  }
   const gateways = (gatewayArg ?? "")
     .split(",")
     .map((g) => g.trim())
@@ -157,19 +329,26 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
   }
   const content = logs?.content;
 
-  let raw: string;
+  let raw: Uint8Array;
   try {
-    raw = await readFile(bundlePath, "utf8");
+    raw = new Uint8Array(await readFile(bundlePath));
   } catch (e) {
     io.err(`cannot read ${bundlePath}: ${e instanceof Error ? e.message : String(e)}`);
     return EXIT_MALFORMED;
   }
 
+  // The one reader both commands use, in both kernels: `case` reads each pack's
+  // bundle.json through it too, so the two commands classify one bundle the
+  // same way (see `readBundleBytes`).
   let parsed: unknown;
   try {
-    parsed = JSON.parse(raw);
+    parsed = readBundleBytes(raw);
   } catch (e) {
-    io.err(`${bundlePath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    if (e instanceof BundleReadError && e.tooDeep) {
+      io.err(`${bundlePath} ${e.detail}; refusing to read it`);
+    } else {
+      io.err(`${bundlePath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
     return EXIT_MALFORMED;
   }
 
@@ -184,11 +363,11 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
       // has no such per-event content. Say so rather than silently ignoring it.
       io.err("note: --logs has no effect on a sanning.agent.proof/v1 bundle (ignored)");
     }
-    const result = await verifyAgentProofBundle(parsed, {
+    const result = await verifyAgentProof(parsed, {
       gateways,
       ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
     });
-    return reportAgentProof(result, bundlePath, gateways, io);
+    return reportAgentProof(result, bundlePath, gateways, io, sink);
   }
 
   // Default: treat anything else as an evidence bundle. verifyEvidenceBundle
@@ -217,26 +396,29 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
   } catch (e) {
     chains = { unreadable: errMsg(e) };
   }
-  const exit = reportEvidence(result, bundlePath, gateways, io, chains, parsed, logs);
+  const exit = reportEvidence(result, bundlePath, gateways, io, chains, parsed, logs, sink);
   // Coverage is reported only once the bundle parsed far enough to have events
   // to compare against; over a MALFORMED bundle there is nothing to say.
   if (logs && result.status !== "malformed") reportLogsCoverage(logs, result, io);
   return exit;
 }
 
-// `proof bundle <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
-// (`proof export` still reaches this, undocumented — see the dispatch above.)
+// `proof export <source-bundle.json> --attestations <f> --key <f> [--out <out>]`
 //
 // Compose a signed, offline-verifiable sanning.evidence.export/v2 artifact from a
 // source sanning.anchor.trace/v3 bundle + operator attestation records + an exporter
-// Ed25519 key (evidence-export.md §5, composer). Writes the export to `-o <out>`
+// Ed25519 key (evidence-export.md §5, composer). Writes the export to `--out <out>`
 // (or stdout when omitted, so it can be piped straight into `proof verify`).
 //
 // Exit codes: 0 composed OK · 1 the recomputed export is FAILED (a bad source or
 // forged/mis-bound attestation — the composer refuses to emit a green artifact
 // over failing evidence) · 2 usage / malformed input (missing flag, unreadable
 // or non-JSON input, bad exporter key, malformed attestation record).
-async function runBundle(rest: string[], io: Cli): Promise<number> {
+async function runExport(rest: string[], io: Cli, sink: JsonSink | null): Promise<number> {
+  if (rest[0] === "--help" || rest[0] === "-h" || rest[0] === "help") {
+    usageExport(io);
+    return EXIT_VERIFIED;
+  }
   let attestationsPath: string | undefined;
   let keyPath: string | undefined;
   let outPath: string | undefined;
@@ -254,15 +436,15 @@ async function runBundle(rest: string[], io: Cli): Promise<number> {
       i++;
       return next;
     };
-    if (a === "--attestations" || a === "-a") {
+    if (a === "--attestations") {
       const v = takeNext(a);
       if (v === undefined) return usageExport(io);
       attestationsPath = v;
-    } else if (a === "--key" || a === "-k") {
+    } else if (a === "--key") {
       const v = takeNext(a);
       if (v === undefined) return usageExport(io);
       keyPath = v;
-    } else if (a === "--out" || a === "-o") {
+    } else if (a === "--out") {
       const v = takeNext(a);
       if (v === undefined) return usageExport(io);
       outPath = v;
@@ -282,6 +464,12 @@ async function runBundle(rest: string[], io: Cli): Promise<number> {
       const v = takeNext(a);
       if (v === undefined) return usageExport(io);
       opts.generatedAt = v;
+    } else if (a.startsWith("-")) {
+      // A flag this verb does not take is a usage error, never a path: `-o`
+      // was a short form of `--out` until 0.13.0, and read as a path it would
+      // send the export to stdout while the caller waits for a file.
+      io.err(`export: unknown option ${a}`);
+      return usageExport(io);
     } else {
       positional.push(a);
     }
@@ -327,6 +515,18 @@ async function runBundle(rest: string[], io: Cli): Promise<number> {
   // FAILED recompute (bad source / forged / mis-bound attestation) exits 1 and
   // still writes the artifact so the caller can inspect it.
   const serialized = JSON.stringify(composed.bundle, null, 2) + "\n";
+  if (sink) {
+    sink.data = {
+      status: composed.status,
+      out: outPath ?? null,
+      source_bundle_hash: composed.sourceBundleHash,
+      attestations: attestations.length,
+      attestations_bound: composed.boundAttestations,
+      // Without --out the artifact rides inside this object, since stdout
+      // carries the object and not the artifact.
+      export: outPath ? null : composed.bundle,
+    };
+  }
   if (outPath) {
     try {
       await writeFile(outPath, serialized, "utf8");
@@ -340,28 +540,34 @@ async function runBundle(rest: string[], io: Cli): Promise<number> {
         `attestations ${composed.boundAttestations}/${attestations.length} bound`,
     );
   } else {
-    io.out(serialized.replace(/\n$/, ""));
+    outJson(io, serialized.replace(/\n$/, ""));
   }
   return composed.status === "failed" ? EXIT_FAILED : EXIT_VERIFIED;
 }
 
 function usageExport(io: Cli): number {
   io.out(
-    "Usage: npx @sanning/proof bundle <source-bundle.json> --attestations <file> --key <file> [-o <out.json>]",
+    "Usage: sanning-proof export <source-bundle.json> --attestations <file> --key <file> [--out <out.json>] [--json]",
   );
   io.out("");
   io.out("Compose a signed, offline-verifiable sanning.evidence.export/v2 artifact from an");
   io.out("sanning.anchor.trace/v3 source bundle + operator attestation records + an exporter");
-  io.out("Ed25519 key. The output verifies with `proof verify <out.json>`.");
+  io.out("Ed25519 key. The output verifies with `sanning-proof verify <out.json>`.");
   io.out("");
   io.out("--attestations <file>  JSON array of attestation records (or {attestations:[...]}).");
   io.out("--key <file>           Exporter Ed25519 key: a 32-byte hex seed, or JSON");
   io.out('                       {"privateKey":"<hex>"} / {"seed":"<hex>"}.');
-  io.out("-o, --out <file>       Write the export here (default: stdout).");
+  io.out("--out <file>           Write the export here (default: stdout).");
   io.out("--issuer-id <id>       Wrapper issuer.issuer_id (default sanning-verify).");
   io.out("--gateway <url>        Named delivery surface (not trusted).");
   io.out("--previous-hash <h>    Custody pointer (default GENESIS).");
   io.out("--generated-at <ts>    RFC 3339 compose time (default now).");
+  io.out("--json                 Print a summary as JSON (with the export inside it");
+  io.out("                       when --out is not given).");
+  io.out("");
+  for (const line of EXIT_CODES_HELP.split("\n")) io.out(line);
+  io.out("");
+  io.out("export: 1 means the recomputed export is failed; it is still written.");
   return EXIT_MALFORMED;
 }
 
@@ -435,7 +641,7 @@ async function readExporterKey(path: string, io: Cli): Promise<string | undefine
 //              disclosure. This is the layout `materializeBundle` writes
 //              (bundle.json + logs/) and the layout the verify page hashes,
 //              so a pack verifies with NO side-input construction step.
-//   JSON MAP   `{ event_id: <even-length lowercase hex | utf8 text> }`, the
+//   JSON MAP   `{ event_id: <even-length hex, either case | utf8 text> }`, the
 //              original form. Unchanged.
 //
 // **Why the directory form exists at all.** Handing a pack to the CLI used to
@@ -454,7 +660,7 @@ async function readExporterKey(path: string, io: Cli): Promise<string | undefine
 // and the verify page agree about one pack.
 interface LoadedLogs {
   // Keyed by event id. A `Uint8Array` is raw bytes (directory form); a `string`
-  // is lowercase hex (map form). Those are exactly the two the verifier
+  // is hex in either case (map form). Those are exactly the two the verifier
   // distinguishes.
   //
   // A `Map`, NOT a plain object, and that is load-bearing rather than stylistic.
@@ -647,7 +853,8 @@ function reportLogsCoverage(logs: LoadedLogs, result: EvidenceBundleResult, io:
   if (undetermined.length > 0) {
     io.err(
       `note: ${undetermined.length} of ${result.events.length} event(s) have undetermined ` +
-        `content — no bytes disclosed, or no committed content_hash to bind them to. ` +
+        `content: no bytes disclosed, or no committed content_hash (message_hash for a ` +
+        `hand-off record) to bind them to. ` +
         `Undisclosed, not failed: ${sample(undetermined.map((e) => e.eventId))}`,
     );
   }
@@ -695,30 +902,39 @@ function decodeLogValue(v: string): Uint8Array | string {
 }
 
 function printUsage(io: Cli): void {
-  io.out("Usage: npx @sanning/proof <command> [args]");
+  io.out("Usage: sanning-proof <command> [args]");
+  io.out("       (npx @sanning/proof <command> [args], without installing)");
   io.out("");
   io.out("Commands:");
-  io.out("  verify <bundle.json> [gateways] [--logs <path>]        Verify a bundle");
-  io.out("  bundle <source.json> --attestations <f> --key <f> [-o] Create an attested bundle");
+  io.out("  verify <bundle.json> [--gateways <urls>] [--logs <path>] [--json]  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>] [--json]          Read several packs as one case");
+  io.out("                                                          (`case --help` for its exit codes)");
   io.out("");
   io.out("Verify a sanning.evidence/v1 bundle (body sanning.anchor.trace/v3,");
   io.out("sanning.stamp.trace/v1, sanning.stamp.evidence/v2 or the attested export");
   io.out("sanning.evidence.export/v2) or a sanning.agent.proof/v1 inclusion bundle,");
-  io.out("fully offline. Supply a comma-separated gateway list to also re-fetch");
-  io.out("each checkpoint and stamp on-chain. Only arweave witnesses are re-fetched;");
+  io.out("fully offline. Pass --gateways <url,url> to also re-fetch each");
+  io.out("checkpoint and stamp on-chain. Only arweave witnesses are re-fetched;");
   io.out("a witness of any other kind is not checked and the run exits 3.");
   io.out("");
+  io.out("--json              Print the verdict, the causes and the exit code as");
+  io.out("                    JSON, for a script, instead of the report.");
+  io.out("");
   io.out("--logs <path>       Bind disclosed raw logs to each event's committed");
-  io.out("                    content_hash. Either shape works, and which one you");
+  io.out("                    content_hash, or message_hash for a hand-off record.");
+  io.out("                    Either shape works, and which one you");
   io.out("                    passed is decided by stat(), not by the extension:");
   io.out("");
   io.out("                      a DIRECTORY of <event_id>.json files — the file's");
   io.out("                      raw bytes ARE the content, nothing is decoded.");
   io.out("                      This is a materialized pack's logs/ directory:");
-  io.out("                        proof verify <pack>/bundle.json --logs <pack>/logs");
+  io.out("                        sanning-proof verify <pack>/bundle.json --logs <pack>/logs");
   io.out("");
   io.out("                      a JSON FILE mapping event_id → bytes (an");
-  io.out("                      even-length lowercase-hex value ⇒ hex, else utf8).");
+  io.out("                      even-length hex value, in either case, ⇒ hex,");
+  io.out("                      else utf8).");
   io.out("");
   io.out("                    In-body events[].content is verified automatically");
   io.out("                    and takes precedence. An event with no disclosed");
@@ -728,8 +944,10 @@ function printUsage(io: Cli): void {
   io.out("a record nobody hashed leaves the pack INCOMPLETE even when the signed");
   io.out("bundle itself is verified. Both verdicts are printed when they differ.");
   io.out("");
-  io.out("Exit codes: 0 verified · 1 failed · 2 malformed · 3 undetermined");
-  io.out("            (an unreachable gateway, or an incomplete pack)");
+  for (const line of EXIT_CODES_HELP.split("\n")) io.out(line);
+  io.out("");
+  io.out("verify: an unreachable gateway reads partial, and a pack with a record");
+  io.out("nobody hashed reads incomplete; both exit 3, and neither is a failure.");
 }
 
 /**
@@ -777,8 +995,10 @@ function reportEvidence(
   chains: ChainOutcome,
   parsed: unknown,
   logs: LoadedLogs | undefined,
+  sink: JsonSink | null,
 ): number {
   if (result.status === "malformed") {
+    if (sink) sink.data = verifyJson(result, null, null, null);
     io.err(paint("MALFORMED", R) + `  ${path}`);
     for (const e of result.errors) io.err(`  - ${e}`);
     return EXIT_MALFORMED;
@@ -876,7 +1096,7 @@ function reportEvidence(
   // answers `partial` and the line below says so in words, and pack grading
   // keeps its own verdict: every pack built before §5.4 carries no
   // declaration, and re-grading them all as undetermined would be a change to
-  // the pinned 0/1/2/3 contract rather than a new check. A pack that DOES
+  // their verdicts rather than a new check. A pack that DOES
   // carry a declaration this reader cannot read is a different case and exits
   // 3: the holder chose that field, so UNKNOWN is the honest answer.
   const declaration = checkDeclaration(parsed, logs?.content);
@@ -915,7 +1135,47 @@ function reportEvidence(
     );
   }
 
-  return mapGradeToExit(grade, result);
+  if (sink) sink.data = verifyJson(result, grade, declaration, chains);
+  return mapGradeToExit(grade);
+}
+
+/**
+ * What `verify --json` prints for an evidence bundle, the same keys and the
+ * same words as `_verify_json` in the Python twin. `grade`, `declaration` and
+ * `chains` are null for a bundle no verdict could be rendered over.
+ */
+function verifyJson(
+  result: EvidenceBundleResult,
+  grade: PackGrade | null,
+  declaration: ReturnType<typeof checkDeclaration> | null,
+  chains: ChainOutcome | null,
+): Record<string, unknown> {
+  let chainBlock: Record<string, unknown> | null = null;
+  if (chains !== null) {
+    chainBlock =
+      "unreadable" in chains
+        ? { unreadable: chains.unreadable, chains: 0, findings: [] }
+        : {
+            unreadable: null,
+            chains: chains.chains.length,
+            findings: chains.findings.map((f) => renderChainFinding(f, "this bundle")),
+          };
+  }
+  return {
+    verdict: grade ? grade.verdict : result.status,
+    bundle_status: result.status,
+    asserted_status: result.assertedStatus ?? null,
+    body_type: result.bodyType ?? null,
+    on_chain_checked: result.onChainChecked,
+    declaration: declaration ? declaration.verdict : null,
+    declaration_notes: declaration ? declaration.notes.map(renderNote) : [],
+    causes: grade ? grade.causes.map((c) => renderCause(c, "the pack")) : [],
+    notes: [...result.errors],
+    records: grade
+      ? { presented: result.events.length, content_verified: grade.recordsVerified }
+      : null,
+    chains: chainBlock,
+  };
 }
 
 /**
@@ -933,8 +1193,8 @@ function reportEvidence(
  *    complete" does not follow, and two customer-facing documents had already
  *    made that leap. The limit travels with the result or it gets dropped.
  * 3. It does not touch the exit code. Findings are evidence; the exit code is
- *    the verdict surface, and the pinned 0/1/2/3 contract stays exactly what it
- *    was. A dangling link is something for a person to look at, not a machine
+ *    the verdict surface, and the one exit-code table (`./exit-codes.ts`) reads
+ *    the verdict and nothing else. A dangling link is something for a person to look at, not a machine
  *    decision this check is entitled to make.
  */
 function reportChains(reading: ChainOutcome, io: Cli): void {
@@ -996,7 +1256,17 @@ function reportAgentProof(
   path: string,
   gateways: string[],
   io: Cli,
+  sink: JsonSink | null,
 ): number {
+  if (sink) {
+    sink.data = {
+      verdict: result.status,
+      bundle_status: result.status,
+      spec_version: "sanning.agent.proof/v1",
+      on_chain_checked: result.onChainChecked,
+      notes: [...result.errors],
+    };
+  }
   if (result.status === "malformed") {
     io.err(paint("MALFORMED", R) + `  ${path}`);
     for (const e of result.errors) io.err(`  - ${e}`);
@@ -1016,7 +1286,7 @@ function reportAgentProof(
   printRollup(result.status, result.status, null, gateways, result.onChainChecked, io);
   for (const e of result.errors) io.out(paint(`  note: ${e}`, DIM));
 
-  return mapStatusToExit(result.status, result.errors);
+  return exitCodeFor(result.status);
 }
 
 function printRollup(
@@ -1071,34 +1341,989 @@ function printRollup(
 }
 
 /**
- * The exit code follows the PACK verdict, then falls back to the bundle status.
+ * The exit code is the PACK verdict's, through the one table (`./exit-codes.ts`).
  *
- * `incomplete` is 3 rather than 0: it is undetermined, which is what 3 already
- * meant for an unreachable gateway, and it is emphatically not 1: the bytes
- * being absent is never reported as tamper (`evidence-bundle.md` §5.1).
+ * `incomplete` and `partial` are 3: undetermined, which is what 3 means for an
+ * unreachable gateway too, and emphatically not 1: the bytes being absent is
+ * never reported as tamper (`evidence-bundle.md` §5.1). Until 0.13.0 `partial`
+ * exited 0 here unless a gateway was unreachable, while `case` exited 3 on it.
  */
-function mapGradeToExit(grade: PackGrade, result: EvidenceBundleResult): number {
-  if (grade.verdict === "malformed") return EXIT_MALFORMED;
-  if (grade.verdict === "failed") return EXIT_FAILED;
-  if (grade.verdict === "incomplete") return EXIT_UNDETERMINED;
-  return mapStatusToExit(result.status, result.errors);
-}
-
-function mapStatusToExit(status: string, errors: string[]): number {
-  if (status === "failed") return EXIT_FAILED;
-  if (status === "malformed") return EXIT_MALFORMED;
-  // "partial" caused specifically by an unreachable gateway — or an export
-  // source_bundle_ref whose bytes are unavailable offline (evidence-export.md
-  // §5 step 3) — maps to exit 3 (undetermined, network-dependent).
-  if (
-    status === "partial" &&
-    errors.some((e) => /unreachable|could not be re-fetched|unavailable offline/.test(e))
-  ) {
-    return EXIT_UNDETERMINED;
-  }
-  // "verified" → 0. "partial" from a withheld record (semantics-undetermined,
-  // not a failure) also exits 0 — the bundle is cryptographically sound.
-  return EXIT_VERIFIED;
+function mapGradeToExit(grade: PackGrade): number {
+  return exitCodeFor(grade.verdict);
+}
+
+// ─── What `proof case` reads (proof#141) ─────────────────────────────────────
+//
+// Directories on disk, split into packs. This lives in the CLI module, and not
+// in a kernel module, because it is the command's own read of files a person
+// named on the command line, the same class of read as `verify`'s read of
+// `bundle.json`, and it reads `bundle.json` with `verify`'s own reader,
+// `readBundleBytes`.
+//
+// The case READING is `readCase`, and nothing here touches it. This turns the
+// directories a reader typed into a list of packs. Its twin is the same section
+// of `src/sanning_proof/cli.py`, and both are held to one table,
+// `vectors/case-split.json`, whose rows are directory trees.
+//
+// ── 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.
+//
+// ── The walk ──
+//
+// Iterative, never recursive, bytewise-sorted at each level, and bounded:
+//
+//   - A directory nested more than MAX_WALK_DEPTH levels below an argument
+//     refuses the whole input (exit 2).
+//   - More than MAX_WALK_ENTRIES names listed, across every argument, refuses
+//     the whole input (exit 2).
+//   - A name that is not valid UTF-8 refuses the whole input (exit 2). It is
+//     not escaped or replaced: two different names would then read as one.
+//   - A symbolic link is never followed, whatever it points at, and anything
+//     else that is not a regular file or a directory is never opened. Each is
+//     listed as outside every pack and not read, even when it sits under a
+//     pack's `logs/` or is named `bundle.json`.
+//
+// ── The split: the verify page's rule over the tree ──
+//
+// The verify page (`sanning-io/verify-page`, `src/lib/case.ts` `splitCase` and
+// `src/lib/pack.ts` `assemble`) is the other surface that reads a case. Both
+// apply the same splitting rule to the same unpacked tree. The page's rule
+// lives in the page, so neither kernel can call it; it is restated here and in
+// the Python twin, and the shared table pins it:
+//
+//   1. Every regular file whose path ends in `/bundle.json` is a pack, rooted
+//      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.
+//   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,
+//      and any other file under `logs/` is UNACCOUNTED.
+//   6. A pack's `ref` is its root without the trailing slash.
+//   7. No `bundle.json` anywhere refuses.
+//
+// One directory argument is read at `<its name>/<path inside it>`, which is how
+// the page names the files of a dropped folder. Several are read as one folder
+// 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
+// `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
+// disclosed content by a plain object, so it loses a record named `__proto__`,
+// which this command keeps.
+
+/** The error text for an input with no pack in it, word for word the page's. */
+export const NO_BUNDLE =
+  "No bundle.json found. An evidence pack contains bundle.json plus logs/.";
+
+/** A directory nested deeper than this below an argument refuses the input. */
+export const MAX_WALK_DEPTH = 32;
+/** More names than this, across every argument, refuse the input. */
+export const MAX_WALK_ENTRIES = 50_000;
+/**
+ * `bundle.json` nested deeper than this is refused before it is parsed, by
+ * `verify` and by `case` alike (see `readBundleBytes`).
+ */
+export const MAX_JSON_DEPTH = 512;
+
+const BUNDLE_PATH = /(?:^|\/)bundle\.json$/;
+const LOG_PATH = /^logs\/([^/]+)\.json$/;
+const ZIP_NAME = /\.zip$/i;
+
+/** The one line a `.zip` gets, as an argument or as the way through a refusal. */
+const UNZIP_FIRST =
+  "Pass the .zip itself, or unzip it first (for example, unzip file.zip -d " +
+  "case/) and pass the folder.";
+
+/**
+ * The input could not be read as a case. The message is the whole report,
+ * identical in both kernels, and the command exits 2 on it. `hint` is an
+ * optional second line naming a way through.
+ */
+export class CaseInputError extends Error {
+  readonly hint: string | null;
+  constructor(message: string, hint: string | null = null) {
+    super(message);
+    this.hint = hint;
+  }
+}
+
+/**
+ * `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,
+ * which differ by kernel and are printed by `verify` only.
+ */
+export class BundleReadError extends Error {
+  readonly tooDeep: boolean;
+  readonly detail: string;
+  constructor(tooDeep: boolean, detail: string) {
+    super(detail);
+    this.tooDeep = tooDeep;
+    this.detail = detail;
+  }
+}
+
+// `ignoreBOM: true` KEEPS a byte-order mark in the text, as Node's
+// `readFile(path, "utf8")` did for `verify`, so a leading one is not JSON.
+const bundleDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
+const nameDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/**
+ * How both `verify` and `case` turn `bundle.json` bytes into JSON, in both
+ * kernels (`read_bundle_bytes` in the Python twin). UTF-8 with each ill-formed
+ * sequence read as U+FFFD, and a byte-order mark kept; then nesting deeper than
+ * MAX_JSON_DEPTH is refused before any parser walks into it; then `JSON.parse`.
+ * Throws `BundleReadError`.
+ */
+export function readBundleBytes(bytes: Uint8Array): unknown {
+  const text = bundleDecoder.decode(bytes);
+  if (jsonDepthExceeds(text, MAX_JSON_DEPTH)) {
+    throw new BundleReadError(true, `nests deeper than ${MAX_JSON_DEPTH} levels`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new BundleReadError(false, e instanceof Error ? e.message : String(e));
+  }
+}
+
+export interface SplitPack {
+  ref: string;
+  bundlePath: string;
+  bundleBytes: Uint8Array;
+  /**
+   * `logs/<event_id>.json` bytes by event id. A `Map` and not an object: an
+   * event id is written by the audited party, and `obj["__proto__"] = bytes`
+   * replaces the prototype instead of storing the disclosure.
+   */
+  content: Map<string, Uint8Array>;
+  unaccounted: string[];
+}
+
+export interface SplitCase {
+  packs: SplitPack[];
+  /** Paths that belong to no pack, sorted. Never opened. */
+  outside: string[];
+  /** The part of `outside` that is not a regular file. Never followed, never opened. */
+  notRegular: string[];
+}
+
+/** One name the walk found that is not a directory. */
+export interface TreeEntry {
+  /** Where it sits on disk. Empty for an entry read out of a case-file `.zip`. */
+  fsPath: string;
+  /**
+   * `true` for a regular file; `false` for a link or anything else, including a
+   * `.zip` entry the reader refused.
+   */
+  regular: boolean;
+  /** The bytes of an entry read out of a case-file `.zip`. */
+  data?: Uint8Array | null;
+}
+
+/**
+ * The page's `splitCase` followed by its `assemble` per pack, over the walk's
+ * tree. `read` opens a file; it is called for the files a pack owns and for
+ * nothing else.
+ */
+export async function splitCase(
+  tree: Map<string, TreeEntry>,
+  read: (entry: TreeEntry, key: string) => Promise<Uint8Array>,
+): Promise<SplitCase> {
+  const roots = [...tree]
+    .filter(([p, e]) => e.regular && BUNDLE_PATH.test(p))
+    .map(([p]) => p.slice(0, p.length - "bundle.json".length))
+    .sort();
+
+  if (roots.length === 0) {
+    const zips = [...tree.keys()].filter((p) => ZIP_NAME.test(p)).sort();
+    const hint =
+      zips.length > 0
+        ? `It holds ${zips.length} .zip file(s) (${zips[0]}` +
+          `${zips.length > 1 ? ", …" : ""}), and case never opens a .zip inside a folder. ` +
+          UNZIP_FIRST
+        : null;
+    throw new CaseInputError(NO_BUNDLE, hint);
+  }
+
+  const owned = new Map<string, string[]>(roots.map((r) => [r, []]));
+  const outside: string[] = [];
+  const notRegular: string[] = [];
+  for (const [path, entry] of tree) {
+    if (!entry.regular) {
+      outside.push(path);
+      notRegular.push(path);
+      continue;
+    }
+    let best: string | null = null;
+    for (const root of roots) {
+      const mine = path === `${root}bundle.json` || path.startsWith(`${root}logs/`);
+      if (mine && (best === null || root.length > best.length)) best = root;
+    }
+    if (best === null) outside.push(path);
+    else owned.get(best)!.push(path);
+  }
+
+  const packs: SplitPack[] = [];
+  for (const root of roots) {
+    const bundlePath = `${root}bundle.json`;
+    const content = new Map<string, Uint8Array>();
+    const unaccounted: string[] = [];
+    for (const p of owned.get(root)!.sort()) {
+      if (p === bundlePath) continue;
+      const rel = p.slice(root.length);
+      const m = LOG_PATH.exec(rel);
+      if (m) content.set(m[1]!, await read(tree.get(p)!, p));
+      else unaccounted.push(rel);
+    }
+    packs.push({
+      ref: root.slice(0, -1),
+      bundlePath,
+      bundleBytes: await read(tree.get(bundlePath)!, bundlePath),
+      content,
+      unaccounted: unaccounted.sort(),
+    });
+  }
+  return { packs, outside: outside.sort(), notRegular: notRegular.sort() };
+}
+
+/** `verify`'s reader, with the refusal named by the pack's path. */
+export function loadBundle(pack: SplitPack): unknown {
+  try {
+    return readBundleBytes(pack.bundleBytes);
+  } catch (e) {
+    if (e instanceof BundleReadError && e.tooDeep) {
+      throw new CaseInputError(`${pack.bundlePath} nests deeper than ${MAX_JSON_DEPTH} levels`);
+    }
+    throw new CaseInputError(`${pack.bundlePath} is not valid JSON`);
+  }
+}
+
+/**
+ * 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.
+ */
+export async function readFileEntry(entry: TreeEntry, key: string): 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);
+  let handle;
+  try {
+    handle = await open(entry.fsPath, flags);
+  } catch {
+    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 {
+    throw new CaseInputError(`cannot read ${key}`);
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Every name under `root`, into `tree` at `<prefix><path inside>`. Breadth
+ * first from an explicit queue, never by recursion. `seen` is the count of
+ * names listed so far, across every argument.
+ */
+async function walk(
+  root: string,
+  prefix: string,
+  arg: string,
+  tree: Map<string, TreeEntry>,
+  seen: { n: number },
+): Promise<void> {
+  const queue: [string, string, number][] = [[root, prefix, 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 {
+      throw new CaseInputError(`cannot read ${rel.slice(0, -1)}`);
+    }
+    names.sort(Buffer.compare);
+    for (const raw of names) {
+      seen.n++;
+      if (seen.n > MAX_WALK_ENTRIES) {
+        throw new CaseInputError(
+          `${arg} holds more than ${MAX_WALK_ENTRIES} files and folders; refusing to read it`,
+        );
+      }
+      let name: string;
+      try {
+        name = nameDecoder.decode(raw);
+      } catch {
+        throw new CaseInputError(
+          `${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 key = `${rel}${name}`;
+      let s;
+      try {
+        s = await lstat(path);
+      } catch {
+        throw new CaseInputError(`cannot read ${key}`);
+      }
+      if (s.isDirectory()) {
+        if (depth + 1 > MAX_WALK_DEPTH) {
+          throw new CaseInputError(
+            `${arg} is nested more than ${MAX_WALK_DEPTH} folders deep; refusing to read it`,
+          );
+        }
+        queue.push([path, `${key}/`, depth + 1]);
+      } else {
+        tree.set(key, { fsPath: path, regular: s.isFile() });
+      }
+    }
+  }
+}
+
+// The name the page would see for a dropped folder: the last segment of the
+// absolute path, so `.` and `pack/` name the directory itself.
+function baseName(path: string): string {
+  return basename(resolve(path));
+}
+
+/**
+ * Every name under the directories named, keyed `<name>/<path inside>`. Each
+ * argument must be a directory, and not a link to one. A `.zip` is refused
+ * with the way through.
+ */
+export async function treeFromArguments(paths: readonly string[]): Promise<Map<string, TreeEntry>> {
+  if (paths.length === 0) throw new CaseInputError("case: at least one pack is required");
+  for (const arg of paths) {
+    // `link/` resolves the link; the name without the slash does not.
+    let s;
+    try {
+      s = await lstat(arg.replace(/\/+$/, "") || arg);
+    } catch {
+      throw new CaseInputError(`cannot read ${arg}`);
+    }
+    if (s.isSymbolicLink()) {
+      throw new CaseInputError(
+        `${arg} is a symbolic link, which case does not follow; pass the folder it points to`,
+      );
+    }
+    if (s.isDirectory()) continue;
+    if (s.isFile() && ZIP_NAME.test(arg)) continue;
+    throw new CaseInputError(
+      `${arg} is not a folder or a .zip. Pass pack folders, the folder that holds them, or a case file.`,
+    );
+  }
+
+  const tree = new Map<string, TreeEntry>();
+  const claimed = new Map<string, string>();
+  const seen = { n: 0 };
+  for (const arg of paths) {
+    let isZip = false;
+    if (ZIP_NAME.test(arg)) {
+      try {
+        isZip = !(await stat(arg)).isDirectory();
+      } catch {
+        isZip = true;
+      }
+    }
+    let name = baseName(arg);
+    if (isZip) {
+      // `unzip <name>.zip -d <name>` is the command HOW-TO-VERIFY.txt pins, so
+      // the archive is read under the folder that command makes.
+      name = name.slice(0, -".zip".length);
+      if (name.length === 0) throw new CaseInputError(`${arg} has no name before .zip; rename it`);
+    }
+    const earlier = claimed.get(name);
+    if (earlier !== undefined) {
+      throw new CaseInputError(`${earlier} and ${arg} would both be read as ${name}/; rename one`);
+    }
+    claimed.set(name, arg);
+    if (isZip) await unzip(arg, `${name}/`, tree, seen);
+    else await walk(arg, `${name}/`, arg, tree, seen);
+  }
+  return tree;
+}
+
+/**
+ * A case file named on the command line, read as the folder `unzip` would make
+ * of it: `<name>.zip` is read at `<name>/<entry>` (5.6.4), so the zip and its
+ * unpacked folder give one reading. The archive is read by `readZip` and
+ * nothing else; an entry it refuses is listed as outside every pack and never
+ * read, as the walk lists a link.
+ */
+async function unzip(
+  arg: string,
+  prefix: string,
+  tree: Map<string, TreeEntry>,
+  seen: { n: number },
+): Promise<void> {
+  let data: Uint8Array;
+  try {
+    data = new Uint8Array(await readFile(arg));
+  } catch {
+    throw new CaseInputError(`cannot read ${arg}`);
+  }
+  let entries;
+  try {
+    entries = readZip(data);
+  } catch (e) {
+    if (e instanceof ZipReadError) throw new CaseInputError(`${arg} ${e.message}`);
+    throw e;
+  }
+  for (const entry of entries) {
+    seen.n++;
+    if (seen.n > MAX_WALK_ENTRIES) {
+      throw new CaseInputError(
+        `${arg} holds more than ${MAX_WALK_ENTRIES} files and folders; refusing to read it`,
+      );
+    }
+    tree.set(`${prefix}${entry.name}`, {
+      fsPath: "",
+      regular: entry.refused === null,
+      data: entry.data,
+    });
+  }
+}
+
+// ─── `proof case` (proof#141) ────────────────────────────────────────────────
+//
+// The case reading from a terminal, so an auditor holding several packs does
+// not depend on Sanning's page for the one check the audited party cannot
+// write for itself. The twin is `run_case` in `src/sanning_proof/cli.py`, and
+// the two commands are compared as child processes by
+// `cross-kernel/run_case_cli.sh`: same stdout, same `--json`, same exit code,
+// over every `case/` vector.
+//
+// The reading is `readCase`, entire. This command splits the input into packs
+// (the section above, the verify page's rule) and prints what the kernel said.
+// No color: the two commands print the same bytes.
+
+// The exit code of a case verdict is the one table's (`./exit-codes.ts`).
+// `mixed` has its own code, 4, because each other code would say something a
+// mixed case has not established: 0 would soften a case with an unsettled or
+// unreadable outcome in it, 3 would hide the outcomes that did settle, and 1
+// would accuse a case in which nothing was proven wrong. A case holding a
+// failure never exits 4: a proven failure keeps the headline (evidence-bundle
+// 5.5.4 v1.16, A17), so it reads `failed` and exits 1.
+
+export const CASE_USAGE = `sanning-proof case -- a case reading: one verdict over one pack or many, offline
+
+  sanning-proof case <folder or case file>... [--gateways <url,url>] [--json]
+
+  <folder>    a pack folder (bundle.json plus logs/), a folder that holds
+              several packs, or an unzipped case file. Packs are found by the
+              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
+              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
+              nested more than 32 levels deep, more than 50000 files and
+              folders in all, or a name that is not valid UTF-8 exits 2.
+  <case file> a case file named as <name>.zip, read as the folder
+              unzip <name>.zip -d <name> would make, so the two give one
+              reading. An entry that is encrypted, a symbolic link, stored by
+              another method, or named outside the folder is listed as outside
+              and not read.
+              Where the folder or case file holds contents.json at its root,
+              the index is compared with what is there and each disagreement
+              is listed; the index never moves the verdict.
+  --gateways  comma-separated gateway URLs. Each pack's witnesses are then
+              looked up on the public record, pack by pack, and reported on
+              the witness line. The lookup never changes the verdict word.
+  --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.
+
+Each pack's bundle.json is read as verify reads it, so the two commands
+classify one bundle the same way.
+
+What a case reading establishes: every pack is verified offline by this
+kernel and graded as a pack; every record every pack supplied is read, in one
+pile, under the hand-off rules of envelope-spec section 4.1; a hand-off record
+with no counterpart among the records read is always named, and when a pack
+signed by the key it names is in the reading, it says that pack holds none,
+unless every candidate it had was accounted for by another record (A20),
+which reads as no counterpart and names no pack.
+
+What it does not establish: that the set of packs is complete (a party can
+decline to hand over a pack); that a party which presented no pack under the named key
+recorded nothing; that two organizations are independent of each other; or
+that any witness is on the public record, which the reading never looks up.
+
+${EXIT_CODES_HELP}
+
+case: an input that cannot be read as packs, or an unexpected error in this
+command, exits 2. With --gateways, a witness that does not match on chain exits
+1, and an on-chain half that could not be settled turns 0 into 3.`;
+
+// What Node writes for a lone surrogate on a UTF-8 stream is U+FFFD. Done here
+// rather than left to the stream, so the lines a test captures in process are
+// the lines a reader sees.
+function noLoneSurrogates(text: string): string {
+  return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "�");
+}
+
+// Keys sorted at every depth, arrays left in their order: the Python twin
+// writes `json.dumps(sort_keys=True, indent=2, ensure_ascii=False)` and this is
+// that, byte for byte.
+function sortKeys(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v !== null && typeof v === "object") {
+    return Object.fromEntries(
+      Object.keys(v as Record<string, unknown>)
+        .sort()
+        .map((k) => [k, sortKeys((v as Record<string, unknown>)[k])]),
+    );
+  }
+  return v;
+}
+
+function jsonText(v: unknown): string {
+  return JSON.stringify(sortKeys(v), null, 2);
+}
+
+interface OnChainRow {
+  ref: string;
+  witnesses: number;
+  confirmed: number;
+  mismatched: number;
+  unreachable: number;
+  not_checked: number;
+}
+
+interface OnChainHalf {
+  /** Present only where a lookup ran: each gateway that answered, in the order given. */
+  answered?: string[];
+  checked: boolean;
+  gateways: string[];
+  packs: OnChainRow[];
+  verdict: "not_checked" | "confirmed" | "failed" | "undetermined";
+}
+
+// Each pack's witnesses, re-fetched through `verifyEvidenceBundle`. Outside the
+// case reading on purpose: `readCase` makes no network call, and neither does
+// the verify page's case reading, so the case verdict stays the one both
+// surfaces compute. This adds the half the reading names as not checked.
+async function onChainHalf(
+  packs: readonly [string, unknown][],
+  gateways: string[],
+  io: Cli,
+): Promise<OnChainHalf> {
+  if (gateways.length === 0) return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
+  const rows: OnChainRow[] = [];
+  const answered = new Set<string>();
+  for (const [ref, bundle] of packs) {
+    const result = await verifyEvidenceBundle(bundle, {
+      gateways,
+      ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
+    });
+    const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
+    const row: OnChainRow = {
+      ref,
+      witnesses: witnesses.length,
+      confirmed: 0,
+      mismatched: 0,
+      unreachable: 0,
+      not_checked: 0,
+    };
+    for (const w of witnesses) {
+      const rollup = w.onChain?.rollup ?? null;
+      if (rollup === "confirm") row.confirmed++;
+      else if (rollup === "mismatch") row.mismatched++;
+      else if (rollup === "unreachable") row.unreachable++;
+      else row.not_checked++;
+    }
+    rows.push(row);
+    for (const w of witnesses) {
+      for (const outcome of w.onChain?.perGateway ?? []) {
+        if (outcome.outcome === "confirm" || outcome.outcome === "mismatch") {
+          answered.add(outcome.gateway);
+        }
+      }
+    }
+  }
+  const verdict = rows.some((r) => r.mismatched > 0)
+    ? "failed"
+    : rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)
+      ? "undetermined"
+      : "confirmed";
+  return {
+    answered: gateways.filter((g) => answered.has(g)),
+    checked: true,
+    gateways: [...gateways],
+    packs: rows,
+    verdict,
+  };
+}
+
+/**
+ * The witness line (evidence-bundle 5.5.6 v1.20, A24, D7) from the on-chain
+ * half: `confirmed` is `confirmed`, `not_checked` and `undetermined` are
+ * `not_checked` with the reason, and `failed` is `differs`. It never moves the
+ * headline.
+ */
+export function witnessLine(onChain: OnChainHalf): WitnessLine {
+  if (!onChain.checked) {
+    return {
+      state: WITNESS_NOT_LOOKED_UP.state,
+      reasons: [...WITNESS_NOT_LOOKED_UP.reasons],
+      services: [...WITNESS_NOT_LOOKED_UP.services],
+    };
+  }
+  const services = [...(onChain.answered ?? [])];
+  if (onChain.verdict === "failed") return { state: "differs", reasons: [], services };
+  if (onChain.verdict === "confirmed") return { state: "confirmed", reasons: [], services };
+  const rows = onChain.packs;
+  const reasons: string[] = [];
+  if (rows.some((r) => r.witnesses === 0)) reasons.push("a pack names no witness");
+  if (rows.some((r) => r.unreachable > 0)) {
+    reasons.push(
+      "a lookup did not settle: the service could not be reached, or it " +
+        "holds no such witness yet",
+    );
+  }
+  if (rows.some((r) => r.not_checked > 0)) {
+    reasons.push("no lookup is made for a witness kind a pack names");
+  }
+  return { state: "not_checked", reasons, services };
+}
+
+/**
+ * The case verdict's code, moved only by an on-chain half that was asked for:
+ * a witness that does not match is a failure whatever the reading said, and an
+ * on-chain half that could not be settled is never a clean 0.
+ */
+export function caseExitCode(verdict: string, onChainVerdict: string): number {
+  const code = exitCodeFor(verdict);
+  if (onChainVerdict === "failed") return EXIT_FAILED;
+  if (onChainVerdict === "undetermined" && code === EXIT_VERIFIED) return EXIT_UNDETERMINED;
+  return code;
+}
+
+interface CaseFileData {
+  root: string;
+  index: string;
+  case_id: string | null;
+  findings: { rendered: string }[];
+}
+
+interface CaseData {
+  title: string;
+  reliance: string;
+  summary: string;
+  witness: { rendered: string };
+  exceptions: { rendered: string }[];
+  notes: { rendered: string }[];
+  packs: {
+    ref: string;
+    log_files: number;
+    unaccounted: string[];
+    signing_key: string | null;
+    grade: string | null;
+  }[];
+  outside: string[];
+  not_regular: string[];
+  case_file: CaseFileData[];
+  on_chain: OnChainHalf;
+}
+
+const titleOf = (word: string): string =>
+  Object.prototype.hasOwnProperty.call(VERDICT_DISPLAY_TITLES, word)
+    ? (VERDICT_DISPLAY_TITLES[word] as string)
+    : word;
+
+/**
+ * The text report, one line per entry, identical in both kernels. The headline
+ * is the verdict's one display title and nothing else sets it (5.5.6, D7); the
+ * scope sentence and the witness line are printed with it every time.
+ */
+function caseReport(data: CaseData): string[] {
+  const lines = [
+    data.title,
+    `  ${data.summary}`,
+    `  ${data.witness.rendered}`,
+    `  ${data.reliance}`,
+  ];
+  for (const e of data.exceptions) lines.push(`  - ${e.rendered}`);
+  for (const n of data.notes) lines.push(`  note: ${n.rendered}`);
+  lines.push(`packs         ${data.packs.length}`);
+  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/`;
+    if (p.unaccounted.length > 0) {
+      line +=
+        `; ${p.unaccounted.length} file(s) under logs/ that cannot be a ` +
+        `record: ${p.unaccounted.join(", ")}`;
+    }
+    lines.push(line);
+  }
+  if (data.outside.length > 0) {
+    lines.push(
+      `outside       ${data.outside.length} file(s) sit outside every ` +
+        "pack, so no verdict here is about them",
+    );
+    const links = new Set(data.not_regular);
+    for (const path of data.outside) {
+      lines.push(links.has(path) ? `  - ${path} (not a regular file: not followed, not read)` : `  - ${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}` : "";
+    lines.push(
+      `case file     ${c.root}/${CASE_FILE_INDEX_NAME} is ${c.index}` +
+        `${label}; ${c.findings.length} disagreement(s) with what is here, ` +
+        "none of which moves the verdict",
+    );
+    for (const f of c.findings) lines.push(`  - ${f.rendered}`);
+  }
+  const oc = data.on_chain;
+  if (oc.checked) {
+    lines.push(
+      `on-chain      looked up against ${oc.gateways.length} gateway(s), ` +
+        "pack by pack; the reading above is offline and this does not " +
+        "change it",
+    );
+    for (const r of oc.packs) {
+      lines.push(
+        `  ${r.ref}  ${r.witnesses} witness(es): ${r.confirmed} ` +
+          `confirmed, ${r.mismatched} mismatched, ${r.unreachable} ` +
+          `unreachable, ${r.not_checked} not checked`,
+      );
+    }
+  }
+  return lines;
+}
+
+/**
+ * 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.
+ */
+async function caseFileReadings(tree: Map<string, TreeEntry>): Promise<CaseFileData[]> {
+  const out: (CaseFileData & { findings: Record<string, unknown>[] })[] = [];
+  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) {
+        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)) });
+        }
+      }
+    }
+    const reading = readCaseFileIndex(indexBytes, files);
+    const nil = <T>(v: T | undefined): T | null => (v === undefined ? null : v);
+    out.push({
+      root,
+      index: reading.index,
+      case_id: reading.caseId,
+      findings: reading.findings.map((f) => ({
+        kind: f.kind,
+        ref: nil(f.ref),
+        path: nil(f.path),
+        listed_sha256: nil(f.listedSha256),
+        sha256: nil(f.sha256),
+        reason: nil(f.reason),
+        public_key: nil(f.publicKey),
+        rendered: renderCaseFileFinding(f),
+      })),
+    });
+  }
+  return out as CaseFileData[];
+}
+
+function caseError(e: CaseInputError, asJson: boolean, io: Cli): number {
+  if (asJson) outJson(io, jsonText({ error: e.message, exit_code: EXIT_MALFORMED, hint: e.hint }));
+  io.err(noLoneSurrogates(`case: ${e.message}`));
+  if (e.hint) io.err(noLoneSurrogates(`case: ${e.hint}`));
+  return EXIT_MALFORMED;
+}
+
+/**
+ * `proof case <folder>... [--gateways <urls>] [--json]`. Every path out of the
+ * command is an exit code from the table: an exception nobody expected exits 2,
+ * never 1, because 1 would name the evidence failed over a defect in this
+ * command.
+ */
+export async function runCase(argv: readonly string[], stream: Cli): Promise<number> {
+  const io = guard(stream);
+  try {
+    return await caseCommand(argv, io);
+  } catch (e) {
+    const name = e instanceof Error ? e.constructor.name : typeof e;
+    try {
+      return caseError(
+        new CaseInputError(
+          `an unexpected error stopped the reading (${name}); this is a defect in the ` +
+            "command, not a verdict on the evidence",
+        ),
+        argv.includes("--json"),
+        io,
+      );
+    } catch {
+      return EXIT_MALFORMED; // a stream that cannot be written
+    }
+  }
+}
+
+async function caseCommand(argv: readonly string[], io: Cli): Promise<number> {
+  let asJson = false;
+  let gateways: string[] = [];
+  const paths: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if ((arg === "--help" || arg === "-h" || arg === "help") && paths.length === 0) {
+      outBlock(io, CASE_USAGE);
+      return EXIT_VERIFIED;
+    }
+    if (arg === "--json") {
+      asJson = true;
+    } else if (arg === "--gateways") {
+      const next = argv[i + 1];
+      if (next === undefined) {
+        io.err("case: --gateways requires a comma-separated list of URLs");
+        outBlock(io, CASE_USAGE);
+        return EXIT_MALFORMED;
+      }
+      gateways = next
+        .split(",")
+        .map((g) => g.trim())
+        .filter((g) => g.length > 0);
+      i++;
+    } else if (arg.startsWith("--")) {
+      io.err(`case: unknown option ${arg}`);
+      outBlock(io, CASE_USAGE);
+      return EXIT_MALFORMED;
+    } else {
+      paths.push(arg);
+    }
+  }
+  if (paths.length === 0) {
+    io.err("case: at least one pack is required");
+    outBlock(io, CASE_USAGE);
+    return EXIT_MALFORMED;
+  }
+
+  let split;
+  let tree: Map<string, TreeEntry>;
+  let bundles: [SplitPack, unknown][];
+  try {
+    tree = await treeFromArguments(paths);
+    split = await splitCase(tree, readFileEntry);
+    bundles = split.packs.map((p): [SplitPack, unknown] => [p, loadBundle(p)]);
+  } catch (e) {
+    if (e instanceof CaseInputError) return caseError(e, asJson, io);
+    throw e;
+  }
+
+  const reading = await readCase(
+    bundles.map(([p, bundle]) => ({ ref: p.ref, bundle, content: p.content })),
+  );
+  let caseFile: CaseFileData[];
+  try {
+    caseFile = await caseFileReadings(tree);
+  } catch (e) {
+    if (e instanceof CaseInputError) return caseError(e, asJson, io);
+    throw e;
+  }
+  const onChain = await onChainHalf(
+    bundles.map(([p, bundle]): [string, unknown] => [p.ref, bundle]),
+    gateways,
+    io,
+  );
+  const witness = witnessLine(onChain);
+  const code = caseExitCode(reading.verdict, onChain.verdict);
+  const nil = <T>(v: T | undefined): T | null => (v === undefined ? null : v);
+
+  const data = {
+    verdict: reading.verdict,
+    title: titleOf(reading.verdict),
+    reliance: CASE_RELIANCE[reading.verdict],
+    exit_code: code,
+    summary: renderCaseSummary(reading),
+    witness: {
+      state: witness.state,
+      reasons: witness.reasons,
+      services: witness.services,
+      rendered: renderWitnessLine(witness),
+    },
+    handoff_records: reading.handoffRecords,
+    on_chain_checked: reading.onChainChecked,
+    exceptions: reading.exceptions.map((e) => ({
+      kind: e.kind,
+      pack_ref: nil(e.packRef),
+      event_id: nil(e.eventId),
+      counterparty_key: nil(e.counterpartyKey),
+      failed_checks: e.failedChecks ?? [],
+      count: nil(e.count),
+      status: nil(e.status),
+      causes: e.causes ?? [],
+      reasons: e.reasons ?? [],
+      rendered: renderException(e),
+    })),
+    notes: reading.notes.map((n) => ({
+      kind: n.kind,
+      pack_ref: n.packRef,
+      count: nil(n.count),
+      rendered: renderCaseNote(n),
+    })),
+    records: reading.records.map((r) => ({
+      pack_ref: r.packRef,
+      event_id: r.eventId,
+      verdict: nil(r.verdict),
+      role: r.role,
+      findings: r.findings,
+      failed_checks: r.failedChecks,
+      counterparts: r.counterparts,
+    })),
+    contributions: reading.contributions.map(([who, verdict]) => [who, verdict]),
+    packs: bundles.map(([p], i) => ({
+      ref: p.ref,
+      bundle_path: p.bundlePath,
+      log_files: p.content.size,
+      unaccounted: p.unaccounted,
+      signing_key: reading.packs[i]!.signingKey,
+      grade: reading.packs[i]!.grade,
+      records_withheld: reading.packs[i]!.recordsWithheld,
+      declaration_version: reading.packs[i]!.declarationVersion,
+    })),
+    outside: split.outside,
+    not_regular: split.notRegular,
+    case_file: caseFile,
+    on_chain: onChain,
+  };
+  if (asJson) outJson(io, jsonText(data));
+  else for (const line of caseReport(data)) io.out(noLoneSurrogates(line));
+  return code;
 }
 
 function shortTx(tx: string): string {
@@ -1133,7 +2358,7 @@ if (isMain) {
       process.exitCode = code;
     })
     .catch((e) => {
-      process.stderr.write(`fatal: ${e instanceof Error ? e.stack ?? e.message : String(e)}\n`);
+      process.stderr.write(`fatal: ${escapeControl(e instanceof Error ? e.stack ?? e.message : String(e))}\n`);
       process.exitCode = EXIT_MALFORMED;
     });
 }