@sanning/proof 0.15.0 → 0.17.0

package/dist/case.js

@@ -243,7 +243,7 @@
  */
 import { DECLARATION_VERSION, DECLARATION_VERSION_V2, checkDeclaration, declarationClaims, packRecords, } from "./declaration.js";
 import { NOT_A_HANDOFF_FINDING, normalizedSigningKey, readHandoffs, recordIsMalformed, } from "./handoff.js";
-import { coSignaturesPresent, verifyEvidenceBundle } from "./evidence.js";
+import { coSignaturesPresent, resolveTraceEvents, verifyEvidenceBundle } from "./evidence.js";
 import { accountDisclosure, completenessNotes, gradePack, } from "./grading.js";
 import { renderWitnessTime } from "./witness-cache.js";
 // ---- The vocabulary ---------------------------------------------------------
@@ -717,6 +717,40 @@ export const CASE_EXCEPTION_KINDS = [
     RECORD_PROFILE_QUARANTINED,
     CASE_HOLDS_NO_PACKS,
 ];
+/**
+ * The status every record in every pack carries (evidence-bundle 5.5.4
+ * v1.35, A43, proof#204), as a closed set. A record is listed for each element
+ * of its pack's `body.events` as `packRecords` reads them, or, for a
+ * `sanning.evidence.export/v2` pack, of the events of the inline source
+ * bundle it wraps (`resolveTraceEvents`), and gets exactly one:
+ *
+ * - `read_clean`: the record went into the pile, no exception carries its
+ *   `packIndex` and `recordIndex`, and its pack's declaration check
+ *   names it by nothing (`declarationFindings` is empty). It says nothing
+ *   about its PACK: the pack's own grade and exceptions are on the pack, and a
+ *   surface MUST show that grade beside the status.
+ * - `read_flagged`: the record went into the pile, and at least one
+ *   exception carries its `packIndex` and `recordIndex`, or its pack's
+ *   declaration check names its `eventId` by a deviation or a content
+ *   finding (`declarationFindings` is not empty; under an `eventId` the
+ *   pack carries twice, every record with that id). An exception about the
+ *   pack alone flags no record.
+ * - `not_read`: the record never went into the pile. `reason` is the kind
+ *   of the exception that says why, on the record
+ *   (`record_profile_quarantined`, `record_envelope_does_not_verify`,
+ *   `record_bytes_withheld`, `record_bytes_unreadable`) or on its pack
+ *   (`pack_key_unreadable`, `pack_does_not_verify`,
+ *   `pack_body_type_unknown`, `pack_grade_not_verified` where the body
+ *   could not be read or the verifier graded a different number of records).
+ *   An export's wrapped records carry the reason of the exception their pack
+ *   actually got: `pack_body_type_unknown` where its wrapper holds, and
+ *   otherwise `pack_key_unreadable`, `pack_does_not_verify` or
+ *   `pack_grade_not_verified`.
+ *
+ * Before A43 the reading listed only the records it read, so a surface had to
+ * work out which records were missing, and why, by a rule of its own.
+ */
+export const CASE_RECORD_STATUSES = ["read_clean", "read_flagged", "not_read"];
 /**
  * What each exception kind contributes to the case verdict. It is a TABLE and
  * not a chain of branches, so "which exceptions move the verdict" is one thing
@@ -970,6 +1004,20 @@ export async function readCase(packs) {
     // human to read; a join rebuilt by splitting one is a join on a value a
     // holder can put a separator in.
     const provenance = [];
+    // Every record of every pack, in pack order and bundle order (A43): where it
+    // went into the pile, its place there (`heldAt`), and where it did not, the
+    // kind of the exception that says why. Nothing is listed only where the pack
+    // body carries no `events` array, and that pack's own exception says why.
+    const slots = [];
+    const unread = (position, packRef, listed, reason) => {
+        listed.forEach((record, recordIndex) => slots.push({ position, packRef, recordIndex, eventId: record.eventId, heldAt: null, reason }));
+    };
+    // The kinds each pack's declaration check names each record by, keyed by the
+    // pack's POSITION and then by `eventId` (A43). The check names a record by
+    // `event_id` alone, so under an id the pack carries twice every record with
+    // that id is named: failing closed, rather than guessing which of the two the
+    // check meant.
+    const declarationFindings = new Map();
     // Keyed by the pack's POSITION and never by its `ref`. `ref` is the reader's
     // own name for a pack, and nothing stops two packs in one archive carrying
     // the same one: keyed by ref, the second pack's claims silently replaced the
@@ -1020,9 +1068,11 @@ export async function readCase(packs) {
             // pack whose signer is UNKNOWN, and not a pack nobody signed. Checked
             // BEFORE verification, because the two bundle verifiers disagree on some
             // of these spellings (proof#135) and the reading must not.
-            note(PACK_KEY_UNREADABLE, { packRef: pack.ref });
+            note(PACK_KEY_UNREADABLE, { packRef: pack.ref, packIndex: position });
             unattributed += 1;
+            unread(position, pack.ref, listedRecords(pack.bundle, pack.content), PACK_KEY_UNREADABLE);
             packReadings.push({
+                index: position,
                 ref: pack.ref,
                 signingKey: null,
                 grade: null,
@@ -1049,9 +1099,11 @@ export async function readCase(packs) {
             : verified;
         // WHOSE PACK IS IT. The wrapper, and only the wrapper.
         if (!wrapperHolds(verified)) {
-            note(PACK_DOES_NOT_VERIFY, { packRef: pack.ref });
+            note(PACK_DOES_NOT_VERIFY, { packRef: pack.ref, packIndex: position });
             unattributed += 1;
+            unread(position, pack.ref, listedRecords(pack.bundle, pack.content), PACK_DOES_NOT_VERIFY);
             packReadings.push({
+                index: position,
                 ref: pack.ref,
                 signingKey: holder,
                 grade: null,
@@ -1067,7 +1119,7 @@ export async function readCase(packs) {
             // the case reading names it rather than moving anything on its account.
             caseNotes.push({
                 position,
-                note: { kind: CO_SIGNATURES_PRESENT, packRef: pack.ref },
+                note: { kind: CO_SIGNATURES_PRESENT, packRef: pack.ref, packIndex: position },
             });
         }
         const bodyType = bodyTypeOf(pack.bundle);
@@ -1131,6 +1183,7 @@ export async function readCase(packs) {
             }
             note(PACK_GRADE_NOT_VERIFIED, {
                 packRef: pack.ref,
+                packIndex: position,
                 status: grade,
                 causes,
                 reasons,
@@ -1139,11 +1192,13 @@ export async function readCase(packs) {
         if (verified.status === "failed" && signed.status !== "failed") {
             note(PACK_BUNDLE_CONTENT_DEPENDENT, {
                 packRef: pack.ref,
+                packIndex: position,
                 reasons: onlyIn(bundleReasons(verified), bundleReasons(signed)),
             });
         }
         const recordsWithheld = full !== null ? full.recordsWithheld : 0;
         packReadings.push({
+            index: position,
             ref: pack.ref,
             signingKey: holder,
             grade,
@@ -1156,13 +1211,20 @@ export async function readCase(packs) {
             // them, so a clean verdict never hides them.
             caseNotes.push({
                 position,
-                note: { kind: CONTENT_WITHHELD_BY_DECLARATION, packRef: pack.ref, count: recordsWithheld },
+                note: {
+                    kind: CONTENT_WITHHELD_BY_DECLARATION,
+                    packRef: pack.ref,
+                    packIndex: position,
+                    count: recordsWithheld,
+                },
             });
         }
         // The body is one the verifier could not read, so it graded no record, and
         // nothing below has a grading to read. Named above.
-        if (signed.status === "malformed")
+        if (signed.status === "malformed") {
+            unread(position, pack.ref, listedRecords(pack.bundle, pack.content), PACK_GRADE_NOT_VERIFIED);
             continue;
+        }
         if (!knownBody) {
             // `sanning.evidence.export/v2` lands here, and it is NOT unwrapped: its
             // records sit under `body.source_bundle`, and reading them is a change to
@@ -1170,20 +1232,35 @@ export async function readCase(packs) {
             // a repair (evidence-bundle.md 5.5.1 step 1 says so too). What this exit
             // costs is that pack's RECORDS, and it is named every time. It no longer
             // costs the pack's KEY: that was read above.
-            note(PACK_BODY_TYPE_UNKNOWN, { packRef: pack.ref });
+            note(PACK_BODY_TYPE_UNKNOWN, { packRef: pack.ref, packIndex: position });
+            // Listed, and not read: the records a `sanning.evidence.export/v2` wraps
+            // are listed from its inline source bundle, so a reading never says "0
+            // not read" of a pack that holds records (A43).
+            unread(position, pack.ref, listedRecords(pack.bundle, pack.content), PACK_BODY_TYPE_UNKNOWN);
             continue;
         }
         // Graded above (`malformed` where the verifier called it `verified`), and
         // none of its records are read.
-        if (ungraded)
+        if (ungraded) {
+            unread(position, pack.ref, records, PACK_GRADE_NOT_VERIFIED);
             continue;
+        }
         if (records.length === 0) {
-            note(PACK_HOLDS_NO_RECORDS, { packRef: pack.ref });
+            note(PACK_HOLDS_NO_RECORDS, { packRef: pack.ref, packIndex: position });
             continue;
         }
         const checked = check;
         claimsByPack.set(position, declarationClaims(pack.bundle));
         rolesByPack.set(position, new Map((checked.roles ?? []).map((r) => [r.eventId, r.role])));
+        const namedByCheck = new Map();
+        for (const finding of [...checked.deviations, ...checked.contentFindings]) {
+            if (finding.eventId === undefined)
+                continue;
+            const kinds = namedByCheck.get(finding.eventId) ?? [];
+            kinds.push(finding.kind);
+            namedByCheck.set(finding.eventId, kinds);
+        }
+        declarationFindings.set(position, namedByCheck);
         if (checked.contentFindings.length > 0) {
             // BESIDE the deviation exception and never instead of it: a pack can do
             // both, over different records, and the two say different things. This
@@ -1191,12 +1268,14 @@ export async function readCase(packs) {
             // it turns on (proof#147).
             note(PACK_DECLARATION_CONTENT_DEPENDENT, {
                 packRef: pack.ref,
+                packIndex: position,
                 count: checked.contentFindings.length,
             });
         }
         if (checked.verdict === "failed") {
             note(PACK_DECLARATION_DEVIATES, {
                 packRef: pack.ref,
+                packIndex: position,
                 count: checked.deviations.length,
             });
         }
@@ -1219,7 +1298,7 @@ export async function readCase(packs) {
             // cannot read", which `gradePack` already carries to `incomplete`. The
             // same posture here, for the same reason: the field has no accept-set and
             // the holder writes it.
-            note(PACK_DECLARATION_UNREADABLE, { packRef: pack.ref });
+            note(PACK_DECLARATION_UNREADABLE, { packRef: pack.ref, packIndex: position });
         }
         else {
             // WHAT IT CONTRIBUTES TURNS ON THE WHOLE READING (5.5.1 step 2 v1.20,
@@ -1242,30 +1321,34 @@ export async function readCase(packs) {
             const record = records[index];
             const graded = verified.events[index];
             const bare = signed.events[index];
+            // Which pack and which record, by position: the two names that are
+            // unique in the reading whatever the reader called the pack and whatever
+            // the holder wrote as `event_id` (A43).
+            const at = {
+                packRef: pack.ref,
+                packIndex: position,
+                eventId: record.eventId,
+                recordIndex: index,
+            };
+            // Not read: listed with the kind of the exception that says why.
+            const skip = (kind, fields = {}) => {
+                note(kind, { ...at, ...fields });
+                slots.push({ position, packRef: pack.ref, recordIndex: index, eventId: record.eventId, heldAt: null, reason: kind });
+            };
             if (underQuarantine(recordSpecVersion(pack.bundle, index))) {
-                note(RECORD_PROFILE_QUARANTINED, { packRef: pack.ref, eventId: record.eventId });
+                skip(RECORD_PROFILE_QUARANTINED);
                 continue;
             }
             if (!graded.envelopeOk) {
-                note(RECORD_ENVELOPE_DOES_NOT_VERIFY, {
-                    packRef: pack.ref,
-                    eventId: record.eventId,
-                    reasons: [...graded.errors],
-                });
+                skip(RECORD_ENVELOPE_DOES_NOT_VERIFY, { reasons: [...graded.errors] });
                 continue;
             }
             if (!record.bytesSupplied) {
-                note(RECORD_BYTES_WITHHELD, {
-                    packRef: pack.ref,
-                    eventId: record.eventId,
-                });
+                skip(RECORD_BYTES_WITHHELD);
                 continue;
             }
             if (record.record === null) {
-                note(RECORD_BYTES_UNREADABLE, {
-                    packRef: pack.ref,
-                    eventId: record.eventId,
-                });
+                skip(RECORD_BYTES_UNREADABLE);
                 continue;
             }
             // Named, and the record stays in the pile (see the kinds). A mismatch
@@ -1273,15 +1356,13 @@ export async function readCase(packs) {
             // with the side map is `incomplete` (proof#159).
             if (bare.contentOk === false) {
                 note(RECORD_CONTENT_MISMATCH, {
-                    packRef: pack.ref,
-                    eventId: record.eventId,
+                    ...at,
                     reasons: [...bare.errors],
                 });
             }
             else if (graded.contentOk === false) {
                 note(RECORD_CONTENT_DEPENDENT, {
-                    packRef: pack.ref,
-                    eventId: record.eventId,
+                    ...at,
                     reasons: onlyIn(graded.errors, bare.errors),
                 });
             }
@@ -1290,17 +1371,24 @@ export async function readCase(packs) {
             if (!(bare.inclusionOk && bare.checkpointBound) ||
                 (!bare.ok && bare.contentOk !== false)) {
                 note(RECORD_DOES_NOT_VERIFY_IN_ITS_PACK, {
-                    packRef: pack.ref,
-                    eventId: record.eventId,
+                    ...at,
                     reasons: [...bare.errors],
                 });
             }
+            slots.push({
+                position,
+                packRef: pack.ref,
+                recordIndex: index,
+                eventId: record.eventId,
+                heldAt: held.length,
+                reason: null,
+            });
             held.push({
                 publicKey: record.publicKey,
                 record: record.record,
                 ref: `${pack.ref}/${record.eventId}`,
             });
-            provenance.push({ position, packRef: pack.ref, eventId: record.eventId });
+            provenance.push({ position, packRef: pack.ref, eventId: record.eventId, recordIndex: index });
         }
     }
     // Step 3. ONE pile, no partition. This is the line anchor#198 turns on and
@@ -1309,20 +1397,12 @@ export async function readCase(packs) {
     // read exactly as a pair inside one.
     const readings = readHandoffs(held);
     // Step 4.
-    const records = [];
     let handoffRecords = 0;
     for (let index = 0; index < readings.length; index += 1) {
         const reading = readings[index];
-        const { position, packRef, eventId } = provenance[index];
-        records.push({
-            packRef,
-            eventId,
-            verdict: reading.verdict,
-            findings: [...reading.findings],
-            failedChecks: [...reading.failedChecks],
-            counterparts: [...reading.candidates],
-            role: rolesByPack.get(position)?.get(eventId) ?? null,
-        });
+        const { position, packRef, eventId, recordIndex } = provenance[index];
+        // The record this reading is about, by position (A43).
+        const at = { packRef, packIndex: position, eventId, recordIndex };
         // proof#137's door, named. Read from the ONE reader of the declaration
         // (`declarationClaims`), never from a second parse here. Only a READABLE
         // declaration can make a record unclaimed: where the claim itself is absent
@@ -1343,7 +1423,7 @@ export async function readCase(packs) {
             claims.readable &&
             claims.version === DECLARATION_VERSION &&
             !claims.claimedSides.includes(eventId)) {
-            note(RECORD_UNCLAIMED, { packRef, eventId });
+            note(RECORD_UNCLAIMED, at);
         }
         if (reading.findings.includes(NOT_A_HANDOFF_FINDING)) {
             // 4.1 (v1.9, A14): information, not absence. A record 4.1 does not govern
@@ -1360,10 +1440,10 @@ export async function readCase(packs) {
             // counterpart, ambiguity and `failedChecks` reporting below all keep
             // running over it.
             if (recordIsMalformed(held[index])) {
-                note(RECORD_MALFORMED, { packRef, eventId });
+                note(RECORD_MALFORMED, at);
                 continue;
             }
-            note(COUNTERPART_MALFORMED, { packRef, eventId });
+            note(COUNTERPART_MALFORMED, at);
         }
         if (reading.findings.includes(COUNTERPART_ABSENT)) {
             // `held`, `provenance` and `readings` are three views of one list in one
@@ -1402,14 +1482,13 @@ export async function readCase(packs) {
                         ? COUNTERPART_ABSENT_SIGNER_UNKNOWN
                         : COUNTERPART_ABSENT;
             note(kind, setAside > 0
-                ? { packRef, eventId, counterpartyKey: named, count: setAside }
-                : { packRef, eventId, counterpartyKey: named });
+                ? { ...at, counterpartyKey: named, count: setAside }
+                : { ...at, counterpartyKey: named });
             continue;
         }
         if (reading.findings.includes(COUNTERPART_AMBIGUOUS)) {
             note(COUNTERPART_AMBIGUOUS, {
-                packRef,
-                eventId,
+                ...at,
                 count: reading.candidateReadings.filter((c) => c.accountedFor === null).length,
             });
         }
@@ -1422,8 +1501,7 @@ export async function readCase(packs) {
         // check whatever the aggregate word is.
         if (reading.failedChecks.length > 0) {
             note(PAIR_FAILED, {
-                packRef,
-                eventId,
+                ...at,
                 failedChecks: [...reading.failedChecks],
             });
         }
@@ -1438,11 +1516,18 @@ export async function readCase(packs) {
     // none.
     for (const slot of undeclaredSlots) {
         if (handoffRecords > 0) {
-            exceptions[slot.exceptionAt] = { kind: PACK_UNDECLARED, packRef: slot.ref };
+            exceptions[slot.exceptionAt] = {
+                kind: PACK_UNDECLARED,
+                packRef: slot.ref,
+                packIndex: slot.position,
+            };
             contributions[slot.contributionAt] = [slot.ref, EXCEPTION_VERDICT[PACK_UNDECLARED]];
         }
         else {
-            caseNotes.push({ position: slot.position, note: { kind: PACK_UNDECLARED, packRef: slot.ref } });
+            caseNotes.push({
+                position: slot.position,
+                note: { kind: PACK_UNDECLARED, packRef: slot.ref, packIndex: slot.position },
+            });
         }
     }
     const named = exceptions.filter((e) => e !== null);
@@ -1453,6 +1538,50 @@ export async function readCase(packs) {
         .map((n, i) => ({ ...n, i }))
         .sort((a, b) => a.position - b.position || a.i - b.i)
         .map((n) => n.note);
+    // Every record of every pack, with its status (A43). A record that went
+    // into the pile is `read_flagged` where any exception names it by pack and
+    // record position, or its pack's declaration check names it (by deviation
+    // or by content finding), and `read_clean` where neither does; every other
+    // record is `not_read`, with the kind of the exception that says why.
+    const flagged = new Set(named
+        .filter((e) => e.packIndex !== undefined && e.recordIndex !== undefined)
+        .map((e) => `${e.packIndex}:${e.recordIndex}`));
+    const records = slots.map((slot) => {
+        const base = {
+            packRef: slot.packRef,
+            packIndex: slot.position,
+            eventId: slot.eventId,
+            recordIndex: slot.recordIndex,
+        };
+        const byCheck = [...(declarationFindings.get(slot.position)?.get(slot.eventId) ?? [])];
+        if (slot.heldAt === null) {
+            return {
+                ...base,
+                status: "not_read",
+                reason: slot.reason,
+                declarationFindings: byCheck,
+                verdict: null,
+                findings: [],
+                failedChecks: [],
+                counterparts: [],
+                role: null,
+            };
+        }
+        const reading = readings[slot.heldAt];
+        return {
+            ...base,
+            status: flagged.has(`${slot.position}:${slot.recordIndex}`) || byCheck.length > 0
+                ? "read_flagged"
+                : "read_clean",
+            reason: null,
+            declarationFindings: byCheck,
+            verdict: reading.verdict,
+            findings: [...reading.findings],
+            failedChecks: [...reading.failedChecks],
+            counterparts: [...reading.candidates],
+            role: rolesByPack.get(slot.position)?.get(slot.eventId) ?? null,
+        };
+    });
     return {
         verdict: verdictOf(named, contributed),
         exceptions: named,
@@ -1464,6 +1593,19 @@ export async function readCase(packs) {
         packs: packReadings,
     };
 }
+/**
+ * The records a pack LISTS where this reader does not read them one by one
+ * (A43): the events `resolveTraceEvents` presents, which unwraps a
+ * `sanning.evidence.export/v2` to its inline source bundle, and otherwise
+ * `body.events` as `packRecords` reads it. Listing is not reading: every record
+ * listed here is `not_read`.
+ */
+function listedRecords(bundle, content) {
+    const events = resolveTraceEvents(bundle);
+    if (events === undefined)
+        return packRecords(bundle, content);
+    return packRecords({ body: { events } }, content);
+}
 /**
  * `body.declaration.declaration_version` where it is one this reader knows,
  * and `null` otherwise.

package/dist/cli.d.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { open } from "node:fs/promises";
+import type { OfferedFile, SkippedFile } from "./file-match.js";
 interface Cli {
     out: (s: string) => void;
     err: (s: string) => void;
@@ -9,6 +11,30 @@ interface Cli {
  * backslash included, so a line with none is printed as it was. */
 export declare function escapeControl(text: string): string;
 export declare function runCli(argv: string[], stream: Cli): Promise<number>;
