paperlint 8.0.0 → 9.0.0

package/scripts/check.ts

@@ -30,8 +30,10 @@
  *
  * ── NO `--fast` FLAG, ON PURPOSE ───────────────────────────────────────────────────────────
  * A subset flag re-creates the exact failure above: the cheap half gets run and reported as
- * "the gates". The slow steps instead SKIP LOUDLY when their prerequisite is genuinely absent
- * (no TeX, no network), and the tail names every skip. "I ran check" then means one thing.
+ * "the gates". Every gate runs with CI=true, as in CI, so a local check is the CI check: the e2e
+ * steps are strict (`test/e2e/need.ts`) — a missing prerequisite (no TeX) FAILS with what to
+ * install, as it does in CI — and a test that still skips is named in the tail, never counted as a
+ * pass. "I ran check" then means one thing.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, rmSync } from "node:fs";
@@ -293,7 +295,9 @@ function runEach(
       cwd: ROOT,
       stdio: "inherit",
       encoding: "utf8",
-      env: { ...process.env, PATH: BIN_FIRST_PATH },
+      // CI=true, as CI runs every gate: libraries read it (typescript-eslint infers a single run and
+      // parses from disk), so without it a local check is not the CI check (2026-10-07).
+      env: { ...process.env, CI: "true", PATH: BIN_FIRST_PATH },
     });
     // 🔴 The exit code is read from the command itself, never from a pipe. `cmd | tail && …`
     // reports the FILTER's status, which is almost always zero — that is how a red harness

package/scripts/coverage-config.test.ts

