@sanning/proof 0.19.0 → 0.20.0

package/dist/witness-cache.d.ts

@@ -1,26 +1,18 @@
 /**
- * The last second a block time can name and still be printed the same way by
- * both kernels: 9999-12-31T23:59:59Z. A larger value is a cache entry this
- * reader cannot print, and reads as none.
+ * The largest printable block time, 9999-12-31T23:59:59Z. A larger value reads
+ * as no entry.
  */
 export declare const MAX_BLOCK_TIME = 253402300799;
-/** The file's name, beside `bundle.json` in the pack's folder (5.6.1). */
+/** The file's name, beside `bundle.json` (§5.6.1). */
 export declare const WITNESS_CACHE_NAME = "witness-cache.json";
-/**
- * The dispatch key: a file whose `cache_version` is absent or any other value
- * reads as no cache.
- */
+/** Any other or absent `cache_version` reads as no cache. */
 export declare const WITNESS_CACHE_VERSION = "sanning.witness-cache/v1";
-/**
- * How deep `[` and `{` may nest in the file before it is refused unread: the
- * limit `bundle.json` and `contents.json` are read under.
- */
+/** Nesting limit for the file, the same as for `bundle.json` and `contents.json`. */
 export declare const MAX_WITNESS_CACHE_DEPTH = 512;
 /**
- * One `cache.witnessed[]` entry that reads, joined to the stamp it names.
- * `witnessKind` and `witnessId` are the stamp's own `anchor_ref`, read from the
- * signed body, never from the cache: the cache says WHEN, and the body alone
- * says WHICH witness it is about.
+ * One readable `cache.witnessed[]` entry joined to its stamp. `witnessKind` and
+ * `witnessId` come from the signed body, never the cache: the cache says when,
+ * the body alone says which witness.
  */
 export interface CachedWitnessTime {
     stampRef: string;
@@ -30,11 +22,8 @@ export interface CachedWitnessTime {
     witnessId: string;
 }
 /**
- * One gateway's answer for one cached time. `matches`: the gateway named the
- * cached block height and block time. `differs`: it named a block, and the
- * block is not the cached one. `unreachable`: it named no block (a transport
- * failure, a refusal, an answer that is not one, or a witness not yet in a
- * block).
+ * One gateway's answer for one cached time. `unreachable` means it named no
+ * block: transport failure, refusal, malformed answer, or not yet mined.
  */
 export interface WitnessTimeAnswer {
     gateway: string;
@@ -43,10 +32,8 @@ export interface WitnessTimeAnswer {
     blockTime: number | null;
 }
 /**
- * One cached time, and what the public record said about it: `differs` when
- * any gateway named a different block, otherwise `matches` when any gateway
- * named the cached one, otherwise `not_checked`. The same worst-answer-wins
- * order as the byte lookup.
+ * One cached time and the public record's answer: `differs` if any gateway
+ * named another block, else `matches` if any named this one, else `not_checked`.
  */
 export interface WitnessTimeCheck {
     cached: CachedWitnessTime;
@@ -54,32 +41,24 @@ export interface WitnessTimeCheck {
     answers: WitnessTimeAnswer[];
 }
 /**
- * The cached witness times the `witness-cache.json` bytes `raw` give for the
- * signed `bundle` beside them, in the order the file lists them. `raw` is
- * `null` where the pack has no such file. Pure, and never throws. The file
- * reads only where it is a JSON object whose `cache_version` is
- * `WITNESS_CACHE_VERSION` and whose `witnessed` is a list. An entry reads only
- * where it is an object whose `stamp_ref` is 64 lowercase hex characters naming
- * exactly one stamp of the signed body that has an `anchor_ref`, whose
- * `block_height` is a non-negative safe integer, and whose `block_time` is a
- * whole number of seconds since 1970-01-01T00:00:00Z from 0 to
- * `MAX_BLOCK_TIME`. A `stamp_ref` two entries name reads for neither.
- * Everything else reads as no cache for the stamp it would have spoken for.
+ * The cached witness times `raw` gives for the signed `bundle`, in file order.
+ * `raw` is `null` where the pack has no cache file. Pure; never throws.
+ *
+ * An entry reads only if its `stamp_ref` names exactly one signed stamp with an
+ * `anchor_ref`, `block_height` is a non-negative safe integer, and `block_time`
+ * is Unix seconds from 0 to `MAX_BLOCK_TIME`. A `stamp_ref` named twice reads
+ * for neither.
  */
 export declare function readWitnessCache(bundle: unknown, raw: Uint8Array | null | undefined): CachedWitnessTime[];
-/** A block time as RFC 3339 UTC to the second, the way both kernels print it: `2026-09-08T12:10:07Z`. */
+/** A block time as RFC 3339 UTC to the second: `2026-09-08T12:10:07Z`. */
 export declare function formatBlockTime(seconds: number): string;
 /** `block 1996701 at 2026-09-08T12:10:07Z`. */
 export declare function renderWitnessTime(blockHeight: number, blockTime: number): string;
-/**
- * The request body the lookup sends: one GraphQL query for one transaction's
- * block, as JCS, so both kernels send the same bytes.
- */
+/** The lookup's request body: one GraphQL query as JCS, so the bytes are fixed. */
 export declare function witnessTimeQuery(witnessId: string): string;
 /**
- * Look each cached time up on every gateway, in order. With no gateways or no
- * `fetchImpl`, nothing is looked up and every time is `not_checked`. A witness
- * that is not `arweave`, or whose id is not a 43-character base64url
- * transaction id, is never looked up.
+ * Looks each cached time up on every gateway, in order. With no gateways or no
+ * `fetchImpl`, every time is `not_checked`. Only `arweave` witnesses with a
+ * 43-character base64url id are looked up.
  */
 export declare function checkWitnessCache(cached: readonly CachedWitnessTime[], gateways: readonly string[], fetchImpl: typeof fetch | undefined): Promise<WitnessTimeCheck[]>;

package/dist/witness-cache.js

@@ -1,77 +1,44 @@
-// The witnessed-time cache: what a pack remembers about its witness, unverified
-// (evidence-bundle.md 5.6.6, v1.25, A30, proof#24).
+// The witnessed-time cache (evidence-bundle.md §5.6.6): `witness-cache.json`
+// beside a pack's `bundle.json`, giving the block height and time of each
+// stamp's witness transaction as the pack builder fetched them. Nobody signs it
+// and anyone can edit it, so every member is unverified.
 //
-// The TypeScript half of `src/sanning_proof/witness_cache.py`. Both kernels are
-// held to one table, `ts/vectors/witness-cache.json`, so neither can pass by
-// agreeing with the other.
+// Trust rules:
+// - `readWitnessCache` is never an input to the bundle verdict, the pack grade
+//   or the case reading.
+// - `checkWitnessCache` asks the public record. A different block is a finding
+//   (`differs`); an unsettled lookup leaves the value `not_checked`.
+// - Nothing here returns a time a reader may rely on. A gateway is named, never
+//   trusted.
 //
-// WHAT THE CACHE IS. A file beside the pack's `bundle.json`,
-// `witness-cache.json`, and never a member of the bundle. Its one list today,
-// `witnessed`, gives for each stamp the block height and block time of the
-// witness transaction, as the builder of the pack fetched them. Nobody signs
-// it, and anyone holding the pack can edit it. EVERY MEMBER OF THE FILE IS
-// UNVERIFIED BY CONSTRUCTION, and the name carries that warning to every field
-// added to it later.
-//
-// Because it is a separate file, a reader before v1.25 never opens it: it lists
-// it as a file outside every pack and reads the pack exactly as it would
-// without it. A `cache` member written INSIDE `bundle.json` is an unknown
-// wrapper field, counted in the signed scope by every reader, this one
-// included.
-//
-// WHAT THIS MODULE DOES, AND WHAT IT MUST NEVER DO.
-//
-// - `readWitnessCache` reads the file's bytes against the signed bundle beside
-//   it. It is pure, and it is never an input to the bundle verdict, the pack
-//   grade or the case reading: neither `verifyEvidenceBundle` nor `readCase` is
-//   ever handed the file.
-// - `checkWitnessCache` looks each cached time up on the public record, where a
-//   caller asked for a lookup. A lookup that answers with a different block is
-//   a finding, reported on the witness line as `differs`. A lookup that does
-//   not settle leaves the cached value labelled not checked.
-// - Nothing here returns a time a reader may rely on. The only time this module
-//   ever reports as the public record's is one a gateway returned, and a
-//   gateway is named, never trusted (6).
-//
-// A file that is absent, that is not JSON under the reader's rule, whose
-// `cache_version` is not `WITNESS_CACHE_VERSION`, whose `witnessed` is not a
-// list, or whose entry is not well formed, reads as no cache for what it could
-// not say. It is never a finding and never moves anything.
+// A file that is absent, malformed, of another `cache_version`, or with a bad
+// entry reads as no cache for what it could not say. It is never a finding.
 import { jsonDepthExceeds } from "./case-file.js";
 import { jcs, jcsParse } from "./verifier.js";
 /**
- * The last second a block time can name and still be printed the same way by
- * both kernels: 9999-12-31T23:59:59Z. A larger value is a cache entry this
- * reader cannot print, and reads as none.
+ * The largest printable block time, 9999-12-31T23:59:59Z. A larger value reads
+ * as no entry.
  */
 export const MAX_BLOCK_TIME = 253402300799;
-/** The file's name, beside `bundle.json` in the pack's folder (5.6.1). */
+/** The file's name, beside `bundle.json` (§5.6.1). */
 export const WITNESS_CACHE_NAME = "witness-cache.json";
-/**
- * The dispatch key: a file whose `cache_version` is absent or any other value
- * reads as no cache.
- */
+/** Any other or absent `cache_version` reads as no cache. */
 export const WITNESS_CACHE_VERSION = "sanning.witness-cache/v1";
-/**
- * How deep `[` and `{` may nest in the file before it is refused unread: the
- * limit `bundle.json` and `contents.json` are read under.
- */
+/** Nesting limit for the file, the same as for `bundle.json` and `contents.json`. */
 export const MAX_WITNESS_CACHE_DEPTH = 512;
 // The bodies that carry `stamps[]`, the only witnesses the cache speaks for.
 const STAMP_BODIES = new Set(["sanning.stamp.trace/v1", "sanning.stamp.evidence/v2"]);
 const STAMP_REF = /^[0-9a-f]{64}$/;
-// The one witness kind a time is looked up for, and the only ids the lookup
-// sends: the same rule the byte lookup applies (evidence-bundle 5.1.1, v1.6).
+// The only witness kind and id shape a lookup sends, as for the byte lookup
+// (evidence-bundle §5.1.1).
 const ADAPTER_KIND = "arweave";
 const ARWEAVE_ID = /^[A-Za-z0-9_-]{43}$/;
-// A GraphQL answer to one query for one transaction is a few hundred bytes. A
-// deeper answer is not one, and refusing it before any parser recurses keeps
-// the two kernels on one reading of it.
+// An answer for one transaction is a few hundred bytes. Refusing a deeper one
+// before parsing keeps every reader on the same result.
 const MAX_ANSWER_DEPTH = 16;
 function isObject(v) {
     return v !== null && typeof v === "object" && !Array.isArray(v);
 }
-// A member the object itself holds, never one inherited from its prototype.
 function own(o, key) {
     return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
 }
@@ -82,8 +49,8 @@ function blockNumber(value, upper) {
         return null;
     return value;
 }
-// `stamp_ref` to `[kind, id]` for every stamp in the signed body that names a
-// witness. A `stamp_ref` spelled on two stamps names neither.
+// `stamp_ref` to `[kind, id]` for each signed stamp that names a witness. A
+// `stamp_ref` on two stamps names neither.
 function stampWitnesses(bundle) {
     const out = new Map();
     if (typeof bundle.body_type !== "string" || !STAMP_BODIES.has(bundle.body_type))
@@ -113,10 +80,8 @@ function stampWitnesses(bundle) {
     }
     return out;
 }
-// The file's JSON, read under the rule `contents.json` is read under (5.6.2):
-// strict UTF-8, no byte-order mark, no `NaN` or `Infinity`, no member named
-// twice, and nothing nested past `MAX_WITNESS_CACHE_DEPTH`. `undefined` for
-// anything else.
+// Strict JSON as for `contents.json` (§5.6.2), within `MAX_WITNESS_CACHE_DEPTH`.
+// `undefined` for anything else.
 function readFile(raw) {
     if (!(raw instanceof Uint8Array))
         return undefined;
@@ -130,17 +95,13 @@ function readFile(raw) {
     }
 }
 /**
- * The cached witness times the `witness-cache.json` bytes `raw` give for the
- * signed `bundle` beside them, in the order the file lists them. `raw` is
- * `null` where the pack has no such file. Pure, and never throws. The file
- * reads only where it is a JSON object whose `cache_version` is
- * `WITNESS_CACHE_VERSION` and whose `witnessed` is a list. An entry reads only
- * where it is an object whose `stamp_ref` is 64 lowercase hex characters naming
- * exactly one stamp of the signed body that has an `anchor_ref`, whose
- * `block_height` is a non-negative safe integer, and whose `block_time` is a
- * whole number of seconds since 1970-01-01T00:00:00Z from 0 to
- * `MAX_BLOCK_TIME`. A `stamp_ref` two entries name reads for neither.
- * Everything else reads as no cache for the stamp it would have spoken for.
+ * The cached witness times `raw` gives for the signed `bundle`, in file order.
+ * `raw` is `null` where the pack has no cache file. Pure; never throws.
+ *
+ * An entry reads only if its `stamp_ref` names exactly one signed stamp with an
+ * `anchor_ref`, `block_height` is a non-negative safe integer, and `block_time`
+ * is Unix seconds from 0 to `MAX_BLOCK_TIME`. A `stamp_ref` named twice reads
+ * for neither.
  */
 export function readWitnessCache(bundle, raw) {
     if (!isObject(bundle))
@@ -172,7 +133,7 @@ export function readWitnessCache(bundle, raw) {
     }
     return read.filter((c) => named.get(c.stampRef) === 1);
 }
-/** A block time as RFC 3339 UTC to the second, the way both kernels print it: `2026-09-08T12:10:07Z`. */
+/** A block time as RFC 3339 UTC to the second: `2026-09-08T12:10:07Z`. */
 export function formatBlockTime(seconds) {
     return new Date(seconds * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
 }
@@ -180,10 +141,7 @@ export function formatBlockTime(seconds) {
 export function renderWitnessTime(blockHeight, blockTime) {
     return `block ${blockHeight} at ${formatBlockTime(blockTime)}`;
 }
-/**
- * The request body the lookup sends: one GraphQL query for one transaction's
- * block, as JCS, so both kernels send the same bytes.
- */
+/** The lookup's request body: one GraphQL query as JCS, so the bytes are fixed. */
 export function witnessTimeQuery(witnessId) {
     return jcs({ query: `query{transaction(id:"${witnessId}"){block{height timestamp}}}` });
 }
@@ -235,10 +193,9 @@ async function ask(cached, gateway, fetchImpl) {
     return { gateway, outcome: same ? "matches" : "differs", blockHeight: height, blockTime: time };
 }
 /**
- * Look each cached time up on every gateway, in order. With no gateways or no
- * `fetchImpl`, nothing is looked up and every time is `not_checked`. A witness
- * that is not `arweave`, or whose id is not a 43-character base64url
- * transaction id, is never looked up.
+ * Looks each cached time up on every gateway, in order. With no gateways or no
+ * `fetchImpl`, every time is `not_checked`. Only `arweave` witnesses with a
+ * 43-character base64url id are looked up.
  */
 export async function checkWitnessCache(cached, gateways, fetchImpl) {
     const out = [];

package/dist/witness-lookup.d.ts

@@ -1,6 +1,7 @@
+import type { EvidenceBundleResult } from "./evidence.js";
 import type { WitnessLine, WitnessState } from "./case.js";
 import { type CachedWitnessTime, type WitnessTimeAnswer, type WitnessTimeCheck } 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;
 }
@@ -11,13 +12,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[];
 }
 export interface WitnessTimeRow {
@@ -40,46 +37,37 @@ 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 declare function onChainRow(ref: string, result: EvidenceBundleResult): {
+    row: OnChainRow;
+    answered: Set<string>;
+};
 /**
- * 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 declare function onChainHalf(packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[], gateways: readonly string[], options?: WitnessLookupOptions, 
+export declare function onChainOutcome(rows: readonly OnChainRow[]): "differs" | "not_settled" | "confirmed";
 /**
- * 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.
+ * 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.
  */
-witnessed?: string[][]): Promise<OnChainHalf>;
+export declare function onChainHalf(packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[], gateways: readonly string[], options?: WitnessLookupOptions): Promise<OnChainHalf>;
 /**
- * `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 declare function witnessLine(onChain: OnChainHalf, cached?: readonly CachedWitnessTime[]): WitnessLine;
-/** 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. */
@@ -91,34 +79,25 @@ 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 declare function lookupPublicRecord(packs: readonly PublicRecordPack[], gateways: readonly string[], options?: WitnessLookupOptions): Promise<PublicRecordResult>;