+export declare const MAX_FOLDER_BYTES: number;
+export declare const TOO_LARGE = "too_large";
+export declare function hashFile(path: string, follow: boolean, budget?: {
+    n: number;
+}): Promise<string | null>;
+export declare function readOfferedFiles(paths: readonly string[], cap?: number): Promise<{
+    offered: OfferedFile[];
+    skipped: SkippedFile[];
+} | string>;
+export interface LoadedLogs {
+    content: Map<string, Uint8Array | string>;
+    suppliedIds: string[];
+    notes: string[];
+}
+export declare const MAX_LOGS_BYTES: number;
+export declare class LogsTooLarge extends Error {
+}
+export declare function readLogFile(path: string, budget: {
+    n: number;
+}, opener?: typeof open): Promise<Uint8Array>;
+export declare function loadLogsDirectory(dirPath: string, io: Cli, limits?: {
+    bytes: number;
+    entries: number;
+}): Promise<LoadedLogs | undefined>;
 /** The error text for an input with no pack in it, word for word the page's. */
 export declare const NO_BUNDLE = "No bundle.json found. An evidence pack contains bundle.json plus logs/.";
 /** A directory nested deeper than this below an argument refuses the input. */
@@ -29,6 +55,14 @@ export declare class CaseInputError extends Error {
     readonly hint: string | null;
     constructor(message: string, hint?: string | null);
 }
