@sanning/proof 0.12.0 → 0.14.0

package/dist/cli.d.ts

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
+import { type WitnessLine } from "./case.js";
+import { type CachedWitnessTime, type WitnessTimeAnswer, type WitnessTimeCheck } from "./witness-cache.js";
 interface Cli {
     out: (s: string) => void;
     err: (s: string) => void;
     fetchImpl?: typeof fetch;
 }
-export declare function runCli(argv: string[], io: Cli): Promise<number>;
+/** Each control character in `text` as a visible escape: `\x1b` for ESC,
+ * `\u202e` for RIGHT-TO-LEFT OVERRIDE. Every other character is unchanged, a
+ * backslash included, so a line with none is printed as it was. */
+export declare function escapeControl(text: string): string;
+export declare function runCli(argv: string[], stream: Cli): Promise<number>;
 /** 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. */
@@ -28,18 +34,23 @@ export declare class CaseInputError extends Error {
 /**
  * `bundle.json` bytes that `readBundleBytes` will not read. `tooDeep` separates
  * the one refusal that is not a parse error; `detail` is the parser's own words,
- * which differ by kernel and are printed by `verify` only.
+ * which differ by kernel and are printed by `verify` only. `duplicate` marks the
+ * one parse refusal whose `detail` is kernel wording, identical in both kernels
+ * (`duplicate key "<name>"`, proof#144), so both commands print it.
  */
 export declare class BundleReadError extends Error {
     readonly tooDeep: boolean;
     readonly detail: string;
-    constructor(tooDeep: boolean, detail: string);
+    readonly duplicate: boolean;
+    constructor(tooDeep: boolean, detail: string, duplicate?: boolean);
 }
+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`.
+ * MAX_JSON_DEPTH is refused before any parser walks into it; then `JSON.parse`,
+ * refusing an object that repeats a member name (I-JSON, RFC 7493; proof#144).
  * Throws `BundleReadError`.
  */
 export declare function readBundleBytes(bytes: Uint8Array): unknown;
@@ -64,9 +75,15 @@ export interface SplitCase {
 }
 /** One name the walk found that is not a directory. */
 export interface TreeEntry {
+    /** Where it sits on disk. Empty for an entry read out of a case-file `.zip`. */
     fsPath: string;
-    /** `true` for a regular file; `false` for a link or anything else. */
+    /**
+     * `true` for a regular file; `false` for a link or anything else, including a
+     * `.zip` entry the reader refused.
+     */
     regular: boolean;
+    /** The bytes of an entry read out of a case-file `.zip`. */
+    data?: Uint8Array | null;
 }
 /**
  * The page's `splitCase` followed by its `assemble` per pack, over the walk's
@@ -88,8 +105,47 @@ export declare function readFileEntry(entry: TreeEntry, key: string): Promise<Ui
  * with the way through.
  */
 export declare function treeFromArguments(paths: readonly string[]): Promise<Map<string, TreeEntry>>;
-export declare const CASE_EXIT_CODES: Readonly<Record<string, number>>;
-export declare const CASE_USAGE = "sanning-proof case -- one verdict over several evidence packs, offline\n\n  sanning-proof case <folder>... [--gateways <url,url>] [--json]\n\n  <folder>    a pack folder (bundle.json plus logs/), or a folder that holds\n              several packs, such as an unpacked decision file. case reads\n              folders only: given a .zip, it exits 2 and says to unzip it\n              first (for example, unzip file.zip -d case/) and pass the folder.\n              Packs are found by the verify page's splitting rule: every\n              bundle.json is a pack, a file belongs to the deepest pack whose\n              bundle.json or logs/ it sits in, and every other file is listed\n              as outside every pack and never opened. A .zip inside a folder is\n              a file like any other. A symbolic link is never followed: it is\n              listed as outside and not read, even under a pack's logs/.\n              Several folders are read as one folder holding them, each under\n              its own name. A folder nested more than 32 levels deep, more than\n              50000 files and folders in all, or a name that is not valid UTF-8\n              exits 2.\n  --gateways  comma-separated gateway URLs. Each pack's witnesses are then\n              re-fetched on chain, pack by pack, and reported beside the case\n              reading. Without it the on-chain half is NOT checked, and the\n              output says so.\n  --json      the full reading as JSON: the verdict, every exception with its\n              rendered line, every record, every contribution, the packs, the\n              files outside them, and the on-chain half.\n\nEach pack's bundle.json is read as verify reads it, so the two commands\nclassify one bundle the same way.\n\nWhat a case reading establishes: every pack is verified offline by this\nkernel; every record every pack supplied is read, in one pile, under the\nhand-off rules of envelope-spec section 4.1; a hand-off record with no\ncounterpart among the case's records is always named, and when a pack signed by\nthe key it names is in the case, the reading says that pack holds none, unless\nevery candidate it had was accounted for by another record (A20), which reads\nas no counterpart and names no pack.\n\nWhat it does not establish: that the case is complete (a party can decline to\nhand over a pack); that a party which presented no pack under the named key\nrecorded nothing; that two organizations are independent of each other; or\nthat any witness was re-fetched on chain, which the reading never does.\n\nExit codes: 0 verified \u00B7 1 failed \u00B7 2 malformed, usage, an input that cannot\nbe read as a case, or an unexpected error in this command \u00B7 3 incomplete or\npartial (undetermined, not failed) \u00B7 4 mixed (more than one outcome: read the\nexceptions). With --gateways, a witness that does not match on chain exits 1,\nand an on-chain half that could not be settled turns 0 into 3.";
+export declare const CASE_USAGE: string;
+interface OnChainRow {
+    ref: string;
+    witnesses: number;
+    confirmed: number;
+    mismatched: number;
+    unreachable: number;
+    not_checked: number;
+    /** Present only where the pack caches a witness time (5.6.6, v1.25, A30). */
+    witness_times?: WitnessTimeRow[];
+}
+interface WitnessTimeRow {
+    stamp_ref: string;
+    cached: {
+        block_height: number;
+        block_time: number;
+    };
+    outcome: WitnessTimeCheck["outcome"];
+    answers: {
+        gateway: string;
+        outcome: WitnessTimeAnswer["outcome"];
+        block_height: number | null;
+        block_time: number | null;
+    }[];
+}
+interface OnChainHalf {
+    /** Present only where a lookup ran: each gateway that answered, in the order given. */
+    answered?: string[];
+    checked: boolean;
+    gateways: string[];
+    packs: OnChainRow[];
+    verdict: "not_checked" | "confirmed" | "failed" | "undetermined";
+}
+/**
+ * `cached` is every witness time the packs cache (5.6.6, v1.25, A30). Where no
+ * lookup ran, each is printed labelled not checked. Where one ran, each time
+ * the public record matched is printed as the record's, each time no lookup
+ * settled stays labelled not checked, and a time the record contradicts is the
+ * reason the line reads `differs`.
+ */
+export declare function witnessLine(onChain: OnChainHalf, cached?: readonly CachedWitnessTime[]): WitnessLine;
 /**
  * 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
@@ -102,5 +158,5 @@ export declare function caseExitCode(verdict: string, onChainVerdict: string): n
  * never 1, because 1 would name the evidence failed over a defect in this
  * command.
  */
-export declare function runCase(argv: readonly string[], io: Cli): Promise<number>;
+export declare function runCase(argv: readonly string[], stream: Cli): Promise<number>;
 export {};