paperlint 2.0.0

package/skills/verify-citations/verify-citations.eval.mjs

@@ -0,0 +1,19 @@
+/**
+ * verify-citations — the PAID tier: does this skill's description actually fire?
+ *
+ * COLOCATED ON PURPOSE (vigiles decides coverage by placement as of 2026-08-11).
+ * The prompts live in `.claude/lib/skill-trigger-cases.mjs` so all 21 cases
+ * are reviewed as one table where collisions between siblings are visible;
+ * copying them here would recreate the drift that rule exists to prevent.
+ *
+ * Measures recall (fires on its own territory) AND precision (stays quiet on a
+ * colliding sibling's territory), against the REAL `.claude` harness so the skill
+ * competes with every other installed description — an isolated run overstates
+ * recall and understates false positives.
+ *
+ * Costs money; not CI.
+ *   node .claude/skills/verify-citations/verify-citations.eval.mjs [trials]
+ */
+import { runSkillTriggerEval } from "../../lib/skill-eval-kit.mjs";
+
+await runSkillTriggerEval("verify-citations");

package/skills/verify-citations/verify-citations.harness.mjs

@@ -0,0 +1,23 @@
+/**
+ * verify-citations — the free, deterministic tier. No model, no network.
+ *
+ * COLOCATED ON PURPOSE. vigiles decides coverage by PLACEMENT as of 2026-08-11:
+ * a test that merely names a surface no longer counts, because that tier was
+ * crediting surfaces nothing touched. So each skill needs a file inside its own
+ * directory — this one.
+ *
+ * The assertions live in `.claude/lib/skill-checks.mjs` and are CALLED here with
+ * this skill's name. They are not copied: 22 copies of the same checks is the drift that
+ * module exists to avoid. (Until 2026-08-11 this was an env-var side channel into a
+ * 614-line file named after no surface; it is a function call now.)
+ *
+ * What this proves: this skill's frontmatter parses as strict YAML, its declared
+ * tool contract is sane, its pipeline wiring points at scripts that exist, and it
+ * announces/records under ITS OWN identity rather than a sibling's.
+ *
+ * What it does NOT prove: that the skill fires, or that its guidance produces a
+ * good result. Those need a real model — see `verify-citations.eval.mjs`.
+ */
+import { checkSkill } from "../../lib/skill-checks.mjs";
+
+await checkSkill("verify-citations");

