paperlint 3.1.1 → 3.1.3

package/src/adapters/references/index.ts

@@ -2,18 +2,36 @@
  * The online reference checks, as the `CheckReferences` port: `verify-cites` (the cited work
  * exists, the title matches — Crossref, OpenAlex, Semantic Scholar, arXiv) and `bib-authors` (the
  * authors are the published version's — DBLP). Both ship in this package's verify-citations skill;
- * this adapter only runs them and shapes their answers.
+ * this adapter only runs them, shapes their answers, and serves them from the paper's lookup cache.
+ *
+ * 🔴 THE CACHE HOLDS ANSWERS, AND ONLY THE CHECKERS' OWN SEAMS TOUCH IT. verify-cites takes a
+ * `cache` object keyed per resolver × identifier and stores only successful responses; it is
+ * handed the paper's cached responses and whatever it adds is new. bib-authors takes a `lookup`
+ * (title → DBLP hits) and a `pause`; the lookup is wrapped to answer from the cache, and the pause
+ * is skipped after a cached answer — DBLP's 900 ms pace and its retries run only for titles never
+ * answered. Neither checker's logic changes. Verdicts are derived from the answers on every build
+ * (`domain/lookup-cache.ts` says why).
  *
  * "Not checked" is decided up front, by one request: when Crossref cannot be reached at all, the
  * checkers would degrade every entry to `unresolvable` / `unchecked`, which reads like a result.
- * Saying `not-checked` with the reason is the honest record.
+ * Saying `not-checked` with the reason is the honest record. That request is skipped when every
+ * question this bibliography would ask is already answered in the cache: a warm build is offline.
  */
 import type {
   CheckReferences,
   EntryVerdict,
 } from "../../ports/check-references.ts";
+import {
+  freshPart,
+  type CachedDblp,
+  type CachedResponse,
+  type DblpHit,
+  type LookupCache,
+} from "../../domain/lookup-cache.ts";
+import { sha256Hex } from "../../domain/sha256.ts";
 import { mapLimit } from "./pool.ts";
 import { unreachable } from "./reach.io.ts";
+import { sleep, todayUtc } from "./clock.io.ts";
 
 /** Citations looked up at once (#107). */
 const LOOKUPS_IN_FLIGHT = 6;
@@ -26,6 +44,8 @@ interface CiteResult {
   readonly id: string;
   readonly verdict: "true" | "false" | "unresolvable";
   readonly reason?: string;
+  /** "<service>: <reason>" for each question a refusing service did not answer (#120). */
+  readonly refused?: readonly string[];
 }
 interface AuthorFinding {
   readonly key: string;
@@ -64,6 +84,18 @@ const authorsOf = (key: string, a: AuthorBuckets): EntryVerdict["authors"] =>
         ? "match"
         : "skipped";
 
+/**
+ * Why a work was not confirmed: verify-cites' reason, then — when some registry refused — which
+ * one, so "unresolvable" is not read as "every registry looked and found nothing". Nothing for a
+ * confirmed work: a refusal after a confirmation changed nothing.
+ */
+const unconfirmed = (
+  c: CiteResult | undefined,
+): readonly (string | undefined)[] =>
+  c && c.verdict !== "true"
+    ? [c.reason, ...(c.refused ?? []).map((r) => `not asked: ${r}`)]
+    : [];
+
 /** One entry's verdict from the two checkers' answers. */
 function entryVerdict(
   key: string,
@@ -73,7 +105,7 @@ function entryVerdict(
   const c = found.find((x) => x.id === key);
   const mismatch = a.findings.find((f) => f.key === key);
   const why = [
-    c && c.verdict !== "true" ? c.reason : undefined,
+    ...unconfirmed(c),
     mismatch ? describeAuthors(mismatch) : undefined,
     a.unchecked.find((u) => u.key === key)?.why,
   ]
@@ -87,31 +119,168 @@ function entryVerdict(
   };
 }
 
-export const onlineReferences: CheckReferences = async (bib) => {
-  const why = await unreachable();
-  if (why !== null) return { kind: "not-checked", why };
-  // 🔴 #107: the lookups were one at a time — 27 references took 217 s. They now run
-  // LOOKUPS_IN_FLIGHT at a time, and the DBLP author pass runs beside them (it keeps its own
-  // serial pace and 900 ms pause, which DBLP asks for). Each citation's own requests go to four
-  // different services one after another, so a pool of 6 is at most 6 requests to any one of
-  // them. The cache is shared: two citations with the same identifier may both miss it and ask
-  // twice — an extra request, never a different answer.
-  const cache = {};
-  const citations = (cites.parseBib(bib) as { id?: string }[]).filter(
-    (c) => c.id,
+interface BibAuthorsEntry {
+  readonly key: string;
+  readonly title: string;
+  readonly author: string;
+}
+
+/** Whether bib-authors will ask DBLP about this entry — the filter its `checkAuthors` applies. */
+const asksDblp = (e: BibAuthorsEntry): boolean =>
+  Boolean(e.title && e.author) &&
+  (authors.claimsPublished(e) as boolean) &&
+  !(authors.truncated(e.author) as boolean);
+
+/** Is every question this bibliography would ask already answered in `cache`? */
+async function fullyCached(
+  citations: readonly object[],
+  entries: readonly BibAuthorsEntry[],
+  cache: LookupCache,
+  store: Readonly<Record<string, unknown>>,
+): Promise<boolean> {
+  const asks = await Promise.all(
+    citations.map((c) => cites.wouldAsk(c, store) as Promise<boolean>),
   );
-  const [found, a] = await Promise.all([
-    mapLimit(
-      citations,
-      LOOKUPS_IN_FLIGHT,
-      (c) => cites.verifyCitationLive(c, { cache }) as Promise<CiteResult>,
-    ),
-    authors.checkAuthors(authors.parseBib(bib)) as Promise<AuthorBuckets>,
-  ]);
-  const keys = new Set([
-    ...found.map((c) => c.id),
-    ...a.findings.map((f) => f.key),
+  return (
+    !asks.includes(true) &&
+    entries.filter(asksDblp).every((e) => cache.dblp.has(dblpTitleKey(e.title)))
+  );
+}
+
+/**
+ * The key a DBLP answer is stored under in the lookup cache: the title's identity (verify-cites'
+ * `titleIdentity` — the same rule its own title keys use, so the two caches cannot drift), hashed.
+ * A re-cased or re-braced title keeps its answer; `C` and `C++` do not share one.
+ */
+export const dblpTitleKey = (title: string): string =>
+  sha256Hex(new TextEncoder().encode(cites.titleIdentity(title))).slice(0, 16);
+
+export interface ReferencesCheckerOptions {
+  /** The day a new answer is stamped with, YYYY-MM-DD. */
+  readonly today: () => string;
+}
+
+/**
+ * bib-authors' `lookup` and `pause`, answering from the cached DBLP hits first.
+ *
+ * 🔴 DBLP IS ASKED UNTIL IT REFUSES ONCE, THEN NOT AT ALL FOR THE REST OF THE RUN (#120). A 429, an
+ * HTML page where JSON was asked, a timeout: bib-authors would retry each title three times with
+ * backoff, and move on to the next title to do it again — 51 titles × 3 × up to 15 s. After the
+ * first refusal every lookup fails at once with the reason, and no pause is waited, so each entry
+ * lands in bib-authors' `unchecked` bucket ("never a pass") for the price of ONE request.
+ *
+ * The 900 ms pace protects DBLP, so it is kept only after an answer DBLP actually gave: not after a
+ * cached answer, and not once DBLP is off.
+ */
+function cachedDblp(cache: LookupCache, today: () => string) {
+  const dblp = new Map<string, CachedDblp>(cache.dblp);
+  let lastWasCached = false;
+  let refused: string | null = null;
+  return {
+    dblp,
+    lookup: async (title: string): Promise<readonly DblpHit[]> => {
+      const hit = dblp.get(dblpTitleKey(title));
+      lastWasCached = hit !== undefined;
+      if (hit) return hit.hits;
+      if (refused !== null)
+        throw new Error(`DBLP refused earlier in this run (${refused})`);
+      try {
+        const hits = (await authors.dblpHits(title)) as DblpHit[];
+        dblp.set(dblpTitleKey(title), { fetched: today(), title, hits });
+        return hits;
+      } catch (e) {
+        refused = (e as Error).message;
+        throw new Error(`DBLP refused earlier in this run (${refused})`);
+      }
+    },
+    pause: (ms: number): Promise<void> =>
+      lastWasCached || refused !== null ? Promise.resolve() : sleep(ms),
+  };
+}
+
+/**
+ * The cache after a run: the old answers with every new one laid over them, dated today — or the
+ * very object passed in when nothing was fetched, so the caller can tell there is nothing to write.
+ * "New" is measured against `usable`, the part the run answered from: an answer too old to use was
+ * asked again, and its fresh copy replaces the old one. An old answer the run could not refresh
+ * (the service refused) stays, and is asked again next build.
+ */
+function grown(
+  loaded: { readonly cache: LookupCache; readonly usable: LookupCache },
+  run: {
+    readonly store: Readonly<Record<string, unknown>>;
+    readonly dblp: ReadonlyMap<string, CachedDblp>;
+  },
+  today: () => string,
+): LookupCache {
+  const { cache, usable } = loaded;
+  const { store, dblp } = run;
+  const fresh = Object.entries(store).filter(([k]) => !usable.citations.has(k));
+  const freshDblp = [...dblp].filter(([k]) => !usable.dblp.has(k));
+  if (fresh.length === 0 && freshDblp.length === 0) return cache;
+  const dated = fresh.map(([k, response]): [string, CachedResponse] => [
+    k,
+    { fetched: today(), response: response as CachedResponse["response"] },
   ]);
-  const entries = [...keys].map((key) => entryVerdict(key, found, a));
-  return { kind: "checked", entries };
-};
+  return {
+    citations: new Map([...cache.citations, ...dated]),
+    dblp: new Map([...cache.dblp, ...freshDblp]),
+  };
+}
+
+/** The checker, with its clock injected; `onlineReferences` is the one the CLI wires. */
+export const referencesChecker =
+  ({ today }: ReferencesCheckerOptions): CheckReferences =>
+  async (bib, cache) => {
+    // Answers past MAX_AGE_DAYS are left out, so the run asks them again (and `grown` re-dates them).
+    const usable = freshPart(cache, today());
+    const citations = (cites.parseBib(bib) as { id?: string }[]).filter(
+      (c) => c.id,
+    );
+    const parsed = authors.parseBib(bib) as BibAuthorsEntry[];
+    const store: Record<string, unknown> = Object.fromEntries(
+      [...usable.citations].map(([k, v]) => [k, v.response]),
+    );
+    if (!(await fullyCached(citations, parsed, usable, store))) {
+      const why = await unreachable();
+      if (why !== null) return { check: { kind: "not-checked", why }, cache };
+    }
+    // 🔴 #107: the lookups run LOOKUPS_IN_FLIGHT at a time, and the DBLP author pass runs beside
+    // them. Each citation's own requests go to four different services one after another, so a
+    // pool of 6 is at most 6 requests to any one of them. The store is shared: two citations with
+    // the same identifier may both miss it and ask twice — an extra request, never a different
+    // answer.
+    // One breaker for the run: a service that refuses is not asked again, not once per citation
+    // (#120). Requests already in flight when it starts refusing still land — at most six.
+    const breaker = cites.createBreaker() as unknown;
+    const d = cachedDblp(usable, today);
+    const [found, a] = await Promise.all([
+      mapLimit(
+        citations,
+        LOOKUPS_IN_FLIGHT,
+        (c) =>
+          cites.verifyCitationLive(c, {
+            cache: store,
+            breaker,
+          }) as Promise<CiteResult>,
+      ),
+      authors.checkAuthors(parsed, {
+        lookup: d.lookup,
+        pause: d.pause,
+      }) as Promise<AuthorBuckets>,
+    ]);
+    const keys = new Set([
+      ...found.map((c) => c.id),
+      ...a.findings.map((f) => f.key),
+    ]);
+    const entries = [...keys].map((key) => entryVerdict(key, found, a));
+    return {
+      check: { kind: "checked", entries },
+      cache: grown({ cache, usable }, { store, dblp: d.dblp }, today),
+    };
+  };
+
+/** The checker the CLI wires: the real clock. */
+export const onlineReferences: CheckReferences = referencesChecker({
+  today: todayUtc,
+});

package/src/build.ts

@@ -562,6 +562,10 @@ export const measureStep: BuildStep = {
  * authors are the published version's (bib-authors) — and record the verdicts in
  * `_build/references.json` for the offline lint rules (`reference-rules.ts`). OPTIONAL and NEVER
  * FAILING: without network the PDF is still built, and the record says `not-checked`.
+ *
+ * What the services answered is read from and added to `<paper>/repro/references-cache.json`
+ * (`references.ts`, `domain/lookup-cache.ts`), committed with the paper, so only a new or edited
+ * entry is asked, and an unchanged bibliography is checked with no network at all (#107).
  */
 export const referencesStep: BuildStep = {
   name: "references",
@@ -665,9 +669,12 @@ function baseDefaults({
 }
 
 /** Without a checker the record says so — never a pass. The CLI wires the real one. */
-const notWired: CheckReferences = async () => ({
-  kind: "not-checked",
-  why: "no reference checker was wired into this build",
+const notWired: CheckReferences = async (_bib, cache) => ({
+  check: {
+    kind: "not-checked",
+    why: "no reference checker was wired into this build",
+  },
+  cache,
 });
 
 /** banal as the measurer, wired from the build's environment: the one piece of root work left here (#76). */

package/src/domain/lookup-cache.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+import {
+  freshPart,
+  EMPTY_LOOKUP_CACHE,
+  parseLookupCache,
+  serializeLookupCache,
+  type LookupCache,
+} from "./lookup-cache.ts";
+import { err, ok } from "./result.ts";
+
+const HIT = {
+  venue: "ICSE",
+  year: "2024",
+  type: "Conference and Workshop Papers",
+  title: "Good Paper.",
+  authors: ["Ada Lovelace"],
+};
+const CACHE: LookupCache = {
+  citations: new Map([
+    [
+      "crossref:doi:10.1/good",
+      {
+        fetched: "2026-09-27",
+        response: { db: "crossref", transport: "ok", query: "doi" },
+      },
+    ],
+  ]),
+  dblp: new Map([
+    [
+      "0123456789abcdef",
+      { fetched: "2026-09-26", title: "Good Paper", hits: [HIT] },
+    ],
+  ]),
+};
+const doc = (o: object): string => JSON.stringify({ schema: 1, ...o });
+
+describe("serializeLookupCache / parseLookupCache", () => {
+  it("round-trips, keys sorted, one trailing newline", () => {
+    const text = serializeLookupCache(CACHE);
+    expect(text).toBe(
+      `${JSON.stringify(
+        {
+          schema: 1,
+          citations: {
+            "crossref:doi:10.1/good": {
+              fetched: "2026-09-27",
+              response: { db: "crossref", transport: "ok", query: "doi" },
+            },
+          },
+          dblp: {
+            ["0123456789abcdef"]: {
+              fetched: "2026-09-26",
+              title: "Good Paper",
+              hits: [HIT],
+            },
+          },
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    expect(parseLookupCache(text)).toEqual(ok(CACHE));
+  });
+
+  it("the empty cache writes both sections, and reads back as empty", () => {
+    expect(parseLookupCache(serializeLookupCache(EMPTY_LOOKUP_CACHE))).toEqual(
+      ok(EMPTY_LOOKUP_CACHE),
+    );
+  });
+});
+
+// Guards: a committed file that is wrong in any way is refused with a NAMED reason. Read as
+// empty, it would silently turn every build into a full online run — the defect this file fixes.
+const REFUSALS: [string, string][] = [
+  ["[]", "expected an object with `schema`, `citations` and `dblp`"],
+  [doc({ schema: 2 }), "schema 2: this paperlint reads schema 1"],
+  [doc({ citations: {}, dblp: {}, x: 1 }), "unknown field `x`"],
+  [doc({ dblp: {} }), "`citations`: expected an object"],
+  [doc({ citations: {} }), "`dblp`: expected an object"],
+  [doc({ citations: { k: 1 }, dblp: {} }), "`citations.k`: expected an object"],
+  [
+    doc({
+      citations: { k: { fetched: "2026-9-1", response: {} } },
+      dblp: {},
+    }),
+    "`citations.k.fetched`: expected a date, YYYY-MM-DD",
+  ],
+  [
+    doc({
+      citations: {
+        k: { fetched: "2026-09-01", response: { transport: "error" } },
+      },
+      dblp: {},
+    }),
+    '`citations.k.response`: expected a successful response ({"transport": "ok", …})',
+  ],
+  [
+    doc({
+      citations: {
+        k: { fetched: "2026-09-01", response: { transport: "ok" }, y: 1 },
+      },
+      dblp: {},
+    }),
+    "`citations.k`: unknown field `y`",
+  ],
+  [
+    doc({
+      citations: {},
+      dblp: { t: { fetched: "2026-09-01", title: 3, hits: [] } },
+    }),
+    "`dblp.t.title`: expected a string",
+  ],
+  [
+    doc({
+      citations: {},
+      dblp: { t: { fetched: "2026-09-01", title: "T", hits: {} } },
+    }),
+    "`dblp.t.hits`: expected an array",
+  ],
+  [
+    doc({
+      citations: {},
+      dblp: {
+        t: {
+          fetched: "2026-09-01",
+          title: "T",
+          hits: [{ ...HIT, authors: [1] }],
+        },
+      },
+    }),
+    "`dblp.t.hits[0]`: expected {venue, year, type, title: string; authors: string[]}",
+  ],
+  [
+    doc({
+      citations: {},
+      dblp: { t: { fetched: "2026-09-01", title: "T", hits: [3] } },
+    }),
+    "`dblp.t.hits[0]`: expected {venue, year, type, title: string; authors: string[]}",
+  ],
+];
+
+describe("parseLookupCache refusals", () => {
+  it("refuses text that is not JSON, saying so", () => {
+    const r = parseLookupCache("{");
+    // The rest of the message is Node's parser; its wording is not the subject.
+    expect(r.ok ? "" : r.error).toMatch(/^not JSON: /);
+  });
+
+  // Guards: see REFUSALS.
+  it.each(REFUSALS)("refuses %s with a named reason", (text, why) => {
+    expect(parseLookupCache(text)).toEqual(err(why));
+  });
+});
+
+describe("freshPart", () => {
+  const cache = (fetched: string): LookupCache => ({
+    citations: new Map([
+      [
+        "k",
+        {
+          fetched,
+          response: { db: "crossref", transport: "ok", query: "doi" },
+        },
+      ],
+    ]),
+    dblp: new Map(),
+  });
+  // Guards: the age window has two ends. A date in the future (a clock ahead, a typo) has a
+  // negative age; read as fresh, a miss would be trusted until that date plus 30 days.
+  it.each([
+    ["2026-09-27", 1],
+    ["2026-08-28", 1],
+    ["2026-08-27", 0],
+    ["2026-09-28", 0],
+  ])("on 2026-09-27, an answer fetched %s is kept %i time(s)", (fetched, n) => {
+    expect(freshPart(cache(fetched), "2026-09-27").citations.size).toBe(n);
+  });
+});

package/src/domain/lookup-cache.ts

@@ -0,0 +1,202 @@
+/**
+ * THE LOOKUP CACHE — `<paper>/repro/references-cache.json`: what the citation services ANSWERED,
+ * kept so that a build asks each question at most once every MAX_AGE_DAYS, not once per build (#107).
+ *
+ *   { "schema": 1,
+ *     "citations": { "<resolver>:<identifier>": { "fetched": "YYYY-MM-DD", "response": {…} } },
+ *     "dblp":      { "<title key>":             { "fetched": "YYYY-MM-DD", "title": "…", "hits": […] } } }
+ *
+ * `citations` holds verify-cites' per-resolver responses (Crossref, OpenAlex, Semantic Scholar,
+ * arXiv, doi.org, NVD), under verify-cites' own cache keys. `dblp` holds the hits DBLP returned for
+ * a title, under the references adapter's `dblpTitleKey`. Only successful answers are ever stored: a failed request is not an
+ * answer, so the next build asks again.
+ *
+ * 🔴 RESPONSES, NEVER VERDICTS. The verdicts (`_build/references.json`) are DERIVED from these
+ * responses on every build, by the current version of the checkers. A cached verdict would freeze
+ * whatever the checker believed the day it ran — a bug fixed in the comparison would never reach a
+ * paper whose entries are cached. A cached response is evidence: it cannot be made up, only
+ * refetched. The precedent is `extract-ref-facts.mjs`'s `repro/refs-cache.json` ("the cache is
+ * evidence, not a second declaration").
+ *
+ * 🔴 COMMITTED, so CI and every other clone start warm: a build whose entries are all here makes no
+ * network request at all, not even the reachability probe. It lives in `repro/`, beside the paper,
+ * not in `_build/`, which is build output and gitignored.
+ *
+ * WHAT INVALIDATES AN ENTRY: its key, or its age. Editing a bib entry's DOI, arXiv id or title
+ * changes the keys it is looked up under, so only that entry is asked again. An answer older than
+ * MAX_AGE_DAYS (by `fetched`) is asked again too, so a work a service had not indexed yet is found
+ * once it is. To refresh an answer sooner, delete its entry, or the file.
+ *
+ * Parsed here, once, at the boundary: a file that does not match is refused with a named reason,
+ * never read as empty.
+ */
+import { err, ok, type Result } from "./result.ts";
+
+export const LOOKUP_CACHE_SCHEMA = 1;
+
+type Json = Readonly<Record<string, unknown>>;
+
+/** One resolver's successful answer, as verify-cites shapes it (`{ transport: "ok", … }`). */
+export interface CachedResponse {
+  /** When it was fetched, YYYY-MM-DD. */
+  readonly fetched: string;
+  readonly response: Json;
+}
+
+/** One DBLP hit, as bib-authors' `dblpHits` shapes it. */
+export interface DblpHit {
+  readonly venue: string;
+  readonly year: string;
+  readonly type: string;
+  readonly title: string;
+  readonly authors: readonly string[];
+}
+
+export interface CachedDblp {
+  readonly fetched: string;
+  /** The title as it was asked — for a human reading the file; the key is the adapter's `dblpTitleKey(title)`. */
+  readonly title: string;
+  readonly hits: readonly DblpHit[];
+}
+
+export interface LookupCache {
+  readonly citations: ReadonlyMap<string, CachedResponse>;
+  readonly dblp: ReadonlyMap<string, CachedDblp>;
+}
+
+export const EMPTY_LOOKUP_CACHE: LookupCache = {
+  citations: new Map(),
+  dblp: new Map(),
+};
+
+/**
+ * How long a cached answer is used before it is asked again. A registry, doi.org or DBLP that had
+ * not indexed a work yet answers "no record"; kept forever, that answer would outlive the work's
+ * indexing. The age is judged against `fetched`, so every answer — a hit or a miss — gets the
+ * same rule, and nothing has to decide which answers are "negative".
+ */
+export const MAX_AGE_DAYS = 30;
+
+const dayNumber = (date: string): number =>
+  Date.parse(`${date}T00:00:00Z`) / 86_400_000;
+
+/** The part of `cache` still young enough to answer from on `today` (YYYY-MM-DD). */
+export function freshPart(cache: LookupCache, today: string): LookupCache {
+  // An age below zero is a date in the future (a clock ahead, a typo): not trusted, asked again.
+  const young = ({ fetched }: { fetched: string }): boolean => {
+    const age = dayNumber(today) - dayNumber(fetched);
+    return age >= 0 && age <= MAX_AGE_DAYS;
+  };
+  return {
+    citations: new Map([...cache.citations].filter(([, v]) => young(v))),
+    dblp: new Map([...cache.dblp].filter(([, v]) => young(v))),
+  };
+}
+
+const isObject = (v: unknown): v is Json =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+const unknownField = (o: Json, known: readonly string[]): string | undefined =>
+  Object.keys(o).find((k) => !known.includes(k));
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const isDate = (v: unknown): v is string =>
+  typeof v === "string" && DATE.test(v);
+
+/** Parse every value of `section` with `one`, or the first named reason. */
+function sectionOf<T>(
+  name: string,
+  section: unknown,
+  known: readonly string[],
+  one: (o: Json, at: string) => Result<T, string>,
+): Result<Map<string, T>, string> {
+  if (!isObject(section)) return err(`\`${name}\`: expected an object`);
+  const out = new Map<string, T>();
+  for (const [key, v] of Object.entries(section)) {
+    const at = `\`${name}.${key}`;
+    if (!isObject(v)) return err(`${at}\`: expected an object`);
+    const extra = unknownField(v, known);
+    if (extra !== undefined) return err(`${at}\`: unknown field \`${extra}\``);
+    if (!isDate(v["fetched"]))
+      return err(`${at}.fetched\`: expected a date, YYYY-MM-DD`);
+    const r = one(v, at);
+    if (!r.ok) return r;
+    out.set(key, r.value);
+  }
+  return ok(out);
+}
+
+const cachedResponse = (o: Json, at: string): Result<CachedResponse, string> =>
+  isObject(o["response"]) && o["response"]["transport"] === "ok"
+    ? ok({ fetched: o["fetched"] as string, response: o["response"] })
+    : err(
+        `${at}.response\`: expected a successful response ({"transport": "ok", …})`,
+      );
+
+const isHit = (h: unknown): h is DblpHit =>
+  isObject(h) &&
+  ["venue", "year", "type", "title"].every((k) => typeof h[k] === "string") &&
+  Array.isArray(h["authors"]) &&
+  h["authors"].every((a) => typeof a === "string");
+
+function cachedDblp(o: Json, at: string): Result<CachedDblp, string> {
+  const { title, hits } = o;
+  if (typeof title !== "string") return err(`${at}.title\`: expected a string`);
+  if (!Array.isArray(hits)) return err(`${at}.hits\`: expected an array`);
+  const bad = hits.findIndex((h) => !isHit(h));
+  if (bad !== -1)
+    return err(
+      `${at}.hits[${String(bad)}]\`: expected {venue, year, type, title: string; authors: string[]}`,
+    );
+  return ok({
+    fetched: o["fetched"] as string,
+    title,
+    hits: hits as DblpHit[],
+  });
+}
+
+/** The cache in `text`, or why it cannot be read. */
+export function parseLookupCache(text: string): Result<LookupCache, string> {
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch (e) {
+    return err(`not JSON: ${(e as Error).message}`);
+  }
+  if (!isObject(json))
+    return err("expected an object with `schema`, `citations` and `dblp`");
+  if (json["schema"] !== LOOKUP_CACHE_SCHEMA)
+    return err(
+      `schema ${String(json["schema"])}: this paperlint reads schema ${String(LOOKUP_CACHE_SCHEMA)}`,
+    );
+  const extra = unknownField(json, ["schema", "citations", "dblp"]);
+  if (extra !== undefined) return err(`unknown field \`${extra}\``);
+  const citations = sectionOf(
+    "citations",
+    json["citations"],
+    ["fetched", "response"],
+    cachedResponse,
+  );
+  if (!citations.ok) return citations;
+  const dblp = sectionOf(
+    "dblp",
+    json["dblp"],
+    ["fetched", "title", "hits"],
+    cachedDblp,
+  );
+  if (!dblp.ok) return dblp;
+  return ok({ citations: citations.value, dblp: dblp.value });
+}
+
+const sorted = <T>(m: ReadonlyMap<string, T>): Record<string, T> =>
+  Object.fromEntries([...m.keys()].sort().map((k) => [k, m.get(k) as T]));
+
+/** The cache as the file holds it: keys sorted, so one new answer is a small diff. */
+export const serializeLookupCache = (c: LookupCache): string =>
+  `${JSON.stringify(
+    {
+      schema: LOOKUP_CACHE_SCHEMA,
+      citations: sorted(c.citations),
+      dblp: sorted(c.dblp),
+    },
+    null,
+    2,
+  )}\n`;