paperlint 3.2.0 → 4.1.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

@@ -2,12 +2,12 @@
  * `adapters/banal/index.ts` — banal as the two ports the app sees. What `run.test.ts` checks in
  * banal's own terms is checked here as the domain receives it: a `Geometry` whose provenance names
  * banal and the rule that found it, a reason that is one line of text, a `Ready` that says what was
- * verified. In-memory ports throughout; the real banal is `test/e2e/banal.ts`.
+ * verified. In-memory ports throughout; the real banal is `test/e2e/tex/banal.e2e.ts`.
  */
 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

@@ -7,13 +7,13 @@
  * (`Error: Failed to run pdftohtml`, measured); told a version below 0.85 it applies a larger
  * correction and every font size moves. So `$PDFTOHTML` (banal's own override, line 166) points at a
  * stub that answers `-v` with `XML_DIALECT.version` — the pdftohtml whose XML `xml.ts` writes — and
- * refuses anything else. `test/e2e/banal.ts` shows both failures with the real banal.
+ * refuses anything else. `test/e2e/tex/banal.e2e.ts` shows both failures with the real banal.
  */
 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/output.test.ts

@@ -1,6 +1,6 @@
 /**
  * `output.ts` — every way a banal run can end, as a table of `ProcessExit` → `Result`, and the
- * measurement → geometry projection. Pure: no perl, no disk. The real banal is `test/e2e/banal.ts`.
+ * measurement → geometry projection. Pure: no perl, no disk. The real banal is `test/e2e/tex/banal.e2e.ts`.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";

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

@@ -1,7 +1,7 @@
 /**
  * `adapters/banal/run.ts` — running and installing banal, on in-memory ports: which `Command` it builds, what it stages,
  * what it downloads and writes, and what it concludes. No perl, no disk, no network: the adapters
- * record, and each assertion reads the record. Real perl and the real banal are `test/e2e/banal.ts`;
+ * record, and each assertion reads the record. Real perl and the real banal are `test/e2e/tex/banal.e2e.ts`;
  * the adapters' own behaviour is `src/adapters/node/*.test.ts`.
  */
 import assert from "node:assert/strict";
@@ -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 });
 }
 

package/src/adapters/banal/settings.ts

@@ -9,7 +9,7 @@ import {
   type Environment,
   type HostDirs,
 } from "../../domain/host.ts";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, type AbsolutePath } from "../../domain/paths.ts";
 
 /** An explicit banal to use instead of paperlint's (a path to the script). */
 export const BANAL_ENV = "BANAL";
@@ -29,7 +29,7 @@ export interface BanalSettings {
 
 /** `resolve` with an absolute base never consults the process's cwd. */
 const absolute = (cwd: string, p: string): AbsolutePath =>
-  resolve(cwd, p) as AbsolutePath;
+  absolutePath(resolve(cwd, p));
 
 /** An unset variable and an empty one mean the same: not set. */
 const set = (v: string | undefined): string | null => (v ? v : null);

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

@@ -4,7 +4,7 @@
  *
  * Every page here is written by hand. The real-PDF half — pdf.js boxes of a committed fixture,
  * written as XML, measured by the real banal and compared with banal on real pdftohtml — is
- * `test/e2e/banal.ts`, which runs where `paperlint toolchain` has installed banal.
+ * `test/e2e/tex/banal.e2e.ts`, which runs where `paperlint toolchain` has installed banal.
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";

package/src/adapters/curl/download.test.ts

@@ -15,18 +15,18 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterAll as after, test } from "vitest";
-import type { AbsolutePath } from "../../domain/paths.ts";
+import { absolutePath, joinPath } from "../../domain/paths.ts";
 import { curlDownload, curlFailure } from "./download.io.ts";
 import type { ProcessExit } from "../../ports/process.ts";
 import { spawnProcess } from "../node/index.ts";
 
-const root = realpathSync(
-  mkdtempSync(join(tmpdir(), "paperlint-download-test-")),
+const root = absolutePath(
+  realpathSync(mkdtempSync(join(tmpdir(), "paperlint-download-test-"))),
 );
 after(() => {
   rmSync(root, { recursive: true, force: true });
 });
-const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
+const at = (...p: string[]) => joinPath(root, ...p);
 
 const dl = (env: Record<string, string>) => {
   const tmp = at("dl-tmp");