paperlint 3.1.0 → 3.1.2

package/skills/verify-citations/scripts/verify-cites.mjs

@@ -45,14 +45,22 @@
  *         + a summary line on stderr. Exit 1 iff any verdict is `false`.
  */
 
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, extname } from "node:path";
 import { createHash } from "node:crypto";
-import { consumerContactEmail } from "../../paper-pipeline/scripts/consumer.mjs";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const CACHE_PATH = join(__dirname, ".cite-cache.json");
+import {
+  consumerContactEmail,
+  isMain,
+} from "../../paper-pipeline/scripts/consumer.mjs";
+
+// The command line's cache (`paperlint build` passes its own, per paper, and never reads this file).
+// In the user's cache directory, NOT beside this script: installed, this script sits inside
+// node_modules, which `npm ci` wipes. VERIFY_CITES_CACHE points it elsewhere — how a test keeps the
+// run from writing into the home directory.
+const CACHE_PATH =
+  process.env.VERIFY_CITES_CACHE ||
+  join(homedir(), ".cache", "paperlint", "cite-cache.json");
 // 🔴 THE ADDRESS IS THE CONSUMER'S, NOT OURS. Crossref's "polite pool" keys off this `mailto:`:
 // it decides who gets the faster tier and, more to the point, WHOM THEY WARN before blocking.
 // Hard-coded, it pointed at one person for every user of this package — so the warnings would
@@ -122,11 +130,6 @@ export function titleSimilarity(a, b) {
   return 1 - levenshtein(na, nb) / maxLen;
 }
 
-/** Two titles "match" iff normalized similarity ≥ threshold (default 0.70). */
-export function titlesMatch(a, b, threshold = TITLE_THRESHOLD) {
-  return titleSimilarity(a, b) >= threshold;
-}
-
 /** Normalize a DOI: strip a `doi:` / resolver-URL prefix and any TRAILING sentence
  *  punctuation a .bib or prose extractor swallowed. A trailing `.` makes doi.org
  *  return responseCode 100, so an unnormalized real DOI reads as fabrication (the
@@ -201,7 +204,7 @@ function isAcronymOf(base, words) {
   for (let i = 0; i < words.length; i++) {
     let acr = "";
     for (let j = i; j < words.length && acr.length < base.length; j++) {
-      acr += words[j][0] || "";
+      acr += words[j].charAt(0); // "" for an empty token, like the first letter of nothing
     }
     if (acr === base) return true;
   }
@@ -251,8 +254,7 @@ export function titleRelation(a, b) {
   const sb = scriptsOf(nb);
   if (sa.size && sb.size && ![...sa].some((x) => sb.has(x)))
     return "incomparable";
-  const sim = 1 - levenshtein(na, nb) / Math.max(na.length, nb.length);
-  if (sim >= TITLE_THRESHOLD) return "match";
+  if (titleSimilarity(a, b) >= TITLE_THRESHOLD) return "match";
   const A = contentTokens(na);
   const B = contentTokens(nb);
   if (A.length && B.length) {
@@ -686,50 +688,78 @@ function loadCache() {
 }
 function saveCache(cache) {
   try {
+    mkdirSync(dirname(CACHE_PATH), { recursive: true });
     writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2));
   } catch {
     /* best-effort; a cache write failure must never fail the run */
   }
 }
 