package/src/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md — `src/`
+
+The package's TypeScript: the CLI, the build, the toolchain installer, and the measuring that feeds
+the facts file. Loaded when working under `src/`; the repository-wide rules are in the root
+`CLAUDE.md`.
+
+**`src/` is hexagonal on two axes, and the linter enforces both** (`eslint.config.mjs`; fixtures in
+`test/fixtures/layers/`, run by `test/eslint-layers.test.ts`; issue #76).
+
+**Axis A — knowledge. Core means the DOMAIN, not "no I/O".** A file belongs to an adapter when it
+exists because of one external program or format: _if banal / pdf.js / TeX Live / ESLint / Claude
+Code disappeared tomorrow, which files would change? Those are its adapter, wherever they sit
+today._ The domain is what would not change if every one of them were swapped. Purity is not the
+test — a parser for banal's JSON is pure and is still banal's.
+
+| element   | where                  | holds                                                                                                                                                              | may import                                                                                                              |
+| --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `domain`  | `src/domain/`          | values and decisions in the paper's vocabulary                                                                                                                     | `domain`; `ts-essentials`, `node:path`, `node:crypto`                                                                   |
+| `port`    | `src/ports/`           | interfaces **shaped by what the inside needs**, never by what a tool does (Graça: "created to fit the Application Core needs and not simply mimic the tools APIs") | `domain`, `port`; the same three externals                                                                              |
+| `app`     | `src/*.ts`             | use cases over ports; **no I/O defaults** — a use case without its deps does not compile                                                                           | `domain`, `port`, `app`, the package's `.mjs`; Node's `util`/`url`/`module`                                             |
+| `adapter` | `src/adapters/<tool>/` | everything that knows `<tool>` exists, pure parsers included; used through its `index.ts`                                                                          | `domain`, `port`, its own folder, its tool's packages, the package's `.mjs`. **Never** `app`, **never** another adapter |
+| `root`    | `src/cli.ts`           | reads `process.*`, builds adapters, wires ports                                                                                                                    | anything                                                                                                                |
+
+Folders are ELEMENTS of `eslint-plugin-boundaries`, single files are CATEGORIES (`root`, `app`,
+`test`, `io`): v7 matches element patterns as folders. Everyone — tests included — reaches an
+adapter through its `index.ts`; the files inside one adapter import each other freely.
+
+**Axis B — purity.** An effect (disk, process, network, env, clock, TTY) may be written only in
+`src/adapters/<tool>/<x>.io.ts` and `src/cli.ts`. Every other file, adapters' parsers included,
+takes a port. Test: _can a call here fail for a reason not in its arguments?_ Imports are checked
+through the `io` file category in `boundaries/dependencies`; the `process` and `fetch` globals by
+`no-restricted-globals`.
+
+**The legacy app files are held by a ratchet, not exempted.** A site that still breaks either axis
+carries `// eslint-disable-next-line <rule> -- legacy <I/O|layer>, moves behind a port in #76`.
+Unused directives are errors (`reportUnusedDisableDirectives`), so a fixed site must drop its
+comment; the per-file counts are frozen in `scripts/layer-legacy.frozen.json` and checked by
+`scripts/layer-legacy-frozen.mjs` (`npm run check`, CI), which counts ESLint's own
+`suppressedMessages` and fails when a file's count grows, a file not in the list carries one, or
+anything under `src/domain/`, `src/ports/` or `src/adapters/` does. A NEW module that needs the
+world is a new `*.io.ts` in the adapter of the program it talks to — never a new directive.
+
+Parse at the boundary, into types that cannot hold an invalid state (a banal path that exists only
+after its sha256 and probe passed; a `Ready` only an installer mints; an outcome as a discriminated
+union, not a string); the inside never re-validates.
+
+⚠️ **Two settings are load-bearing.** `boundaries/root-path`: without it the plugin matches paths
+against `process.cwd()`, so lint started from any other directory classifies nothing and passes.
+`checkAllOrigins: true`: without it no `module:` policy is evaluated, so axis B and the library bans
+report nothing — dropping it turns the fixtures `src/domain/reads-disk.ts` and
+`src/adapters/one/disk.ts` clean (measured).

package/src/action-ref.test.ts

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { actionRef } from "./action-ref.ts";
+
+/** [the running package's version, the ref `paperlint init` may pin the action to]. */
+const TABLE: readonly (readonly [string | undefined, string | null])[] = [
+  ["1.2.3", "v1.2.3"],
+  ["1.0.0", "v1.0.0"],
+  ["10.20.30", "v10.20.30"],
+  // Guards: a git checkout / `npm link` carries the unreleased placeholder — there is no tag for it.
+  ["0.0.0-semantically-released", null],
+  // Guards: only a plain release is known to have a tag; anything else stays the placeholder.
+  ["1.2.3-beta.1", null],
+  ["v1.2.3", null],
+  ["1.2", null],
+  ["", null],
+  ["latest", null],
+  [" 1.2.3", null],
+  // Guards: the CLI could not read its own manifest — no version, no pin.
+  [undefined, null],
+];
+
+for (const [version, ref] of TABLE)
+  test(`actionRef(${JSON.stringify(version)})`, () => {
+    assert.equal(actionRef(version), ref);
+  });

package/src/action-ref.ts

@@ -0,0 +1,15 @@
+/**
+ * The ref `paperlint init` pins the GitHub Action to, decided from the version of the package that is
+ * running. semantic-release tags every release `v<version>` on the commit it publishes, so the
+ * action at that tag is the same code as the installed package.
+ *
+ * Only a plain `X.Y.Z` has such a tag. A git checkout or `npm link` carries the unreleased
+ * placeholder `0.0.0-semantically-released`, a version that could not be read is `undefined`, and
+ * anything else is not known to be tagged: those return `null` ("no pin known"), and the caller
+ * keeps the placeholder. A wrong tag written confidently is worse than an obvious placeholder.
+ */
+export function actionRef(version: string | undefined): string | null {
+  return version !== undefined && /^\d+\.\d+\.\d+$/.test(version)
+    ? `v${version}`
+    : null;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * `failure.ts` — the one place a sentence about a banal failure is written, and the probe that
+ * accepts a banal by a measurement.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { describe, describeLine, PERL_MISSING } from "./failure.ts";
+import { acceptProbe } from "./probe.ts";
+
+test("describe: perl missing carries the fix", () => {
+  assert.deepEqual(describe({ kind: "perl-missing" }), [PERL_MISSING]);
+  assert.match(PERL_MISSING, /apt-get install perl/);
+});
+
+test("describe: an explicit $BANAL that is not there says so, and nothing else is suggested", () => {
+  // Guards: an explicit choice that is wrong is named, not replaced by "run paperlint toolchain".
+  const [line] = describe({
+    kind: "banal-missing",
+    missing: { kind: "explicit-not-found", path: "/x/banal" },
+  });
+  assert.equal(
+    line,
+    "banal not found: $BANAL names /x/banal, which does not exist",
+  );
+});
+
+test("describe: not installed names where it was looked for and the fix", () => {
+  const [line] = describe({
+    kind: "banal-missing",
+    missing: { kind: "not-installed", installed: "/c/banal" },
+  });
+  assert.equal(
+    line,
+    "banal not found: /c/banal — `npx paperlint toolchain` installs it",
+  );
+});
+
+test("describe: a sha256 mismatch shows both hashes on their own lines", () => {
+  const lines = describe({
+    kind: "sha-mismatch",
+    url: "https://x/banal",
+    expected: "a".repeat(64),
+    got: "b".repeat(64),
+  });
+  assert.equal(lines.length, 3);
+  assert.match(lines[0], /does not have the pinned sha256/);
+  assert.equal(lines[1], `expected ${"a".repeat(64)}`);
+});
+
+test("describeLine: a nonzero exit with no stderr says so", () => {
+  assert.equal(
+    describeLine({ kind: "process-failed", status: 3, stderrHead: "" }),
+    "banal failed (exit 3): no output",
+  );
+});
+
+test("acceptProbe: one page and a body size is accepted; anything else is `probe-rejected`", () => {
+  assert.ok(acceptProbe({ pages: [{}], bodyfontsize: 10.3 }).ok);
+  // Guards: acceptance is a MEASUREMENT — a banal that runs and measures nothing is refused.
+  const r = acceptProbe({ pages: [{}], bodyfontsize: null });
+  assert.equal(!r.ok && r.error.kind, "probe-rejected");
+  assert.equal(acceptProbe({ pages: [], bodyfontsize: 10 }).ok, false);
+});

package/src/adapters/banal/failure.ts

@@ -0,0 +1,118 @@
+/**
+ * Every way getting a measurement from banal can fail, as ONE union — and `describe`, the only
+ * place a sentence about it is written. Callers branch on `kind`; nobody parses a message.
+ */
+import type { Lines } from "../../domain/text.ts";
+import type { BanalMissing } from "./locate.ts";
+
+export type { BanalMissing } from "./locate.ts";
+
+export type BanalFailure =
+  | { readonly kind: "perl-missing" }
+  | { readonly kind: "banal-missing"; readonly missing: BanalMissing }
+  | {
+      readonly kind: "process-failed";
+      readonly status: number;
+      readonly stderrHead: string;
+    }
+  | {
+      readonly kind: "signalled";
+      readonly signal: string;
+      readonly stderrHead: string;
+    }
+  | { readonly kind: "spawn-failed"; readonly message: string }
+  | { readonly kind: "timed-out"; readonly afterMs: number }
+  | { readonly kind: "no-json"; readonly head: string }
+  /** banal's own `{"error": true}` — printed with exit 0 for an input it could not read. */
+  | { readonly kind: "banal-error"; readonly stderrHead: string }
+  | { readonly kind: "unexpected-shape"; readonly issues: readonly string[] }
+  | { readonly kind: "probe-rejected"; readonly got: unknown }
+  | {
+      readonly kind: "download-failed";
+      readonly url: string;
+      readonly detail: string;
+    }
+  | {
+      readonly kind: "sha-mismatch";
+      readonly url: string;
+      readonly expected: string;
+      readonly got: string;
+    }
+  /** The installed file is there, and is not the pin. */
+  | { readonly kind: "not-pinned"; readonly path: string }
+  /** The installed, pinned banal did not measure the probe page. */
+  | {
+      readonly kind: "does-not-run";
+      readonly path: string;
+      readonly why: BanalFailure;
+    };
+
+export const PERL_MISSING =
+  "perl is not installed — banal, the page-geometry script HotCRP runs, is a Perl program. " +
+  "Install perl (Debian/Ubuntu: apt-get install perl; macOS ships it) and run `npx paperlint toolchain`";
+
+function missing(m: BanalMissing): string {
+  return m.kind === "explicit-not-found"
+    ? `banal not found: $BANAL names ${m.path}, which does not exist`
+    : `banal not found: ${m.installed} — \`npx paperlint toolchain\` installs it`;
+}
+
+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;
+};
+
+const orNone = (s: string): string => s || "no output";
+
+const DESCRIBE: Describers = {
+  "perl-missing": () => [PERL_MISSING],
+  "banal-missing": (f) => [missing(f.missing)],
+  "process-failed": (f) => [
+    `banal failed (exit ${String(f.status)}): ${orNone(f.stderrHead)}`,
+  ],
+  signalled: (f) => [`banal failed (${f.signal}): ${orNone(f.stderrHead)}`],
+  "spawn-failed": (f) => [`banal failed: ${f.message}`],
+  "timed-out": (f) => [`banal failed: no answer after ${String(f.afterMs)} ms`],
+  "no-json": (f) => [`banal printed no JSON: ${f.head || "nothing"}`],
+  "banal-error": (f) => [
+    `banal could not read the banal input XML: ${f.stderrHead}`,
+  ],
+  "unexpected-shape": (f) => [
+    `banal printed JSON that is not a measurement: ${f.issues.join("; ")}`,
+  ],
+  "probe-rejected": (f) => [
+    `banal ran on a one-page probe but measured nothing: ${JSON.stringify(f.got)}`,
+  ],
+  "download-failed": (f) => [
+    `could not download banal from ${f.url}: ${f.detail}`,
+  ],
+  "sha-mismatch": (f) => [
+    `banal from ${f.url} does not have the pinned sha256 — refusing to install it`,
+    `expected ${f.expected}`,
+    `got      ${f.got}`,
+  ],
+  "not-pinned": (f) => [
+    `banal in ${f.path} is not the pinned one (sha256 differs)`,
+  ],
+  "does-not-run": (f) => [
+    `banal in ${f.path} does not run: ${describeLine(f.why)}`,
+  ],
+};
+
+/**
+ * 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.
+ */
+export function describe(f: BanalFailure): Lines {
+  const write = DESCRIBE[f.kind] as (f: BanalFailure) => Lines;
+  return write(f);
+}
+
+/** `describe` as one line, for a caller that has a single line to fill. */
+export function describeLine(f: BanalFailure): string {
+  return describe(f).join("; ");
+}

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

@@ -0,0 +1,119 @@
+/**
+ * `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.mjs`.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { whyNoGeometry } from "../../domain/geometry.ts";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { ProcessExit } from "../../ports/process.ts";
+import { sha256Hex } from "../../domain/sha256.ts";
+import {
+  exitedWith,
+  fixedDownload,
+  memoryFiles,
+  memoryPorts,
+  scriptedProcess,
+} from "../memory/index.ts";
+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 MEASURED =
+  '{"papersize":[792,612],"columns":2,"bodyfontsize":9,"pages":[{},{"type":"bib","reffontsize":7}]}';
+
+/** banal's measurer over in-memory ports: `/own/banal` on "disk", banal answering `exit`. */
+function measurer(env: Record<string, string>, exit?: ProcessExit) {
+  const run = scriptedProcess(() => exit ?? exitedWith(MEASURED));
+  const io = memoryPorts({ run, files: memoryFiles({ "/own/banal": "" }) });
+  return { run, m: banalMeasurer(io, parseBanalSettings(env, dirs), project) };
+}
+
+test("no banal anywhere: unmeasured, and the reason says banal was not found", () => {
+  const g = measurer({}).m.measure([]);
+  assert.match(
+    g.kind === "unmeasured" ? whyNoGeometry(g) : "",
+    /^banal not found: /,
+  );
+});
+
+test("with $BANAL: banal gets the .xml and a quoted $PDFTOHTML, and the geometry is the domain's", () => {
+  const { m, run } = measurer({ BANAL: "/own/banal" });
+  const g = m.measure([]);
+  assert.equal(g.kind, "measured");
+  assert.deepEqual(g.kind === "measured" && g.by, {
+    tool: "banal",
+    path: "/own/banal",
+    how: "$BANAL",
+  });
+  assert.deepEqual(
+    g.kind === "measured" && [g.geometry.columns, g.geometry.bodyPages],
+    [2, 1],
+  );
+  const c = run.calls[0];
+  // Guards: the poppler-free path — banal is handed rpp's XML, never the PDF.
+  assert.match(c?.args.at(-1) ?? "", /\.xml$/);
+  assert.match(c?.env["PDFTOHTML"] ?? "", /^'.*pdftohtml'$/);
+});
+
+test("a failing banal: unmeasured, and the reason names exit, message and source", () => {
+  const { m } = measurer(
+    { BANAL: "/own/banal" },
+    { kind: "exited", status: 3, stdout: "", stderr: "boom\n" },
+  );
+  const g = m.measure([]);
+  // Guards: a banal that runs and fails is not reported as "not found".
+  assert.match(
+    g.kind === "unmeasured" ? whyNoGeometry(g) : "",
+    /^banal failed \(exit 3\): boom \(banal from \$BANAL: \/own\/banal\)$/,
+  );
+});
+
+// ── the installer ───────────────────────────────────────────────────────────────────────
+const BODY = "print qq(...);\n";
+/** What banal prints for the one-page probe — what acceptance requires. */
+const PROBE = '{"bodyfontsize": 10.3, "columns": 1, "pages": [{}]}';
+const source = {
+  url: "https://example.test/banal",
+  sha256: sha256Hex(new TextEncoder().encode(BODY)),
+};
+
+test("installer: ensure reports the download, and Ready says where and what was verified", () => {
+  const io = memoryPorts({
+    run: scriptedProcess((c) =>
+      c.args[0] === "-e" ? exitedWith("") : exitedWith(PROBE),
+    ),
+    download: fixedDownload(BODY),
+  });
+  const i = banalInstaller(io, parseBanalSettings({}, dirs), source);
+  assert.match(i.label, /^banal \d/);
+  const told: string[] = [];
+  const r = i.ensure((l) => told.push(l));
+  assert.ok(r.ok);
+  assert.equal(r.value.fresh, true);
+  assert.match(r.value.where, /\/banal$/);
+  assert.equal(
+    r.value.verified,
+    "sha256 verified, and it measured a probe page",
+  );
+  assert.equal(told.length, 1);
+  assert.equal(i.check().ok, true);
+});
+
+test("installer: a failure is lines of text, the first saying what happened", () => {
+  const io = memoryPorts({
+    run: scriptedProcess(() => ({ kind: "not-found", file: "perl" })),
+  });
+  const r = banalInstaller(io, parseBanalSettings({}, dirs), source).check();
+  assert.ok(!r.ok);
+  assert.match(r.error[0], /perl/);
+});
+
+test("a Ready cannot be written by hand — only an installer mints one", () => {
+  // @ts-expect-error — the brand: a literal is not a Ready (tsc -p tsconfig.test.json checks this line).
+  const forged: Ready = { where: "/x", fresh: true, verified: "trust me" };
+  assert.equal(forged.where, "/x");
+});

package/src/adapters/banal/index.ts

@@ -0,0 +1,100 @@
+/**
+ * banal's adapter — its ENTRY POINT. Everything under `src/adapters/banal/` exists because banal
+ * (HotCRP's page-geometry script, GPL, run as a separate program — see `./run.ts` for the licence
+ * boundary) exists; nothing outside this folder names it. What the rest of paperlint sees is two ports:
+ *
+ *   `banalMeasurer` — `MeasureGeometry`: the page geometry of a paper's text boxes, or why none.
+ *   `banalInstaller` — `ToolInstaller`: `paperlint toolchain`'s banal, pinned, verified and running.
+ *
+ * Both are composites over the generic ports a composition root builds (processes, files, scratch
+ * directories, downloads), so this file is pure; its settings are parsed from the environment value
+ * the root read (`parseBanalSettings`).
+ */
+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 { describe } from "./failure.ts";
+import { provenanceLabel, type BanalCandidate } from "./locate.ts";
+import { pinLabel, type BanalSource } from "./pin.ts";
+import {
+  checkBanal,
+  ensureBanal,
+  measureGeometry,
+  type BanalDeps,
+  type Installed,
+  type InstallDeps,
+} from "./run.ts";
+import type { BanalSettings } from "./settings.ts";
+
+export {
+  BANAL_DIR_ENV,
+  BANAL_ENV,
+  parseBanalSettings,
+  type BanalSettings,
+} from "./settings.ts";
+export type { BanalDeps, InstallDeps } from "./run.ts";
+export type { BanalSource } from "./pin.ts";
+
+/** The domain's provenance for a banal: what the facts file writes, and which rule found it. */
+const provenance = (c: BanalCandidate): Provenance => ({
+  tool: "banal",
+  path: c.path,
+  how: provenanceLabel(c.provenance),
+});
+
+/** banal as the `MeasureGeometry` port: `$BANAL`, the project's `vendor/banal`, then the cache. */
+export function banalMeasurer(
+  d: BanalDeps,
+  s: BanalSettings,
+  projectRoot: AbsolutePath,
+): MeasureGeometry {
+  return {
+    measure(pages): Geometry {
+      const g = measureGeometry(d, s, projectRoot, pages);
+      return g.source === "banal"
+        ? { kind: "measured", by: provenance(g.by), geometry: g.geometry }
+        : {
+            kind: "unmeasured",
+            why: describe(g.why),
+            tried: g.tried ? provenance(g.tried) : null,
+          };
+    },
+  };
+}
+
+/** The one place banal's `Ready` is minted: from an `Installed`, whose `PinnedBanal` only run.ts mints. */
+const ready = (i: Installed): Ready =>
+  ({
+    where: i.banal.path as string,
+    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
+ * probe page. `source` is the pin unless a test passes a local file.
+ */
+export function banalInstaller(
+  d: InstallDeps,
+  s: BanalSettings,
+  source?: BanalSource,
+): ToolInstaller {
+  return {
+    label: pinLabel(),
+    ensure(report) {
+      const r = ensureBanal(d, s, {
+        ...(source ? { source } : {}),
+        onDownload: report,
+      });
+      return r.ok ? ok(ready(r.value)) : err(describe(r.error));
+    },
+    check() {
+      const r = checkBanal(d, s, source);
+      return r.ok
+        ? ok(ready({ banal: r.value, fresh: false }))
+        : err(describe(r.error));
+    },
+  };
+}

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

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { sha256Hex } from "../../domain/sha256.ts";
+import { installedState, verifyPin } from "./install.ts";
+
+const bytes = new TextEncoder().encode("banal");
+const source = { url: "file:///x", sha256: sha256Hex(bytes) };
+
+test("verifyPin: the pinned bytes pass; others are refused with both hashes", () => {
+  assert.ok(verifyPin(bytes, source).ok);
+  const r = verifyPin(new TextEncoder().encode("other"), source);
+  assert.equal(!r.ok && r.error.expected, source.sha256);
+});
+
+test("installedState: absent, other bytes, pinned — one predicate for install and --check", () => {
+  assert.equal(installedState(null, source).kind, "absent");
+  // Guards: the pin is checked on every run — a changed file is not trusted.
+  assert.equal(installedState(new Uint8Array([1]), source).kind, "other-bytes");
+  assert.equal(installedState(bytes, source).kind, "pinned");
+});

package/src/adapters/banal/install.ts

@@ -0,0 +1,41 @@
+/**
+ * The install decisions, on bytes: is what is on disk the pin, and may downloaded bytes be kept.
+ * One predicate for `paperlint toolchain` and `paperlint toolchain --check`, so the two cannot disagree.
+ */
+import type { Opaque } from "ts-essentials";
+import { err, ok, type Result } from "../../domain/result.ts";
+import { sha256Hex, type Sha256 } from "../../domain/sha256.ts";
+import type { BanalSource } from "./pin.ts";
+
+/** Bytes that hash to the pin. Minted by `verifyPin` only; the installer writes nothing else. */
+export type PinnedBytes = Opaque<Uint8Array, "PinnedBytes">;
+
+export interface ShaMismatch {
+  readonly expected: Sha256;
+  readonly got: 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 });
+}
+
+/** What is installed, judged against the pin. */
+export type InstalledState =
+  | { readonly kind: "absent" }
+  | { readonly kind: "other-bytes"; readonly mismatch: ShaMismatch }
+  | { readonly kind: "pinned" };
+
+export function installedState(
+  current: Uint8Array | null,
+  source: BanalSource,
+): InstalledState {
+  if (current === null) return { kind: "absent" };
+  const v = verifyPin(current, source);
+  return v.ok ? { kind: "pinned" } : { kind: "other-bytes", mismatch: v.error };
+}