@geonosis/ratchet 1.2.0 → 1.4.0

package/README.md

@@ -172,10 +172,17 @@ lines) is refused **even on a clean exit**. `npm ERR!` is not stripped — that
 command never ran, and it must never read as zero. Unset is the default and changes nothing, so a repo that never opts in keeps exactly
 the behaviour it had. Valid values: `unix`, `agent`, `default`.
 
-When a number **grew**, the last ten lines of that counter's command output print under the
+When a number **grew**, up to ten lines of that counter's command output print under the
 `<-- REGRESSED` line, indented — so the report says what grew, not only that something did. A
 counter that reads a file rather than running a command (`lawLineCount`) prints nothing extra.
 
+The lines are the ones the counter says its number came from, not the tail of the run. `oxlintRule`
+cites the findings attributed to ITS rule; `oxlintErrors` cites errors and `oxlintWarnings`
+warnings. The tail was wrong for exactly the run that needs it most: a consumer's +2 on one rule
+printed two unrelated **warnings** as its evidence, because those were the last lines oxlint wrote
+and the two real errors sat higher up. A counter written outside this package that names nothing —
+or that recognises nothing in a run — falls back to the tail, as before.
+
 ### `testFailures` reads the runner's summary, never the exit code
 
 The counter looks for the runner's own count and **refuses when it cannot parse one**. It never
@@ -281,6 +288,19 @@ been shown to work — and this one guards the running time of every other gate.
   nothing more. If a child command needs `NODE_OPTIONS` — a TypeScript shim, a loader — put it on
   the script that invokes `geonosis-ratchet`, not on the counter's own line, and not only in your
   interactive shell.
+- **`NODE_OPTIONS` in the parent script + a counter that shells out to `pnpm` = the counter dies.**
+  The nested `pnpm` INHERITS the option. dielime preloads a TypeScript-5 shim through
+  `NODE_OPTIONS` in its `lint` script; run the ratchet from inside that script and the nested pnpm
+  goes looking for a `.pnpmfile.mjs` that is not there and exits non-zero. The ratchet refuses —
+  correctly, a command that cannot run is never a silent zero — but nothing in the message is near
+  the cause. Run the ratchet outside that script, or unset `NODE_OPTIONS` for the nested call:
+
+  ```json
+  { "counter": "archViolations", "command": "env -u NODE_OPTIONS pnpm --silent verify:arch" }
+  ```
+
+  `geonosis-doctor --only drift` asks for this shape by name: a manifest script carrying
+  `NODE_OPTIONS` beside a counter whose command shells to `pnpm`.
 - **A path in a counter's command must be absolute, or `--prove` cannot run it.** A probe runs in a
   scratch directory with none of your repo in it, so a loader or shim named relatively — `node
   --import ./scripts/ts5-shim.mjs …` — resolves to nothing there and the counter comes back
@@ -423,3 +443,10 @@ npx geonosis-doctor --baseline-against origin/main --strict
 ```
 
 Apache-2.0.
+
+## The pairing rule (#136)
+
+A scoped fast tier (changed files only) is safe exactly when the full tier is TOTAL: every hard cap
+— max-lines, bundle bytes, suppression counts — needs a full-tier counter watching the whole tree,
+or it is a cap in prose that a file can sit over indefinitely. `oxlintRule`, `suppressionCount`,
+`bundleBytes` and friends exist to be that counter.

package/dist/{chunk-LSYVFUP4.js → chunk-ESN6ULZZ.js}

@@ -1,13 +1,76 @@
+// src/core/envelope.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var ENVELOPES_DIR = ".geonosis/envelopes";
+var envelopePath = (root, tool) => join(root, ENVELOPES_DIR, `${tool}.json`);
+var UnbalancedEnvelope = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnbalancedEnvelope";
+  }
+};
+var isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+var unbalancedMessage = (envelope, next) => `${envelope.tool}: considered ${envelope.considered} but accounts for ${envelope.read + envelope.refused.length + envelope.excused.length} \u2014 ${envelope.read} read + ${envelope.refused.length} refused + ${envelope.excused.length} excused. A run that has lost count of its own inputs cannot say what it measured, so no verdict was rendered and no envelope was written. Next: ${next}`;
+var writeEnvelope = ({
+  envelope,
+  next,
+  root
+}) => {
+  if (envelope.tool.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `an envelope with no tool name cannot be filed or reported against. Next: ${next}`
+    );
+  }
+  if (envelope.version.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: an envelope that cannot name the build that wrote it dates nothing, and a stale one reads exactly like a fresh one. Next: ${next}`
+    );
+  }
+  if (!isCount(envelope.considered) || !isCount(envelope.read)) {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: considered ${envelope.considered} and read ${envelope.read} \u2014 a census is a whole number of things, and arithmetic over anything else balances by accident. Next: ${next}`
+    );
+  }
+  if (envelope.considered !== envelope.read + envelope.refused.length + envelope.excused.length) {
+    throw new UnbalancedEnvelope(unbalancedMessage(envelope, next));
+  }
+  const at = envelopePath(root, envelope.tool);
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, `${JSON.stringify(envelope, void 0, 2)}
+`);
+  return at;
+};
+var UNKNOWN = "unknown";
+var versionIn = (dir) => {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var versionOf = (moduleUrl) => {
+  let dir = dirname(fileURLToPath(moduleUrl));
+  for (; ; ) {
+    const found = versionIn(dir);
+    if (found !== void 0) return found;
+    const up = dirname(dir);
+    if (up === dir) return UNKNOWN;
+    dir = up;
+  }
+};
+
 // src/core/lock.ts
 import { randomUUID } from "crypto";
-import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { linkSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "fs";
 import { homedir } from "os";
-import { dirname, join } from "path";
-var heavyLockPath = () => process.env.GEONOSIS_HEAVY_LOCK ?? join(homedir(), ".cache", "geonosis", "heavy.lock");
+import { dirname as dirname2, join as join2 } from "path";
+var heavyLockPath = () => process.env.GEONOSIS_HEAVY_LOCK ?? join2(homedir(), ".cache", "geonosis", "heavy.lock");
 var sleep = (ms) => new Promise((done) => setTimeout(done, ms));
 var holderOf = (path) => {
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
     return typeof parsed.pid === "number" ? {
       cwd: parsed.cwd ?? "somewhere",
       pid: parsed.pid,
@@ -31,7 +94,7 @@ var heldFor = (holder) => {
   return `${Math.round((Date.now() - since) / 1e3)}s`;
 };
 var write = (path) => {
-  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync2(dirname2(path), { recursive: true });
   const mine = {
     cwd: process.cwd(),
     pid: process.pid,
@@ -39,7 +102,7 @@ var write = (path) => {
   };
   const staging = `${path}.${process.pid}.${randomUUID()}`;
   try {
-    writeFileSync(staging, JSON.stringify(mine));
+    writeFileSync2(staging, JSON.stringify(mine));
     linkSync(staging, path);
     return true;
   } catch (error) {
@@ -89,7 +152,7 @@ var acquireExclusive = async ({
 };
 
 // src/core/config.ts
-import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { existsSync, readFileSync as readFileSync3 } from "fs";
 import { resolve } from "path";
 var CONFIG_FILE = "geonosis.ratchet.json";
 var keyOf = (entry) => entry.key ?? entry.counter;
@@ -98,7 +161,7 @@ var loadConfig = (cwd) => {
   if (!existsSync(path)) {
     throw new Error(`no ${CONFIG_FILE} in ${cwd} \u2014 the ratchet has nothing to count`);
   }
-  const parsed = JSON.parse(readFileSync2(path, "utf8"));
+  const parsed = JSON.parse(readFileSync3(path, "utf8"));
   if (!Array.isArray(parsed.counters)) {
     throw new Error(`${CONFIG_FILE} has no "counters" array`);
   }
@@ -124,6 +187,14 @@ var loadConfig = (cwd) => {
   }
   return { baseline: parsed.baseline ?? "gate-baseline.json", counters: parsed.counters };
 };
+var resolveBaseline = (cwd) => {
+  try {
+    const parsed = JSON.parse(readFileSync3(resolve(cwd, CONFIG_FILE), "utf8"));
+    return typeof parsed.baseline === "string" ? parsed.baseline : "gate-baseline.json";
+  } catch {
+    return "gate-baseline.json";
+  }
+};
 
 // src/core/types.ts
 var CounterError = class extends Error {
@@ -136,23 +207,21 @@ var CounterError = class extends Error {
 };
 
 // src/core/shell.ts
-import { execSync } from "child_process";
+import { spawnSync } from "child_process";
 var ANSI = /\[[0-9;]*m/g;
 var runCommand = (cwd, counterId, env) => (command) => {
-  try {
-    const output = execSync(`(
-${command}
-) 2>&1`, {
+  {
+    const run = spawnSync(command, {
       cwd,
       encoding: "utf8",
       env,
       maxBuffer: 64 * 1024 * 1024,
+      shell: true,
       stdio: ["ignore", "pipe", "pipe"]
     });
-    return { code: 0, output: output.replaceAll(ANSI, "") };
-  } catch (error) {
-    const failed = error;
-    const output = `${failed.stdout ?? ""}${failed.stderr ?? ""}`.replaceAll(ANSI, "");
+    const output = `${run.stdout ?? ""}${run.stderr ?? ""}`.replaceAll(ANSI, "");
+    if (run.error === void 0 && (run.status ?? 0) === 0) return { code: 0, output };
+    const failed = { status: run.status ?? 1, stderr: "", stdout: "" };
     const code = failed.status ?? -1;
     if (code === 126 || code === 127 || code === -1) {
       throw new CounterError(
@@ -166,13 +235,13 @@ ${output.trim()}`
 };
 
 // src/core/prove.ts
