@sanning/proof 0.12.0 → 0.13.0

package/src/index.ts

@@ -12,7 +12,7 @@
 // gateway/transport concerns are consumer-layer logic composed above it.
 
 // ACCEPTED_SPEC_MAJORS is exported for parity with the sibling kernels'
-// registries (Python ACCEPTED_SPEC_VERSIONS, Go SupportedSpecMajor): a consumer
+// registries (Python ACCEPTED_SPEC_MAJORS, Go SupportedSpecMajor): a consumer
 // can see which profiles this build admits without inferring it from probe
 // calls. It is frozen at its definition (`Object.freeze`, typed
 // `readonly string[]`) because the verifier reads that same array — an exported
@@ -60,6 +60,7 @@ export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions
 // bytes, and only for events whose verification bound them to the committed
 // content_hash. Additive; verifyEvidenceBundle's behavior is unchanged.
 export {
+  ACCEPTED_EVIDENCE_MAJORS,
   ANCHOR_TRACE_BODY_TYPE,
   EXPORT_BODY_TYPE,
   STAMP_BODY_VERSION,
@@ -128,6 +129,8 @@ export type {
 // derivation to it, and diff its copy against ours. Additive — no existing
 // export changes.
 export {
+  PACK_GRADE_CAUSE_KINDS,
+  PACK_VERDICTS,
   accountDisclosure,
   completenessNotes,
   gradeCauses,
@@ -162,7 +165,14 @@ export type {
 // optional fourth argument, so a surface gets one verdict; omitting it is the
 // pre-§5.4 behavior, unchanged. Additive: no existing export changes.
 export {
+  DECLARATION_CONTENT_KINDS,
+  DECLARATION_DEVIATION_KINDS,
+  DECLARATION_NOTE_KINDS,
+  DECLARATION_ROLES,
+  DECLARATION_VERDICTS,
   DECLARATION_VERSION,
+  DECLARATION_VERSION_V2,
+  DECLARATION_VERSIONS,
   checkDeclaration,
   declarationClaims,
   packRecords,
@@ -180,6 +190,7 @@ export type {
   DeclarationDeviationKind,
   DeclarationNote,
   DeclarationNoteKind,
+  DeclarationRole,
   DeclarationVerdict,
   PackRecord,
 } from "./declaration.js";
@@ -206,20 +217,53 @@ export {
   CASE_EXCEPTION_KINDS,
   CASE_QUARANTINED_PROFILES,
   CASE_RECORD_PROFILES,
+  CASE_NOTE_KINDS,
+  CASE_RELIANCE,
   CASE_VERDICTS,
+  CONTENT_WITHHELD_BY_DECLARATION,
+  VERDICT_DISPLAY_TITLES,
+  WITNESS_NOT_LOOKED_UP,
+  WITNESS_STATES,
   readCase,
+  renderCaseNote,
   renderCaseSummary,
   renderException,
+  renderWitnessLine,
 } from "./case.js";
 export type {
   CaseException,
   CaseExceptionKind,
+  CaseNote,
+  CaseNoteKind,
   CasePack,
+  CasePackReading,
   CaseReading,
   CaseRecordReading,
   CaseVerdict,
+  WitnessLine,
+  WitnessState,
 } from "./case.js";
 
+// The case file's index (src/case-file.ts, evidence-bundle.md §5.6, A25):
+// compared with the drop it describes, with NO verdict contribution. The index
+// is never an input to `readCase`. Pure: bytes and a file list in.
+export {
+  CASE_FILE_FINDING_KINDS,
+  CASE_FILE_INDEX_NAME,
+  CASE_FILE_VERSION,
+  HOW_TO_VERIFY_NAME,
+  REPORT_README_FIRST_LINE,
+  howToVerifyText,
+  isPackRef,
+  readCaseFileIndex,
+  renderCaseFileFinding,
+} from "./case-file.js";
+export type {
+  CaseFileFinding,
+  CaseFileFindingKind,
+  CaseFileIndexReading,
+} from "./case-file.js";
+
 // Chain reading (src/chain.ts): following the pointer every sanning.events/v2
 // record carries to the record before it, over the records ONE bundle presents.
 //
@@ -258,13 +302,25 @@ export type {
 // signed, offline-verifiable sanning.evidence.export/v2 artifact from a source
 // anchor-trace bundle + operator attestations + an exporter Ed25519 key. The
 // inverse of verifyEvidenceBundle's verifyExportBody dispatch.
+// One exit-code table for every verb (0.13.0): the verdict word to the exit
+// code, and the help text every verb prints. Additive.
+export {
+  EXIT_CODES,
+  EXIT_CODES_HELP,
+  EXIT_FAILED,
+  EXIT_MALFORMED,
+  EXIT_MIXED,
+  EXIT_UNDETERMINED,
+  EXIT_VERIFIED,
+  exitCodeFor,
+} from "./exit-codes.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 
 // Agent inclusion-proof bundle verification: the
 // sanning.agent.proof/v1 bundle. The CLI sniffs spec_version and routes here so
 // one verifier covers both agent and anchor bundles.
-export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
+export { AGENT_PROOF_SPEC_VERSION, isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
 export type {
   AgentProofBundle,
   AgentProofResult,

package/src/message-parts.ts

@@ -278,17 +278,19 @@ const HELD_UNCHECKED_RESULTS: readonly string[] = [
 
 /**
  * The keys that make a part carry its content INLINE, in the order they are
- * read. Named rather than inferred: `bytes` is A2A's spelling of an inline file
- * part, and `data` and `content` are the two other spellings in the wild. The
- * FIRST of them present with a value that is not `null` is the inline content,
- * so a part spelling it twice reads one way in both kernels.
+ * read. Named rather than inferred: `bytes`, `data` and `content` are the
+ * spellings in the wild. None is A2A 1.0.0's: its `Part` has no `kind` and
+ * carries a file as `raw` or `url`, so a literal A2A part reads
+ * `part_not_a_file` (envelope-spec §4.1, A19). The FIRST of them present with
+ * a value that is not `null` is the inline content, so a part spelling it
+ * twice reads one way in both kernels.
  *
  * A key present with `null` is an ABSENT inline value, on A14's ruling that an
- * absent value and one written as `null` name one thing. That matters: an A2A
- * `FilePart` with `uri` set carries `"bytes": null`, and so does proto3 JSON,
- * and reading those as inline made a conformant DESCRIPTOR part uncheckable
- * (proof#156 gate). They fall through to the descriptor rule, which is what
- * they are.
+ * absent value and one written as `null` name one thing. That matters: a
+ * proto3 JSON encoder can write an unset field as `"bytes": null`, and reading
+ * that as inline made a conformant DESCRIPTOR part uncheckable
+ * (proof#156 gate). Such a part falls through to the descriptor rule, which is
+ * what it is.
  */
 // A conformant DESCRIPTOR part that also carries a `content` or `data` key
 // meaning something else (a filename, a metadata blob) is reclassified by this

package/src/types.ts

@@ -48,6 +48,11 @@ export interface VerifyOptions {
   // Content bind: the caller's own hash of an artifact (e.g. the in-browser
   // hash of a user's file) to match against the hashes the envelope commits to.
   expectedContentHash?: string;
+  // NARROWS the accept-set for this call and never widens it: the set used is
+  // `ACCEPTED_SPEC_MAJORS` intersected with this list, so a caller cannot
+  // admit a profile this kernel does not. The Python twin is
+  // `accepted_spec_majors` (P-10, 0.13.0).
+  acceptedSpecMajors?: readonly string[];
 }
 
 export interface VerificationResult {

package/src/verifier.ts

@@ -23,7 +23,7 @@ import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from ".
 // profile-specific dialect (no underscore strip, that is mlflow-only).
 //
 // Exported for parity with the sibling kernels' registries — Python
-// `ACCEPTED_SPEC_VERSIONS`, Go `SupportedSpecMajor` — so the accept-set is
+// `ACCEPTED_SPEC_MAJORS`, Go `SupportedSpecMajor` — so the accept-set is
 // assertable rather than inferable: test/accept-set.test.ts holds it to the
 // ratified §4/§5 set transcribed in cross-kernel/accept-set.json, and the
 // cross-kernel gate probes one signed envelope per identifier. This entry list
@@ -231,6 +231,16 @@ const JCS_BOM = "";
  * Throws for anything that is not conformant; every call site treats a throw as
  * "this reader cannot read these bytes" and names the check that failed.
  */
+/**
+ * Bytes as strict UTF-8, a leading byte-order mark KEPT as a character.
+ * `utf8_strict` in the Python twin's `canonicalize.py` is the same rule, and
+ * `jcsParse` below performs the identical decode. Throws on bytes that are not
+ * UTF-8.
+ */
+export function utf8Strict(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+}
+
 export function jcsParse(bytes: Uint8Array): unknown {
   const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
   if (text.startsWith(JCS_BOM)) throw new Error("jcsParse: leading byte-order mark");
@@ -311,9 +321,17 @@ function hasLoneSurrogate(s: string): boolean {
 // `<major>.<minor>` where minor is `[0-9]+`. A non-numeric minor suffix is
 // malformed, not a tolerated future version — matching the Python kernel's
 // 0.1.1 semantics (the TS/Go fail-open lenience was closed deliberately).
-export function specVersionSupported(specVersion: string): boolean {
+//
+// `accepted` NARROWS the registry and never widens it, as the Python twin's
+// `spec_version_supported(spec_version, accepted)` does (P-10, 0.13.0).
+export function specVersionSupported(
+  specVersion: string,
+  accepted?: readonly string[],
+): boolean {
   if (typeof specVersion !== "string" || specVersion === "") return false;
-  return ACCEPTED_SPEC_MAJORS.some((m) => {
+  const registry =
+    accepted === undefined ? ACCEPTED_SPEC_MAJORS : ACCEPTED_SPEC_MAJORS.filter((m) => accepted.includes(m));
+  return registry.some((m) => {
     if (specVersion === m) return true;
     if (!specVersion.startsWith(`${m}.`)) return false;
     const minor = specVersion.slice(m.length + 1);
@@ -456,22 +474,26 @@ export function contentHashes(env: Envelope): { role: ContentRole; hash: string
 // signature, so stripping it to fake "external" — or injecting one to fake
 // "inline" — breaks the signature).
 //
-// The second argument accepts the legacy `expectedContentHash` string form
-// or a VerifyOptions object ({ payloadBytes, expectedContentHash }).
+// The second argument is a VerifyOptions object ({ payloadBytes,
+// expectedContentHash, acceptedSpecMajors }). Until 0.13.0 it could also be a
+// bare `expectedContentHash` string; that overload is gone (P-10), so the two
+// kernels take one options shape: write `{ expectedContentHash: hash }`.
 export async function verifyEnvelope(
   env: Envelope,
-  optionsOrContentHash?: string | VerifyOptions,
+  options?: VerifyOptions,
 ): Promise<VerificationResult> {
-  const opts: VerifyOptions =
-    typeof optionsOrContentHash === "string"
-      ? { expectedContentHash: optionsOrContentHash }
-      : (optionsOrContentHash ?? {});
+  if (typeof options === "string") {
+    throw new TypeError(
+      "verifyEnvelope: pass { expectedContentHash } rather than a bare string (0.13.0)",
+    );
+  }
+  const opts: VerifyOptions = options ?? {};
   // REFUSE an unknown option key rather than ignore it. `expected_content_hash`
   // — the Python kernel's spelling — previously fell through as `undefined`, so
   // the content bind silently never ran and the caller got a clean pass with no
   // errors at all. A check that quietly does not happen is worse than one that
   // fails: the caller believes they verified an artifact they never checked.
-  const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash"]);
+  const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash", "acceptedSpecMajors"]);
   const unknownOptions = Object.keys(opts).filter((k) => !KNOWN_VERIFY_OPTIONS.has(k));
   if (unknownOptions.length > 0) {
     throw new TypeError(
@@ -551,7 +573,7 @@ async function verifyEnvelopeChecked(
     };
   }
 
-  const specVersionOk = specVersionSupported(env.spec_version);
+  const specVersionOk = specVersionSupported(env.spec_version, opts.acceptedSpecMajors);
   if (!specVersionOk) errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
 
   // Skeleton field format (envelope-spec §2, proof#95): a present `signed_at`
@@ -625,7 +647,7 @@ async function verifyEnvelopeChecked(
   let signatureOk = false;
   try {
     const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
-    signatureOk = await ed25519Verify(env.signature, utf8(jcs(envelopeForSig)), env.public_key);
+    signatureOk = await ed25519Verify(utf8(jcs(envelopeForSig)), env.signature, env.public_key);
     if (!signatureOk) errors.push("Ed25519 signature verification failed");
   } catch (e) {
     errors.push(`signature verification error: ${stringifyErr(e)}`);

package/src/zip-reader.ts

@@ -0,0 +1,229 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Pure: bytes in, entries out. The caller turns them into the tree `case`
+ * splits.
+ */
+
+import { inflateRawSync } from "node:zlib";
+
+import { utf8Strict } from "./verifier.js";
+
+/** More entries than this refuse the archive: the walk's own bound on names. */
+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;
+/** A name nested deeper than this many folders refuses the archive. */
+export const MAX_ZIP_DEPTH = 32;
+
+const EOCD = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+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. */
+export class ZipReadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ZipReadError";
+  }
+}
+
+/**
+ * One file entry. `refused` is why the entry is reported and not read, or
+ * `null`; `data` is its bytes where it was read.
+ */
+export interface ZipEntry {
+  name: string;
+  refused: string | null;
+  data: Uint8Array | null;
+}
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function refusal(name: string): string | null {
+  if (name.startsWith("/")) return "an absolute name";
+  if (name.includes("\\")) return "a name with a backslash";
+  if (name.includes("\u0000")) return "a name with a NUL";
+  for (const segment of name.split("/")) {
+    if (segment === "" || segment === "." || segment === "..") {
+      return "a name with an empty, . or .. segment";
+    }
+  }
+  return null;
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  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`.
+ */
+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.
+  let eocd = -1;
+  const lowest = Math.max(0, n - 22 - 0xffff);
+  for (let at = n - 22; at >= lowest; at--) {
+    if (u32(at) === EOCD && at + 22 + u16(at + 20) === n) {
+      eocd = at;
+      break;
+    }
+  }
+  if (eocd < 0) throw new ZipReadError("is not a readable .zip archive");
+  const disk = u16(eocd + 4);
+  const cdDisk = u16(eocd + 6);
+  const hereCount = u16(eocd + 8);
+  const count = u16(eocd + 10);
+  const cdSize = u32(eocd + 12);
+  const cdOffset = u32(eocd + 16);
+  if (count === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff) {
+    throw new ZipReadError("is a ZIP64 archive, which case does not read");
+  }
+  if (disk !== 0 || cdDisk !== 0 || hereCount !== count) {
+    throw new ZipReadError("spans more than one disk, which case does not read");
+  }
+  if (count > MAX_ZIP_ENTRIES) {
+    throw new ZipReadError(`holds more than ${MAX_ZIP_ENTRIES} entries; refusing to read it`);
+  }
+  if (cdOffset + cdSize > eocd) throw new ZipReadError("is not a readable .zip archive");
+
+  const entries: ZipEntry[] = [];
+  const names = new Set<string>();
+  let total = 0;
+  let at = cdOffset;
+  for (let e = 0; e < count; e++) {
+    if (at + 46 > eocd || u32(at) !== CENTRAL) {
+      throw new ZipReadError("is not a readable .zip archive");
+    }
+    const madeBy = u16(at + 4);
+    const flags = u16(at + 8);
+    const method = u16(at + 10);
+    const crc = u32(at + 16);
+    const csize = u32(at + 20);
+    const usize = u32(at + 24);
+    const nameLen = u16(at + 28);
+    const extraLen = u16(at + 30);
+    const commentLen = u16(at + 32);
+    const external = u32(at + 38);
+    const localAt = u32(at + 42);
+    const rawName = data.subarray(at + 46, at + 46 + nameLen);
+    at += 46 + nameLen + extraLen + commentLen;
+    if (at > eocd) throw new ZipReadError("is not a readable .zip archive");
+    let name: string;
+    try {
+      name = utf8Strict(rawName);
+    } catch {
+      throw new ZipReadError(
+        "holds a name that is not valid UTF-8; rename it, then run case again",
+      );
+    }
+    if (names.has(name)) throw new ZipReadError(`holds ${name} twice`);
+    names.add(name);
+    if (name.endsWith("/")) continue;
+    if (name.split("/").length - 1 > MAX_ZIP_DEPTH) {
+      throw new ZipReadError(
+        `is nested more than ${MAX_ZIP_DEPTH} folders deep; refusing to read it`,
+      );
+    }
+    let refused = refusal(name);
+    if (refused === null && flags & 0x1) refused = "an encrypted entry";
+    if (
+      refused === null &&
+      madeBy >> 8 === UNIX &&
+      ((external >>> 16) & S_IFMT) === S_IFLNK
+    ) {
+      refused = "a symbolic link";
+    }
+    if (refused === null && method !== 0 && method !== 8) {
+      refused = "a compression method other than stored or deflate";
+    }
+    if (refused !== null) {
+      entries.push({ name, refused, data: null });
+      continue;
+    }
+
+    total += usize;
+    if (total > MAX_ZIP_BYTES) {
+      throw new ZipReadError(
+        `holds more than ${MAX_ZIP_BYTES} bytes uncompressed; refusing to read it`,
+      );
+    }
+    const unreadable = () => new ZipReadError(`holds ${name}, which cannot be read`);
+    if (localAt + 30 > cdOffset || u32(localAt) !== LOCAL) throw unreadable();
+    const localNameLen = u16(localAt + 26);
+    const localExtraLen = u16(localAt + 28);
+    if (!sameBytes(data.subarray(localAt + 30, localAt + 30 + localNameLen), rawName)) {
+      throw unreadable();
+    }
+    const start = localAt + 30 + localNameLen + localExtraLen;
+    if (start + csize > cdOffset) throw unreadable();
+    const packed = data.subarray(start, start + csize);
+    let body: Uint8Array;
+    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.
+      let result: { buffer: Buffer; engine: { bytesWritten: number } };
+      try {
+        result = inflateRawSync(packed, {
+          info: true,
+          maxOutputLength: usize + 1,
+        }) as unknown as { buffer: Buffer; engine: { bytesWritten: number } };
+      } catch {
+        throw unreadable();
+      }
+      if (result.engine.bytesWritten !== packed.length) throw unreadable();
+      body = new Uint8Array(result.buffer.buffer, result.buffer.byteOffset, result.buffer.length);
+    }
+    if (body.length !== usize || crc32(body) !== crc) throw unreadable();
+    entries.push({ name, refused: null, data: body.slice() });
+  }
+  return entries;
+}

package/vectors/README.md

@@ -107,17 +107,34 @@ happened, and the reason this file moved here.
 
 | Key | Meaning |
 |---|---|
-| `ruleVersion` | Bumped when a case's expectation changes **or a case is added**. An implementation asserts the version it was written against, so a table it does not understand fails loudly rather than passing vacuously. Currently **3**. |
-| `kernelEventClasses` | The four per-event outcome classes a verification result can carry, named so a case can be written as counts rather than as a hand-built bundle. |
+| `ruleVersion` | Bumped when a case's expectation changes **or a case is added**. An implementation asserts the version it was written against, so a table it does not understand fails loudly rather than passing vacuously. Currently **6**: `evidence-bundle.md` §5.4.5, where a record withheld by a readable declaration is counted apart and holds the pack at nothing. |
+| `kernelEventClasses` | The six per-event outcome classes a verification result can carry, named so a case can be written as counts rather than as a hand-built bundle. The two added at rule version 6, `withheldBound` and `withheldUnbound`, carry an `eventId` and a `payloadBindingOk`; `howToUse` says how an adapter builds them. |
 | `cases[].kernel` | The verification result to grade, as class counts. |
 | `cases[].logs` | The disclosure account: how many records the bundle presents, and how many disclosed usable bytes. |
 | `cases[].omissions` | Completeness notes — a checkpoint's signed `leaf_count` against the records the pack presents for it. |
-| `cases[].expect` | The verdict, the three counts, and how many causes the grade must carry. |
+| `cases[].expect` | The verdict, the three counts, how many causes the grade must carry, and, from rule version 6, `recordsWithheld` where a case pins it. |
 
 Nothing in a case names a transport. A directory read and a browser drop produce
 the same account and must produce the same verdict; a table that encoded one
 surface's mechanism would let the other one drift while staying green.
 
+## `case-file-index.json`
+
+How a reader compares a case file's index, `contents.json`, with the folder it
+sits at the root of (`evidence-bundle.md` §5.6.3, v1.20 A25). One pure function
+in both kernels, `readCaseFileIndex` in [`../src/case-file.ts`](../src/case-file.ts)
+and `read_case_file_index` in `src/sanning_proof/case_file.py`, asserted against
+this table by [`../test/case-file-index.test.ts`](../test/case-file-index.test.ts)
+**and by the Python kernel against the same bytes**, in
+`tests/test_case_file_index.py`. Each row gives the index bytes as hex (or
+`null` for a folder with no index) and every file in the folder with its
+SHA-256, and expects the index state, its `case_id` label and the findings in
+the pinned order. **No finding moves a verdict**: the index is never an input
+to the case reading, and a surface that took one from it would be trusting
+whoever assembled the drop. Written by
+`tools/gen-vectors/gen_case_file_index_vectors.py`, whose expectations are
+literals.
+
 ## `case-split.json`
 
 How `case` turns the folders it was handed into packs: the verify page's
@@ -130,8 +147,9 @@ because the page's code lives in the page. Two tables and the limits:
   given as bytes, or a folder filled with N empty files), the arguments, and
   the packs, the outside paths and the paths that are not regular files, or
   the refusal. The rows include the decision file unpacked, a symbolic link
-  under `logs/`, each side of the depth and entry limits, and names that are
-  not UTF-8.
+  under `logs/`, each side of the depth and entry limits, names that are not
+  UTF-8, and (v1.20, A25) a case file unpacked and as a `.zip` argument, with
+  the entries a reader lists and never reads and the archives it refuses.
 - `parses`: how `bundle.json` bytes become JSON through the reader `verify`
   and `case` share, including each side of the nesting limit.
 - `limits`: the walk depth (32), the entry count (50,000) and the JSON nesting