+/**
+ * A file `case` reads whole that does not fit in what is left of the run's
+ * 1 GiB. Always a `CaseInputError`; the type lets a caller that can carry on
+ * without the file (`contents.json`, `witness-cache.json`) tell this refusal
+ * from an unreadable file.
+ */
+export declare class WholeReadRefused extends CaseInputError {
+}
 /**
  * `bundle.json` bytes that `readBundleBytes` will not read. `tooDeep` separates
  * the one refusal that is not a parse error; `detail` is the parser's own words,
@@ -66,7 +100,7 @@ export interface SplitPack {
 }
 export interface SplitCase {
     packs: SplitPack[];
-    /** Paths that belong to no pack, sorted. Never opened. */
+    /** Paths that belong to no pack, sorted. Never read as part of a pack; a regular one is hashed, and nothing else is read of it (A41). */
     outside: string[];
     /** The part of `outside` that is not a regular file. Never followed, never opened. */
     notRegular: string[];
@@ -82,6 +116,13 @@ export interface TreeEntry {
     regular: boolean;
     /** The bytes of an entry read out of a case-file `.zip`. */
     data?: Uint8Array | null;
+    /**
+     * `true` for a symbolic link, on disk or an entry of a `.zip`: the one reason
+     * a link is skipped under, here and under `--files`.
+     */
+    link?: boolean;
+    /** The `.zip` reader's own words for an entry it refused (not a link). */
+    refused?: string;
 }
 /**
  * The page's `splitCase` followed by its `assemble` per pack, over the walk's
@@ -89,14 +130,53 @@ export interface TreeEntry {
  * nothing else.
  */
 export declare function splitCase(tree: Map<string, TreeEntry>, read: (entry: TreeEntry, key: string) => Promise<Uint8Array>): Promise<SplitCase>;
