@sanning/proof 0.12.0 → 0.14.0

package/dist/cli.js

@@ -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
@@ -36,28 +43,86 @@
 // checked, and exit 3 is how this command says "undetermined".
 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 { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
-import { readCase, renderCaseSummary, renderException } from "./case.js";
+import { VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, caseReliance, 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 { isHexField, utf8 } from "./crypto.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 { WITNESS_CACHE_NAME, checkWitnessCache, readWitnessCache, renderWitnessTime, } from "./witness-cache.js";
 import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
 import { completenessNotes, gradePack, renderCause } 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;
-const G = "\x1b[32m";
-const R = "\x1b[31m";
-const Y = "\x1b[33m";
-const DIM = "\x1b[2m";
-const B = "\x1b[1m";
-const X = "\x1b[0m";
+import { EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
+// ── 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) {
+    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) {
+    return escapeControl(text).split(COLOR_MARK).join("\x1b[");
+}
+const RAW = Symbol("sanning.cli.raw");
+function guard(io) {
+    if (RAW in io)
+        return io;
+    const 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) {
+    return io[RAW] ?? io;
+}
+/** JSON, printed unescaped: a script reads it, not a terminal. */
+function outJson(io, text) {
+    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, text) {
+    rawOf(io).out(text.split("\n").map(forTerminal).join("\n"));
+}
 function useColor() {
     // Honor NO_COLOR; otherwise color only a TTY.
     if (process.env.NO_COLOR)
@@ -75,7 +140,8 @@ function mark(ok) {
 function paint(s, c) {
     return useColor() ? `${c}${s}${X}` : s;
 }
-export async function runCli(argv, io) {
+export async function runCli(argv, stream) {
+    const io = guard(stream);
     const [command, ...rest] = argv;
     if (command === undefined || command === "help" || command === "--help" || command === "-h") {
         printUsage(io);
@@ -85,11 +151,15 @@ export async function runCli(argv, io) {
         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);
@@ -99,13 +169,55 @@ export async function runCli(argv, io) {
         printUsage(io);
         return EXIT_MALFORMED;
     }
-    // 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).
+    if (rest.includes("--json")) {
+        return runJson(rest.filter((a) => a !== "--json"), io, runVerify);
+    }
+    return runVerify(rest, io, null);
+}
+async function runJson(rest, io, verb) {
+    const errs = [];
+    const sink = { data: null };
+    const quiet = {
+        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, io, sink) {
+    // `--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;
+    let filePaths;
+    let gatewayArg;
     const positional = [];
     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) {
@@ -117,14 +229,30 @@ export async function runCli(argv, io) {
             i++;
             continue;
         }
+        if (a === "--files") {
+            const taken = takeFilePaths(rest, i + 1);
+            if (taken.length === 0) {
+                io.err("verify: --files requires at least one file path");
+                printUsage(io);
+                return EXIT_MALFORMED;
+            }
+            filePaths = [...(filePaths ?? []), ...taken];
+            i += taken.length;
+            continue;
+        }
         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())
@@ -138,6 +266,15 @@ export async function runCli(argv, io) {
             io.err(`note: ${n}`);
     }
     const content = logs?.content;
+    let offered;
+    if (filePaths !== undefined) {
+        const read = await readOfferedFiles(filePaths);
+        if (typeof read === "string") {
+            io.err(`verify: ${read}`);
+            return EXIT_MALFORMED;
+        }
+        offered = read;
+    }
     let raw;
     try {
         raw = new Uint8Array(await readFile(bundlePath));
@@ -157,6 +294,9 @@ export async function runCli(argv, io) {
         if (e instanceof BundleReadError && e.tooDeep) {
             io.err(`${bundlePath} ${e.detail}; refusing to read it`);
         }
+        else if (e instanceof BundleReadError && e.duplicate) {
+            io.err(`${bundlePath} ${NOT_I_JSON}: ${e.detail}`);
+        }
         else {
             io.err(`${bundlePath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
         }
@@ -171,11 +311,14 @@ export async function runCli(argv, io) {
             // 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, {
+        if (offered) {
+            io.err("note: --files has no effect on a sanning.agent.proof/v1 bundle (ignored)");
+        }
+        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
     // rejects an unknown major as "malformed" so a genuinely unknown shape still
@@ -204,26 +347,65 @@ export async function runCli(argv, io) {
     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);
+    // 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);
+        for (const line of renderFileMatch(reading))
+            io.out(line);
+        if (sink !== null && sink.data !== null)
+            sink.data.files = fileMatchToJson(reading);
+    }
     // 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.)
+// The paths after `--files`: every argument up to the next option.
+function takeFilePaths(args, start) {
+    const out = [];
+    for (const arg of args.slice(start)) {
+        if (arg.startsWith("--"))
+            break;
+        out.push(arg);
+    }
+    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) {
+    const out = [];
+    for (const path of paths) {
+        try {
+            if (!(await stat(path)).isFile())
+                return `--files ${path} is not a readable file`;
+            out.push({ name: path, bytes: new Uint8Array(await readFile(path)) });
+        }
+        catch {
+            return `--files ${path} is not a readable file`;
+        }
+    }
+    return out;
+}
+// `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, io) {
+async function runExport(rest, io, sink) {
+    if (rest[0] === "--help" || rest[0] === "-h" || rest[0] === "help") {
+        usageExport(io);
+        return EXIT_VERIFIED;
+    }
     let attestationsPath;
     let keyPath;
     let outPath;
@@ -240,19 +422,19 @@ async function runBundle(rest, io) {
             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);
@@ -282,6 +464,13 @@ async function runBundle(rest, io) {
                 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);
         }
@@ -326,6 +515,18 @@ async function runBundle(rest, io) {
     // 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");
@@ -339,25 +540,32 @@ async function runBundle(rest, io) {
             `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) {
-    io.out("Usage: npx @sanning/proof bundle <source-bundle.json> --attestations <file> --key <file> [-o <out.json>]");
+    io.out("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;
 }
 // Read + parse a JSON file; report a clear error and return undefined on any
@@ -372,9 +580,13 @@ async function readJson(path, io) {
         return undefined;
     }
     try {
-        return JSON.parse(raw);
+        return parseRefusingDuplicates(raw);
     }
     catch (e) {
+        if (e instanceof DuplicateKeyError) {
+            io.err(`${path} ${NOT_I_JSON}: ${e.message}`);
+            return undefined;
+        }
         io.err(`${path} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
         return undefined;
     }
@@ -456,9 +668,15 @@ async function loadLogsMap(logsPath, io) {
     }
     let logsParsed;
     try {
-        logsParsed = JSON.parse(logsRaw);
+        logsParsed = parseRefusingDuplicates(logsRaw);
     }
     catch (e) {
+        if (e instanceof DuplicateKeyError) {
+            // One event id named twice hands the reader two contents for one
+            // record, and the last one silently won (proof#144).
+            io.err(`--logs ${logsPath} ${NOT_I_JSON}: ${e.message}`);
+            return undefined;
+        }
         io.err(`--logs ${logsPath} is not valid JSON: ${errMsg(e)}`);
         return undefined;
     }
@@ -585,7 +803,8 @@ function reportLogsCoverage(logs, result, io) {
     const undetermined = result.events.filter((e) => e.contentOk === null);
     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))}`);
     }
 }
@@ -628,32 +847,49 @@ function decodeLogValue(v) {
     return utf8(v); // raw utf8 bytes
 }
 function printUsage(io) {
-    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("  case <folder>... [--gateways <urls>] [--json]          Read several packs as one case");
+    io.out("  verify <bundle.json> [--gateways <urls>] [--logs <path>] [--files <path>...] [--json]");
+    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("                                                          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("--files <path>...   Files handed in beside the pack, every path up to the");
+    io.out("                    next option. Each is hashed and matched, by SHA-256");
+    io.out("                    alone, against what the pack's signed records commit");
+    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("");
     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");
@@ -663,8 +899,11 @@ function printUsage(io) {
     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.");
 }
 /**
  * The disclosure account this command can honestly make, from what the VERIFIER
@@ -699,8 +938,10 @@ function cliDisclosureAccount(result, logs) {
         extra: (logs?.suppliedIds ?? []).filter((id) => !known.has(id)),
     };
 }
-function reportEvidence(result, path, gateways, io, chains, parsed, logs) {
+function reportEvidence(result, path, gateways, io, chains, parsed, logs, sink) {
     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}`);
@@ -784,7 +1025,7 @@ function reportEvidence(result, path, gateways, io, chains, parsed, logs) {
     // 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);
@@ -808,7 +1049,42 @@ function reportEvidence(result, path, gateways, io, chains, parsed, logs) {
     if (result.events.length > 0) {
         io.out(paint(`  logs: ${grade.recordsVerified}/${result.events.length} record(s) content-verified`, DIM));
     }
-    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, grade, declaration, chains) {
+    let chainBlock = 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,
+    };
 }
 /**
  * The chain block: what following each record's pointer to the record before it
@@ -825,8 +1101,8 @@ function reportEvidence(result, path, gateways, io, chains, parsed, logs) {
  *    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, io) {
@@ -868,7 +1144,16 @@ function reportExport(exp, io) {
         }
     }
 }
-function reportAgentProof(result, path, gateways, io) {
+function reportAgentProof(result, path, gateways, io, sink) {
+    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)
@@ -886,7 +1171,7 @@ function reportAgentProof(result, path, gateways, io) {
     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(headline, bundleStatus, asserted, gateways, onChainChecked, io) {
     const scope = onChainChecked
@@ -925,36 +1210,15 @@ function printRollup(headline, bundleStatus, asserted, gateways, onChainChecked,
     }
 }
 /**
- * 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, result) {
-    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, errors) {
-    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) {
+    return exitCodeFor(grade.verdict);
 }
 // ─── What `proof case` reads (proof#141) ─────────────────────────────────────
 //
@@ -1039,7 +1303,8 @@ 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 = "Unzip it first (for example, unzip file.zip -d case/), then pass the folder.";
+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
@@ -1055,50 +1320,26 @@ export class CaseInputError extends Error {
 /**
  * `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.
+ * which differ by kernel and are printed by `verify` only. `duplicate` marks the
+ * one parse refusal whose `detail` is kernel wording, identical in both kernels
+ * (`duplicate key "<name>"`, proof#144), so both commands print it.
  */
 export class BundleReadError extends Error {
     tooDeep;
     detail;
-    constructor(tooDeep, detail) {
+    duplicate;
+    constructor(tooDeep, detail, duplicate = false) {
         super(detail);
         this.tooDeep = tooDeep;
         this.detail = detail;
+        this.duplicate = duplicate;
     }
 }
-/**
- * Whether `[` and `{` outside strings ever nest deeper than `limit`. One pass,
- * no recursion; the same scan as `_json_depth_exceeds` in the Python twin, so
- * both kernels refuse the same text.
- */
-function jsonDepthExceeds(text, limit) {
-    let depth = 0;
-    let inString = false;
-    let escaped = false;
-    for (let i = 0; i < text.length; i++) {
-        const ch = text[i];
-        if (inString) {
-            if (escaped)
-                escaped = false;
-            else if (ch === "\\")
-                escaped = true;
-            else if (ch === '"')
-                inString = false;
-        }
-        else if (ch === '"') {
-            inString = true;
-        }
-        else if (ch === "[" || ch === "{") {
-            depth++;
-            if (depth > limit)
-                return true;
-        }
-        else if (ch === "]" || ch === "}") {
-            depth--;
-        }
-    }
-    return false;
-}
+// What both commands say about bytes that repeat a member name, before the
+// kernel's own `duplicate key "<name>"`. RFC 8259 JSON permits a repeat and
+// I-JSON (RFC 7493), which JCS is defined over, does not, so "not valid JSON"
+// would be the wrong sentence. `NOT_I_JSON` in the Python twin.
+export const NOT_I_JSON = "is not I-JSON (RFC 7493)";
 // `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 });
@@ -1107,7 +1348,8 @@ 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`.
+ * MAX_JSON_DEPTH is refused before any parser walks into it; then `JSON.parse`,
+ * refusing an object that repeats a member name (I-JSON, RFC 7493; proof#144).
  * Throws `BundleReadError`.
  */
 export function readBundleBytes(bytes) {
@@ -1116,9 +1358,11 @@ export function readBundleBytes(bytes) {
         throw new BundleReadError(true, `nests deeper than ${MAX_JSON_DEPTH} levels`);
     }
     try {
-        return JSON.parse(text);
+        return parseRefusingDuplicates(text);
     }
     catch (e) {
+        if (e instanceof DuplicateKeyError)
+            throw new BundleReadError(false, e.message, true);
         throw new BundleReadError(false, e instanceof Error ? e.message : String(e));
     }
 }
@@ -1136,7 +1380,7 @@ export async function splitCase(tree, read) {
         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. ` +
+                `${zips.length > 1 ? ", …" : ""}), and case never opens a .zip inside a folder. ` +
                 UNZIP_FIRST
             : null;
         throw new CaseInputError(NO_BUNDLE, hint);
@@ -1186,6 +1430,30 @@ export async function splitCase(tree, read) {
     }
     return { packs, outside: outside.sort(), notRegular: notRegular.sort() };
 }
+/**
+ * The bytes of the `witness-cache.json` beside a pack's `bundle.json`
+ * (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
+ * 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.
+ */
+async function witnessCacheBytes(tree, split, pack) {
+    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);
+    }
+    catch (e) {
+        if (e instanceof CaseInputError)
+            return null;
+        throw e;
+    }
+}
 /** `verify`'s reader, with the refusal named by the pack's path. */
 export function loadBundle(pack) {
     try {
@@ -1195,6 +1463,9 @@ export function loadBundle(pack) {
         if (e instanceof BundleReadError && e.tooDeep) {
             throw new CaseInputError(`${pack.bundlePath} nests deeper than ${MAX_JSON_DEPTH} levels`);
         }
+        if (e instanceof BundleReadError && e.duplicate) {
+            throw new CaseInputError(`${pack.bundlePath} ${NOT_I_JSON}: ${e.detail}`);
+        }
         throw new CaseInputError(`${pack.bundlePath} is not valid JSON`);
     }
 }
@@ -1204,6 +1475,8 @@ export function loadBundle(pack) {
  * the walk listed it is refused rather than followed or waited on.
  */
 export async function readFileEntry(entry, key) {
+    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 {
@@ -1301,24 +1574,79 @@ export async function treeFromArguments(paths) {
         }
         if (s.isDirectory())
             continue;
-        if (ZIP_NAME.test(arg))
-            throw new CaseInputError(`${arg} is a .zip archive. ${UNZIP_FIRST}`);
-        throw new CaseInputError(`${arg} is not a folder. Pass pack folders, or the folder that holds them.`);
+        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();
     const claimed = new Map();
     const seen = { n: 0 };
     for (const arg of paths) {
-        const name = baseName(arg);
+        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);
-        await walk(arg, `${name}/`, arg, tree, seen);
+        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, prefix, tree, seen) {
+    let data;
+    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
@@ -1331,67 +1659,69 @@ export async function treeFromArguments(paths) {
 // 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.
-// Exit code per case verdict word. The four codes `verify` uses mean what they
-// mean there, and `mixed` gets its own, because each code already in use would
-// say something a mixed case has not established: 0 and 3 would soften a case
-// that holds a failure, and 1 would accuse a case whose outcomes are all
-// undetermined.
-const EXIT_MIXED = 4;
-export const CASE_EXIT_CODES = {
-    verified: EXIT_VERIFIED,
-    failed: EXIT_FAILED,
-    malformed: EXIT_MALFORMED,
-    incomplete: EXIT_UNDETERMINED,
-    partial: EXIT_UNDETERMINED,
-    mixed: EXIT_MIXED,
-};
-export const CASE_USAGE = `sanning-proof case -- one verdict over several evidence packs, offline
+// 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>... [--gateways <url,url>] [--json]
+  sanning-proof case <folder or case file>... [--gateways <url,url>] [--files <path>...] [--json]
 
-  <folder>    a pack folder (bundle.json plus logs/), or a folder that holds
-              several packs, such as an unpacked decision file. case reads
-              folders only: given a .zip, it exits 2 and says to unzip it
-              first (for example, unzip file.zip -d case/) and pass the folder.
-              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 folders 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.
+  <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
-              re-fetched on chain, pack by pack, and reported beside the case
-              reading. Without it the on-chain half is NOT checked, and the
-              output says so.
-  --json      the full reading as JSON: the verdict, every exception with its
-              rendered line, every record, every contribution, the packs, the
-              files outside them, and the on-chain half.
+              looked up on the public record, pack by pack, and reported on
+              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.
+  --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; 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 case's records is always named, and when a pack signed by
-the key it names is in the case, the reading 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.
+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 case is complete (a party can decline to
-hand over a pack); that a party which presented no pack under the named key
+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 was re-fetched on chain, which the reading never does.
+that any witness is on the public record, which the reading never looks up.
 
-Exit codes: 0 verified · 1 failed · 2 malformed, usage, an input that cannot
-be read as a case, or an unexpected error in this command · 3 incomplete or
-partial (undetermined, not failed) · 4 mixed (more than one outcome: read the
-exceptions). 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.`;
+${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.
@@ -1414,6 +1744,19 @@ function sortKeys(v) {
 function jsonText(v) {
     return JSON.stringify(sortKeys(v), null, 2);
 }
+function witnessTimeRow(t) {
+    return {
+        stamp_ref: t.cached.stampRef,
+        cached: { block_height: t.cached.blockHeight, block_time: t.cached.blockTime },
+        outcome: t.outcome,
+        answers: t.answers.map((a) => ({
+            gateway: a.gateway,
+            outcome: a.outcome,
+            block_height: a.blockHeight,
+            block_time: a.blockTime,
+        })),
+    };
+}
 // 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
@@ -1422,7 +1765,8 @@ async function onChainHalf(packs, gateways, io) {
     if (gateways.length === 0)
         return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
     const rows = [];
-    for (const [ref, bundle] of packs) {
+    const answered = new Set();
+    for (const [ref, bundle, cached] of packs) {
         const result = await verifyEvidenceBundle(bundle, {
             gateways,
             ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
@@ -1447,14 +1791,114 @@ async function onChainHalf(packs, gateways, io) {
             else
                 row.not_checked++;
         }
+        // The witness times the pack's witness-cache.json gives, looked up where
+        // it gives any (5.6.6, v1.25, A30). A pack with no cache gets no key and
+        // no request.
+        const times = await checkWitnessCache(cached, gateways, io.fetchImpl ?? fetch);
+        if (times.length > 0)
+            row.witness_times = times.map(witnessTimeRow);
         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);
+                }
+            }
+        }
+        for (const t of times) {
+            for (const a of t.answers) {
+                if (a.outcome === "matches" || a.outcome === "differs")
+                    answered.add(a.gateway);
+            }
+        }
     }
-    const verdict = rows.some((r) => r.mismatched > 0)
+    const verdict = rows.some((r) => r.mismatched > 0 || (r.witness_times ?? []).some((t) => t.outcome === "differs"))
         ? "failed"
         : rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)
             ? "undetermined"
             : "confirmed";
-    return { checked: true, gateways: [...gateways], packs: rows, verdict };
+    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.
+ */
+// Distinct `[blockHeight, blockTime]` pairs, in time order.
+function distinctTimes(times) {
+    const seen = new Map();
+    for (const [h, t] of times)
+        seen.set(`${h}:${t}`, [h, t]);
+    return [...seen.values()].sort((a, b) => a[1] - b[1] || a[0] - b[0]);
+}
+// Only the keys that carry something: a line with no cached or recorded time
+// is the line 0.13.0 printed, field for field.
+function withTimes(line, cached, recorded) {
+    return {
+        ...line,
+        ...(cached.length > 0 ? { cached } : {}),
+        ...(recorded.length > 0 ? { recorded } : {}),
+    };
+}
+/**
+ * `cached` is every witness time the packs cache (5.6.6, v1.25, A30). Where no
+ * lookup ran, each is printed labelled not checked. Where one ran, each time
+ * the public record matched is printed as the record's, each time no lookup
+ * settled stays labelled not checked, and a time the record contradicts is the
+ * reason the line reads `differs`.
+ */
+export function witnessLine(onChain, cached = []) {
+    if (!onChain.checked) {
+        return withTimes({
+            state: WITNESS_NOT_LOOKED_UP.state,
+            reasons: [...WITNESS_NOT_LOOKED_UP.reasons],
+            services: [...WITNESS_NOT_LOOKED_UP.services],
+        }, distinctTimes(cached.map((c) => [c.blockHeight, c.blockTime])), []);
+    }
+    const services = [...(onChain.answered ?? [])];
+    const rows = onChain.packs;
+    const times = rows.flatMap((r) => r.witness_times ?? []);
+    const unsettled = distinctTimes(times
+        .filter((t) => t.outcome === "not_checked")
+        .map((t) => [t.cached.block_height, t.cached.block_time]));
+    const recorded = distinctTimes(times
+        .filter((t) => t.outcome === "matches")
+        .flatMap((t) => t.answers.filter((a) => a.outcome === "matches"))
+        .map((a) => [a.block_height, a.block_time]));
+    const contradicted = [];
+    for (const t of times) {
+        if (t.outcome !== "differs")
+            continue;
+        const a = t.answers.find((x) => x.outcome === "differs");
+        const reason = `a pack dates the witness ${renderWitnessTime(t.cached.block_height, t.cached.block_time)}` +
+            `, and the public record dates it ${renderWitnessTime(a.block_height, a.block_time)}`;
+        if (!contradicted.includes(reason))
+            contradicted.push(reason);
+    }
+    if (onChain.verdict === "failed") {
+        return withTimes({ state: "differs", reasons: contradicted, services }, unsettled, recorded);
+    }
+    if (onChain.verdict === "confirmed") {
+        return withTimes({ state: "confirmed", reasons: [], services }, unsettled, recorded);
+    }
+    const reasons = [];
+    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 withTimes({ state: "not_checked", reasons, services }, unsettled, recorded);
 }
 /**
  * The case verdict's code, moved only by an on-chain half that was asked for:
@@ -1462,20 +1906,37 @@ async function onChainHalf(packs, gateways, io) {
  * on-chain half that could not be settled is never a clean 0.
  */
 export function caseExitCode(verdict, onChainVerdict) {
-    const code = CASE_EXIT_CODES[verdict] ?? EXIT_MALFORMED;
+    const code = exitCodeFor(verdict);
     if (onChainVerdict === "failed")
         return EXIT_FAILED;
     if (onChainVerdict === "undetermined" && code === EXIT_VERIFIED)
         return EXIT_UNDETERMINED;
     return code;
 }
+const titleOf = (word) => Object.prototype.hasOwnProperty.call(VERDICT_DISPLAY_TITLES, word)
+    ? VERDICT_DISPLAY_TITLES[word]
+    : 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) {
-    const lines = [data.verdict.toUpperCase(), `  ${data.summary}`];
+    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) {
-        let line = `  ${p.ref}  ${p.log_files} record file(s) under logs/`;
+        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 ` +
@@ -1491,28 +1952,79 @@ function caseReport(data) {
             lines.push(links.has(path) ? `  - ${path} (not a regular file: not followed, not read)` : `  - ${path}`);
         }
     }
-    const oc = data.on_chain;
-    if (!oc.checked) {
-        lines.push("on-chain      NOT CHECKED: no gateway was supplied, so no witness " +
-            "any pack names was re-fetched. Name gateways with --gateways to " +
-            "check them.");
+    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}`);
     }
-    else {
-        lines.push(`on-chain      re-fetched against ${oc.gateways.length} gateway(s), ` +
-            "pack by pack; the case reading above is offline and this does not " +
+    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`);
         }
-        lines.push(`on-chain      ${oc.verdict.toUpperCase()}`);
     }
     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) {
+    const out = [];
+    const roots = [...new Set([...tree.keys()].map((k) => k.split("/", 1)[0]))].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 = [];
+        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 = (v) => (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;
+}
 function caseError(e, asJson, io) {
     if (asJson)
-        io.out(jsonText({ error: e.message, exit_code: EXIT_MALFORMED, hint: e.hint }));
+        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}`));
@@ -1524,7 +2036,8 @@ function caseError(e, asJson, io) {
  * never 1, because 1 would name the evidence failed over a defect in this
  * command.
  */
-export async function runCase(argv, io) {
+export async function runCase(argv, stream) {
+    const io = guard(stream);
     try {
         return await caseCommand(argv, io);
     }
@@ -1543,10 +2056,11 @@ async function caseCommand(argv, io) {
     let asJson = false;
     let gateways = [];
     const paths = [];
+    let filePaths;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if ((arg === "--help" || arg === "-h" || arg === "help") && paths.length === 0) {
-            io.out(CASE_USAGE);
+            outBlock(io, CASE_USAGE);
             return EXIT_VERIFIED;
         }
         if (arg === "--json") {
@@ -1556,7 +2070,7 @@ async function caseCommand(argv, io) {
             const next = argv[i + 1];
             if (next === undefined) {
                 io.err("case: --gateways requires a comma-separated list of URLs");
-                io.out(CASE_USAGE);
+                outBlock(io, CASE_USAGE);
                 return EXIT_MALFORMED;
             }
             gateways = next
@@ -1565,9 +2079,19 @@ async function caseCommand(argv, io) {
                 .filter((g) => g.length > 0);
             i++;
         }
+        else if (arg === "--files") {
+            const taken = takeFilePaths(argv, i + 1);
+            if (taken.length === 0) {
+                io.err("case: --files requires at least one file path");
+                outBlock(io, CASE_USAGE);
+                return EXIT_MALFORMED;
+            }
+            filePaths = [...(filePaths ?? []), ...taken];
+            i += taken.length;
+        }
         else if (arg.startsWith("--")) {
             io.err(`case: unknown option ${arg}`);
-            io.out(CASE_USAGE);
+            outBlock(io, CASE_USAGE);
             return EXIT_MALFORMED;
         }
         else {
@@ -1576,13 +2100,22 @@ async function caseCommand(argv, io) {
     }
     if (paths.length === 0) {
         io.err("case: at least one pack is required");
-        io.out(CASE_USAGE);
+        outBlock(io, CASE_USAGE);
         return EXIT_MALFORMED;
     }
+    let offered;
+    if (filePaths !== undefined) {
+        const read = await readOfferedFiles(filePaths);
+        if (typeof read === "string")
+            return caseError(new CaseInputError(read), asJson, io);
+        offered = read;
+    }
     let split;
+    let tree;
     let bundles;
     try {
-        split = await splitCase(await treeFromArguments(paths), readFileEntry);
+        tree = await treeFromArguments(paths);
+        split = await splitCase(tree, readFileEntry);
         bundles = split.packs.map((p) => [p, loadBundle(p)]);
     }
     catch (e) {
@@ -1591,13 +2124,37 @@ async function caseCommand(argv, io) {
         throw e;
     }
     const reading = await readCase(bundles.map(([p, bundle]) => ({ ref: p.ref, bundle, content: p.content })));
-    const onChain = await onChainHalf(bundles.map(([p, bundle]) => [p.ref, bundle]), gateways, io);
+    let caseFile;
+    try {
+        caseFile = await caseFileReadings(tree);
+    }
+    catch (e) {
+        if (e instanceof CaseInputError)
+            return caseError(e, asJson, io);
+        throw e;
+    }
+    const caches = [];
+    for (const [p, bundle] of bundles) {
+        caches.push(readWitnessCache(bundle, await witnessCacheBytes(tree, split, p)));
+    }
+    const onChain = await onChainHalf(bundles.map(([p, bundle], i) => [p.ref, bundle, caches[i]]), gateways, io);
+    const witness = witnessLine(onChain, caches.flat());
     const code = caseExitCode(reading.verdict, onChain.verdict);
     const nil = (v) => (v === undefined ? null : v);
     const data = {
         verdict: reading.verdict,
+        title: titleOf(reading.verdict),
+        reliance: caseReliance(reading.verdict, reading.handoffRecords),
         exit_code: code,
         summary: renderCaseSummary(reading),
+        witness: {
+            state: witness.state,
+            reasons: witness.reasons,
+            services: witness.services,
+            ...(witness.cached ? { cached: witness.cached } : {}),
+            ...(witness.recorded ? { recorded: witness.recorded } : {}),
+            rendered: renderWitnessLine(witness),
+        },
         handoff_records: reading.handoffRecords,
         on_chain_checked: reading.onChainChecked,
         exceptions: reading.exceptions.map((e) => ({
@@ -1608,32 +2165,55 @@ async function caseCommand(argv, io) {
             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]) => ({
+        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,
     };
+    // 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`.
+    let fileLines = [];
+    const out = data;
+    if (offered !== undefined) {
+        const fileReading = await matchCaseFiles(bundles.map(([p, bundle]) => ({ ref: p.ref, bundle, content: p.content })), offered);
+        out.files = fileMatchToJson(fileReading);
+        fileLines = renderFileMatch(fileReading);
+    }
     if (asJson)
-        io.out(jsonText(data));
+        outJson(io, jsonText(out));
     else
-        for (const line of caseReport(data))
+        for (const line of [...caseReport(data), ...fileLines])
             io.out(noLoneSurrogates(line));
     return code;
 }
@@ -1670,7 +2250,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;
     });
 }