+/**
+ * A title's IDENTITY, for cache keys: case, accents, BibTeX braces and runs of whitespace
+ * normalized, punctuation kept. Not `normalizeTitle`, which drops punctuation so that `Title: Sub`
+ * and `Title - Sub` still COMPARE equal — as a key that would make `C` and `C++` one entry, and
+ * the second would be served the first's answers. A punctuation-only variant costs one extra
+ * lookup instead. The one owner of this rule: DBLP's cache key (the references adapter) uses it too.
+ */
+export function titleIdentity(t) {
+  return (t ?? "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/\p{M}+/gu, "")
+    .replace(/[{}]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
 function titleHash(t) {
-  return createHash("sha1")
-    .update(normalizeTitle(t))
-    .digest("hex")
-    .slice(0, 16);
+  return createHash("sha1").update(titleIdentity(t)).digest("hex").slice(0, 16);
 }
 function cacheKey(kind, val) {
   return `${kind}:${val}`;
 }
 
-async function httpGet(url, { json = true } = {}) {
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+/** One request, classified: rate-limit/outage and other failures → `ok:false`, 404 → `notFound`. */
+async function request(url, json, signal) {
+  const res = await fetch(url, {
+    headers: {
+      "User-Agent": USER_AGENT,
+      Accept: json ? "application/json" : "*/*",
+    },
+    signal,
+  });
+  if (res.status === 429 || res.status >= 500) {
+    return { ok: false, reason: `http ${res.status}` }; // rate-limit / outage
+  }
+  if (res.status === 404) return { ok: true, notFound: true };
+  if (!res.ok) return { ok: false, reason: `http ${res.status}` };
+  const text = await res.text();
+  if (!json) return { ok: true, data: text };
+  // 🔴 A service that is rate-limiting some clients answers 200 with an HTML page instead of JSON
+  // (DBLP does, #110). That is a refusal, named as one — not a parse error to puzzle over.
   try {
-    const res = await fetch(url, {
-      headers: {
-        "User-Agent": USER_AGENT,
-        Accept: json ? "application/json" : "*/*",
-      },
-      signal: ctrl.signal,
-    });
-    if (res.status === 429 || res.status >= 500) {
-      return { ok: false, reason: `http ${res.status}` }; // rate-limit / outage
-    }
-    if (res.status === 404) return { ok: true, notFound: true };
-    if (!res.ok) return { ok: false, reason: `http ${res.status}` };
-    const data = json ? await res.json() : await res.text();
-    return { ok: true, data };
-  } catch (e) {
+    return { ok: true, data: JSON.parse(text) };
+  } catch {
     return {
       ok: false,
-      reason: e.name === "AbortError" ? "timeout" : String(e),
+      reason: text.trimStart().startsWith("<")
+        ? "answered HTML, not JSON"
+        : "answered something that is not JSON",
     };
-  } finally {
-    clearTimeout(timer);
   }
 }
 
+async function httpGet(url, { json = true } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  const result = await request(url, json, ctrl.signal).catch((e) => ({
+    ok: false,
+    reason: e.name === "AbortError" ? "timeout" : String(e),
+  }));
+  clearTimeout(timer);
+  return result;
+}
+
 // Each *Resolver returns a normalized response (the shape classifyResolver eats).
 // A transport failure → { transport:'error' }: degrade to unresolvable, NEVER false.
 
@@ -739,7 +769,7 @@ async function crossrefResolve(citation) {
     const r = await httpGet(
       `https://api.crossref.org/works/${encodeURIComponent(citation.doi)}`,
     );
-    if (!r.ok) return { db, transport: "error" };
+    if (!r.ok) return { db, transport: "error", reason: r.reason };
     if (r.notFound) return { db, transport: "ok", query: "doi", record: null };
     const w = r.data?.message;
     return {
@@ -757,24 +787,22 @@ async function crossrefResolve(citation) {
         : null,
     };
   }
-  if (citation.title) {
-    const url = `https://api.crossref.org/works?query.bibliographic=${encodeURIComponent(
-      citation.title,
-    )}&rows=5`;
-    const r = await httpGet(url);
-    if (!r.ok) return { db, transport: "error" };
-    const items = r.data?.message?.items || [];
-    return {
-      db,
-      transport: "ok",
-      query: "title",
-      records: items.map((w) => ({
-        title: (w.title || [])[0] || "",
-        year: crYear(w),
-      })),
-    };
-  }
-  return null;
+  // Asked only with a DOI or a title (`PAPER_RESOLVERS`), so without a DOI there is a title.
+  const url = `https://api.crossref.org/works?query.bibliographic=${encodeURIComponent(
+    citation.title,
+  )}&rows=5`;
+  const r = await httpGet(url);
+  if (!r.ok) return { db, transport: "error", reason: r.reason };
+  const items = r.data?.message?.items || [];
+  return {
+    db,
+    transport: "ok",
+    query: "title",
+    records: items.map((w) => ({
+      title: (w.title || [])[0] || "",
+      year: crYear(w),
+    })),
+  };
 }
 function crYear(w) {
   return (
@@ -790,7 +818,7 @@ async function openalexResolve(citation) {
     const r = await httpGet(
       `https://api.openalex.org/works/doi:${encodeURIComponent(citation.doi)}`,
     );
-    if (!r.ok) return { db, transport: "error" };
+    if (!r.ok) return { db, transport: "error", reason: r.reason };
     if (r.notFound) return { db, transport: "ok", query: "doi", record: null };
     const w = r.data;
     return {
@@ -802,63 +830,61 @@ async function openalexResolve(citation) {
         : null,
     };
   }
-  if (citation.title) {
-    const r = await httpGet(
-      `https://api.openalex.org/works?search=${encodeURIComponent(citation.title)}&per-page=5`,
-    );
-    if (!r.ok) return { db, transport: "error" };
-    const items = r.data?.results || [];
-    return {
-      db,
-      transport: "ok",
-      query: "title",
-      records: items.map((w) => ({
-        title: w.display_name || "",
-        year: w.publication_year,
-      })),
-    };
-  }
-  return null;
+  // Asked only with a DOI or a title (`PAPER_RESOLVERS`), so without a DOI there is a title.
+  const r = await httpGet(
+    `https://api.openalex.org/works?search=${encodeURIComponent(citation.title)}&per-page=5`,
+  );
+  if (!r.ok) return { db, transport: "error", reason: r.reason };
+  const items = r.data?.results || [];
+  return {
+    db,
+    transport: "ok",
+    query: "title",
+    records: items.map((w) => ({
+      title: w.display_name || "",
+      year: w.publication_year,
+    })),
+  };
 }
 
-async function semanticScholarResolve(citation) {
+const S2 = "https://api.semanticscholar.org/graph/v1/paper";
+
+// By its id when the citation has one, else by the title — the resolvers run only for a citation
+// with at least one of the three, so the title search is given a title.
+const semanticScholarResolve = (citation) =>
+  citation.doi || citation.arxiv
+    ? semanticScholarById(citation)
+    : semanticScholarByTitle(citation.title);
+
+async function semanticScholarById(citation) {
   const db = "semantic_scholar";
-  const base = "https://api.semanticscholar.org/graph/v1/paper";
-  if (citation.doi || citation.arxiv) {
-    const id = citation.doi ? `DOI:${citation.doi}` : `arXiv:${citation.arxiv}`;
-    const r = await httpGet(
-      `${base}/${encodeURIComponent(id)}?fields=title,year`,
-    );
-    if (!r.ok) return { db, transport: "error" };
-    if (r.notFound)
-      return {
-        db,
-        transport: "ok",
-        query: citation.doi ? "doi" : "arxiv",
-        record: null,
-      };
-    const w = r.data;
-    return {
-      db,
-      transport: "ok",
-      query: citation.doi ? "doi" : "arxiv",
-      record: w?.title != null ? { title: w.title || "", year: w.year } : null,
-    };
-  }
-  if (citation.title) {
-    const r = await httpGet(
-      `${base}/search?query=${encodeURIComponent(citation.title)}&fields=title,year&limit=5`,
-    );
-    if (!r.ok) return { db, transport: "error" };
-    const items = r.data?.data || [];
-    return {
-      db,
-      transport: "ok",
-      query: "title",
-      records: items.map((w) => ({ title: w.title || "", year: w.year })),
-    };
-  }
-  return null;
+  const query = citation.doi ? "doi" : "arxiv";
+  const id = citation.doi ? `DOI:${citation.doi}` : `arXiv:${citation.arxiv}`;
+  const r = await httpGet(`${S2}/${encodeURIComponent(id)}?fields=title,year`);
+  if (!r.ok) return { db, transport: "error", reason: r.reason };
+  if (r.notFound) return { db, transport: "ok", query, record: null };
+  const w = r.data;
+  return {
+    db,
+    transport: "ok",
+    query,
+    record: w?.title != null ? { title: w.title || "", year: w.year } : null,
+  };
+}
+
+async function semanticScholarByTitle(title) {
+  const db = "semantic_scholar";
+  const r = await httpGet(
+    `${S2}/search?query=${encodeURIComponent(title)}&fields=title,year&limit=5`,
+  );
+  if (!r.ok) return { db, transport: "error", reason: r.reason };
+  const items = r.data?.data || [];
+  return {
+    db,
+    transport: "ok",
+    query: "title",
+    records: items.map((w) => ({ title: w.title || "", year: w.year })),
+  };
 }
 
 async function arxivResolve(citation) {
@@ -869,26 +895,24 @@ async function arxivResolve(citation) {
       `https://export.arxiv.org/api/query?id_list=${encodeURIComponent(citation.arxiv)}&max_results=1`,
       { json: false },
     );
-    if (!r.ok) return { db, transport: "error" };
+    if (!r.ok) return { db, transport: "error", reason: r.reason };
     const entry = parseArxivFeed(r.data);
     return { db, transport: "ok", query: "arxiv", record: entry[0] ?? null };
   }
-  if (citation.title && !citation.doi) {
-    const r = await httpGet(
-      `https://export.arxiv.org/api/query?search_query=ti:${encodeURIComponent(
-        '"' + citation.title + '"',
-      )}&max_results=5`,
-      { json: false },
-    );
-    if (!r.ok) return { db, transport: "error" };
-    return {
-      db,
-      transport: "ok",
-      query: "title",
-      records: parseArxivFeed(r.data),
-    };
-  }
-  return null;
+  // Asked only with an arXiv id or a title and no DOI (`PAPER_RESOLVERS`).
+  const r = await httpGet(
+    `https://export.arxiv.org/api/query?search_query=ti:${encodeURIComponent(
+      '"' + citation.title + '"',
+    )}&max_results=5`,
+    { json: false },
+  );
+  if (!r.ok) return { db, transport: "error", reason: r.reason };
+  return {
+    db,
+    transport: "ok",
+    query: "title",
+    records: parseArxivFeed(r.data),
+  };
 }
 export function parseArxivFeed(xml) {
   const out = [];
@@ -917,13 +941,12 @@ export function parseArxivFeed(xml) {
  * means "no metadata here"; doi.org responseCode 100 means "this DOI does not
  * exist". Returns { transport, responseCode } for classifyDoiAuthority.
  */
-async function doiAuthorityCheck(citation) {
-  if (!citation.doi) return null;
+async function doiAuthorityCheck(doi) {
   // Keep the DOI's own slashes as path separators; encode the rest.
-  const path = encodeURIComponent(citation.doi.trim()).replace(/%2F/gi, "/");
+  const path = encodeURIComponent(doi.trim()).replace(/%2F/gi, "/");
   const r = await httpGet(`https://doi.org/api/handles/${path}`);
   if (r.notFound) return { transport: "ok", responseCode: 100 }; // 404 = not found
-  if (!r.ok) return { transport: "error" };
+  if (!r.ok) return { transport: "error", reason: r.reason };
   const code = r.data?.responseCode;
   return {
     transport: "ok",
@@ -931,113 +954,230 @@ async function doiAuthorityCheck(citation) {
   };
 }
 
-async function nvdCheck(citation) {
-  if (!citation.cve) return null;
-  if (!isValidCveId(citation.cve)) {
+async function nvdCheck(cve) {
+  if (!isValidCveId(cve)) {
     // Malformed CVE id — treat as a provided-id-that-cannot-resolve (fabrication).
     return { transport: "ok", found: false };
   }
   const r = await httpGet(
     `https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=${encodeURIComponent(
-      citation.cve.toUpperCase(),
+      cve.toUpperCase(),
     )}`,
   );
-  if (!r.ok) return { transport: "error" };
+  if (!r.ok) return { transport: "error", reason: r.reason };
   if (r.notFound) return { transport: "ok", found: false };
   const total = r.data?.totalResults ?? (r.data?.vulnerabilities || []).length;
   return { transport: "ok", found: total > 0 };
 }
 
 /**
- * Verify ONE citation live (with caching). Returns the reduceVerdict result.
- *
- * 🔴 CONTRACT: CALL SEQUENTIALLY. The shared `cache` is read BEFORE the `await` and written AFTER
- * it (three places below), so two concurrent calls sharing the same `cache` will both miss the
- * write and both fall through to the network. This doesn't corrupt the data — the resolvers are
- * deterministic, and the second call writes an equivalent value — but it's extra requests to
- * CrossRef / OpenAlex / Semantic Scholar / arXiv / NVD, i.e. a direct route to a 429, which is
- * exactly why the neighboring `bib-authors.mjs` has 900ms pauses.
- *
- * Today the contract IS HONORED: the only caller is `main()` in this same file (a sequential
- * `for … of` with `await`), so the interleaving `require-atomic-updates` warns about does not
- * exist. The rule is deliberately left at `warn` for that reason: it judges the SHAPE, not the
- * fact of it. But the function IS EXPORTED and takes a shared cache — exactly what gets
- * parallelized via `Promise.all` — so the warning is left visible rather than suppressed. The real
- * fix would be caching UNRESOLVED promises in the cache (in-flight deduplication) rather than
- * values; that's incompatible with the current JSON-based `saveCache()` and so hasn't been done
- * (measured 2026-08-28).
+ * The paper registries, each with the ONE question it asks of a citation: `ask` picks the
+ * identifier (`{ doi }`, `{ arxiv }` or `{ title }`), or `null` when the registry cannot answer this
+ * citation — then it is not called and stores nothing. The resolver is handed ONLY that question,
+ * and the cache key is built from the same question, so the key always names what was asked: arXiv
+ * asked by arXiv id is keyed by it even when the entry also has a DOI, and correcting that id asks
+ * again.
  */
-export async function verifyCitationLive(
-  citation,
-  { cache = {}, offline = false } = {},
-) {
-  citation = normalizeIdentifiers(citation); // clean doi:/arXiv: prefixes + trailing punct first
-  const commitFlags = checkCommit(citation);
-
-  if (offline) {
-    // No network: everything degrades to unresolvable (matches narrowed-false).
-    return reduceVerdict(citation, [], commitFlags);
-  }
+const PAPER_RESOLVERS = [
+  {
+    name: "crossref",
+    fn: crossrefResolve,
+    ask: (c) => (c.doi ? { doi: c.doi } : c.title ? { title: c.title } : null),
+  },
+  {
+    name: "openalex",
+    fn: openalexResolve,
+    ask: (c) => (c.doi ? { doi: c.doi } : c.title ? { title: c.title } : null),
+  },
+  {
+    name: "semantic_scholar",
+    fn: semanticScholarResolve,
+    ask: (c) =>
+      c.doi
+        ? { doi: c.doi }
+        : c.arxiv
+          ? { arxiv: c.arxiv }
+          : { title: c.title },
+  },
+  {
+    name: "arxiv",
+    fn: arxivResolve,
+    // No DOI endpoint: by arXiv id, else a title search — but not for a DOI-only entry.
+    ask: (c) =>
+      c.arxiv
+        ? { arxiv: c.arxiv }
+        : c.title && !c.doi
+          ? { title: c.title }
+          : null,
+  },
+];
+
+/** The cache key of one registry's question: the identifier it was asked by. */
+const paperKey = (name, q) =>
+  cacheKey(
+    name,
+    q.doi
+      ? `doi:${q.doi}`
+      : q.arxiv
+        ? `arxiv:${q.arxiv}`
+        : `title:${titleHash(q.title)}`,
+  );
 
+/**
+ * The evidence for one citation, asked in order through `lookup(key, service, fetch, keep)`, which
+ * decides where each answer comes from (the cache, the network, or nowhere). ONE code path for the
+ * live run and for `wouldAsk`, so the two cannot disagree about which questions a citation asks.
+ *
+ * 🔴 IT STOPS AT THE FIRST MATCH. `reduceVerdict` lets a match win over everything else, so once one
+ * registry has confirmed the work, no further answer can change the verdict — asking Semantic
+ * Scholar after Crossref confirmed a DOI only costs a request, and a rate-limited one at that.
+ */
+async function consult(citation, lookup) {
   const evidence = [];
-
-  // Paper resolvers (skip when the citation is CVE/commit-only).
+  const matched = () => evidence.at(-1)?.status === "matched";
   if (citation.doi || citation.arxiv || citation.title) {
-    const resolvers = [
-      { name: "crossref", fn: crossrefResolve },
-      { name: "openalex", fn: openalexResolve },
-      { name: "semantic_scholar", fn: semanticScholarResolve },
-      { name: "arxiv", fn: arxivResolve },
-    ];
-    for (const { name, fn } of resolvers) {
-      const ck = cacheKey(
+    for (const { name, fn, ask } of PAPER_RESOLVERS) {
+      const question = ask(citation);
+      if (question === null) continue;
+      const resp = await lookup(
+        paperKey(name, question),
         name,
-        citation.doi
-          ? `doi:${citation.doi}`
-          : citation.arxiv
-            ? `arxiv:${citation.arxiv}`
-            : `title:${titleHash(citation.title)}`,
+        () => fn(question),
+        () => true,
       );
-      let resp;
-      if (cache[ck]) {
-        resp = cache[ck];
-      } else {
-        resp = await fn(citation);
-        if (resp && resp.transport === "ok") cache[ck] = resp; // only cache successes
-      }
-      if (resp) evidence.push(classifyResolver(citation, resp));
+      evidence.push(classifyResolver(citation, resp));
+      if (matched()) return evidence;
     }
-
-    // DOI authority (doi.org) — the ONLY source that can disprove a DOI (M1).
-    // Always consulted when a DOI is present so a registry-404 never becomes
-    // `false` without doi.org confirming responseCode 100.
+    // DOI authority (doi.org) — the ONLY source that can disprove a DOI (M1). Consulted whenever no
+    // registry confirmed the DOI, so a registry-404 never becomes `false` without doi.org.
     if (citation.doi) {
-      const ck = cacheKey("doi_authority", citation.doi);
-      let auth = cache[ck];
-      if (!auth) {
-        auth = await doiAuthorityCheck(citation);
-        // Cache only POSITIVE existence; never cache authority-absent (100), so a
-        // freshly-minted DOI checked pre-propagation isn't pinned to `false` on re-run.
-        if (auth && auth.transport === "ok" && auth.responseCode !== 100)
-          cache[ck] = auth;
-      }
-      if (auth) evidence.push(classifyDoiAuthority(auth));
+      const auth = await lookup(
+        cacheKey("doi_authority", citation.doi),
+        "doi_authority",
+        () => doiAuthorityCheck(citation.doi),
+        // Cache only POSITIVE existence; never authority-absent (100), so a freshly-minted DOI
+        // checked pre-propagation isn't pinned to `false` on re-run.
+        (a) => a.responseCode !== 100,
+      );
+      evidence.push(classifyDoiAuthority(auth));
     }
   }
-
-  // CVE via NVD.
   if (citation.cve) {
-    const ck = cacheKey("nvd", citation.cve.toUpperCase());
-    let nvd = cache[ck];
-    if (!nvd) {
-      nvd = await nvdCheck(citation);
-      if (nvd && nvd.transport === "ok") cache[ck] = nvd;
-    }
+    const nvd = await lookup(
+      cacheKey("nvd", citation.cve.toUpperCase()),
+      "nvd",
+      () => nvdCheck(citation.cve),
+      // Cache only POSITIVE existence, as for doi.org: a CVE cited before NVD indexes it must not
+      // be pinned to "not found" in the committed cache. A missing CVE is asked again each build.
+      (a) => a.found,
+    );
     const e = checkNvd(citation, nvd);
     if (e) evidence.push(e);
   }
+  return evidence;
+}
+
+/**
+ * Would verifying `citation` make a request, given `cache`? `paperlint build` asks this BEFORE any
+ * request: when no citation would, the build makes no network request at all, not even its
+ * reachability probe. It walks the same `consult` as the live run, answering from the cache only.
+ */
+export async function wouldAsk(citation, cache) {
+  let missed = false;
+  await consult(normalizeIdentifiers(citation), async (key) => {
+    if (cache[key]) return cache[key];
+    missed = true;
+    return { transport: "error" };
+  });
+  return missed;
+}
+
+/**
+ * A circuit breaker for ONE run, per service. The first request to a service goes alone; until it
+ * has answered, every other request to that service waits for it. Once a service REFUSES — a
+ * transport error, a 429 or 5xx, a timeout, HTML where JSON was asked — it is not asked again for
+ * the rest of the run: every later question to it is answered "refused earlier in this run" at no
+ * cost. A service that refuses from its first request costs ONE request per run, not one per
+ * citation, and not one per retry (#120). One that answers first and starts refusing later costs
+ * at most the requests already in flight when the refusal lands — the caller's concurrency (six in
+ * `paperlint build`). Queueing every request to a service behind the previous one would remove that
+ * margin, at the price of making every cold build sequential per service.
+ *
+ * Nothing about a refusal is remembered past the run: the next run asks again, once.
+ *
+ * `attempt` returns `{ ok: true, value }` or `{ ok: false, reason }`; `call` returns the same shape,
+ * with `reason` saying "refused earlier" when the service was not asked.
+ */
+export function createBreaker() {
+  const state = new Map();
+  const call = async (service, attempt) => {
+    const s = state.get(service);
+    if (s?.refused)
+      return {
+        ok: false,
+        reason: `${service} refused earlier in this run (${s.refused})`,
+      };
+    if (s?.first) {
+      await s.first;
+      return call(service, attempt);
+    }
+    const pending = attempt();
+    if (!s) state.set(service, { first: pending });
+    const r = await pending;
+    if (!r.ok) state.set(service, { refused: r.reason });
+    else if (!s) state.set(service, { answered: true });
+    return r;
+  };
+  return { call };
+}
 
-  return reduceVerdict(citation, evidence, commitFlags);
+/**
+ * Verify ONE citation live (with caching). Returns the reduceVerdict result, plus `refused` —
+ * "<service>: <reason>" for every question that went unanswered — when there were any.
+ *
+ * ⚠️ CONCURRENT CALLS SHARING ONE `cache` MAY ASK TWICE. The cache is read BEFORE the `await` and
+ * written AFTER it, so two concurrent calls for the SAME identifier both miss and both go to the
+ * network. The data does not suffer — the resolvers are deterministic and the second write is
+ * equivalent — the cost is an extra request per duplicate identifier.
+ *
+ * Callers: `main()` here calls it one citation at a time; `paperlint build`'s references step
+ * (`src/adapters/references/index.ts`) calls it six at a time (#107), sharing one `breaker` for the
+ * run. `require-atomic-updates` stays at `warn` because the interleaving it describes exists, and is
+ * accepted for the reason above.
+ */
+export async function verifyCitationLive(
+  citation,
+  { cache = {}, offline = false, breaker = createBreaker() } = {},
+) {
+  citation = normalizeIdentifiers(citation); // clean doi:/arXiv: prefixes + trailing punct first
+  const commitFlags = checkCommit(citation);
+
+  if (offline) {
+    // No network: everything degrades to unresolvable (matches narrowed-false).
+    return reduceVerdict(citation, [], commitFlags);
+  }
+
+  const refused = [];
+  const evidence = await consult(
+    citation,
+    async (key, service, fetch, keep) => {
+      if (cache[key]) return cache[key];
+      const r = await breaker.call(service, async () => {
+        const resp = await fetch();
+        return resp.transport === "ok"
+          ? { ok: true, value: resp }
+          : { ok: false, reason: resp.reason };
+      });
+      if (!r.ok) {
+        refused.push(`${service}: ${r.reason}`);
+        return { db: service, transport: "error" };
+      }
+      if (keep(r.value)) cache[key] = r.value; // only successes are ever cached
+      return r.value;
+    },
+  );
+  const verdict = reduceVerdict(citation, evidence, commitFlags);
+  return refused.length ? { ...verdict, refused } : verdict;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1072,6 +1212,7 @@ async function main() {
   }
 
   const cache = loadCache();
+  const breaker = createBreaker();
   const results = [];
   for (const c of cites) {
     if (!c || !c.id) {
@@ -1083,7 +1224,7 @@ async function main() {
       });
       continue;
     }
-    results.push(await verifyCitationLive(c, { cache, offline }));
+    results.push(await verifyCitationLive(c, { cache, offline, breaker }));
   }
   saveCache(cache);
 
@@ -1103,6 +1244,10 @@ async function main() {
 }
 
 // Run as CLI only when invoked directly (not when imported by the test).
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+// 🔴 `isMain`, not `fileURLToPath(import.meta.url) === process.argv[1]`. The skill runs this file
+// through `.claude/skills/verify-citations`, a symlink; Node reports `import.meta.url` as the
+// realpath and `argv[1]` as the link, so the old comparison was false and the CLI exited 0 having
+// done nothing — a silent PASS for any bibliography. (consumer.mjs `isMain` documents the class.)
+if (isMain(import.meta.url)) {
   main();
 }