@sanning/proof 0.13.0 → 0.15.0

package/dist/witness-cache.js

@@ -0,0 +1,264 @@
+// The witnessed-time cache: what a pack remembers about its witness, unverified
+// (evidence-bundle.md 5.6.6, v1.25, A30, proof#24).
+//
+// 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.
+//
+// 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.
+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.
+ */
+export const MAX_BLOCK_TIME = 253402300799;
+/** The file's name, beside `bundle.json` in the pack's folder (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.
+ */
+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.
+ */
+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).
+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.
+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;
+}
+function blockNumber(value, upper) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        return null;
+    if (value < 0 || 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.
+function stampWitnesses(bundle) {
+    const out = new Map();
+    if (typeof bundle.body_type !== "string" || !STAMP_BODIES.has(bundle.body_type))
+        return out;
+    const body = bundle.body;
+    const stamps = isObject(body) ? body.stamps : undefined;
+    if (!Array.isArray(stamps))
+        return out;
+    const seen = new Set();
+    for (const stamp of stamps) {
+        if (!isObject(stamp))
+            continue;
+        const ref = stamp.stamp_ref;
+        if (typeof ref !== "string" || !STAMP_REF.test(ref))
+            continue;
+        if (seen.has(ref)) {
+            out.delete(ref);
+            continue;
+        }
+        seen.add(ref);
+        const anchor = stamp.anchor_ref;
+        if (!isObject(anchor))
+            continue;
+        if (typeof anchor.kind === "string" && typeof anchor.id === "string") {
+            out.set(ref, [anchor.kind, anchor.id]);
+        }
+    }
+    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.
+function readFile(raw) {
+    if (!(raw instanceof Uint8Array))
+        return undefined;
+    if (jsonDepthExceeds(raw, MAX_WITNESS_CACHE_DEPTH))
+        return undefined;
+    try {
+        return jcsParse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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.
+ */
+export function readWitnessCache(bundle, raw) {
+    if (!isObject(bundle))
+        return [];
+    const cache = readFile(raw);
+    if (!isObject(cache))
+        return [];
+    if (own(cache, "cache_version") !== WITNESS_CACHE_VERSION)
+        return [];
+    const entries = own(cache, "witnessed");
+    if (!Array.isArray(entries))
+        return [];
+    const witnesses = stampWitnesses(bundle);
+    const read = [];
+    const named = new Map();
+    for (const entry of entries) {
+        if (!isObject(entry))
+            continue;
+        const ref = own(entry, "stamp_ref");
+        if (typeof ref !== "string" || !witnesses.has(ref))
+            continue;
+        named.set(ref, (named.get(ref) ?? 0) + 1);
+        const height = blockNumber(own(entry, "block_height"), Number.MAX_SAFE_INTEGER);
+        const time = blockNumber(own(entry, "block_time"), MAX_BLOCK_TIME);
+        if (height === null || time === null)
+            continue;
+        const [kind, id] = witnesses.get(ref);
+        read.push({ stampRef: ref, blockHeight: height, blockTime: time, witnessKind: kind, witnessId: id });
+    }
+    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`. */
+export function formatBlockTime(seconds) {
+    return new Date(seconds * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** `block 1996701 at 2026-09-08T12:10:07Z`. */
+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.
+ */
+export function witnessTimeQuery(witnessId) {
+    return jcs({ query: `query{transaction(id:"${witnessId}"){block{height timestamp}}}` });
+}
+function readAnswer(raw) {
+    if (jsonDepthExceeds(raw, MAX_ANSWER_DEPTH))
+        return null;
+    let node;
+    try {
+        node = jcsParse(raw);
+    }
+    catch {
+        return null;
+    }
+    for (const key of ["data", "transaction", "block"]) {
+        if (!isObject(node))
+            return null;
+        node = node[key];
+    }
+    if (!isObject(node))
+        return null;
+    const height = blockNumber(node.height, Number.MAX_SAFE_INTEGER);
+    const time = blockNumber(node.timestamp, Number.MAX_SAFE_INTEGER);
+    if (height === null || time === null)
+        return null;
+    return [height, time];
+}
+async function ask(cached, gateway, fetchImpl) {
+    const unreachable = { gateway, outcome: "unreachable", blockHeight: null, blockTime: null };
+    const url = `${gateway.replace(/\/+$/, "")}/graphql`;
+    let raw;
+    try {
+        const resp = await fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: witnessTimeQuery(cached.witnessId),
+        });
+        if (!resp.ok)
+            return unreachable;
+        raw = new Uint8Array(await resp.arrayBuffer());
+    }
+    catch {
+        return unreachable;
+    }
+    const block = readAnswer(raw);
+    if (block === null)
+        return unreachable;
+    const [height, time] = block;
+    const same = height === cached.blockHeight && time === cached.blockTime;
+    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.
+ */
+export async function checkWitnessCache(cached, gateways, fetchImpl) {
+    const out = [];
+    for (const c of cached) {
+        if (gateways.length === 0 ||
+            fetchImpl === undefined ||
+            c.witnessKind !== ADAPTER_KIND ||
+            !ARWEAVE_ID.test(c.witnessId)) {
+            out.push({ cached: c, outcome: "not_checked", answers: [] });
+            continue;
+        }
+        const answers = [];
+        for (const gw of gateways)
+            answers.push(await ask(c, gw, fetchImpl));
+        const outcome = answers.some((a) => a.outcome === "differs")
+            ? "differs"
+            : answers.some((a) => a.outcome === "matches")
+                ? "matches"
+                : "not_checked";
+        out.push({ cached: c, outcome, answers });
+    }
+    return out;
+}

package/dist/witness-lookup.d.ts

@@ -0,0 +1,112 @@
+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`. */
+export interface WitnessLookupOptions {
+    fetchImpl?: typeof fetch;
+}
+export 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[];
+}
+export 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;
+    }[];
+}
+export 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";
+}
+/**
+ * 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).
+ */
+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.
+ */
+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`. */
+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.
+ */
+export interface PublicRecordPack {
+    /** How this pack is named in the result; carries no meaning beyond that. */
+    ref: string;
+    bundle: unknown;
+    witnessCache?: Uint8Array | null;
+}
+export interface PublicRecordResult {
+    state: PublicRecordState;
+    reasons: string[];
+    services: string[];
+    /** Witness times a pack caches that no lookup settled (5.6.6, v1.25, A30). */
+    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. */
+    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`).
+ *
+ * `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.
+ *
+ * `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).
+ *
+ * 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.
+ */
+export declare function lookupPublicRecord(packs: readonly PublicRecordPack[], gateways: readonly string[], options?: WitnessLookupOptions): Promise<PublicRecordResult>;