@@ -21,7 +21,7 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { globSync, readFileSync } from "node:fs";
-import { dirname, join, matchesGlob, resolve } from "node:path";
+import { basename, dirname, join, matchesGlob, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
 import ts from "typescript";
@@ -146,16 +146,23 @@ test("every typeOnly exclusion has no runtime code", () => {
 });
 
 test("every evalOnly exclusion is imported only by an eval or another evalOnly module", () => {
-  const evalOnly = new Set(expand(CONFIG.evalOnly).map((f) => join(ROOT, f)));
+  const only = expand(CONFIG.evalOnly);
+  const evalOnly = new Set(only.map((f) => join(ROOT, f)));
+  // Any import of one names it — `./x.mjs`, `#lib/x` — so a source whose text holds none of their
+  // base names imports none of them, and only the others are parsed.
+  const names = only.map((f) => basename(f).replace(/\.[^.]+$/, ""));
   const sources = globSync("**/*.{mjs,ts}", {
     cwd: ROOT,
     exclude: (p) => p === "node_modules" || p === "dist" || p === "coverage",
   });
   const importers = sources.flatMap((f) => {
     const abs = join(ROOT, f);
-    return importedPaths(abs, readFileSync(abs, "utf8"))
-      .filter((target) => evalOnly.has(target))
-      .map(() => f);
+    const text = readFileSync(abs, "utf8");
+    return names.some((n) => text.includes(n))
+      ? importedPaths(abs, text)
+          .filter((target) => evalOnly.has(target))
+          .map(() => f)
+      : [];
   });
   const outsiders = importers.filter(
     (f) => !f.endsWith(".eval.mjs") && !evalOnly.has(join(ROOT, f)),
@@ -258,11 +265,13 @@ test("no measured source carries a coverage-ignore comment", () => {
   // The scan covers exactly what c8 measures: the same set, derived from the tracked files.
   assert.deepEqual(files, trackedSources().filter(isMeasured));
   assert.ok(files.length > 0);
-  const offenders = files.filter((f) =>
-    comments(f, readFileSync(join(ROOT, f), "utf8")).some((c) =>
-      IGNORE.test(c),
-    ),
-  );
+  // An ignore comment's text matches IGNORE, so a source whose text does not holds none, and only
+  // the others have their comments read off the tree.
+  const offenders = files
+    .map((f) => [f, readFileSync(join(ROOT, f), "utf8")] as const)
+    .filter(([, text]) => IGNORE.test(text))
+    .filter(([f, text]) => comments(f, text).some((c) => IGNORE.test(c)))
+    .map(([f]) => f);
   assert.deepEqual(offenders, []);
 });
 

package/scripts/layer-legacy-frozen.test.ts

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import { test } from "vitest";
 import {
   checkFrozen,
+  filesToLint,
   FROZEN_FILE,
   judge,
   main,
@@ -164,8 +165,9 @@ test("main: problems are listed and fail; a clean count passes", async () => {
   );
 });
 
-// Lints the whole of src/ with the real config: ~3 s alone, 5.6 s measured under c8 with the
-// suite running in parallel — past vitest's 5 s default, so the budget is stated here.
+// Loads the real config (about 2.5 s) and lints the src/ files that carry a directive (21 of 223),
+// measured 2026-10-07: 5.5 s alone, 10–11 s under c8 — past vitest's 5 s default, so the budget is
+// stated here. Linting all of src/ took 22–23 s under c8 and timed out with the suite in parallel.
 test(
   "checkFrozen on this repository: nothing new, nothing grown — and on a tree with no src/, ESLint refuses loudly",
   {
@@ -186,6 +188,43 @@ test(
   },
 );
 
+test("filesToLint: every src/ file whose text carries an eslint-disable directive, in any form — and no other", () => {
+  const root = useTempDir("layer-frozen-files-");
+  writeTree(root, {
+    "src/line.ts": "export const a = 1; // eslint-disable-line no-console\n",
+    "src/next.ts":
+      "// eslint-disable-next-line no-console\nexport const b = 1;\n",
+    "src/block.ts": "/* eslint-disable no-console */\nexport const c = 1;\n",
+    "src/deep/inner.ts":
+      "// eslint-disable-next-line x -- why\nexport const d = 1;\n",
+    "src/plain.ts": "export const e = 1;\n",
+    "lib/outside.ts": "// eslint-disable-next-line no-console\n",
+  });
+  assert.deepEqual(filesToLint(root), [
+    "src/block.ts",
+    "src/deep/inner.ts",
+    "src/line.ts",
+    "src/next.ts",
+  ]);
+});
+
+test("checkFrozen with the real ESLint on a tree: a new legacy directive in a file the list does not name still fails", async () => {
+  const root = useTempDir("layer-frozen-real-");
+  writeTree(root, {
+    [FROZEN_FILE]: JSON.stringify({ files: {} }),
+    "eslint.config.mjs":
+      'export default [{ files: ["src/**/*.ts"], rules: { "no-restricted-globals": ["error", "process"] } }];\n',
+    "src/plain.ts": "export const quiet = 1;\n",
+    "src/new.ts": `// eslint-disable-next-line no-restricted-globals -- ${IO}\nexport const env = process;\n`,
+  });
+  const r = await checkFrozen(root);
+  assert.deepEqual(r.counts, { "src/new.ts": { "no-restricted-globals": 1 } });
+  assert.match(
+    r.problems.join("\n"),
+    /^src\/new\.ts: a new legacy layer exemption/,
+  );
+});
+
 test("checkFrozen: a lint that returns no result reports that nothing was counted", async () => {
   const root = useTempDir("layer-frozen-empty-");
   writeTree(root, {

package/scripts/layer-legacy-frozen.ts

@@ -32,10 +32,15 @@
  * counted by construction — and a range directive (`/* eslint-disable … *\/` around a multi-line
  * import) counts exactly what it silences.
  *
+ * ESLint lints only the files that can carry one (`filesToLint`): a suppressed finding comes from a
+ * directive, and every directive's text holds `eslint-disable` (`-line`, `-next-line`, the block
+ * form). The bulk-suppressions file is not applied here. So the narrowing drops only files that
+ * cannot add to the count — 21 of 223 today — and the count still comes from ESLint's report.
+ *
  * Run: `node scripts/layer-legacy-frozen.ts` (also part of `npm run check`)
  */
 import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
-import { readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ESLint } from "eslint";
@@ -195,11 +200,35 @@ function layerLint(cwd: string): ESLint {
   });
 }
 
+/**
+ * The `src/**\/*.ts` files of `root` whose text holds `eslint-disable` — every file that can carry a
+ * suppressed finding — relative to `root`, POSIX separators, sorted.
+ */
+export function filesToLint(root: string): string[] {
+  const src = join(root, "src");
+  const all = readdirSync(src, { recursive: true, withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".ts"))
+    .map((e) => join(e.parentPath, e.name));
+  return all
+    .filter((f) => readFileSync(f, "utf8").includes("eslint-disable"))
+    .map((f) => relative(root, f).split(sep).join("/"))
+    .sort();
+}
+
+/**
+ * The files ESLint lints: those that can carry a suppression, or — when there are none, or no
+ * `src/` — the whole glob, so ESLint itself refuses a tree with no source.
+ */
+const lintTargets = (root: string): string[] => {
+  const narrowed = existsSync(join(root, "src")) ? filesToLint(root) : [];
+  return narrowed.length > 0 ? narrowed : ["src/**/*.ts"];
+};
+
 /** Lint `src/` with the repository's configuration and run the whole check. */
 export async function checkFrozen(
   root: string = ROOT,
   {
-    lint = (cwd: string) => layerLint(cwd).lintFiles(["src/**/*.ts"]),
+    lint = (cwd: string) => layerLint(cwd).lintFiles(lintTargets(cwd)),
   }: { lint?: (cwd: string) => Promise<readonly Suppressed[]> } = {},
 ): Promise<FrozenCheck> {
   const data = FrozenFile.parse(

package/skills/grade-paper-writing/SKILL.md

@@ -4,7 +4,7 @@ description: Use when asking "does this paper read well?" / "is the writing any
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill]
 ---
 
-<!-- vigiles:sha256:6401b9117bbf899f compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:21c8899648c9b223 compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
 
 # grade-paper-writing — grade how the paper READS, then fix it sentence by sentence
 
@@ -222,8 +222,9 @@ is what happened.
    node ${CLAUDE_SKILL_DIR}/prose-lint.mjs --headings <paper-dir>/paper.tex  # the headings as a set
    ```
 
-   It measures the prose a reader sees — includes spliced, no preamble, comments, floats or inline
-   `.bib` — so its rates are the paper's, not the source file's. The skill is what must ACT on it.
+   It measures the prose a reader sees — the files the last build read spliced in, no preamble,
+   comments, floats or inline `.bib` — so its rates are the paper's, not the source file's. Run
+   `npx paperlint build` first: with no current build record it reads `paper.tex` alone and says so. The skill is what must ACT on it.
    Its thresholds are sourced; a FLAG means the text sits above a published human or machine
    baseline, which is a defect with a number attached, not an opinion.
    Two entries in `THRESHOLDS` exist because this skill previously ran five times without either

package/skills/grade-paper-writing/SKILL.md.spec.ts

@@ -228,8 +228,9 @@ is what happened.
    node \${CLAUDE_SKILL_DIR}/prose-lint.mjs --headings <paper-dir>/paper.tex  # the headings as a set
    \`\`\`
 
-   It measures the prose a reader sees — includes spliced, no preamble, comments, floats or inline
-   \`.bib\` — so its rates are the paper's, not the source file's. The skill is what must ACT on it.
+   It measures the prose a reader sees — the files the last build read spliced in, no preamble,
+   comments, floats or inline \`.bib\` — so its rates are the paper's, not the source file's. Run
+   \`npx paperlint build\` first: with no current build record it reads \`paper.tex\` alone and says so. The skill is what must ACT on it.
    Its thresholds are sourced; a FLAG means the text sits above a published human or machine
    baseline, which is a defect with a number attached, not an opinion.
    Two entries in \`THRESHOLDS\` exist because this skill previously ran five times without either

package/skills/grade-paper-writing/prose-lint.mjs

@@ -11,7 +11,9 @@
  * `8127 words` against ~4636 real ones — and every metric here is a fraction of that count, so all
  * of them came out understated by about half and printed `ok`. `paperProse` (src/paper-prose.ts)
  * gives the body as the `tex/register` rule reads it: includes spliced, the abstract to the back
- * matter, no headings, captions, floats, code or citation marks.
+ * matter, no headings, captions, floats, code or citation marks. The files spliced in are the ones the
+ * paper's last build recorded TeX reading (`_build/sources.json`); a paper with no current record is
+ * read as `paper.tex` alone, and the run says so on stderr rather than print rates of half a paper.
  *
  * A `.txt` is the text of the rendered PDF — the page a reviewer actually reads.
  *
@@ -21,8 +23,10 @@
  * Advisory: it prints findings; `--flags-only` exits with code 1 if anything was found.
  */
 import { paperProse } from "#src/paper-prose";
+import { paperRecord } from "#src/paper-record";
 import { latexReader } from "#src/adapters/latex/index";
 import { nodeFiles } from "#src/adapters/node/index";
+import { sourcesCodec } from "#src/adapters/sources-record/index";
 import { texToMdast } from "#eslint-rules/latex-language";
 
 const THRESHOLDS = {
@@ -481,9 +485,14 @@ const flagsOnly = args.includes("--flags-only");
 let flagged = 0;
 for (const f of args.filter((a) => !a.startsWith("--"))) {
   const raw = fs.readFileSync(f, "utf8");
+  const deps = { files: nodeFiles, latex: latexReader, codec: sourcesCodec };
   const tex = f.endsWith(".tex")
-    ? paperProse(path.resolve(f), raw, { files: nodeFiles, latex: latexReader })
+    ? paperProse(path.resolve(f), raw, deps)
     : null;
+  if (tex && paperRecord(path.dirname(path.resolve(f)), deps).kind !== "fresh")
+    console.error(
+      `prose-lint: ${f} has no current build record (_build/sources.json), so only paper.tex was read, not the files it includes — run \`npx paperlint build\` first`,
+    );
   // 🔴 NOTHING LEFT IS NOT "CLEAN". A body that strips to no words used to be analysed anyway: every
   // metric is a fraction of the word count, so the report printed NaN, FLAGged three metrics and
   // exited 0. Refused — no number is better than a meaningless one. The test is on sentences: a

package/skills/grade-paper-writing/prose-lint.test.ts

@@ -8,6 +8,8 @@ import { join } from "node:path";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expect, test } from "vitest";
+import { cpSync } from "node:fs";
+import { layRecord, recordedTree } from "../../test/recorded-fixture.ts";
 import { runNode, useTempDir, writeTree } from "../../test/support.ts";
 
 const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "prose-lint.mjs");
@@ -17,16 +19,17 @@ const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "prose-lint.mjs");
  */
 const SPAWN_LATEX_MS = 60_000;
 /** An accepted paper whose bibliography sits inline in `filecontents`, beside a long preamble. */
-const ACCEPTED = join(
+const ACCEPTED_DIR = join(
   dirname(fileURLToPath(import.meta.url)),
   "..",
   "..",
   "fixtures",
   "accepted-papers",
   "agenticdev-acm26",
-  "paper.tex",
 );
 const root = useTempDir("prose-lint-");
+/** The accepted paper as a build left it: a copy with TeX's record laid at `_build/sources.json`. */
+const ACCEPTED = join(root, "accepted", "paper.tex");
 
 const LONG_CAPTION_SENTENCE = Array.from(
   { length: 45 },
@@ -37,7 +40,7 @@ const LONG_CAPTION_SENTENCE = Array.from(
 const tex = (body: string): string =>
   `\\documentclass{article}\n\\begin{document}\n${body}\n\\end{document}\n`;
 
-writeTree(root, {
+const TREE = {
   "p/paper.tex": tex(
     "\\section{Introduction}\nIn this paper we present a linter. It might possibly help.\n\\input{figures/fig1}\n\\input{figures/fig2}\n\\input{figures/fig4}\n\\input{figures/fig5}",
   ),
@@ -66,7 +69,36 @@ writeTree(root, {
   "page.txt":
     "A rendered page. It was hyphen-\nated across a line.\n\n12\n\fNext page text here.\nReferences\n[1] cut here.\n",
   "notes.rtf": "not a paper",
-});
+};
+/** What each paper's last build read: its paper.tex, and the files it includes. */
+const READ: Readonly<Record<string, readonly string[]>> = {
+  p: [
+    "paper.tex",
+    "figures/fig1.tex",
+    "figures/fig2.tex",
+    "figures/fig4.tex",
+    "figures/fig5.tex",
+  ],
+  clean: ["paper.tex"],
+  inline: ["paper.tex", "sec/results.tex"],
+  commented: ["paper.tex"],
+  "ends-on-marks": ["paper.tex"],
+  empty: ["paper.tex"],
+};
+writeTree(
+  root,
+  Object.entries(READ).reduce<Record<string, string>>(
+    (tree, [dir, files]) =>
+      recordedTree(
+        tree,
+        dir,
+        files.map((path) => ({ path, role: "body" as const })),
+      ),
+    TREE,
+  ),
+);
+cpSync(ACCEPTED_DIR, join(root, "accepted"), { recursive: true });
+layRecord(join(root, "accepted"), join(ACCEPTED_DIR, "tex-truth.json"));
 
 test("no arguments: the usage line, exit 0", () => {
   assert.deepEqual(runNode(SCRIPT), {
@@ -157,6 +189,22 @@ test("--flags-only: a paper with no figures directory is clean, exit 0 and silen
   );
 });
 
+test("🔴 a paper no build has recorded is read as paper.tex alone, and the run says so", () => {
+  writeTree(root, {
+    "unbuilt/paper.tex": tex("Short and plain. Nothing else."),
+  });
+  const file = join(root, "unbuilt", "paper.tex");
+  const r = runNode(SCRIPT, ["--flags-only", file]);
+  assert.deepEqual(
+    { status: r.status, stdout: r.stdout, stderr: r.stderr },
+    {
+      status: 0,
+      stdout: "",
+      stderr: `prose-lint: ${file} has no current build record (_build/sources.json), so only paper.tex was read, not the files it includes — run \`npx paperlint build\` first\n`,
+    },
+  );
+});
+
 test("a .tex with no prose in its body is refused with exit 2, not reported as NaN", () => {
   const file = join(root, "empty", "paper.tex");
   assert.deepEqual(runNode(SCRIPT, [file]), {

package/skills/paper-pipeline/scripts/extract-ref-facts.harness.mjs

@@ -9,7 +9,7 @@
  * 🔴 THREE MEASUREMENTS HERE — THESE ARE THREE DEFECTS THAT LIVED THE ENTIRE LIFE OF THE PREDECESSOR. Each
  * is pinned by an assertion on a REAL repository file, not a fixture, because all three
  * held exactly because nobody ever passed the real file:
- *   1. `refs.bib` was not in the list of sources (`resolveSource`);
+ *   1. `refs.bib` was never opened;
  *   2. the regex `.bib` required `}` on a separate line and gave 0 entries on both our files;
  *   3. in `.bib` an author is written "LastName, FirstName", but comparison took the last token.
  *
@@ -39,11 +39,18 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { bibReader } from "#src/adapters/bibtex/index";
+import { absolutePath } from "#src/domain/paths";
+import { sha256Hex } from "#src/domain/sha256";
+import { serializeSourcesRecord } from "#src/domain/sources-record";
 import { consumerRoot } from "./consumer.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = consumerRoot();
 const X = await import(join(HERE, "extract-ref-facts.mjs"));
+/** The facts' entries of a BibTeX text, read by the one bibtex reader. */
+const factsOf = (text) =>
+  X.factEntries(bibReader.readFile(absolutePath("/p/refs.bib"), text));
 
 // 🔴 PAPERS ROOT — FROM THE DECLARATION, NOT BY THE FIRST CONSUMER'S DIRECTORY NAME (12.09.2026).
 // `package.json` → `paperlint.papersDir`, default `papers`. The same key is read by
@@ -70,38 +77,71 @@ const REAL_PAPERS = existsSync(PAPERS_ROOT)
   : [];
 
 const TMP = realpathSync(mkdtempSync(join(tmpdir(), "extract-ref-facts-")));
+
+/**
+ * What `paperlint build` leaves in a paper's folder (`_build/sources.json`): bibtex opened `refs.bib`.
+ * The paper is read through that record and refused without it, so every paper here is built first.
+ */
+function built(dir) {
+  const digest = (name) => sha256Hex(readFileSync(join(dir, name)));
+  mkdirSync(join(dir, "_build"), { recursive: true });
+  writeFileSync(
+    join(dir, "_build", "sources.json"),
+    serializeSourcesRecord({
+      schema: 1,
+      inputs: [
+        { path: "paper.tex", role: "body" },
+        { path: "refs.bib", role: "preamble" },
+      ],
+      written: [],
+      bibdata: ["refs"],
+      bibtex: {
+        ran: true,
+        databases: ["refs.bib"],
+        keys: [],
+        exit: 0,
+        errors: [],
+      },
+      sha256: {
+        "paper.tex": digest("paper.tex"),
+        "refs.bib": digest("refs.bib"),
+      },
+    }),
+  );
+}
 // Cleanup is attached IMMEDIATELY: assertions throw, and "rmSync at end of file" does not execute precisely in those
 // runs that are red.
 process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
 
-// ── 1. DEFECT #1: `refs.bib` must be in the list of sources ─────────────────
+// ── 1. DEFECT #1: the `.bib` a paper declares is opened ──────────────────────
+//
+// The build recorded that bibtex opened `refs.bib`, and `bibliographyAt` opens it. A fixture paper
+// holds the frozen real `.bib`, so the leg is proven on a real file in every checkout.
 {
-  assert.ok(
-    X.SOURCE_ORDER.includes("refs.bib"),
-    `refs.bib missing from SOURCE_ORDER — this is the defect that kept the .bib leg from ever opening: ${X.SOURCE_ORDER.join(", ")}`,
+  const dir = join(TMP, "declares-real-bib");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "paper.tex"),
+    "\\documentclass{article}\\begin{document}x\\bibliography{refs}\\end{document}\n",
   );
-  // 🔴 SUBJECT — FIXTURE, real papers ADDITION (12.09.2026). There used to be only a loop over
-  // our two papers with `continue` if file doesn't exist. In this repo they exist, and test is green;
-  // in the extracted pipeline their directories WON'T EXIST — both loops make no iteration, and
-  // harness prints success having checked zero files. "Green over void", a class this base has paid for thrice. Fixture makes an empty run INEXPRESSIBLE: it always lies nearby.
-  //
-  // ⚠️ Directory, not file: `resolveSource` returns the path itself if it IS A FILE, and only for
-  // a directory descends the `SOURCE_ORDER`. A fixture-file would check the wrong branch.
-  {
-    const dir = join(HERE, "fixtures", "real-bib");
-    assert.equal(
-      X.resolveSource(dir),
-      join(dir, "refs.bib"),
-      "resolveSource cannot find the frozen real .bib — .bib leg is dead again",
-    );
-  }
+  writeFileSync(
+    join(dir, "refs.bib"),
+    readFileSync(join(HERE, "fixtures", "real-bib", "refs.bib")),
+  );
+  built(dir);
+  const found = X.bibliographyFrom(dir);
+  assert.deepEqual(
+    found.ok && found.texts.map((t) => t.path),
+    [join(dir, "refs.bib")],
+    `a paper declaring \\bibliography{refs} does not open its refs.bib — the .bib leg is dead again: ${JSON.stringify(found.why ?? "")}`,
+  );
+  // Real consumer papers: whatever each declares is either read or refused WITH A REASON — never a
+  // silent nothing.
   for (const paper of REAL_PAPERS) {
-    const dir = join(PAPERS_ROOT, paper);
-    if (!existsSync(join(dir, "refs.bib"))) continue;
-    assert.equal(
-      X.resolveSource(dir),
-      join(dir, "refs.bib"),
-      `resolveSource cannot find real refs.bib for ${paper} — .bib leg is dead again`,
+    const r = X.bibliographyFrom(join(PAPERS_ROOT, paper));
+    assert.ok(
+      r.ok ? r.texts.length > 0 : r.why.length > 0,
+      `${paper}: neither a bibliography nor a reason`,
     );
   }
 }
@@ -128,7 +168,7 @@ process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
     parsed++;
     const text = readFileSync(f, "utf8");
     const want = (text.match(/^@\w+\{/gm) ?? []).length;
-    const got = await X.parseBib(text);
+    const got = factsOf(text);
     assert.ok(
       want > 0,
       `${paper}/refs.bib: no @… entries in file — fixture is broken`,
@@ -170,7 +210,7 @@ process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
 @misc{inst2,
   author={{sh-guard contributors}},
   title={Another}, year={2026}}`;
-  const es = await X.parseBib(bib);
+  const es = factsOf(bib);
   assert.deepEqual(
     es.map((e) => e.authors),
     [["Adversa AI"], ["sh-guard contributors"]],
@@ -185,7 +225,7 @@ process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
 // single brace — ordinary author, and order "LastName, FirstName" must be unwound.
 {
   const bib = `@misc{human, author={Adversa, Alice}, title={T}, year={2026}}`;
-  const [e] = await X.parseBib(bib);
+  const [e] = factsOf(bib);
   assert.deepEqual(
     e.authors,
     ["Alice Adversa"],
@@ -201,7 +241,7 @@ process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
   const bib = `@inproceedings{k1,
   author={Jimenez, Carlos E. and Di Penta, Massimiliano and others},
   title={A Title}, booktitle={ICLR}, year={2024}, note={arXiv:2310.06770}}`;
-  const [e] = await X.parseBib(bib);
+  const [e] = factsOf(bib);
   assert.deepEqual(
     e.authors,
     ["Carlos E. Jimenez", "Massimiliano Di Penta"],
@@ -313,7 +353,12 @@ process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
   const { spawnSync } = await import("node:child_process");
   const dir = join(TMP, "empty");
   mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "paper.tex"),
+    "\\documentclass{article}\\begin{document}x\\bibliography{refs}\\end{document}\n",
+  );
   writeFileSync(join(dir, "refs.bib"), "% no entries at all\n");
+  built(dir);
   const r = spawnSync(
     "node",
     [join(HERE, "extract-ref-facts.mjs"), dir, "--offline"],
@@ -346,8 +391,8 @@ process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
   );
   assert.equal(r.status, 1);
   assert.ok(
-    /refs\.bib/u.test(r.stderr),
-    "message must list sources, including refs.bib",
+    /no paper\.tex/u.test(r.stderr),
+    `message must say what is missing: ${r.stderr}`,
   );
 }
 
@@ -360,6 +405,11 @@ process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
     "@misc{lovelace2025,\n  author={Lovelace, Ada and Hopper, Grace},\n  title={A Study},\n" +
     "  note={arXiv:2503.09002},\n  year={2025}}\n";
   writeFileSync(join(dir, "refs.bib"), paper);
+  writeFileSync(
+    join(dir, "paper.tex"),
+    "\\documentclass{article}\\begin{document}x\\bibliography{refs}\\end{document}\n",
+  );
+  built(dir);
   writeFileSync(
     join(dir, "repro", "refs-cache.json"),
     JSON.stringify({
@@ -390,6 +440,6 @@ process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
 }
 
 console.log(
-  "✓ extract-ref-facts: refs.bib in sources, both real .bib parse completely, name order unwound, " +
+  "✓ extract-ref-facts: the declared refs.bib is opened, both real .bib parse completely, name order unwound, " +
     "arXiv-DOI does not go to CrossRef, registry readers run on raw bodies, zero entries = refusal",
 );