@sanning/proof 0.14.0 → 0.16.0

package/src/declaration.ts

@@ -131,10 +131,15 @@
 // 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, type HandoffRecord } from "./handoff.js";
-import { hasSideContent, inBodyContentOffered, type SideContentMap } from "./side-content.js";
+import {
+  hasSideContent,
+  inBodyContentOffered,
+  sideContentEntry,
+  type SideContentMap,
+} from "./side-content.js";
 
 /** The first declaration schema, which every earlier reader knows. */
 export const DECLARATION_VERSION = "sanning.declaration/v1";
@@ -278,6 +283,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",
 ] as const;
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 
@@ -698,6 +720,149 @@ function roleReading(
   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: unknown, keys: string[]): value is Record<string, unknown> {
+  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: unknown): boolean {
+  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: unknown,
+  p: PackRecord,
+  content: SideContentMap | null | undefined,
+): Uint8Array | null {
+  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: Uint8Array, b: Uint8Array): boolean {
+  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: Uint8Array): boolean {
+  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: unknown,
+  pack: PackRecord[],
+  declaration: unknown,
+  content: SideContentMap | null | undefined,
+): DeclarationNote[] {
+  const events = pack.length > 0 ? (bodyOf(bundle)?.events ?? []) : [];
+  let own: Uint8Array | null = null;
+  try {
+    own = utf8(jcs(declaration));
+  } catch {
+    own = null;
+  }
+  const notes: DeclarationNote[] = [];
+  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.
  *
@@ -915,6 +1080,12 @@ export function checkDeclaration(
     }
   }
 
+  // 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
@@ -1120,6 +1291,18 @@ export function renderNote(note: DeclarationNote): string {
         `${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/src/index.ts

@@ -251,6 +251,31 @@ export {
   witnessTimeQuery,
 } from "./witness-cache.js";
 export type { CachedWitnessTime, WitnessTimeAnswer, WitnessTimeCheck } 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";
+export type {
+  OnChainHalf,
+  OnChainRow,
+  PublicRecordPack,
+  PublicRecordResult,
+  PublicRecordState,
+  WitnessLookupOptions,
+  WitnessTimeRow,
+} from "./witness-lookup.js";
 export type {
   CaseException,
   CaseExceptionKind,

package/src/witness-lookup.ts

@@ -0,0 +1,428 @@
+// 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 type { WitnessLine, WitnessState } from "./case.js";
+import { WITNESS_NOT_LOOKED_UP, renderWitnessLine } from "./case.js";
+import {
+  type CachedWitnessTime,
+  type WitnessTimeAnswer,
+  type WitnessTimeCheck,
+  checkWitnessCache,
+  readWitnessCache,
+  renderWitnessTime,
+} 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;
+  }[];
+}
+
+function witnessTimeRow(t: WitnessTimeCheck): WitnessTimeRow {
+  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,
+    })),
+  };
+}
+
+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 async function onChainHalf(
+  packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[],
+  gateways: readonly string[],
+  options: WitnessLookupOptions = {},
+): Promise<OnChainHalf> {
+  if (gateways.length === 0) return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const rows: OnChainRow[] = [];
+  const answered = new Set<string>();
+  for (const [ref, bundle, cached] of packs) {
+    const result = await verifyEvidenceBundle(bundle, { gateways: [...gateways], fetchImpl });
+    const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
+    const row: OnChainRow = {
+      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: Iterable<[number, number]>): [number, number][] {
+  const seen = new Map<string, [number, number]>();
+  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: WitnessLine,
+  cached: [number, number][],
+  recorded: [number, number][],
+): WitnessLine {
+  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: OnChainHalf, cached: readonly CachedWitnessTime[] = []): WitnessLine {
+  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): [number, number] => [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): [number, number] => [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): [number, number] => [a.block_height as number, a.block_time as number]),
+  );
+  const contradicted: string[] = [];
+  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 as number, a.block_time as number)}`;
+    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: string[] = [];
+  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-entry-point export (proof#200) ─────────────────────────────
+//
+// `onChainHalf` and `witnessLine` above are the CLI's own two-step shape:
+// gateways in, an `OnChainHalf` (every row, every gateway) out, then a
+// `WitnessLine` (three states: `confirmed`, `not_checked`, `differs`) rendered
+// from it. A second caller, the verify page, does not want the CLI's
+// internal row shape and does want a fourth state the CLI's three-state
+// `WitnessLine` cannot name: a pack that carries NO witness at all yet is not
+// "not checked" (a lookup that could have found something and didn't), it is
+// "there is nothing on the public record to check". Folding that pack into
+// `not_checked` is not wrong for the CLI (`case` already says so in the
+// reason text: "a pack names no witness"), but a tag that only ever reads
+// "Not checked" hides the one distinction an auditor most wants: did we look
+// and find nothing, or is there nothing to look for yet.
+//
+// `lookupPublicRecord` is additive over the two functions above: it calls
+// them, never reimplements them, so there is exactly one place the network
+// call and the verdict arithmetic live. It never throws: the underlying
+// primitives (`verifyEvidenceBundle`, `checkWitnessCache`) already treat a
+// gateway's answer as untrusted input and report `unreachable`/`differs`
+// rather than raise, and this function adds no new path to the network or the
+// parser.
+
+/** 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 async function lookupPublicRecord(
+  packs: readonly PublicRecordPack[],
+  gateways: readonly string[],
+  options: WitnessLookupOptions = {},
+): Promise<PublicRecordResult> {
+  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: [string, unknown, readonly CachedWitnessTime[]][] = 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: PublicRecordState =
+      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: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[],
+  gateways: readonly string[],
+  options: WitnessLookupOptions,
+): Promise<{ half: OnChainHalf; witnessCounts: number[]; verifies: boolean[] }> {
+  const witnessCounts: number[] = [];
+  const verifies: boolean[] = [];
+  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 };
+}