@sanning/proof 0.14.0 → 0.16.0

package/dist/cli.d.ts

@@ -1,6 +1,4 @@
 #!/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;
@@ -106,46 +104,6 @@ export declare function readFileEntry(entry: TreeEntry, key: string): Promise<Ui
  */
 export declare function treeFromArguments(paths: readonly string[]): Promise<Map<string, TreeEntry>>;
 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

package/dist/cli.js

@@ -48,7 +48,7 @@ import { basename, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
 import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
-import { VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+import { VERDICT_DISPLAY_TITLES, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
 import { CASE_FILE_INDEX_NAME, jsonDepthExceeds, readCaseFileIndex, renderCaseFileFinding, } from "./case-file.js";
 import { ZipReadError, readZip } from "./zip-reader.js";
 import { composeExport } from "./compose.js";
@@ -56,7 +56,13 @@ import { isHexField, sha256Hex, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
 import { DuplicateKeyError, parseRefusingDuplicates } from "./verifier.js";
 import { fileMatchToJson, matchCaseFiles, matchFiles, renderFileMatch } from "./file-match.js";
-import { WITNESS_CACHE_NAME, checkWitnessCache, readWitnessCache, renderWitnessTime, } from "./witness-cache.js";
+import { WITNESS_CACHE_NAME, readWitnessCache, } from "./witness-cache.js";
+// The public-record (witness) lookup this command runs with `--gateways`:
+// moved to its own pure module (proof#200) so a consumer that is not this CLI,
+// the verify page, can call the SAME implementation. `onChainHalf` and
+// `witnessLine` are this command's own two building blocks, unchanged; see
+// `./witness-lookup.ts` for the exported entry point, `lookupPublicRecord`.
+import { onChainHalf, witnessLine } from "./witness-lookup.js";
 import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
 import { completenessNotes, gradePack, renderCause } from "./grading.js";
 import { EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
@@ -1744,162 +1750,6 @@ function sortKeys(v) {
 function jsonText(v) {
     return JSON.stringify(sortKeys(v), null, 2);
 }
-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.
-async function onChainHalf(packs, gateways, io) {
-    if (gateways.length === 0)
-        return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
-    const rows = [];
-    const answered = new Set();
-    for (const [ref, bundle, cached] of packs) {
-        const result = await verifyEvidenceBundle(bundle, {
-            gateways,
-            ...(io.fetchImpl ? { fetchImpl: io.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, io.fetchImpl ?? fetch);
-        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,
-    };
-}
-/**
- * The witness line (evidence-bundle 5.5.6 v1.20, A24, D7) from the on-chain
- * half: `confirmed` is `confirmed`, `not_checked` and `undetermined` are
- * `not_checked` with the reason, and `failed` is `differs`. It never moves the
- * headline.
- */
-// 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`.
- */
-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 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
@@ -2137,7 +1987,7 @@ async function caseCommand(argv, io) {
     for (const [p, bundle] of bundles) {
         caches.push(readWitnessCache(bundle, await witnessCacheBytes(tree, split, p)));
     }
-    const onChain = await onChainHalf(bundles.map(([p, bundle], i) => [p.ref, bundle, caches[i]]), gateways, io);
+    const onChain = await onChainHalf(bundles.map(([p, bundle], i) => [p.ref, bundle, caches[i]]), gateways, { ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}) });
     const witness = witnessLine(onChain, caches.flat());
     const code = caseExitCode(reading.verdict, onChain.verdict);
     const nil = (v) => (v === undefined ? null : v);

package/dist/declaration.d.ts

@@ -60,7 +60,7 @@ export interface DeclarationContentFinding {
     eventId?: string;
 }
 /** Everything this check reports that is NOT a deviation, as a closed set. */
-export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld"];
+export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld", "other_declaration_held", "other_declaration_withheld"];
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 /**
  * One named non-deviation finding, as data.

package/dist/declaration.js

@@ -130,10 +130,10 @@
 // The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
 // byte-order mark, no non-finite literal. `jcs_loads` in
 // `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
-import { hexToBytes } from "./crypto.js";
-import { jcsParse } from "./verifier.js";
+import { hexToBytes, utf8 } from "./crypto.js";
+import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
-import { hasSideContent, inBodyContentOffered } from "./side-content.js";
+import { hasSideContent, inBodyContentOffered, sideContentEntry, } from "./side-content.js";
 /** The first declaration schema, which every earlier reader knows. */
 export const DECLARATION_VERSION = "sanning.declaration/v1";
 /**
@@ -255,6 +255,23 @@ export const DECLARATION_NOTE_KINDS = [
      * because its payload binding is undetermined.
      */
     "role_step_withheld",
+    /**
+     * Rule 10 (v1.29, A36). A record whose signed `event_type` is `declaration`
+     * and whose content HANDED IN to this reader is exactly `JCS(object)` of a
+     * declaration object of a version this reader knows, carrying exactly that
+     * version's keys, and not this pack's own. The note names the content handed
+     * in, never the record: whether those bytes bind to the record's
+     * `content_hash` is the bundle verifier's check, and an accuser can hand in
+     * declaration-shaped bytes for an honest record. What the pack holds is what
+     * the declaration in its body says, so this moves no verdict.
+     */
+    "other_declaration_held",
+    /**
+     * Rule 10. A record whose signed `event_type` is `declaration` and whose
+     * content did not reach this reader from either channel, so whether it is a
+     * declaration other than this pack's own is UNKNOWN.
+     */
+    "other_declaration_withheld",
 ];
 /**
  * The record committed inside one `events[]` entry, or `null`.
@@ -500,6 +517,155 @@ function roleReading(p, role, claimed) {
     }
     return null;
 }
+/**
+ * The `event_type` a declaration record is signed under: a reserved
+ * single-segment name, and the one `@sanning/anchor`'s `bundle` anchors a
+ * declaration as.
+ */
+const DECLARATION_EVENT_TYPE = "declaration";
+/**
+ * The keys a declaration object carries, under every version this reader
+ * knows: exactly these, no more and no fewer (5.4.1).
+ */
+const DECLARATION_KEYS = ["declaration_version", "case_id", "agents", "period", "records", "handoffs"];
+function hasExactKeys(value, keys) {
+    if (!isObject(value))
+        return false;
+    const have = Object.keys(value);
+    return have.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(value, k));
+}
+/**
+ * Whether `obj` is shaped like a declaration this reader knows: one of
+ * `DECLARATION_VERSIONS` compared exactly, exactly the keys that version
+ * defines, and the value types this module reads.
+ *
+ * It is the shape test `@sanning/anchor`'s `isDeclarationShape` makes, and it
+ * checks shape only, not the 5.4.1 rules `readDeclaration` grades: a stale
+ * declaration is somebody else's claim, and this reader does not grade it, it
+ * names it.
+ */
+function isDeclarationShape(obj) {
+    if (!isObject(obj))
+        return false;
+    const version = obj["declaration_version"];
+    if (version !== DECLARATION_VERSION && version !== DECLARATION_VERSION_V2)
+        return false;
+    if (!hasExactKeys(obj, DECLARATION_KEYS))
+        return false;
+    if (!isId(obj["case_id"]))
+        return false;
+    const agents = obj["agents"];
+    if (!Array.isArray(agents) || !agents.every((a) => typeof a === "string"))
+        return false;
+    const period = obj["period"];
+    if (!hasExactKeys(period, ["start", "end"]))
+        return false;
+    if (typeof period["start"] !== "string" || typeof period["end"] !== "string")
+        return false;
+    const recordKeys = version === DECLARATION_VERSION_V2 ? ["event_id", "disclosure", "role"] : ["event_id", "disclosure"];
+    const records = obj["records"];
+    if (!Array.isArray(records))
+        return false;
+    for (const r of records) {
+        if (!hasExactKeys(r, recordKeys) || typeof r["event_id"] !== "string")
+            return false;
+    }
+    const handoffs = obj["handoffs"];
+    if (!Array.isArray(handoffs))
+        return false;
+    return handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"]));
+}
+/**
+ * The content bytes disclosed for one record, or `null` where none are usable:
+ * `events[].content` first, then the side-content map, chosen the way the
+ * bundle verifier chooses the bytes it binds.
+ */
+function disclosedBytes(ev, p, content) {
+    const inBody = isObject(ev) ? ev["content"] : undefined;
+    if (typeof inBody === "string") {
+        try {
+            return hexToBytes(inBody);
+        }
+        catch {
+            // falls through to the side channel, as the bundle verifier does
+        }
+    }
+    if (!p.nameable)
+        return null;
+    const side = sideContentEntry(content, p.eventId).value;
+    if (side instanceof Uint8Array)
+        return side;
+    if (typeof side === "string") {
+        try {
+            return hexToBytes(side);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Whether `raw` is exactly `JCS(object)` of a declaration-shaped object.
+ * Canonical bytes, not merely parseable ones: a declaration is anchored as
+ * `JCS(declaration)`, and nothing an agent writes by accident.
+ */
+function isDeclarationBytes(raw) {
+    try {
+        const obj = jcsParse(raw);
+        return isDeclarationShape(obj) && sameBytes(utf8(jcs(obj)), raw);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Rule 10: every record that is a declaration other than the pack's own, in
+ * bundle order.
+ *
+ * The record's `event_type` is read from its signed `event_bytes`, so a record
+ * whose bytes the pack withholds is not named: the reader cannot see what it
+ * was signed as. Its content is read from either channel; a record whose
+ * content is byte for byte `JCS` of the pack's own declaration is the pack's
+ * own and is never named.
+ */
+function otherDeclarationNotes(bundle, pack, declaration, content) {
+    const events = pack.length > 0 ? (bodyOf(bundle)?.events ?? []) : [];
+    let own = null;
+    try {
+        own = utf8(jcs(declaration));
+    }
+    catch {
+        own = null;
+    }
+    const notes = [];
+    pack.forEach((p, i) => {
+        if (p.record === null || p.record.event_type !== DECLARATION_EVENT_TYPE)
+            return;
+        const raw = disclosedBytes(events[i], p, content);
+        if (raw === null) {
+            // Offered and unusable is not withheld: something arrived, it is not a
+            // declaration, and the bundle verifier names what is wrong with it.
+            // Nothing arrived is the reading the reader cannot settle.
+            if (!p.disclosed)
+                notes.push({ kind: "other_declaration_withheld", eventId: p.eventId });
+            return;
+        }
+        if (own !== null && sameBytes(raw, own))
+            return;
+        if (isDeclarationBytes(raw))
+            notes.push({ kind: "other_declaration_held", eventId: p.eventId });
+    });
+    return notes;
+}
 /**
  * Check a pack against the declaration inside its body.
  *
@@ -719,6 +885,11 @@ export function checkDeclaration(bundle, content) {
                 deviations.push({ kind, eventId });
         }
     }
+    // Rule 10 (5.4.2 v1.29, A36): content handed in for a record signed
+    // `declaration` that is a declaration other than this pack's own. Notes only, in bundle order, after every other note, and
+    // never a deviation: the pack holds what its own declaration says whatever
+    // one of its records says.
+    notes.push(...otherDeclarationNotes(bundle, pack, declaration, content));
     // A proven deviation wins: it is a mismatch between what the pack claimed
     // and what its own signed body carries, and a failing check always wins.
     // With no deviation and a content-dependent finding, the pack lines up with
@@ -838,6 +1009,14 @@ export function renderNote(note) {
         case "role_step_withheld":
             return (`${note.eventId} is signed as a step and this pack withholds its ` +
                 "record bytes, so whether it is one is UNKNOWN");
+        case "other_declaration_held":
+            return (`the content handed in for ${note.eventId} is a declaration that is ` +
+                "not this pack's own: it says what some pack holds, and what this " +
+                "pack holds is what the declaration in its body says");
+        case "other_declaration_withheld":
+            return (`${note.eventId} is signed as a declaration and no content for it ` +
+                "reached this verifier, so whether it is a declaration other than " +
+                "this pack's own is UNKNOWN");
     }
 }
 /**

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { DeclarationCheck, DeclarationClaims, DeclarationContentFinding, De
 export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_NOTE_KINDS, CASE_RELIANCE, CASE_RELIANCE_HANDOFF_CLAUSE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, CO_SIGNATURES_PRESENT, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, WITNESS_TIME_CACHED, WITNESS_TIME_RECORDED, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
 export { MAX_BLOCK_TIME, MAX_WITNESS_CACHE_DEPTH, WITNESS_CACHE_NAME, WITNESS_CACHE_VERSION, checkWitnessCache, formatBlockTime, readWitnessCache, renderWitnessTime, witnessTimeQuery, } from "./witness-cache.js";
 export type { CachedWitnessTime, WitnessTimeAnswer, WitnessTimeCheck } from "./witness-cache.js";
+export { lookupPublicRecord, onChainHalf, witnessLine } from "./witness-lookup.js";
+export type { OnChainHalf, OnChainRow, PublicRecordPack, PublicRecordResult, PublicRecordState, WitnessLookupOptions, WitnessTimeRow, } from "./witness-lookup.js";
 export type { CaseException, CaseExceptionKind, CaseNote, CaseNoteKind, CasePack, CasePackReading, CaseReading, CaseRecordReading, CaseVerdict, WitnessLine, WitnessState, } from "./case.js";
 export { CASE_FILE_FINDING_KINDS, CASE_FILE_INDEX_NAME, CASE_FILE_VERSION, HOW_TO_VERIFY_NAME, REPORT_README_FIRST_LINE, howToVerifyText, isPackRef, readCaseFileIndex, renderCaseFileFinding, } from "./case-file.js";
 export type { CaseFileFinding, CaseFileFindingKind, CaseFileIndexReading, } from "./case-file.js";

package/dist/index.js

@@ -89,6 +89,21 @@ export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_
 // The witnessed-time cache (evidence-bundle 5.6.6, v1.25, A30): read it, look it
 // up, print it. Never an input to a verdict.
 export { MAX_BLOCK_TIME, MAX_WITNESS_CACHE_DEPTH, WITNESS_CACHE_NAME, WITNESS_CACHE_VERSION, checkWitnessCache, formatBlockTime, readWitnessCache, renderWitnessTime, witnessTimeQuery, } from "./witness-cache.js";
+// The public-record (witness) lookup the CLI runs with `--gateways`
+// (src/witness-lookup.ts, proof#200): moved out of the CLI so a consumer
+// that is not the CLI, the verify page, calls the SAME implementation
+// rather than keeping its own copy (verify-page#70). Pure kernel scope: the
+// one network call lives in `lookupPublicRecord` and `onChainHalf`, runs
+// only when a caller hands in a gateway, and goes through `options.fetchImpl`
+// where a caller supplies one (a browser page's own `fetch`) or the ambient
+// global `fetch` otherwise, so this export runs in a browser exactly as it
+// runs in Node. `onChainHalf` and `witnessLine` are the CLI's own unchanged
+// building blocks; `lookupPublicRecord` is the new one-call, four-state entry
+// point a page wants, additive over both. `confirmed` from
+// `lookupPublicRecord` is a claim about the BYTES only, never about whether
+// the pack itself verifies, and a caller must never show it apart from the
+// pack's own verdict.
+export { lookupPublicRecord, onChainHalf, witnessLine } from "./witness-lookup.js";
 // The case file's index (src/case-file.ts, evidence-bundle.md §5.6, A25):
 // compared with the drop it describes, with NO verdict contribution. The index
 // is never an input to `readCase`. Pure: bytes and a file list in.

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>;