-import { existsSync as existsSync2, mkdtempSync, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync2, mkdtempSync, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
 import { tmpdir } from "os";
-import { delimiter, dirname as dirname3, join as join2, resolve as resolve3 } from "path";
+import { delimiter, dirname as dirname4, join as join3, resolve as resolve3 } from "path";
 
 // src/core/exclusive.ts
 import { spawn } from "child_process";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { dirname as dirname3, resolve as resolve2 } from "path";
 var MARK = /^exclusive-hold (start|end) (\d+)$/gm;
 var KEY = "exclusive";
 var spanOf = (output) => {
@@ -187,7 +256,7 @@ var hold = (cli, holdMs, lockPath) => new Promise((done) => {
     process.execPath,
     [cli, "--exclusive", "--exclusive-timeout", "60", "--hold", String(holdMs)],
     {
-      cwd: dirname2(resolve2(cli)),
+      cwd: dirname3(resolve2(cli)),
       env: { ...process.env, GEONOSIS_HEAVY_LOCK: lockPath },
       stdio: ["ignore", "pipe", "pipe"]
     }
@@ -239,9 +308,9 @@ var toolPath = (cwd) => {
   const dirs = [];
   let dir = resolve3(cwd);
   for (; ; ) {
-    const bin = join2(dir, "node_modules", ".bin");
+    const bin = join3(dir, "node_modules", ".bin");
     if (existsSync2(bin)) dirs.push(bin);
-    const parent = dirname3(dir);
+    const parent = dirname4(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -249,7 +318,7 @@ var toolPath = (cwd) => {
 };
 var NO_PROBE = "no probe \u2014 a counter nobody has seen read a planted finding has not been shown to measure";
 var oneProofOf = async (counter, key, path, probe) => {
-  const dir = mkdtempSync(join2(tmpdir(), "geonosis-prove-"));
+  const dir = mkdtempSync(join3(tmpdir(), "geonosis-prove-"));
   try {
     probe.input(dir);
     const command = probe.command?.(dir);
@@ -316,11 +385,43 @@ var runProve = async ({
     if (taken.some((one) => one.verdict !== "proven" && one.verdict !== "skipped")) {
       return { proofs, proven: false };
     }
+    const customized = (counter.readingParams ?? []).filter((one) => entry[one] !== void 0);
+    if (customized.length > 0) {
+      const declared = entry.probe;
+      const named = customized.map((one) => `${one} ${JSON.stringify(entry[one])}`).join(", ");
+      if (declared === void 0 || typeof declared.sample !== "string" || typeof declared.expect !== "number") {
+        proofs.push({
+          counter: counter.id,
+          key,
+          reason: `the configured ${named} is not exercised by this counter's shipped probe \u2014 declare probe: { sample, expect } beside it, a sample this reading must count`,
+          verdict: "unproven"
+        });
+        return { proofs, proven: false };
+      }
+      const sample = declared.sample;
+      const entryProbe = {
+        command: () => "cat sample.txt",
+        expect: declared.expect,
+        input: (dir) => writeFileSync3(join3(dir, "sample.txt"), sample),
+        name: "configured reading",
+        params: Object.fromEntries(customized.map((one) => [one, entry[one]]))
+      };
+      const proof = await oneProofOf(counter, key, path, entryProbe);
+      const said = proof.verdict === "cannot-fail" ? {
+        counter: counter.id,
+        expected: declared.expect,
+        key,
+        reading: 0,
+        verdict: "misread"
+      } : proof;
+      proofs.push(said);
+      if (said.verdict !== "proven") return { proofs, proven: false };
+    }
   }
   if (exclusiveVia !== void 0) {
-    const dir = mkdtempSync(join2(tmpdir(), "geonosis-lock-"));
+    const dir = mkdtempSync(join3(tmpdir(), "geonosis-lock-"));
     try {
-      const proof = await proveExclusive({ cli: exclusiveVia, lockPath: join2(dir, "heavy.lock") });
+      const proof = await proveExclusive({ cli: exclusiveVia, lockPath: join3(dir, "heavy.lock") });
       proofs.push(proof);
       if (proof.verdict !== "serialised") return { proofs, proven: false };
     } finally {
@@ -331,16 +432,23 @@ var runProve = async ({
 };
 
 // src/core/ratchet.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
 import { resolve as resolve4 } from "path";
 var EVIDENCE_LINES = 10;
-var recorded = (run) => {
+var recorded = (counter, params, run) => {
   let output = "";
+  let lastCommand;
+  const trimmed = (lines) => lines.map((line) => line.trimEnd()).filter((line) => line !== "").slice(-EVIDENCE_LINES);
   return {
-    last: () => output.split("\n").map((line) => line.trimEnd()).filter((line) => line !== "").slice(-EVIDENCE_LINES),
+    cited: () => {
+      const counted = counter.evidence === void 0 ? [] : counter.evidence({ output, params });
+      return trimmed(counted.length > 0 ? counted : output.split("\n"));
+    },
+    lastCommand: () => lastCommand,
     run: (command) => {
       const result = run(command);
       output = result.output;
+      lastCommand = command;
       return result;
     }
   };
@@ -376,9 +484,10 @@ var runRatchet = async ({
   if (!existsSync3(baselinePath)) {
     throw new Error(`no ${config.baseline} in ${cwd} \u2014 nothing to ratchet against`);
   }
-  const baseline = JSON.parse(readFileSync3(baselinePath, "utf8"));
+  const baseline = JSON.parse(readFileSync4(baselinePath, "utf8"));
   const byId = new Map(counters.map((one) => [one.id, one]));
   const measurements = [];
+  const refusals = [];
   for (const entry of config.counters) {
     const counter = byId.get(entry.counter);
     if (counter === void 0) {
@@ -398,12 +507,22 @@ var runRatchet = async ({
       );
     }
     const tolerance = toleranceOf(entry, key, counter);
-    const recorder = recorded(runCommand(cwd, entry.counter));
-    const now = await counter.run({ cwd, key, params: entry, run: recorder.run });
+    const recorder = recorded(counter, entry, runCommand(cwd, entry.counter));
+    let now;
+    try {
+      now = await counter.run({ cwd, key, params: entry, run: recorder.run });
+    } catch (error) {
+      const ran = recorder.lastCommand();
+      refusals.push({
+        key,
+        reason: `${error.message}${ran === void 0 ? "" : `. Next: run \`${ran}\` in ${cwd} and read what it prints`}`
+      });
+      continue;
+    }
     const verdict = verdictOf(now, limit, tolerance);
     measurements.push({
       baseline: limit,
-      evidence: verdict === "grew" ? recorder.last() : [],
+      evidence: verdict === "grew" ? recorder.cited() : [],
       key,
       now,
       verdict
@@ -411,16 +530,16 @@ var runRatchet = async ({
   }
   const grew = measurements.some((one) => one.verdict === "grew");
   const shrank = measurements.some((one) => one.verdict === "shrank");
-  if (shrank && !grew) {
+  if (shrank && !grew && refusals.length === 0) {
     const next = { ...baseline };
     for (const one of measurements) {
       if (one.verdict === "shrank") next[one.key] = one.now;
     }
-    writeFileSync2(baselinePath, `${JSON.stringify(next, null, 2)}
+    writeFileSync4(baselinePath, `${JSON.stringify(next, null, 2)}
 `);
-    return { measurements, rewritten: true };
+    return { considered: config.counters.length, measurements, refusals, rewritten: true };
   }
-  return { measurements, rewritten: false };
+  return { considered: config.counters.length, measurements, refusals, rewritten: false };
 };
 
 // src/counters/params.ts
@@ -439,12 +558,12 @@ var countMatches = (text, pattern) => text.match(new RegExp(pattern.source, `${p
 var escapeForRegex = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 // src/counters/plant.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname4, join as join3 } from "path";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname5, join as join4 } from "path";
 var plant = (dir, relative, contents) => {
-  const path = join3(dir, relative);
-  mkdirSync2(dirname4(path), { recursive: true });
-  writeFileSync3(path, contents);
+  const path = join4(dir, relative);
+  mkdirSync3(dirname5(path), { recursive: true });
+  writeFileSync5(path, contents);
 };
 var captured = (sample) => ({
   command: () => "cat sample.txt",
@@ -529,8 +648,8 @@ var bundleBytes = {
 };
 
 // src/counters/ci.ts
-import { readdirSync, readFileSync as readFileSync4 } from "fs";
-import { join as join4, resolve as resolve5 } from "path";
+import { readdirSync, readFileSync as readFileSync5 } from "fs";
+import { join as join5, resolve as resolve5 } from "path";
 var DISABLED = /\bif:[ \t]*false\b/;
 var WORKFLOW = /\.ya?ml$/;
 var disabledCiJobs = {
@@ -548,7 +667,7 @@ var disabledCiJobs = {
     const dir = resolve5(cwd, relative);
     let files;
     try {
-      files = readdirSync(dir, { withFileTypes: true }).filter((entry) => WORKFLOW.test(entry.name)).map((entry) => join4(dir, entry.name));
+      files = readdirSync(dir, { withFileTypes: true }).filter((entry) => WORKFLOW.test(entry.name)).map((entry) => join5(dir, entry.name));
     } catch {
       return 0;
     }
@@ -556,7 +675,7 @@ var disabledCiJobs = {
     for (const file of files) {
       let contents;
       try {
-        contents = readFileSync4(file, "utf8");
+        contents = readFileSync5(file, "utf8");
       } catch (error) {
         throw new CounterError(
           "disabledCiJobs",
@@ -579,10 +698,11 @@ var cloneCount = {
     const output = run(command).output;
     const found = output.match(CLONES)?.[1];
     if (found === void 0) {
+      const said = output.trim();
       throw new CounterError(
         "cloneCount",
-        `no "Found N clones" line:
-${output.trim().slice(-500)}`
+        said === "" ? 'the command printed nothing at all, so there is no "Found N clones" line to read and no output to show \u2014 it is not installed, or it never ran' : `no "Found N clones" line in what it printed:
+${said.slice(-500)}`
       );
     }
     return Number(found);
@@ -636,7 +756,7 @@ var unformattedFiles = {
 };
 
 // src/counters/gate-report.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
 import { resolve as resolve7 } from "path";
 var DEFAULT_REPORT = ".geonosis/gate-report.json";
 var fastTierMs = {
@@ -646,7 +766,7 @@ var fastTierMs = {
     expect: 4500,
     input: (dir) => plant(
       dir,
-      DEFAULT_REPORT,
+      ".geonosis/gate-report.fast.json",
       JSON.stringify({
         finishedAt: "2026-08-30T10:00:04.500Z",
         ok: true,
@@ -657,8 +777,10 @@ var fastTierMs = {
     )
   },
   run: async ({ cwd, params }) => {
-    const relative = stringParam("fastTierMs", params, "report", DEFAULT_REPORT);
     const wanted = stringParam("fastTierMs", params, "tier", "fast");
+    const own = `.geonosis/gate-report.${wanted}.json`;
+    const asked = stringParam("fastTierMs", params, "report", "");
+    const relative = asked !== "" ? asked : existsSync5(resolve7(cwd, own)) ? own : DEFAULT_REPORT;
     const path = resolve7(cwd, relative);
     if (!existsSync5(path)) {
       throw new CounterError(
@@ -668,7 +790,7 @@ var fastTierMs = {
     }
     let report;
     try {
-      report = JSON.parse(readFileSync5(path, "utf8"));
+      report = JSON.parse(readFileSync6(path, "utf8"));
     } catch (error) {
       throw new CounterError(
         "fastTierMs",
@@ -678,7 +800,7 @@ var fastTierMs = {
     if (report.tier !== wanted) {
       throw new CounterError(
         "fastTierMs",
-        `${relative} is a report of tier "${String(report.tier)}", not "${wanted}"`
+        `${relative} is a report of tier "${String(report.tier)}", not "${wanted}" \u2014 run \`geonosis-verify ${wanted}\`, which records ${own}`
       );
     }
     const spent = Date.parse(String(report.finishedAt)) - Date.parse(String(report.startedAt));
@@ -690,7 +812,7 @@ var fastTierMs = {
 };
 
 // src/counters/law.ts
-import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
 import { resolve as resolve8 } from "path";
 var lawLineCount = {
   id: "lawLineCount",
@@ -703,12 +825,12 @@ var lawLineCount = {
     const relative = stringParam("lawLineCount", params, "path", "CLAUDE.md");
     const path = resolve8(cwd, relative);
     if (!existsSync6(path)) throw new CounterError("lawLineCount", `no law file at ${relative}`);
-    return readFileSync6(path, "utf8").replace(/\n$/, "").split("\n").length;
+    return readFileSync7(path, "utf8").replace(/\n$/, "").split("\n").length;
   }
 };
 
 // src/counters/oxlint.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync8, rmSync as rmSync3, writeFileSync as writeFileSync6 } from "fs";
 import { resolve as resolve9 } from "path";
 var DEFAULT_COMMAND = "npx oxlint --format=unix --config .oxlintrc.json .";
 var PROBE_COMMAND = "oxlint --format=unix --config .oxlintrc.json .";
@@ -729,12 +851,32 @@ var UNIX_FINDING = /^\S[^\n]*:\d+:\d+: .*\[(Error|Warning)\/[^\]\n]+\]$/gm;
 var UNIX_SUMMARY = /^(\d+) problems?$/m;
 var AGENT_FINDING = /^\S[^\n]*:\d+:\d+: (error|warning) /gm;
 var DEFAULT_SUMMARY = /^Found (\d+) warnings? and (\d+) errors?\.$/m;
-var DEFAULT_FINDING = /^\s*[x!] [^\s(]+\([^)\n]+\): /m;
+var DEFAULT_FINDING = /^\s*([x!]) [^\s(]+\([^)\n]+\): /m;
 var FINDING_SHAPES = [UNIX_FINDING, AGENT_FINDING, DEFAULT_FINDING].map(
   (shape) => new RegExp(shape.source)
 );
 var RULE_TOKEN = /\([^()\n]+\)/;
-var findingLinesOf = (output) => output.split("\n").filter((line) => FINDING_SHAPES.some((shape) => shape.test(line)));
+var SEVERITY_BY_TOKEN = {
+  "!": "warning",
+  Error: "error",
+  error: "error",
+  Warning: "warning",
+  warning: "warning",
+  x: "error"
+};
+var severityOf = (line) => {
+  for (const shape of FINDING_SHAPES) {
+    const token = shape.exec(line)?.[1];
+    if (token !== void 0) return SEVERITY_BY_TOKEN[token];
+  }
+  return void 0;
+};
+var findingLinesOf = (output) => output.split("\n").filter((line) => severityOf(line) !== void 0);
+var linesOfSeverity = (output, want) => output.split("\n").filter((line) => severityOf(line) === want);
+var linesOfRule = (output, rule) => {
+  const named = new RegExp(`\\(${escapeForRegex(rule)}\\)`);
+  return findingLinesOf(output).filter((line) => named.test(line));
+};
 var FORMATS = ["agent", "default", "unix"];
 var isFormat = (value) => typeof value === "string" && FORMATS.some((one) => one === value);
 var expectedFormat = (counter, params) => {
@@ -793,6 +935,7 @@ ${output.trim()}`);
   return refuse2(`the tool exited ${code} and printed no findings and no summary`);
 };
 var oxlintErrors = {
+  evidence: ({ output }) => linesOfSeverity(output, "error"),
   id: "oxlintErrors",
   probe: {
     ...oxlintProbe("error", "typescript/no-explicit-any", ONE_ANY),
@@ -806,6 +949,7 @@ var oxlintErrors = {
   }
 };
 var oxlintWarnings = {
+  evidence: ({ output }) => linesOfSeverity(output, "warning"),
   id: "oxlintWarnings",
   // A warning, so the run exits 0 — the window `expectFormat` exists to close is also the window a
   // probe has to survive.
@@ -830,10 +974,12 @@ var countRule = (result, rule, expect) => {
 ${result.output.trim()}`
     );
   }
-  const named = new RegExp(`\\(${escapeForRegex(rule)}\\)`);
-  return lines.filter((line) => named.test(line)).length;
+  return linesOfRule(result.output, rule).length;
 };
 var oxlintRule = {
+  // The rule is a required param, so a run that got here always has one; a citation is not the
+  // place to raise that, and the report falls back to the tail rather than losing the regression.
+  evidence: ({ output, params }) => typeof params.rule === "string" ? linesOfRule(output, params.rule) : [],
   id: "oxlintRule",
   // The probe names its OWN rule: which rule a repo tracks is its business, and a probe that had to
   // make the repo's rule fire would need the repo's plugin loadable from a scratch directory.
@@ -851,11 +997,11 @@ var oxlintRule = {
     const source = resolve9(cwd, config);
     if (!existsSync7(source)) throw new CounterError("oxlintRule", `no config at ${config}`);
     const strictName = `.oxlintrc.ratchet-${key}.json`;
-    const strict = readFileSync7(source, "utf8").replace(
+    const strict = readFileSync8(source, "utf8").replace(
       new RegExp(`("[^"]*${escapeForRegex(rule)}"\\s*:\\s*\\[?\\s*)"(warn|off)"`),
       '$1"error"'
     );
-    writeFileSync4(resolve9(cwd, strictName), strict);
+    writeFileSync6(resolve9(cwd, strictName), strict);
     try {
       return countRule(run(command.replace("{config}", strictName)), rule, expect);
     } finally {
@@ -889,15 +1035,15 @@ var runtimeCodeShipped = {
 
 // src/counters/scripts.ts
 import { readdirSync as readdirSync3 } from "fs";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/counters/workspace.ts
-import { existsSync as existsSync8, readdirSync as readdirSync2, readFileSync as readFileSync8 } from "fs";
-import { join as join5, resolve as resolve10 } from "path";
+import { existsSync as existsSync8, readdirSync as readdirSync2, readFileSync as readFileSync9 } from "fs";
+import { join as join6, resolve as resolve10 } from "path";
 var SKIP = /^(node_modules|\.)/;
 var childDirs = (dir) => {
   try {
-    return readdirSync2(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !SKIP.test(entry.name)).map((entry) => join5(dir, entry.name));
+    return readdirSync2(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !SKIP.test(entry.name)).map((entry) => join6(dir, entry.name));
   } catch {
     return [];
   }
@@ -907,14 +1053,14 @@ var expand = (root, pattern) => {
   const segments = pattern.split("/").filter((one) => one !== "" && one !== ".");
   let dirs = [root];
   for (const segment of segments) {
-    dirs = segment === "*" ? dirs.flatMap((dir) => childDirs(dir)) : segment === "**" ? dirs.flatMap((dir) => descendants(dir, 3)) : dirs.map((dir) => join5(dir, segment)).filter((dir) => existsSync8(dir));
+    dirs = segment === "*" ? dirs.flatMap((dir) => childDirs(dir)) : segment === "**" ? dirs.flatMap((dir) => descendants(dir, 3)) : dirs.map((dir) => join6(dir, segment)).filter((dir) => existsSync8(dir));
   }
   return dirs;
 };
 var QUOTED = /^['"]|['"]$/g;
 var cleaned = (value) => value.replace(/#.*$/, "").trim().replaceAll(QUOTED, "");
 var pnpmPatterns = (path) => {
-  const lines = readFileSync8(path, "utf8").split("\n");
+  const lines = readFileSync9(path, "utf8").split("\n");
   const at = lines.findIndex((line) => line.startsWith("packages:"));
   if (at === -1) return [];
   const inline = lines[at]?.slice("packages:".length).trim() ?? "";
@@ -933,15 +1079,15 @@ var pnpmPatterns = (path) => {
   return patterns;
 };
 var npmPatterns = (path) => {
-  const parsed = JSON.parse(readFileSync8(path, "utf8"));
+  const parsed = JSON.parse(readFileSync9(path, "utf8"));
   const declared = Array.isArray(parsed.workspaces) ? parsed.workspaces : parsed.workspaces?.packages ?? [];
   return declared.filter((one) => typeof one === "string");
 };
 var nameOf = (dir) => {
-  const manifest = join5(dir, "package.json");
+  const manifest = join6(dir, "package.json");
   if (!existsSync8(manifest)) return void 0;
   try {
-    const { name } = JSON.parse(readFileSync8(manifest, "utf8"));
+    const { name } = JSON.parse(readFileSync9(manifest, "utf8"));
     return typeof name === "string" && name !== "" ? name : void 0;
   } catch {
     return void 0;
@@ -949,15 +1095,15 @@ var nameOf = (dir) => {
 };
 var workspaceDirs = (cwd) => {
   const root = resolve10(cwd);
-  const pnpm = join5(root, "pnpm-workspace.yaml");
-  const manifest = join5(root, "package.json");
+  const pnpm = join6(root, "pnpm-workspace.yaml");
+  const manifest = join6(root, "package.json");
   const patterns = existsSync8(pnpm) ? pnpmPatterns(pnpm) : existsSync8(manifest) ? npmPatterns(manifest) : [];
-  const dirs = patterns.filter((pattern) => !pattern.startsWith("!")).flatMap((pattern) => expand(root, pattern)).filter((dir) => existsSync8(join5(dir, "package.json")));
+  const dirs = patterns.filter((pattern) => !pattern.startsWith("!")).flatMap((pattern) => expand(root, pattern)).filter((dir) => existsSync8(join6(dir, "package.json")));
   return [...new Set(dirs)];
 };
 var manifestOf = (dir) => {
   try {
-    const parsed = JSON.parse(readFileSync8(join5(dir, "package.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync9(join6(dir, "package.json"), "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : void 0;
   } catch {
     return void 0;
@@ -987,7 +1133,7 @@ var holdsTests = (dir, depth = 6) => {
     if (entry.isDirectory()) {
       if (entry.name === TEST_DIR) return true;
       if (SKIP2.test(entry.name) || depth === 0) continue;
-      if (holdsTests(join6(dir, entry.name), depth - 1)) return true;
+      if (holdsTests(join7(dir, entry.name), depth - 1)) return true;
       continue;
     }
     if (TEST_FILE.test(entry.name)) return true;
@@ -1028,17 +1174,67 @@ var packagesWithoutTypecheck = {
 var sumOfCounts = {
   id: "sumOfCounts",
   probe: { ...captured("src/a.ts:1\nsrc/b.ts:0\n"), expect: 1 },
+  readingParams: ["match"],
   run: async ({ params, run }) => {
     const command = stringParam("sumOfCounts", params, "command");
-    const match = new RegExp(stringParam("sumOfCounts", params, "match", ":(\\d+)$"), "gm");
-    return [...run(command).output.matchAll(match)].map(([, digits]) => Number(digits ?? 0)).filter((count) => Number.isFinite(count)).reduce((sum, count) => sum + count, 0);
+    const pattern = stringParam("sumOfCounts", params, "match", ":(\\d+)$");
+    const match = new RegExp(pattern, "gm");
+    const output = run(command).output;
+    const found = [...output.matchAll(match)];
+    if (found.length === 0 && output.trim() !== "") {
+      throw new CounterError(
+        "sumOfCounts",
+        `its match ${pattern} read nothing from ${output.trim().split("\n").length} line(s) of output (first: ${JSON.stringify(output.trim().split("\n")[0])}) \u2014 a match that cannot read the tool is not a zero`
+      );
+    }
+    return found.map(([, digits]) => Number(digits ?? 0)).filter((count) => Number.isFinite(count)).reduce((sum, count) => sum + count, 0);
+  }
+};
+
+// src/counters/suppressions.ts
+import { readdirSync as readdirSync4, readFileSync as readFileSync10 } from "fs";
+import { join as join8, resolve as resolve11 } from "path";
+var CODE_FILE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|vue|svelte|astro)$/;
+var SKIP3 = /^(?:node_modules|dist|coverage|\.[^.]|__fixtures__)/;
+var SUPPRESSION = /(?:eslint|oxlint|biome)-(?:disable|ignore)(?:-next-line|-line)?|@ts-expect-error|@ts-ignore/g;
+var countIn = (dir, depth = 12) => {
+  let entries;
+  try {
+    entries = readdirSync4(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  let found = 0;
+  for (const entry of entries) {
+    if (SKIP3.test(entry.name)) continue;
+    if (entry.isDirectory()) {
+      if (depth > 0) found += countIn(join8(dir, entry.name), depth - 1);
+      continue;
+    }
+    if (!CODE_FILE.test(entry.name)) continue;
+    try {
+      found += readFileSync10(join8(dir, entry.name), "utf8").match(SUPPRESSION)?.length ?? 0;
+    } catch {
+    }
+  }
+  return found;
+};
+var suppressionCount = {
+  id: "suppressionCount",
+  probe: {
+    expect: 2,
+    input: (dir) => plant(dir, "src/planted.ts", "// eslint-disable-next-line x\n// @ts-expect-error y\n")
+  },
+  run: async ({ cwd, params }) => {
+    const roots = stringsParam(params, "roots", ["."]);
+    return roots.reduce((sum, root) => sum + countIn(resolve11(cwd, root)), 0);
   }
 };
 
 // src/counters/tests.ts
-import { existsSync as existsSync9, mkdtempSync as mkdtempSync2, readFileSync as readFileSync9, rmSync as rmSync4 } from "fs";
+import { existsSync as existsSync9, mkdtempSync as mkdtempSync2, readFileSync as readFileSync11, rmSync as rmSync4 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { join as join7, resolve as resolve11 } from "path";
+import { join as join9, resolve as resolve12 } from "path";
 var COUNTER = "testFailures";
 var VITEST_LINE = /^\s*Tests {2,}(.+?)\s*$/;
 var VITEST_TOTAL = /\(\d+\)$/;
@@ -1078,7 +1274,7 @@ var fromReport = (path) => {
   }
   let report;
   try {
-    report = JSON.parse(readFileSync9(path, "utf8"));
+    report = JSON.parse(readFileSync11(path, "utf8"));
   } catch (error) {
     throw new CounterError(
       COUNTER,
@@ -1102,14 +1298,14 @@ var fromReport = (path) => {
 };
 var reportPathFor = (cwd, params, command) => {
   const named = params.reportPath;
-  if (typeof named === "string" && named !== "") return { own: false, path: resolve11(cwd, named) };
+  if (typeof named === "string" && named !== "") return { own: false, path: resolve12(cwd, named) };
   if (!command.includes(PLACEHOLDER)) {
     throw new CounterError(
       COUNTER,
       `report: "${VITEST_JSON}" needs somewhere to put the report \u2014 write ${PLACEHOLDER} into the command (--outputFile=${PLACEHOLDER}) or give the entry a "reportPath"`
     );
   }
-  return { own: true, path: join7(mkdtempSync2(join7(tmpdir2(), "geonosis-report-")), "report.json") };
+  return { own: true, path: join9(mkdtempSync2(join9(tmpdir2(), "geonosis-report-")), "report.json") };
 };
 var testFailures = {
   id: COUNTER,
@@ -1158,7 +1354,7 @@ var testFailures = {
       run(command.replaceAll(PLACEHOLDER, path));
       return fromReport(path);
     } finally {
-      if (own) rmSync4(join7(path, ".."), { force: true, recursive: true });
+      if (own) rmSync4(join9(path, ".."), { force: true, recursive: true });
     }
   }
 };
@@ -1198,8 +1394,8 @@ var typecheckErrors = {
 };
 
 // src/counters/walk.ts
-import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
-import { resolve as resolve12 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync12 } from "fs";
+import { resolve as resolve13 } from "path";
 var DEFAULT_REPORT2 = ".geonosis/walk-report.json";
 var CLASSES = /* @__PURE__ */ new Set([
   "buy-box-above-fold",
@@ -1243,7 +1439,7 @@ var walkFindings = {
   },
   run: async ({ cwd, params }) => {
     const relative = stringParam("walkFindings", params, "report", DEFAULT_REPORT2);
-    const path = resolve12(cwd, relative);
+    const path = resolve13(cwd, relative);
     if (!existsSync10(path)) {
       throw new CounterError(
         "walkFindings",
@@ -1252,7 +1448,7 @@ var walkFindings = {
     }
     let report;
     try {
-      report = JSON.parse(readFileSync10(path, "utf8"));
+      report = JSON.parse(readFileSync12(path, "utf8"));
     } catch (error) {
       throw new CounterError(
         "walkFindings",
@@ -1282,6 +1478,7 @@ var COUNTERS = [
   fastTierMs,
   knipIssues,
   lawLineCount,
+  suppressionCount,
   oxlintErrors,
   oxlintRule,
   oxlintWarnings,
@@ -1306,7 +1503,7 @@ var counterById = (id) => {
 
 // src/report.ts
 var WIDTH = 28;
-var formatReport = ({ measurements, rewritten }) => {
+var formatReport = ({ measurements, refusals, rewritten }) => {
   const lines = measurements.map((one) => {
     if (one.verdict === "skipped") {
       return `  SKIP ${one.key}: not measured by --tier ${one.tier}`;
@@ -1319,8 +1516,14 @@ var formatReport = ({ measurements, rewritten }) => {
     if (one.verdict === "shrank") return `${head}  <-- improved -${one.baseline - one.now}`;
     return head;
   });
+  lines.push(...refusals.map((one) => `  CANNOT MEASURE ${one.key}: ${one.reason}`));
   const grew = measurements.filter((one) => one.verdict === "grew");
-  if (grew.length > 0) {
+  if (refusals.length > 0) {
+    lines.push(
+      "",
+      `ratchet FAIL \u2014 ${refusals.length} counter(s) could not be measured, and a gate that cannot measure has not passed. The baseline was left exactly as it was. Next: run each counter's own command by hand \u2014 ${refusals.map((one) => one.key).join(", ")} \u2014 and fix what it prints.`
+    );
+  } else if (grew.length > 0) {
     lines.push(
       "",
       "ratchet FAIL \u2014 debt grew. Fix it, or say in the commit message why the baseline goes up."
@@ -1342,6 +1545,7 @@ var formatProve = ({ proofs, proven }) => {
     }
     if (one.verdict === "cannot-measure") return `  CANNOT MEASURE ${one.key}: ${one.reason}`;
     if (one.verdict === "cannot-fail") return `  CANNOT FAIL ${one.key}: read 0`;
+    if (one.verdict === "unproven") return `  UNPROVEN ${one.key}: ${one.reason}`;
     if (one.verdict === "misread") {
       return `  MISREAD ${one.key}: read ${one.reading} where its probe planted ${one.expected}`;
     }
@@ -1356,11 +1560,17 @@ var formatProve = ({ proofs, proven }) => {
 };
 
 export {
+  ENVELOPES_DIR,
+  envelopePath,
+  UnbalancedEnvelope,
+  writeEnvelope,
+  versionOf,
   heavyLockPath,
   acquireExclusive,
   CONFIG_FILE,
   keyOf,
   loadConfig,
+  resolveBaseline,
   CounterError,
   runCommand,
   runProve,

package/dist/cli.js

@@ -4,10 +4,83 @@ import {
   formatProve,
   formatReport,
   runProve,
-  runRatchet
-} from "./chunk-LSYVFUP4.js";
+  runRatchet,
+  versionOf,
+  writeEnvelope
+} from "./chunk-ESN6ULZZ.js";
 
 // src/cli.ts
+import process from "process";
+var USAGE = `geonosis-ratchet [--cwd <dir>] [--tier <name>] [--prove] [--exclusive]
+
+Debt as a number that may only shrink. Runs the counters named in geonosis.ratchet.json, compares
+each against gate-baseline.json, and REWRITES the baseline down when a number shrank \u2014 so the win is
+locked in the same commit that earned it.
+
+  --cwd <dir>                  the repo to measure (default: the working directory)
+  --tier <name>                only the counters in that tier (default: every counter)
+  --prove                      plant a finding for each counter and require it to be read
+  --exclusive                  hold the machine-wide heavy lock for the run
+  --exclusive-timeout <secs>   how long to wait for that lock
+  --hold <ms>                  take the lock, wait, give it back \u2014 the --prove self-test's slow thing
+  --help, -h                   this text
+
+Exit codes: 0 no counter grew \xB7 1 a counter grew \xB7 2 the run could not measure.
+
+Every flag it does not know is REFUSED. This bin used to let anything unrecognised fall through to a
+full measurement, so \`--help\` ran the whole ratchet \u2014 a run that can rewrite the baseline, started
+by a typo.`;
+var KNOWN = /* @__PURE__ */ new Set([
+  "--cwd",
+  "--exclusive",
+  "--exclusive-timeout",
+  "--hold",
+  "--prove",
+  "--tier"
+]);
+var TAKES_A_VALUE = /* @__PURE__ */ new Set(["--cwd", "--exclusive-timeout", "--hold", "--tier"]);
+var CONFIG_SHAPE = `geonosis-ratchet reads geonosis.ratchet.json and gate-baseline.json
+
+geonosis.ratchet.json
+  baseline    string?              the file holding the numbers (default "gate-baseline.json")
+  counters    CounterEntry[]       required, and every entry is:
+      counter   string             required \u2014 the id of a counter this build ships
+      key       string?            the baseline key it writes (default: the counter id).
+                                   Two entries writing one key are refused: the loser's debt
+                                   would vanish into the baseline
+      tiers     string[]?          the tiers it runs in (default: all of them). A malformed
+                                   list is refused, never quietly matched to no tier
+      \u2026                            each counter reads its own further keys
+
+gate-baseline.json
+  <key>       number               one number per counter key. Written DOWN in place when a
+                                   number shrank, so the win lands in the commit that earned it`;
+var argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  process.stdout.write(`${USAGE}
+`);
+  process.exit(0);
+}
+if (argv.includes("--print-config-shape")) {
+  process.stdout.write(`${CONFIG_SHAPE}
+`);
+  process.exit(0);
+}
+var refuse = (message) => {
+  process.stderr.write(`geonosis-ratchet: ${message}
+`);
+  process.exit(2);
+};
+for (let at = 0; at < argv.length; at += 1) {
+  const arg = argv[at];
+  if (KNOWN.has(arg)) {
+    if (TAKES_A_VALUE.has(arg)) at += 1;
+    continue;
+  }
+  refuse(
+    `${arg} is not an option it takes. Run geonosis-ratchet --help for the ones it does \u2014 an unrecognised argument is refused rather than measured, because a run here can rewrite the baseline.`
+  );
+}
 var numberAfter = (flag) => {
   const at = process.argv.indexOf(flag);
   return at === -1 ? void 0 : Number(process.argv[at + 1] ?? Number.NaN);
@@ -29,6 +102,19 @@ var holdTheLock = async (ms) => {
 `);
   return 0;
 };
+var ENVELOPE_NEXT = "geonosis-ratchet --print-config-shape, then count the entries in geonosis.ratchet.json \u2014 a run that measured fewer counters than the config named is a bug in this tool, not in the tree it measured";
+var envelopeOf = (result, durationMs) => ({
+  considered: result.considered,
+  durationMs,
+  excused: result.measurements.flatMap(
+    (one) => one.verdict === "skipped" ? [{ path: one.key, reason: `not measured by --tier ${one.tier}` }] : []
+  ),
+  findings: result.measurements.filter((one) => one.verdict === "grew"),
+  read: result.measurements.filter((one) => one.verdict !== "skipped").length,
+  refused: result.refusals.map((one) => ({ path: one.key, reason: one.reason })),
+  tool: "ratchet",
+  version: versionOf(import.meta.url)
+});
 var measure = async () => {
   if (holdMs !== void 0) return holdTheLock(holdMs);
   if (proving) {
@@ -41,8 +127,17 @@ var measure = async () => {
     process.stdout.write(formatProve(proof));
     return proof.proven ? 0 : 2;
   }
+  const startedAt = Date.now();
   const result = await runRatchet({ counters: COUNTERS, cwd, tier });
   process.stdout.write(formatReport(result));
+  const at = writeEnvelope({
+    envelope: envelopeOf(result, Date.now() - startedAt),
+    next: ENVELOPE_NEXT,
+    root: cwd
+  });
+  process.stdout.write(`envelope: ${at}
+`);
+  if (result.refusals.length > 0) return 2;
   return result.measurements.some((one) => one.verdict === "grew") ? 1 : 0;
 };
 try {

package/dist/index.d.ts

@@ -41,6 +41,22 @@ type CounterProbe = {
     params?: Record<string, unknown>;
 };
 type Counter = {
+    /**
+     * Which lines of a run this counter actually COUNTED, for the report to cite when the number
+     * grew. Absent means the tail of the run is shown, which is right for a counter whose tool prints
+     * nothing but findings and wrong for every counter that reads one rule or one severity out of a
+     * mixed run: the tail is whatever printed LAST, and dielime got two unrelated warnings under a
+     * +2 on one rule while the two real errors sat further up.
+     *
+     * It takes the output rather than being handed the lines during the run so that it stays a pure
+     * function of what the tool said — the same reading the count was taken from, testable on its
+     * own. Returning nothing falls back to the tail: a citation nobody could make is no reason to
+     * show the reader nothing at all.
+     */
+    evidence?: (context: {
+        output: string;
+        params: Record<string, unknown>;
+    }) => string[];
     id: string;
     /**
      * Whether this counter's number is a measured QUANTITY — bytes, milliseconds — rather than a
@@ -60,6 +76,14 @@ type Counter = {
      * nobody configured says nothing about the mode they did.
      */
     probe?: CounterProbe | CounterProbe[];
+    /**
+     * The params that change WHAT this counter reads (a `match`), as opposed to where it looks.
+     * #140: a configured reading the probe never exercises can be wrong in a way the probe cannot
+     * see — during.day's mis-escaped match read 0, was certified PROVEN, and the false win was
+     * banked into the baseline. A config customizing one of these must declare `probe: { sample,
+     * expect }` beside it, or the prove line says UNPROVEN.
+     */
+    readingParams?: string[];
     run: (context: CounterContext) => Promise<number>;
 };
 /** One line of `geonosis.ratchet.json`'s `counters` array. */
@@ -118,6 +142,11 @@ type Proof = {
     key: string;
     reason: string;
     verdict: 'cannot-measure';
+} | {
+    counter: string;
+    key: string;
+    reason: string;
+    verdict: 'unproven';
 }
 /**
  * Not a counter: `--exclusive` itself, measured by running two of it. A lock is a claim about the
@@ -141,8 +170,24 @@ type ProveResult = {
     /** False as soon as one counter could not be shown to read its own planted finding. */
     proven: boolean;
 };
+/** A counter whose tool could not be read. Never a number, and never a silent zero. */
+type Refusal = {
+    key: string;
+    reason: string;
+};
 type RatchetResult = {
+    /**
+     * How many counters the config named. The denominator: `considered === measurements.length +
+     * refusals.length`, and a run whose two do not add up has lost one somewhere between the config
+     * and the report.
+     */
+    considered: number;
     measurements: Measurement[];
+    /**
+     * Every counter that blew up, not just the first. The throw that used to leave the run at the
+     * first failure also left every counter behind it unrun and unreported.
+     */
+    refusals: Refusal[];
     /** True when the baseline file was rewritten because something shrank. */
     rewritten: boolean;
 };
@@ -151,6 +196,90 @@ declare const CONFIG_FILE = "geonosis.ratchet.json";
 /** The baseline key an entry writes. Defaults to the counter's own id. */
 declare const keyOf: (entry: CounterConfig) => string;
 declare const loadConfig: (cwd: string) => RatchetConfig;
+/**
+ * #120: the ONE answer to "where does the baseline live". Three tools guessed instead of asking —
+ * rails' deny rail rendered `<root>/gate-baseline.json` over a repo whose baseline is
+ * `scripts/gate-baseline.json` (measured on sandbox-exec: the tampering write LANDED), and mcp's
+ * preamble said "no gate-baseline.json here" over twenty ratcheted counters. Anything that SPEAKS
+ * about the baseline resolves it here; `loadConfig` stays the strict door for anything that RUNS
+ * counters. Never throws: a missing or unreadable config means the default, because naming the
+ * baseline must work in repos that have not adopted the ratchet yet.
+ */
+declare const resolveBaseline: (cwd: string) => string;
+
+/**
+ * The report envelope: what a tool CONSIDERED, against what it actually read.
+ *
+ * Four denominator bugs landed in one day — a migrations run that reported on three of four files,
+ * a plan check that printed `PASS — 0 plan(s)` over a directory of twenty-one, a parity run over a
+ * tree the second config ignored, a chains validator that walked a list it had already filtered.
+ * Every one of them was GREEN, and every one of them was green because the tool published the
+ * numerator and nobody published the denominator.
+ *
+ * So every gate writes this, and the law is arithmetic:
+ *
+ *     considered === read + refused.length + excused.length
+ *
+ * checked HERE, at write time. A tool whose own accounting does not add up has not measured what it
+ * says it measured, so it renders no verdict at all: the write throws, the file is not created, and
+ * the bin exits 2. That is deliberately harsher than a failing gate — a wrong verdict is worse than
+ * no verdict, and a tool that has lost count of its own inputs cannot tell which it is.
+ *
+ * `refused` and `excused` are both "considered and NOT read". They differ in whose fault it is:
+ * refused is the tool unable to read the thing (an unparseable migration, a counter whose command
+ * blew up), excused is the thing legitimately exempt (a contract-migration marker the gate believed,
+ * a step the run never reached, a plan written before the contract). Both carry a reason, because a
+ * bucket without reasons is just a smaller silence.
+ */
+type EnvelopeEntry = {
+    /** What was not read — a file, a counter key, a step id. Whatever the tool names its inputs by. */
+    path: string;
+    /** Why it was not read, in a sentence a reader can act on. */
+    reason: string;
+};
+type ReportEnvelope = {
+    /** Everything this run took as its input. The denominator. */
+    considered: number;
+    durationMs: number;
+    excused: EnvelopeEntry[];
+    /** Whatever the tool found. Shape is the tool's own; nothing here reads into it. */
+    findings: unknown[];
+    /** How many of `considered` the run actually read. The numerator. */
+    read: number;
+    refused: EnvelopeEntry[];
+    /** The name the envelope is filed under, and the name a refusal is reported against. */
+    tool: string;
+    /** The build that wrote it. An envelope that cannot name its build dates nothing. */
+    version: string;
+};
+/** Where every tool writes, and the one directory the doctor's envelope check reads. */
+declare const ENVELOPES_DIR = ".geonosis/envelopes";
+declare const envelopePath: (root: string, tool: string) => string;
+/** A run whose accounting does not add up. Never a verdict — the refusal to render one. */
+declare class UnbalancedEnvelope extends Error {
+    constructor(message: string);
+}
+/**
+ * Writes the envelope, or refuses. Returns the path written so a caller can print it.
+ *
+ * The check is before the write and not after it, because a file on disk is a verdict: the doctor
+ * would read a half-true envelope and report on numbers nobody stands behind.
+ */
+declare const writeEnvelope: ({ envelope, next, root, }: {
+    envelope: ReportEnvelope;
+    /** The command a reader should run to see the accounting for themselves. */
+    next: string;
+    root: string;
+}) => string;
+/**
+ * The version of the package a module belongs to, found by walking up to the nearest manifest.
+ *
+ * Called with `import.meta.url`, it answers the same in `src/` under vitest and in the bundled
+ * `dist/` a bin loads — which is the whole point, because the envelope a consumer's CI writes is
+ * written by the build, and a version baked in at compile time would be the version of whoever
+ * bundled it.
+ */
+declare const versionOf: (moduleUrl: string) => string;
 
 declare const COUNTERS: Counter[];
 declare const counterById: (id: string) => Counter;
@@ -225,7 +354,7 @@ declare const runRatchet: ({ counters, cwd, tier, }: {
  * the tier left out says so by name — printing a number for it would be the stale OK this exists
  * to prevent.
  */
-declare const formatReport: ({ measurements, rewritten }: RatchetResult) => string;
+declare const formatReport: ({ measurements, refusals, rewritten }: RatchetResult) => string;
 declare const formatProve: ({ proofs, proven }: ProveResult) => string;
 
 /**
@@ -244,4 +373,4 @@ declare const formatProve: ({ proofs, proven }: ProveResult) => string;
  */
 declare const runCommand: (cwd: string, counterId: string, env?: NodeJS.ProcessEnv) => (command: string) => CommandResult;
 
-export { CONFIG_FILE, COUNTERS, type CommandResult, type Counter, type CounterConfig, type CounterContext, CounterError, type CounterProbe, type Holder, type Measurement, type Proof, type ProveResult, type RatchetConfig, type RatchetResult, type Verdict, acquireExclusive, counterById, formatProve, formatReport, heavyLockPath, keyOf, loadConfig, runCommand, runProve, runRatchet };
+export { CONFIG_FILE, COUNTERS, type CommandResult, type Counter, type CounterConfig, type CounterContext, CounterError, type CounterProbe, ENVELOPES_DIR, type EnvelopeEntry, type Holder, type Measurement, type Proof, type ProveResult, type RatchetConfig, type RatchetResult, type Refusal, type ReportEnvelope, UnbalancedEnvelope, type Verdict, acquireExclusive, counterById, envelopePath, formatProve, formatReport, heavyLockPath, keyOf, loadConfig, resolveBaseline, runCommand, runProve, runRatchet, versionOf, writeEnvelope };

package/dist/index.js

@@ -2,29 +2,41 @@ import {
   CONFIG_FILE,
   COUNTERS,
   CounterError,
+  ENVELOPES_DIR,
+  UnbalancedEnvelope,
   acquireExclusive,
   counterById,
+  envelopePath,
   formatProve,
   formatReport,
   heavyLockPath,
   keyOf,
   loadConfig,
+  resolveBaseline,
   runCommand,
   runProve,
-  runRatchet
-} from "./chunk-LSYVFUP4.js";
+  runRatchet,
+  versionOf,
+  writeEnvelope
+} from "./chunk-ESN6ULZZ.js";
 export {
   CONFIG_FILE,
   COUNTERS,
   CounterError,
+  ENVELOPES_DIR,
+  UnbalancedEnvelope,
   acquireExclusive,
   counterById,
+  envelopePath,
   formatProve,
   formatReport,
   heavyLockPath,
   keyOf,
   loadConfig,
+  resolveBaseline,
   runCommand,
   runProve,
-  runRatchet
+  runRatchet,
+  versionOf,
+  writeEnvelope
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/ratchet",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "types": "./dist/index.d.ts",
   "description": "Debt as a number that may only shrink — one ratchet, pluggable counters.",
   "keywords": [