+/**
+ * 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 read here, for its contents, and hashed with the other
+ * outside files (A41). It is read as a cache only where it is a regular file the split left outside every pack, so a file under another
+ * pack's `logs/` is that pack's, and a link is never followed. A file that
+ * cannot be read is no cache, never a refusal of the drop. One the run's
+ * whole-read total has no room for is pushed onto `refused` when it is given,
+ * so the output says so.
+ */
+export declare function witnessCacheBytes(tree: Map<string, TreeEntry>, split: SplitCase, pack: SplitPack, budget?: {
+    n: number;
+}, refused?: string[]): Promise<Uint8Array | null>;
 /** `verify`'s reader, with the refusal named by the pack's path. */
 export declare function loadBundle(pack: SplitPack): unknown;
+/**
+ * The refusal for a file `case` would hold whole that does not fit in what is
+ * left of the 1 GiB a run reads whole. The same words in both kernels.
+ */
+export declare const wholeReadRefusal: (key: string) => string;
+/**
+ * Why `contents.json` reads as an unreadable index when the run's whole-read
+ * total has no room for it, and when it cannot be read. The same words in both
+ * kernels.
+ */
+export declare const INDEX_OVER_BUDGET = "it would take case past the 1 GiB it reads whole in one run, so it was not read";
+export declare const INDEX_NOT_READ = "it could not be read";
+/** The note for a `witness-cache.json` the whole-read total had no room for. */
+export declare const witnessCacheRefusedNote: (path: string) => string;
+/** The refusal for an archive file larger than MAX_ZIP_ARCHIVE_BYTES. */
+export declare const zipFileRefusal: (arg: string) => string;
 /**
  * A regular file's bytes. Opened without following a link and without
  * blocking, then checked again, so a file swapped for a link or a pipe after
  * the walk listed it is refused rather than followed or waited on.
+ *
+ * `budget` is the bytes a run may still hold whole from files on disk
+ * (MAX_FOLDER_BYTES at the start). A file larger than what is left, or that
+ * grows past it while it is read, is refused before it is held, so a file of a
+ * terabyte under a pack's own names cannot exhaust memory. A `.zip` entry is
+ * already in memory, inside the archive's own cap, and is not charged.
  */
