@sanning/proof 0.19.0 → 0.20.0

package/src/witness-cache.ts

@@ -1,85 +1,52 @@
-// 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;
 
 /**
- * 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;
@@ -90,11 +57,8 @@ export interface CachedWitnessTime {
 }
 
 /**
- * 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;
@@ -104,10 +68,8 @@ export interface WitnessTimeAnswer {
 }
 
 /**
- * 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;
@@ -119,7 +81,6 @@ function isObject(v: unknown): v is Record<string, unknown> {
   return v !== null && typeof v === "object" && !Array.isArray(v);
 }
 
-// A member the object itself holds, never one inherited from its prototype.
 function own(o: Record<string, unknown>, key: string): unknown {
   return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
 }
@@ -130,8 +91,8 @@ function blockNumber(value: unknown, upper: number): number | 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: Record<string, unknown>): Map<string, [string, string]> {
   const out = new Map<string, [string, string]>();
   if (typeof bundle.body_type !== "string" || !STAMP_BODIES.has(bundle.body_type)) return out;
@@ -157,10 +118,8 @@ function stampWitnesses(bundle: Record<string, unknown>): Map<string, [string, s
   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: Uint8Array | null | undefined): unknown {
   if (!(raw instanceof Uint8Array)) return undefined;
   if (jsonDepthExceeds(raw, MAX_WITNESS_CACHE_DEPTH)) return undefined;
@@ -172,17 +131,13 @@ function readFile(raw: Uint8Array | null | undefined): unknown {
 }
 
 /**
- * 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: unknown, raw: Uint8Array | null | undefined): CachedWitnessTime[] {
   if (!isObject(bundle)) return [];
@@ -208,7 +163,7 @@ export function readWitnessCache(bundle: unknown, raw: Uint8Array | null | undef
   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: number): string {
   return new Date(seconds * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
 }
@@ -218,10 +173,7 @@ export function renderWitnessTime(blockHeight: number, blockTime: number): strin
   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: string): string {
   return jcs({ query: `query{transaction(id:"${witnessId}"){block{height timestamp}}}` });
 }
@@ -272,10 +224,9 @@ async function ask(
 }
 
 /**
- * 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: readonly CachedWitnessTime[],