package/dist/witness-lookup.js

@@ -0,0 +1,300 @@
+// The public-record (witness) lookup the CLI runs with `--gateways`
+// (evidence-bundle.md §5.5.6, v1.20, A24, D7): re-fetch each pack's witness on
+// the public record and report what it said. Moved here from `cli.ts`
+// (proof#200) so the CLI and a consumer that is not the CLI, the verify page,
+// a browser app, call the SAME implementation rather than each keeping its
+// own copy that can drift.
+//
+// Pure by the kernel's own rule (specs/architecture.md §3): the network call
+// is the one exception this module exists to hold, and it never runs unless a
+// caller hands in a gateway to ask. `options.fetchImpl` is the seam: where a
+// caller supplies one (a browser page's own `fetch`, or a test's fake), that
+// is the ONE this module calls; where none is given, it falls back to the
+// ambient global `fetch`, the same fallback `cli.ts` already applied at its
+// own call site before this module existed.
+//
+// `onChainHalf` and `witnessLine` are the CLI's own building blocks,
+// UNCHANGED (proof#200 is additive: the CLI's `case` output and exit codes are
+// byte-for-byte what they were). `lookupPublicRecord` is the new export:
+// one pack (or several) in, one four-state result out, with a pack's
+// `witness-cache.json` read as part of the pack rather than as a side file a
+// caller must remember to also pass in.
+import { verifyEvidenceBundle } from "./evidence.js";
+import { WITNESS_NOT_LOOKED_UP, renderWitnessLine } from "./case.js";
+import { checkWitnessCache, readWitnessCache, renderWitnessTime, } from "./witness-cache.js";
+function witnessTimeRow(t) {
+    return {
+        stamp_ref: t.cached.stampRef,
+        cached: { block_height: t.cached.blockHeight, block_time: t.cached.blockTime },
+        outcome: t.outcome,
+        answers: t.answers.map((a) => ({
+            gateway: a.gateway,
+            outcome: a.outcome,
+            block_height: a.blockHeight,
+            block_time: a.blockTime,
+        })),
+    };
+}
+/**
+ * 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).
+ */
+export async function onChainHalf(packs, gateways, options = {}) {
+    if (gateways.length === 0)
+        return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const rows = [];
+    const answered = new Set();
+    for (const [ref, bundle, cached] of packs) {
+        const result = await verifyEvidenceBundle(bundle, { gateways: [...gateways], fetchImpl });
+        const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
+        const row = {
+            ref,
+            witnesses: witnesses.length,
+            confirmed: 0,
+            mismatched: 0,
+            unreachable: 0,
+            not_checked: 0,
+        };
+        for (const w of witnesses) {
+            const rollup = w.onChain?.rollup ?? null;
+            if (rollup === "confirm")
+                row.confirmed++;
+            else if (rollup === "mismatch")
+                row.mismatched++;
+            else if (rollup === "unreachable")
+                row.unreachable++;
+            else
+                row.not_checked++;
+        }
+        // The witness times the pack's witness-cache.json gives, looked up where
+        // it gives any (5.6.6, v1.25, A30). A pack with no cache gets no key and
+        // no request.
+        const times = await checkWitnessCache(cached, gateways, fetchImpl);
+        if (times.length > 0)
+            row.witness_times = times.map(witnessTimeRow);
+        rows.push(row);
+        for (const w of witnesses) {
+            for (const outcome of w.onChain?.perGateway ?? []) {
+                if (outcome.outcome === "confirm" || outcome.outcome === "mismatch") {
+                    answered.add(outcome.gateway);
+                }
+            }
+        }
+        for (const t of times) {
+            for (const a of t.answers) {
+                if (a.outcome === "matches" || a.outcome === "differs")
+                    answered.add(a.gateway);
+            }
+        }
+    }
+    const verdict = rows.some((r) => r.mismatched > 0 || (r.witness_times ?? []).some((t) => t.outcome === "differs"))
+        ? "failed"
+        : rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)
+            ? "undetermined"
+            : "confirmed";
+    return {
+        answered: gateways.filter((g) => answered.has(g)),
+        checked: true,
+        gateways: [...gateways],
+        packs: rows,
+        verdict,
+    };
+}
+// Distinct `[blockHeight, blockTime]` pairs, in time order.
+function distinctTimes(times) {
+    const seen = new Map();
+    for (const [h, t] of times)
+        seen.set(`${h}:${t}`, [h, t]);
+    return [...seen.values()].sort((a, b) => a[1] - b[1] || a[0] - b[0]);
+}
+// Only the keys that carry something: a line with no cached or recorded time
+// is the line 0.13.0 printed, field for field.
+function withTimes(line, cached, recorded) {
+    return {
+        ...line,
+        ...(cached.length > 0 ? { cached } : {}),
+        ...(recorded.length > 0 ? { recorded } : {}),
+    };
+}
+/**
+ * `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.
+ */
+export function witnessLine(onChain, cached = []) {
+    if (!onChain.checked) {
+        return withTimes({
+            state: WITNESS_NOT_LOOKED_UP.state,
+            reasons: [...WITNESS_NOT_LOOKED_UP.reasons],
+            services: [...WITNESS_NOT_LOOKED_UP.services],
+        }, distinctTimes(cached.map((c) => [c.blockHeight, c.blockTime])), []);
+    }
+    const services = [...(onChain.answered ?? [])];
+    const rows = onChain.packs;
+    const times = rows.flatMap((r) => r.witness_times ?? []);
+    const unsettled = distinctTimes(times
+        .filter((t) => t.outcome === "not_checked")
+        .map((t) => [t.cached.block_height, t.cached.block_time]));
+    const recorded = distinctTimes(times
+        .filter((t) => t.outcome === "matches")
+        .flatMap((t) => t.answers.filter((a) => a.outcome === "matches"))
+        .map((a) => [a.block_height, a.block_time]));
+    const contradicted = [];
+    for (const t of times) {
+        if (t.outcome !== "differs")
+            continue;
+        const a = t.answers.find((x) => x.outcome === "differs");
+        const reason = `a pack dates the witness ${renderWitnessTime(t.cached.block_height, t.cached.block_time)}` +
+            `, and the public record dates it ${renderWitnessTime(a.block_height, a.block_time)}`;
+        if (!contradicted.includes(reason))
+            contradicted.push(reason);
+    }
+    if (onChain.verdict === "failed") {
+        return withTimes({ state: "differs", reasons: contradicted, services }, unsettled, recorded);
+    }
+    if (onChain.verdict === "confirmed") {
+        return withTimes({ state: "confirmed", reasons: [], services }, unsettled, recorded);
+    }
+    const reasons = [];
+    if (rows.some((r) => r.witnesses === 0))
+        reasons.push("a pack names no witness");
+    if (rows.some((r) => r.unreachable > 0)) {
+        reasons.push("a lookup did not settle: the service could not be reached, or it " + "holds no such witness yet");
+    }
+    if (rows.some((r) => r.not_checked > 0)) {
+        reasons.push("no lookup is made for a witness kind a pack names");
+    }
+    return withTimes({ state: "not_checked", reasons, services }, unsettled, recorded);
+}
+/**
+ * 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`).
+ *
+ * `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.
+ *
+ * `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).
+ *
+ * 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.
+ */
+export async function lookupPublicRecord(packs, gateways, options = {}) {
+    try {
+        // Nothing to look up: zero packs means the CALLER handed in nothing to
+        // check, which is not the same claim as "the packs it handed in name no
+        // witness" (`no_public_record`, below). Checked first, and unconditionally,
+        // so a caller than mishandles an empty drop never reads it as confirmed.
+        if (packs.length === 0) {
+            const reasons = [...WITNESS_NOT_LOOKED_UP.reasons];
+            return {
+                state: "not_checked",
+                reasons,
+                services: [],
+                rendered: renderWitnessLine({ state: "not_checked", reasons, services: [] }),
+            };
+        }
+        const caches = packs.map((p) => readWitnessCache(p.bundle, p.witnessCache ?? null));
+        const rows = packs.map((p, i) => [
+            p.ref,
+            p.bundle,
+            caches[i],
+        ]);
+        const onChain = await onChainHalfForWitnessCount(rows, gateways, options);
+        const line = witnessLine(onChain.half, caches.flat());
+        // "No public record yet": every pack this lookup was handed names ZERO
+        // witnesses, so there is nothing the public record could confirm or
+        // contradict. This holds independently of whether a lookup ran, an
+        // offline reading of a fresh, unstamped pack is exactly as much "nothing to
+        // check yet" as an online one, and it is computed from the SAME witness
+        // count `onChainHalf` derives from `verifyEvidenceBundle`'s own parse, never
+        // a second reading of the bundle.
+        //
+        // A pack that does NOT verify (a broken wrapper signature, `bundle: null`,
+        // garbage, an unrecognised body type) also names zero witnesses, by
+        // construction: `verifyEvidenceBundle` never reports a checkpoint or a
+        // stamp for a bundle it could not authenticate. That is not "nothing to
+        // check yet", it is a pack this lookup could not read, so `no_public_record`
+        // is reserved for a pack whose wrapper genuinely verifies
+        // (`signatureOk && bodyHashOk && status !== "failed"`) and that carries no
+        // cached witness time either (a cache entry names something to check).
+        // Anything else that would otherwise qualify reads `not_checked` instead.
+        const noWitnesses = onChain.witnessCounts.every((n) => n === 0);
+        const everyPackVerifies = onChain.verifies.every((v) => v);
+        const noCacheRead = caches.every((c) => c.length === 0);
+        const canBeNoPublicRecord = noWitnesses && everyPackVerifies && noCacheRead;
+        const state = line.state === "not_checked" && canBeNoPublicRecord ? "no_public_record" : line.state;
+        return {
+            state,
+            reasons: line.reasons,
+            services: line.services,
+            ...(line.cached ? { cached: line.cached } : {}),
+            // `recorded` is a claim about the public record confirming a cached
+            // time; it never rides alongside anything but a `confirmed` verdict, so
+            // a pack whose wrapper does not verify can never surface a cached time
+            // as though the record had confirmed it.
+            ...(state === "confirmed" && line.recorded ? { recorded: line.recorded } : {}),
+            rendered: renderWitnessLine({ ...line, state: state === "no_public_record" ? "not_checked" : state }),
+        };
+    }
+    catch (e) {
+        // Untrusted input all the way down: a gateway's answer, a pack's shape, a
+        // caller's `fetchImpl`. Anything this function or what it calls cannot
+        // make sense of settles `not_checked` rather than throw out of an export a
+        // browser page calls directly.
+        const reason = e instanceof Error ? `the lookup did not settle: ${e.message}` : "the lookup did not settle";
+        const reasons = [reason];
+        return {
+            state: "not_checked",
+            reasons,
+            services: [],
+            rendered: renderWitnessLine({ state: "not_checked", reasons, services: [] }),
+        };
+    }
+}
+// `onChainHalf` short-circuits to `{ checked: false, packs: [] }` with no
+// gateways, which is right for the CLI (nothing to print per pack) but leaves
+// `lookupPublicRecord` unable to tell "no gateways" from "no witnesses" for an
+// OFFLINE reading. This wrapper reads each pack's witness count, and whether
+// its wrapper verifies, the same way `onChainHalf` does, via
+// `verifyEvidenceBundle`: an OFFLINE parse (`gateways: []`), so it costs no
+// extra request whether or not a lookup runs, and `verifies` is never itself
+// a statement about the public record, only about the pack's own signature
+// and `body_hash`.
+async function onChainHalfForWitnessCount(packs, gateways, options) {
+    const witnessCounts = [];
+    const verifies = [];
+    for (const [, bundle] of packs) {
+        const result = await verifyEvidenceBundle(bundle, { gateways: [] });
+        witnessCounts.push(result.checkpoints.length + (result.stamps?.length ?? 0));
+        verifies.push(result.signatureOk && result.bodyHashOk && result.status !== "failed");
+    }
+    if (gateways.length > 0) {
+        const half = await onChainHalf(packs, gateways, options);
+        return { half, witnessCounts, verifies };
+    }
+    return { half: { checked: false, gateways: [], packs: [], verdict: "not_checked" }, witnessCounts, verifies };
+}