-export declare function readFileEntry(entry: TreeEntry, key: string): Promise<Uint8Array>;
+export declare function readFileEntry(entry: TreeEntry, key: string, budget?: {
+    n: number;
+}): Promise<Uint8Array>;
 /**
  * Every name under the directories named, keyed `<name>/<path inside>`. Each
  * argument must be a directory, and not a link to one. A `.zip` is refused
@@ -110,6 +190,25 @@ export declare const CASE_USAGE: string;
  * on-chain half that could not be settled is never a clean 0.
  */
 export declare function caseExitCode(verdict: string, onChainVerdict: string): number;
+export interface CaseFileData {
+    root: string;
+    index: string;
+    case_id: string | null;
+    findings: {
+        rendered: string;
+    }[];
+}
+/**
+ * The index comparison, once per argument (5.6.3): each folder or case file
+ * whose root holds `contents.json`. Every file under `packs/` and `report/` is
+ * hashed for it, in pieces, as bytes, and nothing is parsed but the index. The
+ * files share one total of 1 GiB across the run, charged in path order; a file
+ * larger than what is left is reported as too large to hash, never as a match
+ * and never as absent. It is never an input to the reading.
+ */
+export declare function caseFileReadings(tree: Map<string, TreeEntry>, whole?: {
+    n: number;
+}, cap?: number): Promise<CaseFileData[]>;
 /**
  * `proof case <folder>... [--gateways <urls>] [--json]`. Every path out of the
  * command is an exit code from the table: an exception nobody expected exits 2,
@@ -117,4 +216,8 @@ export declare function caseExitCode(verdict: string, onChainVerdict: string): n
  * command.
  */
 export declare function runCase(argv: readonly string[], stream: Cli): Promise<number>;
+export declare function looseFiles(tree: Map<string, TreeEntry>, split: SplitCase, cap?: number): Promise<{
+    offered: OfferedFile[];
+    skipped: SkippedFile[];
+}>;
 export {};