@sanning/proof 0.19.1 → 0.20.0

package/src/witness-lookup.ts

@@ -1,26 +1,14 @@
 // The public-record (witness) lookup the CLI runs with `--gateways`
-// (evidence-bundle.md §5.5.6, v1.20, A24, D7): re-fetch each pack's witness on
-// the public record and report what it said. Moved here from `cli.ts`
-// (proof#200) so the CLI and a consumer that is not the CLI, the verify page,
-// a browser app, call the SAME implementation rather than each keeping its
-// own copy that can drift.
+// (evidence-bundle.md §5.5.6): re-fetch each pack's witness on the public record
+// and report what it said. The CLI and non-CLI callers (the verify page, a
+// browser app) share this one implementation.
 //
-// Pure by the kernel's own rule (specs/architecture.md §3): the network call
-// is the one exception this module exists to hold, and it never runs unless a
-// caller hands in a gateway to ask. `options.fetchImpl` is the seam: where a
-// caller supplies one (a browser page's own `fetch`, or a test's fake), that
-// is the ONE this module calls; where none is given, it falls back to the
-// ambient global `fetch`, the same fallback `cli.ts` already applied at its
-// own call site before this module existed.
-//
-// `onChainHalf` and `witnessLine` are the CLI's own building blocks,
-// UNCHANGED (proof#200 is additive: the CLI's `case` output and exit codes are
-// byte-for-byte what they were). `lookupPublicRecord` is the new export:
-// one pack (or several) in, one four-state result out, with a pack's
-// `witness-cache.json` read as part of the pack rather than as a side file a
-// caller must remember to also pass in.
+// The network call is the one exception to the kernel's purity (specs/architecture.md §3).
+// It never runs unless a caller hands in a gateway, and `options.fetchImpl`
+// is the seam: the caller's `fetch` if given, else the ambient global.
 
 import { SIMULATED_WITNESS_KIND, verifyEvidenceBundle } from "./evidence.js";
