@sanning/proof 0.19.1 → 0.20.0

package/dist/cli.d.ts

@@ -6,9 +6,10 @@ interface Cli {
     err: (s: string) => void;
     fetchImpl?: typeof fetch;
 }
-/** 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. */
+/**
+ * Each control character in `text` as a visible escape (`\x1b`, `‮`).
+ * Every other character, a backslash included, is unchanged.
+ */
 export declare function escapeControl(text: string): string;
 export declare function runCli(argv: string[], stream: Cli): Promise<number>;
 export declare const MAX_FOLDER_BYTES: number;
@@ -48,7 +49,7 @@ export declare const MAX_WALK_ENTRIES = 50000;
 export declare const MAX_JSON_DEPTH = 512;
 /**
  * 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
+ * identical in both kernels, and the command exits 4 on it. `hint` is an
  * optional second line naming a way through.
  */
 export declare class CaseInputError extends Error {
@@ -64,11 +65,10 @@ export declare class CaseInputError extends Error {
 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,
- * 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.
+ * `bundle.json` bytes `readBundleBytes` will not read. `tooDeep` marks the one
+ * refusal that is not a parse error. `detail` is the parser's words, which
+ * differ by kernel, so only `verify` prints it; `duplicate` marks the one
+ * `detail` both kernels word identically.
  */
 export declare class BundleReadError extends Error {
     readonly tooDeep: boolean;
@@ -78,12 +78,12 @@ export declare class BundleReadError extends Error {
 }
 export declare const NOT_I_JSON = "is not I-JSON (RFC 7493)";
 /**
- * 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`,
- * refusing an object that repeats a member name (I-JSON, RFC 7493; proof#144).
- * Throws `BundleReadError`.
+ * How `verify` and `case` turn `bundle.json` bytes into JSON, in both kernels:
+ * UTF-8 with ill-formed sequences as U+FFFD and a BOM kept; nesting past
+ * MAX_JSON_DEPTH refused before parsing; then `JSON.parse`, refusing a repeated
+ * member name.
+ *
+ * @throws BundleReadError
  */
 export declare function readBundleBytes(bytes: Uint8Array): unknown;
 export interface SplitPack {
@@ -91,16 +91,15 @@ export interface SplitPack {
     bundlePath: string;
     bundleBytes: Uint8Array;
     /**
-     * `logs/<event_id>.json` bytes by event id. A `Map` and not an object: an
-     * event id is written by the audited party, and `obj["__proto__"] = bytes`
-     * replaces the prototype instead of storing the disclosure.
+     * `logs/<event_id>.json` bytes by event id. A `Map`, because an event id is
+     * written by the audited party and `obj["__proto__"]` would not store it.
      */
     content: Map<string, Uint8Array>;
     unaccounted: string[];
 }
 export interface SplitCase {
     packs: SplitPack[];
-    /** 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). */
+    /** Paths that belong to no pack, sorted. Never read as part of a pack; a regular one is hashed. */
     outside: string[];
     /** The part of `outside` that is not a regular file. Never followed, never opened. */
     notRegular: string[];
@@ -116,47 +115,35 @@ 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`.
-     */
+    /** `true` for a symbolic link, on disk or in a `.zip`. */
     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
- * tree. `read` opens a file; it is called for the files a pack owns and for
- * nothing else.
+ * The page's `splitCase` then `assemble` per pack, over the walk's tree. `read`
+ * is called only for the files a pack owns.
  */
 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.
+ * (evidence-bundle.md §5.6.6), or `null`. Read only where it is a regular file
+ * the split left outside every pack, and it stays outside. An unreadable file
+ * is no cache, never a refusal; one the whole-read total has no room for is
+ * pushed onto `refused` when given.
  */
 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.
+ * `verify`'s reader over one pack's `bundle.json`: the bundle, or an empty object and why
+ * it could not be read. One pack that cannot be read is that pack's problem, never the
+ * case's: every other pack is still read.
  */
+export declare function loadBundle(pack: SplitPack): [unknown, string | null];
+/** The refusal for a file `case` would read whole past the run's 1 GiB. 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.
- */
+/** Why `contents.json` reads as unreadable when it is over budget or cannot be read. */
 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. */
@@ -164,15 +151,13 @@ 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.
+ * A regular file's bytes, opened without following a link or blocking, then
+ * rechecked, so a swapped-in link or pipe is refused.
  *
- * `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.
+ * `budget` is the bytes a run may still hold whole (MAX_FOLDER_BYTES at the
+ * start). A file larger than that, or that grows past it, is refused before it
+ * is held. A `.zip` entry is already in memory under the archive cap and is not
+ * charged.
  */
 export declare function readFileEntry(entry: TreeEntry, key: string, budget?: {
     n: number;
@@ -184,36 +169,28 @@ export declare function readFileEntry(entry: TreeEntry, key: string, budget?: {
  */
 export declare function treeFromArguments(paths: readonly string[]): Promise<Map<string, TreeEntry>>;
 export declare const CASE_USAGE: string;
-/**
- * The case verdict's code, moved only by an on-chain half that was asked for:
- * a witness that does not match is a failure whatever the reading said, and an
- * on-chain half that could not be settled is never a clean 0.
- */
-export declare function caseExitCode(verdict: string, onChainVerdict: string): number;
 export interface CaseFileData {
     root: string;
     index: string;
     case_id: string | null;
     findings: {
+        kind: string;
         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.
+ * The index comparison, once per argument with a `contents.json` at its root
+ * (§5.6.3). Files under `packs/` and `report/` are hashed in pieces, sharing a
+ * 1 GiB total in path order; a file past what is left reports as too large,
+ * never as a match or absent. 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,
- * never 1, because 1 would name the evidence failed over a defect in this
- * command.
+ * `proof case <folder>... [--gateways <urls>] [--json]`. An unexpected
+ * exception exits 4, never 1: 1 would call the evidence failed over a defect in
+ * this 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<{