paperlint 3.2.0 → 4.0.0

package/skills/tighten-paper/SKILL.md.spec.ts

@@ -10,30 +10,10 @@ export default experimental_skill({
   name: "tighten-paper",
   description:
     "Use when a paper \"feels long / bloated / overly complex / hard to read / doesn't deliver its point / the middle drags\" — or after review rounds deposited hedge-mass. The developmental / editorial pass on a DRAFTED paper: what a real human editor thinks reading it cover to cover — the ONE point, does every section earn its place, can it be SKIMMED, is it too long for its contribution, which sections are TMI that belong in the artifact/appendix, does the conclusion pay off the intro's promise. Produces a structural verdict + a concrete cut / fold / merge / reorder plan — NOT sentence fixes. Its verdict is a required INPUT to pc-panel-review and a hard gate in harden-paper. NOT sentence craft or a writing grade (grade-paper-writing), NOT jargon stalls (the persona stall pass), NOT scientific defects (pc-panel-review / paper-adversarial-review). Run it BEFORE those on a bloated draft — no point polishing sentences in a section that should be cut.",
-  tools: [
-    "Read",
-    "Write",
-    "Edit",
-    "Grep",
-    "Glob",
-    "Agent",
-    "Bash(node .claude/skills/paper-pipeline/scripts/announce.mjs:*)",
-    "Bash(node .claude/skills/paper-pipeline/scripts/ledger.mjs:*)",
-  ],
+  tools: ["Read", "Write", "Edit", "Grep", "Glob", "Agent"],
   body: `
 # tighten-paper — the developmental edit
 
-## Run me
-
-🔴 FIRST, before any other step:
-
-\`\`\`
-node .claude/skills/paper-pipeline/scripts/announce.mjs tighten-paper <paper-dir>
-\`\`\`
-
-An advisory pass cannot be observed failing — silence is both its error state and its normal
-state — so starting is an event, and events get written down.
-
 Sentence-level passes make a wall of text into readable text. They do **not** tell you the wall shouldn't be there
 at all. This pass is the editor who reads the whole paper once and asks: *is this the right paper, at the right
 length, delivering the right point?* Its deliverable is a **cut/fold/merge/reorder plan and a length verdict**, not
@@ -336,32 +316,6 @@ Produce:
 - **The middle-sag diagnosis** and the fix (consolidate these findings, lead each with its point).
 - **Skim-test failures** (headings/lead-sentences that don't carry the argument).
 
-## Record the verdict
-
-🔴 LAST step, once the deliverable exists:
-
-\`\`\`
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record tighten-paper <paper-dir> FINDING <count> <report-path>
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record tighten-paper <paper-dir> ABSTAINED <reason> "<one line>"
-\`\`\`
-
-**FINDING** is the normal row — \`<count>\` is the number of CUT / FOLD / MERGE / REORDER actions in
-the plan and \`<report-path>\` is the plan itself. Add \`--blocking\` when the paper is over its limit
-and the plan cannot get it under.
-**ABSTAINED** — \`no-witness\`: a cover-to-cover read produced no action at all, which on a real draft
-should be rare. \`blocked\`: the declined pass of the section above — content is still being added, so
-there was nothing to read whole.
-
-🔴 **This is the check with the documented history of never saying no**: a tightening pass once
-returned KEEP on 80 of 81 sections and still counted as run. It is also one of the three failures
-that deleted \`PASS\` — the word made "I read it all and nothing moved" indistinguishable from "I did
-not really read it". \`status.mjs\` reports a check that has never recorded a finding, on the
-mutation-testing principle that a test which kills no mutant is not a test. So an \`ABSTAINED
-no-witness\` here owes a note saying what was read and why nothing moved.
-
-The mechanical half of this skill files separately, under \`tighten-paper/structure\` — one check, one
-row. Do not record a \`structure.mjs\` result here.
-
 ## Compose
 Run this FIRST on a draft that "feels bloated" — before grade-paper-writing / the stall pass / pc-panel, because
 polishing sentences in a section that should be folded to the artifact is wasted work. After the plan is applied,

package/skills/tighten-paper/structure.mjs

@@ -22,7 +22,7 @@
  *
  * ── 2026-08-26, EVENING: BOTH NAMED CONSUMERS ARE CLOSED, AND A THIRD ONE TURNED UP ────────
  *
- * The paragraph above named two callers and said that until they are converted, the ledger writes
+ * The paragraph above named two callers and said that until they are converted, they read
  * "no findings" BY SILENCE. That was true and measured: on `the reference paper/paper.md`
  * `--flags-only` printed 0 lines, while the same bytes through ESLint give **6 findings**
  * (`subsection-size` ×2 · `section-lead` · `free-section-size` ×2 · `block-ungraded`).
@@ -31,11 +31,6 @@
  *       stood next to it, running the same rules over the same glob; a measurement showed a
  *       byte-identical list of files. The full justification is in the comment where the removed
  *       step used to be.
- *   `run-mechanical.mjs`, the `tighten-paper/structure` line → CONVERTED to ESLint
- *       (`read: 'eslint'`, filtered by the rules from `eslint-rules/paper-structure.mjs`). Not
- *       deleted: ESLint writes nothing into the ledger, and the ledger is the only place where the
- *       fact "somebody looked at this paper's structure on these bytes" is stored with a hash of the
- *       input.
  *
  * 🔴 A THIRD CALLER THE BANNER DID NOT KNOW ABOUT: `.githooks/pre-commit`. It printed nothing and
  * swallowed the exit code through `|| true`. The lesson is exactly the one already recorded in
@@ -294,11 +289,9 @@ const freeTotal = freeSections.reduce((a, r) => a + r.words, 0);
 // edit, and there is nothing to settle the question of which one is right.
 
 if (flagsOnly) {
-  // Silence and exit code 0 — ALWAYS. Deliberately not one line on stdout/stderr:
-  // `run-mechanical.mjs` reads this mode as `read: 'flags'`, that is, "non-empty output = a
-  // finding", and a pointer saying "the checks have moved" would turn into a permanent false finding
-  // in the ledger. The limitation of this mode is named in the banner at the top; it is cured by
-  // converting both callers to `npx eslint`, not here.
+  // Silence and exit code 0 — ALWAYS. Deliberately not one line on stdout/stderr: a caller that
+  // reads "non-empty output = a finding" would turn a pointer saying "the checks have moved" into a
+  // permanent false finding. The limitation of this mode is named in the banner at the top.
   process.exit(0);
 }
 

package/skills/verify-citations/SKILL.md

@@ -4,21 +4,10 @@ description: Verify every citation is a real work with correct metadata, and tha
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Agent]
 ---
 
-<!-- vigiles:sha256:3a7e10662d0084c4 compiled from skills/verify-citations/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:fe3634eb63db5c0d compiled from skills/verify-citations/SKILL.md.spec.ts -->
 
 # verify-citations — every cite real, the delta explicit
 
-## Run me
-
-🔴 FIRST, before any other step:
-
-```
-node .claude/skills/paper-pipeline/scripts/announce.mjs verify-citations <paper-dir>
-```
-
-An advisory pass cannot be observed failing — silence is both its error state and its normal
-state — so starting is an event, and events get written down.
-
 Reviewers reject on a single fabricated or wrong citation — it reads as either sloppiness or a
 hallucinated bibliography, and either one is fatal. And they reject on "this was already done by ___" if
 your delta over the nearest prior work isn't spelled out. This skill closes both holes before submit.
@@ -30,8 +19,7 @@ bibliography changes, including the edit you make on the last day. Scorecard row
 `<paper-dir>/PIPELINE-STATUS.md`; see the CONTINUOUS section of `paper-pipeline`.
 
 - **A pass dated before the current text is STALE, and stale reads as green.** The date in the `cites`
-  row is compared against the paper's own mtime, and `../paper-pipeline/scripts/pipeline-check.mjs` reports the
-  mismatch — because a `☑` from three days and forty edits ago is worse than a `☐`: it looks closed.
+  row is compared against the paper's own mtime — because a `☑` from three days and forty edits ago is worse than a `☐`: it looks closed.
 - **"We checked last cycle" does not count.** Say it plainly, because it is the exact sentence that
   ships a fabricated cite: a review round adds text, added text adds citations, and the run that
   cleared the bibliography never saw them.
@@ -294,30 +282,6 @@ therefore being checked for the first time.
 fails CI if any line or branch of them goes unexercised. Run `npx vitest run src/references.test.ts`
 after any edit to the rules.
 
-## 6. Record the verdict
-
-🔴 LAST step, once the deliverable exists:
-
-```
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record verify-citations <paper-dir> FINDING <count> <report-path>
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record verify-citations <paper-dir> ABSTAINED <reason> "<one line>"
-```
-
-**FINDING** — `<count>` is the number of cites still `% VERIFY` or `unresolvable`; `<report-path>`
-lists them. Add `--blocking` for a cite an authoritative source disproves, or a missing delta
-sentence; either is a submit blocker.
-**ABSTAINED** — `no-witness`: every cite resolved with correct metadata and the delta sentence is in
-the prose. `crashed`: the registries were unreachable, so nothing was verified — which is emphatically
-not the same as everything checking out, and under the old vocabulary both came back `PASS`.
-
-🔴 **There is no PASS.** `no-witness` here means every cite the paper makes was looked up and none
-of them came back wrong. It does not mean the bibliography is complete: this check cannot see a work
-that should have been cited and is not. That gap belongs to `map-prior-work`, and no row here covers it.
-
-Because this check is CONTINUOUS, it writes a row per run and never a final one. That is the point:
-the ledger compares the row against the paper's current bytes, so a pass that predates the last three
-`\cite` additions reports as STALE-PAPER instead of reading as green.
-
 ## Rules
 - **Re-run on every `\cite` added or moved.** A `cites` row older than the paper's text is a stale pass,
   not a green one — "we checked last cycle" is not a verification.

package/skills/verify-citations/SKILL.md.spec.ts

@@ -24,17 +24,6 @@ export default experimental_skill({
   body: `
 # verify-citations — every cite real, the delta explicit
 
-## Run me
-
-🔴 FIRST, before any other step:
-
-\`\`\`
-node .claude/skills/paper-pipeline/scripts/announce.mjs verify-citations <paper-dir>
-\`\`\`
-
-An advisory pass cannot be observed failing — silence is both its error state and its normal
-state — so starting is an event, and events get written down.
-
 Reviewers reject on a single fabricated or wrong citation — it reads as either sloppiness or a
 hallucinated bibliography, and either one is fatal. And they reject on "this was already done by ___" if
 your delta over the nearest prior work isn't spelled out. This skill closes both holes before submit.
@@ -46,8 +35,7 @@ bibliography changes, including the edit you make on the last day. Scorecard row
 \`<paper-dir>/PIPELINE-STATUS.md\`; see the CONTINUOUS section of \`paper-pipeline\`.
 
 - **A pass dated before the current text is STALE, and stale reads as green.** The date in the \`cites\`
-  row is compared against the paper's own mtime, and \`../paper-pipeline/scripts/pipeline-check.mjs\` reports the
-  mismatch — because a \`☑\` from three days and forty edits ago is worse than a \`☐\`: it looks closed.
+  row is compared against the paper's own mtime — because a \`☑\` from three days and forty edits ago is worse than a \`☐\`: it looks closed.
 - **"We checked last cycle" does not count.** Say it plainly, because it is the exact sentence that
   ships a fabricated cite: a review round adds text, added text adds citations, and the run that
   cleared the bibliography never saw them.
@@ -310,30 +298,6 @@ therefore being checked for the first time.
 fails CI if any line or branch of them goes unexercised. Run \`npx vitest run src/references.test.ts\`
 after any edit to the rules.
 
-## 6. Record the verdict
-
-🔴 LAST step, once the deliverable exists:
-
-\`\`\`
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record verify-citations <paper-dir> FINDING <count> <report-path>
-node .claude/skills/paper-pipeline/scripts/ledger.mjs record verify-citations <paper-dir> ABSTAINED <reason> "<one line>"
-\`\`\`
-
-**FINDING** — \`<count>\` is the number of cites still \`% VERIFY\` or \`unresolvable\`; \`<report-path>\`
-lists them. Add \`--blocking\` for a cite an authoritative source disproves, or a missing delta
-sentence; either is a submit blocker.
-**ABSTAINED** — \`no-witness\`: every cite resolved with correct metadata and the delta sentence is in
-the prose. \`crashed\`: the registries were unreachable, so nothing was verified — which is emphatically
-not the same as everything checking out, and under the old vocabulary both came back \`PASS\`.
-
-🔴 **There is no PASS.** \`no-witness\` here means every cite the paper makes was looked up and none
-of them came back wrong. It does not mean the bibliography is complete: this check cannot see a work
-that should have been cited and is not. That gap belongs to \`map-prior-work\`, and no row here covers it.
-
-Because this check is CONTINUOUS, it writes a row per run and never a final one. That is the point:
-the ledger compares the row against the paper's current bytes, so a pass that predates the last three
-\`\\cite\` additions reports as STALE-PAPER instead of reading as green.
-
 ## Rules
 - **Re-run on every \`\\cite\` added or moved.** A \`cites\` row older than the paper's text is a stale pass,
   not a green one — "we checked last cycle" is not a verification.

package/src/adapters/banal/failure.ts

@@ -59,9 +59,8 @@ function missing(m: BanalMissing): string {
 
 type Kind = BanalFailure["kind"];
 /** One sentence-writer per variant. A mapped type over `kind`, so a new variant without one is a compile error. */
-type Describers = {
-  readonly [K in Kind]: (f: Extract<BanalFailure, { kind: K }>) => Lines;
-};
+type FailureOf = { readonly [K in Kind]: Extract<BanalFailure, { kind: K }> };
+type Describers = { readonly [K in Kind]: (f: FailureOf[K]) => Lines };
 
 const orNone = (s: string): string => s || "no output";
 
@@ -101,15 +100,15 @@ const DESCRIBE: Describers = {
 };
 
 /**
- * What to tell a person. Most failures are one line; a sha256 mismatch shows both hashes.
- *
- * The one assertion below narrows the table's entry for `f.kind` to a function of `f`: the mapped
- * type already pairs each kind with its own variant, and TypeScript cannot correlate the index with
- * the argument on its own.
+ * The describer for `kind`, applied to its own variant. Generic over the kind, so the table's entry
+ * and the argument are correlated through `FailureOf[K]` and need no assertion (TypeScript#47109).
  */
+const describeKind = <K extends Kind>(kind: K, f: FailureOf[K]): Lines =>
+  DESCRIBE[kind](f);
+
+/** What to tell a person. Most failures are one line; a sha256 mismatch shows both hashes. */
 export function describe(f: BanalFailure): Lines {
-  const write = DESCRIBE[f.kind] as (f: BanalFailure) => Lines;
-  return write(f);
+  return describeKind(f.kind, f);
 }
 
 /** `describe` as one line, for a caller that has a single line to fill. */

package/src/adapters/banal/index.test.ts

@@ -7,7 +7,7 @@
 import assert from "node:assert/strict";
 import { test } from "vitest";
 import { whyNoGeometry } from "../../domain/geometry.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { ProcessExit } from "../../ports/process.ts";
 import { sha256Hex } from "../../domain/sha256.ts";
 import {
@@ -21,7 +21,7 @@ import type { Ready } from "../../ports/tool-installer.ts";
 import { banalInstaller, banalMeasurer, parseBanalSettings } from "./index.ts";
 
 const dirs = { home: "/h", tmp: "/t", cwd: "/r" };
-const project = "/r" as AbsolutePath;
+const project = absolutePath("/r");
 const MEASURED =
   '{"papersize":[792,612],"columns":2,"bodyfontsize":9,"pages":[{},{"type":"bib","reffontsize":7}]}';
 

package/src/adapters/banal/index.ts

@@ -14,7 +14,8 @@ import type { Geometry, Provenance } from "../../domain/geometry.ts";
 import type { AbsolutePath } from "../../domain/paths.ts";
 import { err, ok } from "../../domain/result.ts";
 import type { MeasureGeometry } from "../../ports/measure-geometry.ts";
-import type { Ready, ToolInstaller } from "../../ports/tool-installer.ts";
+import { ready, type Ready } from "../../domain/ready.ts";
+import type { ToolInstaller } from "../../ports/tool-installer.ts";
 import { describe } from "./failure.ts";
 import { provenanceLabel, type BanalCandidate } from "./locate.ts";
 import { pinLabel, type BanalSource } from "./pin.ts";
@@ -65,15 +66,12 @@ export function banalMeasurer(
 }
 
 /** The one place banal's `Ready` is minted: from an `Installed`, whose `PinnedBanal` only run.ts mints. */
-const ready = (i: Installed): Ready => {
-  // Widened by annotation: the brand of the path is not part of `Ready`'s shape.
-  const where: string = i.banal.path;
-  return {
-    where,
+const readyOf = (i: Installed): Ready =>
+  ready({
+    where: i.banal.path,
     fresh: i.fresh,
     verified: "sha256 verified, and it measured a probe page",
-  } as Ready;
-};
+  });
 
 /**
  * banal as the `ToolInstaller` port: download at the pin, check the sha256, accept by measuring a
@@ -91,12 +89,12 @@ export function banalInstaller(
         ...(source ? { source } : {}),
         onDownload: report,
       });
-      return r.ok ? ok(ready(r.value)) : err(describe(r.error));
+      return r.ok ? ok(readyOf(r.value)) : err(describe(r.error));
     },
     check() {
       const r = checkBanal(d, s, source);
       return r.ok
-        ? ok(ready({ banal: r.value, fresh: false }))
+        ? ok(readyOf({ banal: r.value, fresh: false }))
         : err(describe(r.error));
     },
   };

package/src/adapters/banal/install.ts

@@ -15,14 +15,19 @@ export interface ShaMismatch {
   readonly got: Sha256;
 }
 
+// The brand's one owner: the predicate IS the pin check, so no assertion is needed to mint the type.
+const isPinned = (
+  bytes: Uint8Array,
+  source: BanalSource,
+): bytes is PinnedBytes => sha256Hex(bytes) === source.sha256;
+
 export function verifyPin(
   bytes: Uint8Array,
   source: BanalSource,
 ): Result<PinnedBytes, ShaMismatch> {
-  const got = sha256Hex(bytes);
-  return got === source.sha256
-    ? ok(bytes as PinnedBytes)
-    : err({ expected: source.sha256, got });
+  return isPinned(bytes, source)
+    ? ok(bytes)
+    : err({ expected: source.sha256, got: sha256Hex(bytes) });
 }
 
 /** What is installed, judged against the pin. */

package/src/adapters/banal/invocation.test.ts

@@ -11,15 +11,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll as after, test } from "vitest";
 import { nodeAdapters } from "../node/index.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
+import type { Scratch } from "../../ports/workspace.ts";
 import {
   banalCommand,
+  parseShQuoted,
   shQuote,
   stage,
   stageBanalInput,
-  type StagedInput,
 } from "./invocation.ts";
-import type { LocatedBanal } from "./locate.ts";
 import { XML_DIALECT } from "./xml.ts";
 
 test("the staging holds BOTH files: the XML and the -v stub answering the dialect paperlint writes", () => {
@@ -32,11 +32,14 @@ test("the staging holds BOTH files: the XML and the -v stub answering the dialec
 });
 
 test("banalCommand: perl runs banal on the staged .xml, with $PDFTOHTML quoted", () => {
-  const banal = {
-    path: "/b/banal" as AbsolutePath,
-    provenance: { kind: "cache" },
-  } as LocatedBanal;
-  const staged = { xml: "/s/paper.xml", stub: "/s d/pdftohtml" } as StagedInput;
+  // A scratch that places the two files in different directories, one with a space.
+  const scratch: Scratch = {
+    dir: absolutePath("/s"),
+    write: (name) =>
+      absolutePath(name === "paper.xml" ? "/s/paper.xml" : "/s d/pdftohtml"),
+  };
+  const staged = stage(scratch, stageBanalInput([]));
+  const banal = { path: absolutePath("/b/banal") };
   const c = banalCommand(banal, staged, { PATH: "/bin" });
   assert.deepEqual(
     [c.file, ...c.args],
@@ -50,6 +53,15 @@ test("shQuote survives a single quote", () => {
   assert.equal(shQuote("it's"), `'it'"'"'s'`);
 });
 
+test("parseShQuoted refuses a word the shell would split or expand", () => {
+  assert.equal(parseShQuoted(`'a b'`), `'a b'`);
+  assert.throws(() => parseShQuoted("a b"), /not one single-quoted shell word/);
+  assert.throws(
+    () => parseShQuoted(`'a'b'`),
+    /not one single-quoted shell word/,
+  );
+});
+
 const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-stage-test-")));
 after(() => {
   rmSync(root, { recursive: true, force: true });

package/src/adapters/banal/invocation.ts

@@ -13,7 +13,7 @@ import type { Opaque } from "ts-essentials";
 import type { AbsolutePath } from "../../domain/paths.ts";
 import type { Command } from "../../ports/process.ts";
 import type { Scratch } from "../../ports/workspace.ts";
-import type { LocatedBanal } from "./locate.ts";
+import type { BanalCandidate } from "./locate.ts";
 import type { PageLayout } from "../../domain/page-layout.ts";
 import { pdf2xml, XML_DIALECT } from "./xml.ts";
 
@@ -23,9 +23,19 @@ export const BANAL_RUN_MS = 120_000;
 /** A path quoted for `/bin/sh`. Minted by `shQuote` only. */
 export type ShQuoted = Opaque<string, "ShQuoted">;
 
+// One single-quoted word: any run of non-quotes, each quote spelled `'"'"'`. What `shQuote` writes.
+const SH_QUOTED = /^'(?:[^']|'"'"')*'$/;
+const isShQuoted = (s: string): s is ShQuoted => SH_QUOTED.test(s);
+
+/** A word already quoted for `/bin/sh`, checked; anything else throws. */
+export function parseShQuoted(s: string): ShQuoted {
+  if (!isShQuoted(s)) throw new Error(`not one single-quoted shell word: ${s}`);
+  return s;
+}
+
 /** banal interpolates `$PDFTOHTML` into a shell command unquoted — so the value is quoted here. */
 export const shQuote = (s: string): ShQuoted =>
-  `'${s.replace(/'/g, `'"'"'`)}'` as ShQuoted;
+  parseShQuoted(`'${s.replace(/'/g, `'"'"'`)}'`);
 
 /** The stub standing in for `pdftohtml`: it answers `-v` and refuses to convert anything. */
 export const PDFTOHTML_STUB = [
@@ -64,11 +74,15 @@ export const stageBanalInput = (
   ],
 });
 
+// Not exported: only `stage` can write the property, so only it can make a StagedInput.
+const STAGED = Symbol("StagedInput");
+
 /** The staging written to disk. Minted by `stage` only: both files written, or nothing returned. */
-export type StagedInput = Opaque<
-  { readonly xml: AbsolutePath; readonly stub: AbsolutePath },
-  "StagedInput"
->;
+export interface StagedInput {
+  readonly xml: AbsolutePath;
+  readonly stub: AbsolutePath;
+  readonly [STAGED]: true;
+}
 
 /** Write a staging into a scratch directory, the stub executable. The only minter of `StagedInput`. */
 export function stage(s: Scratch, staging: BanalStaging): StagedInput {
@@ -76,12 +90,13 @@ export function stage(s: Scratch, staging: BanalStaging): StagedInput {
   return {
     xml: s.write(xml.name, xml.content, xml.mode),
     stub: s.write(stub.name, stub.content, stub.mode),
-  } as StagedInput;
+    [STAGED]: true,
+  };
 }
 
 /** `perl banal -no-time -json <xml>`, with `$PDFTOHTML` quoted by construction. */
 export function banalCommand(
-  banal: LocatedBanal,
+  banal: Pick<BanalCandidate, "path">,
   staged: StagedInput,
   baseEnv: Readonly<Record<string, string>>,
 ): Command {

package/src/adapters/banal/locate.test.ts

@@ -1,13 +1,13 @@
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import { err } from "../../domain/result.ts";
 import { installedBanal, lookupOrder, pickBanal } from "./locate.ts";
 import { BANAL_PIN } from "./pin.ts";
 import { parseBanalSettings } from "./settings.ts";
 
 const dirs = { home: "/h", tmp: "/t", cwd: "/w" };
-const project = "/p" as AbsolutePath;
+const project = absolutePath("/p");
 const cache = `/h/.cache/paperlint/banal/${BANAL_PIN.commit.slice(0, 12)}/banal`;
 const on =
   (...files: string[]) =>

package/src/adapters/banal/locate.ts

@@ -3,9 +3,7 @@
  * `$BANAL` (an explicit choice — if it names nothing, there is NO fallback), `<project>/vendor/banal`
  * (a project that vendors its own copy), then the one `paperlint toolchain` installed.
  */
-import { join } from "node:path";
-import type { Opaque } from "ts-essentials";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { joinPath, type AbsolutePath } from "../../domain/paths.ts";
 import { err, ok, type Result } from "../../domain/result.ts";
 import { BANAL_PIN } from "./pin.ts";
 import type { BanalSettings } from "./settings.ts";
@@ -20,14 +18,20 @@ export interface BanalCandidate {
   readonly provenance: Provenance;
 }
 
-/** A candidate the `Files` port confirmed is a file. Minted by `pickBanal` only. */
-export type LocatedBanal = Opaque<BanalCandidate, "LocatedBanal">;
+// Not exported: only this module can write the property, so only `locate` can make a LocatedBanal.
+const LOCATED = Symbol("LocatedBanal");
 
-/**
- * `paperlint toolchain`'s banal after its bytes hashed to the pin AND it measured the probe page. Minted by
- * `ensureBanal` / `checkBanal` only (`./index.ts`): a "ready" line cannot be printed without one.
- */
-export type PinnedBanal = Opaque<BanalCandidate, "PinnedBanal">;
+/** A candidate the `Files` port confirmed is a file. Minted by `pickBanal` (through `locate`) only. */
+export type LocatedBanal = BanalCandidate & { readonly [LOCATED]: true };
+
+/** `path` as a banal to run — when the `Files` port says it is a file, else null. */
+function locate(
+  path: AbsolutePath,
+  kind: Provenance["kind"],
+  isFile: (p: AbsolutePath) => boolean,
+): LocatedBanal | null {
+  return isFile(path) ? { path, provenance: { kind }, [LOCATED]: true } : null;
+}
 
 /** Why there is no banal to run. */
 export type BanalMissing =
@@ -47,7 +51,7 @@ export type LookupOrder =
 
 /** Where `paperlint toolchain` puts the pinned banal: one directory per HotCRP commit. */
 export const installedBanal = (s: BanalSettings): AbsolutePath =>
-  join(s.cacheDir, BANAL_PIN.commit.slice(0, 12), "banal") as AbsolutePath;
+  joinPath(s.cacheDir, BANAL_PIN.commit.slice(0, 12), "banal");
 
 export function lookupOrder(
   s: BanalSettings,
@@ -56,25 +60,27 @@ export function lookupOrder(
   if (s.explicit) return { kind: "explicit", path: s.explicit };
   return {
     kind: "search",
-    vendor: join(projectRoot, "vendor", "banal") as AbsolutePath,
+    vendor: joinPath(projectRoot, "vendor", "banal"),
     cache: installedBanal(s),
   };
 }
 
-const located = (path: AbsolutePath, kind: Provenance["kind"]) =>
-  ok({ path, provenance: { kind } } as LocatedBanal);
-
 export function pickBanal(
   order: LookupOrder,
   isFile: (p: AbsolutePath) => boolean,
 ): Result<LocatedBanal, BanalMissing> {
-  if (order.kind === "explicit")
-    return isFile(order.path)
-      ? located(order.path, "env")
+  if (order.kind === "explicit") {
+    const own = locate(order.path, "env", isFile);
+    return own
+      ? ok(own)
       : err({ kind: "explicit-not-found", path: order.path });
-  if (isFile(order.vendor)) return located(order.vendor, "vendor");
-  if (isFile(order.cache)) return located(order.cache, "cache");
-  return err({ kind: "not-installed", installed: order.cache });
+  }
+  const found =
+    locate(order.vendor, "vendor", isFile) ??
+    locate(order.cache, "cache", isFile);
+  return found
+    ? ok(found)
+    : err({ kind: "not-installed", installed: order.cache });
 }
 
 /** Which rule found it, as a person reads it. */

package/src/adapters/banal/run.test.ts

@@ -18,7 +18,7 @@ import { checkBanal, ensureBanal, measureGeometry } from "./run.ts";
 import { sha256Hex } from "../../domain/sha256.ts";
 import { installedBanal } from "./locate.ts";
 import { parseBanalSettings } from "./settings.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath } from "../../domain/paths.ts";
 import type { Command, ProcessExit } from "../../ports/process.ts";
 
 const s = parseBanalSettings(
@@ -29,7 +29,7 @@ const noExplicit = parseBanalSettings(
   { PATH: "/bin" },
   { home: "/h", tmp: "/t", cwd: "/w" },
 );
-const project = "/p" as AbsolutePath;
+const project = absolutePath("/p");
 /** What banal prints for the one-page probe. */
 const MEASURED = '{"bodyfontsize": 10.3, "columns": 1, "pages": [{}]}';
 const banalAnswers = (e: ProcessExit) =>

package/src/adapters/banal/run.ts

@@ -44,8 +44,6 @@ import {
   lookupOrder,
   pickBanal,
   type BanalCandidate,
-  type LocatedBanal,
-  type PinnedBanal,
 } from "./locate.ts";
 import {
   geometryOf,
@@ -89,11 +87,14 @@ export type BanalOutcome =
       readonly tried: BanalCandidate | null;
     };
 
-/** Run `banal` on `pages` in a scratch directory that is gone when this returns. */
+/**
+ * Run `banal` on `pages` in a scratch directory that is gone when this returns. It needs the path
+ * only: `measureGeometry` passes the banal `pickBanal` located, `probe` the one whose bytes it verified.
+ */
 function runBanal(
   d: BanalDeps,
   s: BanalSettings,
-  banal: LocatedBanal,
+  banal: Pick<BanalCandidate, "path">,
   pages: readonly PageLayout[],
 ): Result<BanalMeasurement, BanalFailure> {
   return d.workspace.within("paperlint-banal-", (scratch) =>
@@ -148,6 +149,15 @@ function perlRuns(d: BanalDeps, s: BanalSettings): boolean {
   return r.kind === "exited" && r.status === 0;
 }
 
+// Not exported: only `probe` below can write the property, so only it can make a PinnedBanal.
+const PINNED = Symbol("PinnedBanal");
+
+/**
+ * `paperlint toolchain`'s banal after its bytes hashed to the pin AND it measured the probe page. Minted by
+ * `probe` only, for `ensureBanal` / `checkBanal` (`./index.ts`): a "ready" line cannot be printed without one.
+ */
+export type PinnedBanal = BanalCandidate & { readonly [PINNED]: true };
+
 /**
  * Does the installed, pin-verified banal RUN — accepted by measuring the probe page, not by a
  * download's exit code. The one place a `PinnedBanal` is minted; callers verified the bytes first.
@@ -157,13 +167,9 @@ function probe(
   s: BanalSettings,
   path: AbsolutePath,
 ): Result<PinnedBanal, BanalFailure> {
-  const at: BanalCandidate = { path, provenance: { kind: "cache" } };
-  const r = andThen(
-    runBanal(d, s, at as LocatedBanal, [PROBE_PAGE]),
-    acceptProbe,
-  );
+  const r = andThen(runBanal(d, s, { path }, [PROBE_PAGE]), acceptProbe);
   return r.ok
-    ? ok(at as PinnedBanal)
+    ? ok({ path, provenance: { kind: "cache" }, [PINNED]: true })
     : err({ kind: "does-not-run", path, why: r.error });
 }