+import type { EvidenceBundleResult } from "./evidence.js";
 import type { WitnessLine, WitnessState } from "./case.js";
 import { WITNESS_NOT_LOOKED_UP, renderWitnessLine } from "./case.js";
 import {
@@ -32,7 +20,7 @@ import {
   renderWitnessTime,
 } from "./witness-cache.js";
 
-/** The seam every network call in this module goes through: used where given, else the ambient global `fetch`. */
+/** The seam every network call goes through: the caller's `fetch` if given, else the ambient global. */
 export interface WitnessLookupOptions {
   fetchImpl?: typeof fetch;
 }
@@ -44,13 +32,9 @@ export interface OnChainRow {
   mismatched: number;
   unreachable: number;
   not_checked: number;
-  /**
-   * How many of the `not_checked` witnesses are simulated: a sandbox plane's
-   * stand-in for a chain, never looked up. Present only where there
-   * is one, so a production pack's row is unchanged.
-   */
+  /** How many of the `not_checked` witnesses are simulated (a sandbox plane's stand-in for a chain, never looked up). Present only where there is one. */
   simulated?: number;
-  /** Present only where the pack caches a witness time (5.6.6, v1.25, A30). */
+  /** Present only where the pack caches a witness time (5.6.6). */
   witness_times?: WitnessTimeRow[];
 }
 
@@ -86,29 +70,68 @@ export interface OnChainHalf {
   checked: boolean;
   gateways: string[];
   packs: OnChainRow[];
-  verdict: "not_checked" | "confirmed" | "failed" | "undetermined";
+  verdict: "not_checked" | "confirmed" | "differs" | "not_settled";
+}
+
+/** One pack's witnesses as a lookup left them: how many, and each one's rollup. */
+export function onChainRow(
+  ref: string,
+  result: EvidenceBundleResult,
+): { row: OnChainRow; answered: Set<string> } {
+  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++;
+  }
+  const simulated = witnesses.filter((w) => w.anchorRef?.kind === SIMULATED_WITNESS_KIND).length;
+  if (simulated > 0) row.simulated = simulated;
+  const answered = new Set<string>();
+  for (const w of witnesses) {
+    for (const outcome of w.onChain?.perGateway ?? []) {
+      if (outcome.outcome === "confirm" || outcome.outcome === "mismatch") {
+        answered.add(outcome.gateway);
+      }
+    }
+  }
+  return { row, answered };
 }
 
 /**
- * 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.
- *
- * Moved from `cli.ts` unchanged, apart from taking `fetchImpl` directly
- * instead of a `Cli` stream (`io.fetchImpl ?? fetch`, the same fallback the
- * CLI already applied at its own call site).
+ * `differs` where a lookup found other bytes or another time, `not_settled` where one
+ * did not settle, `confirmed` otherwise. Only `differs` moves a verdict.
+ */
+export function onChainOutcome(rows: readonly OnChainRow[]): "differs" | "not_settled" | "confirmed" {
+  if (
+    rows.some((r) => r.mismatched > 0 || (r.witness_times ?? []).some((t) => t.outcome === "differs"))
+  ) {
+    return "differs";
+  }
+  if (rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)) {
+    return "not_settled";
+  }
+  return "confirmed";
+}
+
+/**
+ * Each pack's witnesses, re-fetched through `verifyEvidenceBundle`. Outside the
+ * case reading on purpose: `readCase` makes no network call, so the case verdict
+ * is the same on every surface. This adds the half the reading names as not checked.
  */
 export async function onChainHalf(
   packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[],
   gateways: readonly string[],
   options: WitnessLookupOptions = {},
-  /**
-   * Where given, receives for each pack the `stamp_ref` of every stamp whose
-   * witness this lookup confirmed: the run reading evaluates an enclave token
-   * at a stamp's interval end only there.
-   */
-  witnessed?: string[][],
 ): Promise<OnChainHalf> {
   if (gateways.length === 0) return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -116,53 +139,19 @@ export async function onChainHalf(
   const answered = new Set<string>();
   for (const [ref, bundle, cached] of packs) {
     const result = await verifyEvidenceBundle(bundle, { gateways: [...gateways], fetchImpl });
-    const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
-    const row: OnChainRow = {
-      ref,
-      witnesses: witnesses.length,
-      confirmed: 0,
-      mismatched: 0,
-      unreachable: 0,
-      not_checked: 0,
-    };
-    witnessed?.push(
-      (result.stamps ?? []).filter((st) => st.ok && st.onChain?.rollup === "confirm").map((st) => st.stampRef),
-    );
-    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++;
-    }
-    const simulated = witnesses.filter((w) => w.anchorRef?.kind === SIMULATED_WITNESS_KIND).length;
-    if (simulated > 0) row.simulated = simulated;
-    // 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 { row, answered: heard } = onChainRow(ref, result);
+    for (const g of heard) answered.add(g);
+    // The witness times the pack's witness-cache.json gives (5.6.6). A pack with no cache gets no key and no request.
     const times = await checkWitnessCache(cached, gateways, fetchImpl);
     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 || (r.witness_times ?? []).some((t) => t.outcome === "differs"),
-  )
-    ? "failed"
-    : rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)
-      ? "undetermined"
-      : "confirmed";
+  const verdict = onChainOutcome(rows);
   return {
     answered: gateways.filter((g) => answered.has(g)),
     checked: true,
@@ -179,8 +168,7 @@ function distinctTimes(times: Iterable<[number, number]>): [number, number][] {
   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.
+// Only the keys that carry something.
 function withTimes(
   line: WitnessLine,
   cached: [number, number][],
@@ -194,15 +182,11 @@ function withTimes(
 }
 
 /**
- * `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`.
- *
- * Moved from `cli.ts` unchanged: same inputs, same three states
- * (`WitnessState`), same rendering. The CLI's `case` command still calls this
- * exact function, so its witness line is unchanged.
+ * `cached` is every witness time the packs cache (5.6.6). 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 makes the line read
+ * `differs`.
  */
 export function witnessLine(onChain: OnChainHalf, cached: readonly CachedWitnessTime[] = []): WitnessLine {
   if (!onChain.checked) {
@@ -239,7 +223,7 @@ export function witnessLine(onChain: OnChainHalf, cached: readonly CachedWitness
       `, and the public record dates it ${renderWitnessTime(a.block_height as number, a.block_time as number)}`;
     if (!contradicted.includes(reason)) contradicted.push(reason);
   }
-  if (onChain.verdict === "failed") {
+  if (onChain.verdict === "differs") {
     return withTimes({ state: "differs", reasons: contradicted, services }, unsettled, recorded);
   }
   if (onChain.verdict === "confirmed") {
@@ -258,39 +242,20 @@ export function witnessLine(onChain: OnChainHalf, cached: readonly CachedWitness
   return withTimes({ state: "not_checked", reasons, services }, unsettled, recorded);
 }
 
-// ─── The public-entry-point export (proof#200) ─────────────────────────────
-//
-// `onChainHalf` and `witnessLine` above are the CLI's own two-step shape:
-// gateways in, an `OnChainHalf` (every row, every gateway) out, then a
-// `WitnessLine` (three states: `confirmed`, `not_checked`, `differs`) rendered
-// from it. A second caller, the verify page, does not want the CLI's
-// internal row shape and does want a fourth state the CLI's three-state
-// `WitnessLine` cannot name: a pack that carries NO witness at all yet is not
-// "not checked" (a lookup that could have found something and didn't), it is
-// "there is nothing on the public record to check". Folding that pack into
-// `not_checked` is not wrong for the CLI (`case` already says so in the
-// reason text: "a pack names no witness"), but a tag that only ever reads
-// "Not checked" hides the one distinction an auditor most wants: did we look
-// and find nothing, or is there nothing to look for yet.
+// ─── The public-entry-point export ─────────────────────────────
 //
-// `lookupPublicRecord` is additive over the two functions above: it calls
-// them, never reimplements them, so there is exactly one place the network
-// call and the verdict arithmetic live. It never throws: the underlying
-// primitives (`verifyEvidenceBundle`, `checkWitnessCache`) already treat a
-// gateway's answer as untrusted input and report `unreachable`/`differs`
-// rather than raise, and this function adds no new path to the network or the
-// parser.
+// `lookupPublicRecord` adds a fourth state the CLI's three-state `WitnessLine`
+// cannot name: a pack that names no witness at all is not "not checked" (a
+// lookup that found nothing), it is "nothing on the public record to check". It
+// calls `onChainHalf` and `witnessLine` rather than reimplementing them, so the
+// network call and the verdict arithmetic live in one place.
 
-/** The four states this export's result can carry. The CLI's own `WitnessState` plus `no_public_record`. */
+/** The states a lookup can carry: the CLI's `WitnessState` plus `no_public_record`. */
 export type PublicRecordState = WitnessState | "no_public_record";
 
 /**
- * One pack, as this lookup needs it: the parsed `bundle.json` and, where the
- * pack carries one, the RAW BYTES of its `witness-cache.json`, read as part
- * of the pack, per proof#200's acceptance criteria, rather than as a
- * separately-loaded side file. `null` and `undefined` both mean "this pack has
- * no witness-cache.json", the same reading `readWitnessCache` gives a missing
- * file.
+ * One pack: the parsed `bundle.json` and, where it has one, the raw bytes of its
+ * `witness-cache.json`. `null` and `undefined` both mean no cache file.
  */
 export interface PublicRecordPack {
   /** How this pack is named in the result; carries no meaning beyond that. */
@@ -303,36 +268,27 @@ export interface PublicRecordResult {
   state: PublicRecordState;
   reasons: string[];
   services: string[];
-  /** Witness times a pack caches that no lookup settled (5.6.6, v1.25, A30). */
+  /** Witness times a pack caches that no lookup settled (5.6.6). */
   cached?: [number, number][];
   /** Witness times the public record returned that matched a pack's cache. */
   recorded?: [number, number][];
-  /** The line as both the CLI and a page print it, one string, kernel words. */
+  /** The line as the CLI and a page print it. */
   rendered: string;
 }
 
 /**
- * The public-record lookup the CLI runs with `--gateways`, exported so a
- * consumer that is not the CLI can run the SAME lookup rather than copy it
- * (proof#200; the copy this closes is verify-page#70's `src/lib/verify.ts`).
+ * The public-record lookup the CLI runs with `--gateways`, for non-CLI callers.
  *
- * `packs` is every pack in the drop being read; `gateways` is empty for an
- * offline reading, which never makes a network call and always answers
- * `not_checked` or `no_public_record`. `options.fetchImpl` is the one seam a
- * network call goes through, a browser page supplies its own `fetchImpl`;
- * with none given this falls back to the ambient global `fetch`, so a
- * browser page and a test can each supply their own and Node's `fetch` is
- * never assumed where a caller passed something else.
+ * `packs` is every pack in the drop; `gateways` is empty for an offline reading,
+ * which makes no network call and answers `not_checked` or `no_public_record`.
  *
- * `state` is `confirmed` only about the BYTES: the public record holds what a
- * pack names. It says nothing about whether the pack itself verifies (its
- * wrapper signature, its `body_hash`), and a caller must never show
- * `confirmed` apart from the pack's own verdict (proof#201).
+ * `state` is `confirmed` only about the bytes: the public record holds what a
+ * pack names. It says nothing about whether the pack itself verifies, so a
+ * caller must never show `confirmed` apart from the pack's own verdict.
  *
- * Never throws. Every input, including a malformed pack, a non-string
- * gateway, or a `fetchImpl` that itself misbehaves, is read as untrusted, and
- * anything this function or what it calls cannot make sense of settles as
- * `not_checked` rather than escape as an exception.
+ * Never throws. Every input (a malformed pack, a non-string gateway, a
+ * misbehaving `fetchImpl`) is untrusted, and anything it cannot make sense of
+ * settles as `not_checked`.
  */
 export async function lookupPublicRecord(
   packs: readonly PublicRecordPack[],
@@ -340,10 +296,7 @@ export async function lookupPublicRecord(
   options: WitnessLookupOptions = {},
 ): Promise<PublicRecordResult> {
   try {
-    // Nothing to look up: zero packs means the CALLER handed in nothing to
-    // check, which is not the same claim as "the packs it handed in name no
-    // witness" (`no_public_record`, below). Checked first, and unconditionally,
-    // so a caller than mishandles an empty drop never reads it as confirmed.
+    // Zero packs is the caller handing in nothing, not packs that name no witness (`no_public_record`). Checked first so an empty drop never reads as confirmed.
     if (packs.length === 0) {
       const reasons = [...WITNESS_NOT_LOOKED_UP.reasons];
       return {
@@ -363,23 +316,12 @@ export async function lookupPublicRecord(
     const onChain = await onChainHalfForWitnessCount(rows, gateways, options);
     const line = witnessLine(onChain.half, caches.flat());
 
-    // "No public record yet": every pack this lookup was handed names ZERO
-    // witnesses, so there is nothing the public record could confirm or
-    // contradict. This holds independently of whether a lookup ran, an
-    // offline reading of a fresh, unstamped pack is exactly as much "nothing to
-    // check yet" as an online one, and it is computed from the SAME witness
-    // count `onChainHalf` derives from `verifyEvidenceBundle`'s own parse, never
-    // a second reading of the bundle.
-    //
-    // A pack that does NOT verify (a broken wrapper signature, `bundle: null`,
-    // garbage, an unrecognised body type) also names zero witnesses, by
-    // construction: `verifyEvidenceBundle` never reports a checkpoint or a
-    // stamp for a bundle it could not authenticate. That is not "nothing to
-    // check yet", it is a pack this lookup could not read, so `no_public_record`
-    // is reserved for a pack whose wrapper genuinely verifies
-    // (`signatureOk && bodyHashOk && status !== "failed"`) and that carries no
-    // cached witness time either (a cache entry names something to check).
-    // Anything else that would otherwise qualify reads `not_checked` instead.
+    // `no_public_record`: every pack names zero witnesses, so nothing could be
+    // confirmed or contradicted. Reserved for packs whose wrapper verifies
+    // (`signatureOk && bodyHashOk && status !== "failed"`) and that carry no
+    // cached witness time: a pack that fails to verify also names zero
+    // witnesses, and that is a pack this lookup could not read, so it reads
+    // `not_checked`.
     const noWitnesses = onChain.witnessCounts.every((n) => n === 0);
     const everyPackVerifies = onChain.verifies.every((v) => v);
     const noCacheRead = caches.every((c) => c.length === 0);
@@ -392,18 +334,12 @@ export async function lookupPublicRecord(
       reasons: line.reasons,
       services: line.services,
       ...(line.cached ? { cached: line.cached } : {}),
-      // `recorded` is a claim about the public record confirming a cached
-      // time; it never rides alongside anything but a `confirmed` verdict, so
-      // a pack whose wrapper does not verify can never surface a cached time
-      // as though the record had confirmed it.
+      // `recorded` rides only with a `confirmed` verdict, so a pack whose wrapper does not verify never surfaces a cached time as record-confirmed.
       ...(state === "confirmed" && line.recorded ? { recorded: line.recorded } : {}),
       rendered: renderWitnessLine({ ...line, state: state === "no_public_record" ? "not_checked" : state }),
     };
   } catch (e) {
-    // Untrusted input all the way down: a gateway's answer, a pack's shape, a
-    // caller's `fetchImpl`. Anything this function or what it calls cannot
-    // make sense of settles `not_checked` rather than throw out of an export a
-    // browser page calls directly.
+    // Untrusted input all the way down (a gateway's answer, a pack's shape, a `fetchImpl`): settle `not_checked` rather than throw out of an export a page calls directly.
     const reason =
       e instanceof Error ? `the lookup did not settle: ${e.message}` : "the lookup did not settle";
     const reasons = [reason];
@@ -416,15 +352,9 @@ export async function lookupPublicRecord(
   }
 }
 
-// `onChainHalf` short-circuits to `{ checked: false, packs: [] }` with no
-// gateways, which is right for the CLI (nothing to print per pack) but leaves
-// `lookupPublicRecord` unable to tell "no gateways" from "no witnesses" for an
-// OFFLINE reading. This wrapper reads each pack's witness count, and whether
-// its wrapper verifies, the same way `onChainHalf` does, via
-// `verifyEvidenceBundle`: an OFFLINE parse (`gateways: []`), so it costs no
-// extra request whether or not a lookup runs, and `verifies` is never itself
-// a statement about the public record, only about the pack's own signature
-// and `body_hash`.
+// Reads each pack's witness count and whether its wrapper verifies, via an
+// offline `verifyEvidenceBundle` parse (`gateways: []`), so it costs no request.
+// `verifies` is about the pack's own signature and `body_hash`, never the public record.
 async function onChainHalfForWitnessCount(
   packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[],
   gateways: readonly string[],

package/src/zip-reader.ts

@@ -1,42 +1,34 @@
 /**
  * The one ZIP reader `case` uses, for a case file named on the command line.
  *
- * The TypeScript half of `src/sanning_proof/zip_reader.py`. Node has no ZIP
- * reader, and Python's `zipfile` is not used, so the two kernels read one
- * archive by one rule rather than by two libraries that disagree on the edges:
- * a central directory that contradicts a local header, a name that is not
- * UTF-8, data after the end of a deflate stream. Where either library would
- * have made a choice, this module refuses instead.
+ * Node has no ZIP reader. This one refuses where two libraries would disagree
+ * (evidence-bundle.md 5.6.1). It reads the central directory and each entry
+ * through its local header, stored and deflate only.
  *
- * What it reads (evidence-bundle.md 5.6.1): the central directory, and each
- * entry's data through its local header. Stored and deflate only. What it
- * REFUSES, as a whole archive: no end-of-central-directory record, ZIP64, more
- * than one disk, an entry the central directory places outside the archive, a
- * local header that does not match its central entry, a size or CRC-32 that
- * does not match the data, two entries with one name, a name that is not
- * UTF-8, more than MAX_ZIP_ENTRIES entries or MAX_ZIP_BYTES bytes in all, and
- * a name nested deeper than MAX_ZIP_DEPTH folders. What it REPORTS and never
- * reads, entry by entry: an encrypted entry, a symbolic link, a method other
- * than stored or deflate, and a name that is absolute, holds a backslash or a
- * NUL, or has an empty, `.` or `..` segment.
+ * It refuses the whole archive for: no end-of-central-directory record, ZIP64,
+ * more than one disk, an entry placed outside the archive, a local header that
+ * contradicts its central entry, a size or CRC-32 that does not match, two
+ * entries with one name, a name that is not UTF-8, more than MAX_ZIP_ENTRIES
+ * entries or MAX_ZIP_BYTES bytes, or a name nested deeper than MAX_ZIP_DEPTH.
+ * It reports without reading, per entry: an encrypted entry, a symbolic link,
+ * another method, and a name that is absolute, holds a backslash or NUL, or has
+ * an empty, `.` or `..` segment.
  *
- * Pure: bytes in, entries out. The caller turns them into the tree `case`
- * splits.
+ * Pure: bytes in, entries out.
  */
 
 import { inflateRawSync } from "node:zlib";
 
 import { utf8Strict } from "./verifier.js";
 
-/** More entries than this refuse the archive: the walk's own bound on names. */
+/** More entries than this refuse the archive. */
 export const MAX_ZIP_ENTRIES = 50_000;
 /** More uncompressed bytes than this, across every entry, refuse the archive. */
 export const MAX_ZIP_BYTES = 2 ** 30;
 /**
  * An archive file larger than this is refused before it is read: the
- * uncompressed cap, and room for the headers, the central directory and the
- * deflate framing of an archive that holds that much. The caller checks the
- * size on disk, so the archive is never read whole to find out it is too big.
+ * uncompressed cap plus room for headers and framing. The caller checks the
+ * size on disk.
  */
 export const MAX_ZIP_ARCHIVE_BYTES = MAX_ZIP_BYTES + 256 * 2 ** 20;
 /** A name nested deeper than this many folders refuses the archive. */
@@ -49,7 +41,7 @@ const S_IFMT = 0o170000;
 const S_IFLNK = 0o120000;
 const UNIX = 3;
 
-/** The archive cannot be read as a case file. `message` is the whole report, identical in both kernels. */
+/** The archive cannot be read as a case file. `message` is the whole report. */
 export class ZipReadError extends Error {
   constructor(message: string) {
     super(message);
@@ -57,10 +49,7 @@ export class ZipReadError extends Error {
   }
 }
 
-/**
- * One file entry. `refused` is why the entry is reported and not read, or
- * `null`; `data` is its bytes where it was read.
- */
+/** One file entry. `refused` is why it is reported and not read, or `null`; `data` is set where it was read. */
 export interface ZipEntry {
   name: string;
   refused: string | null;
@@ -101,18 +90,13 @@ function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
   return true;
 }
 
-/**
- * Every FILE entry of a ZIP archive, in central-directory order. A directory
- * entry (a name ending in `/`) is not a file and is not returned. Throws
- * `ZipReadError`.
- */
+/** Every file entry of a ZIP archive, in central-directory order (directory entries are skipped). Throws `ZipReadError`. */
 export function readZip(data: Uint8Array): ZipEntry[] {
   const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
   const n = data.length;
   const u32 = (at: number) => view.getUint32(at, true);
   const u16 = (at: number) => view.getUint16(at, true);
-  // The end-of-central-directory record: 22 bytes plus a comment of at most
-  // 65535, searched backwards so the LAST signature wins.
+  // 22 bytes plus a comment of at most 65535, searched backwards so the last signature wins.
   let eocd = -1;
   const lowest = Math.max(0, n - 22 - 0xffff);
   for (let at = n - 22; at >= lowest; at--) {
@@ -214,9 +198,7 @@ export function readZip(data: Uint8Array): ZipEntry[] {
     if (method === 0) {
       body = packed;
     } else {
-      // `info: true` hands back the engine, whose `bytesWritten` is how many
-      // input bytes the stream consumed. Anything left over is data after the
-      // end of the deflate stream, which Python's `unused_data` refuses too.
+      // Bytes left over after the end of the deflate stream are refused.
       let result: { buffer: Buffer; engine: { bytesWritten: number } };
       try {
         result = inflateRawSync(packed, {