@geonosis/ratchet 1.3.0 → 1.4.0

package/dist/{chunk-HBM6F3GO.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`);
   }
@@ -126,7 +189,7 @@ var loadConfig = (cwd) => {
 };
 var resolveBaseline = (cwd) => {
   try {
-    const parsed = JSON.parse(readFileSync2(resolve(cwd, CONFIG_FILE), "utf8"));
+    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";
@@ -172,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) => {
@@ -193,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"]
     }
@@ -245,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;
   }
@@ -255,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);
@@ -322,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 {
@@ -337,20 +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 = (counter, params, run) => {
   let output = "";
+  let lastCommand;
   const trimmed = (lines) => lines.map((line) => line.trimEnd()).filter((line) => line !== "").slice(-EVIDENCE_LINES);
   return {
     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;
     }
   };
@@ -386,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) {
@@ -409,7 +508,17 @@ var runRatchet = async ({
     }
     const tolerance = toleranceOf(entry, key, counter);
     const recorder = recorded(counter, entry, runCommand(cwd, entry.counter));
-    const now = await counter.run({ cwd, key, params: entry, run: recorder.run });
+    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,
@@ -421,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
@@ -449,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",
@@ -539,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 = {
@@ -558,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;
     }
@@ -566,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",
@@ -589,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);
@@ -646,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 = {
@@ -680,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",
@@ -702,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",
@@ -715,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 .";
@@ -887,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 {
@@ -925,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 [];
   }
@@ -943,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() ?? "";
@@ -969,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;
@@ -985,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;
@@ -1023,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;
@@ -1064,16 +1174,26 @@ 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 readFileSync9 } from "fs";
-import { join as join7, resolve as resolve11 } from "path";
+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;
@@ -1088,12 +1208,12 @@ var countIn = (dir, depth = 12) => {
   for (const entry of entries) {
     if (SKIP3.test(entry.name)) continue;
     if (entry.isDirectory()) {
-      if (depth > 0) found += countIn(join7(dir, entry.name), depth - 1);
+      if (depth > 0) found += countIn(join8(dir, entry.name), depth - 1);
       continue;
     }
     if (!CODE_FILE.test(entry.name)) continue;
     try {
-      found += readFileSync9(join7(dir, entry.name), "utf8").match(SUPPRESSION)?.length ?? 0;
+      found += readFileSync10(join8(dir, entry.name), "utf8").match(SUPPRESSION)?.length ?? 0;
     } catch {
     }
   }
@@ -1112,9 +1232,9 @@ var suppressionCount = {
 };
 
 // src/counters/tests.ts
-import { existsSync as existsSync9, mkdtempSync as mkdtempSync2, readFileSync as readFileSync10, 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 join8, resolve as resolve12 } 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+\)$/;
@@ -1154,7 +1274,7 @@ var fromReport = (path) => {
   }
   let report;
   try {
-    report = JSON.parse(readFileSync10(path, "utf8"));
+    report = JSON.parse(readFileSync11(path, "utf8"));
   } catch (error) {
     throw new CounterError(
       COUNTER,
@@ -1185,7 +1305,7 @@ var reportPathFor = (cwd, params, command) => {
       `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: join8(mkdtempSync2(join8(tmpdir2(), "geonosis-report-")), "report.json") };
+  return { own: true, path: join9(mkdtempSync2(join9(tmpdir2(), "geonosis-report-")), "report.json") };
 };
 var testFailures = {
   id: COUNTER,
@@ -1234,7 +1354,7 @@ var testFailures = {
       run(command.replaceAll(PLACEHOLDER, path));
       return fromReport(path);
     } finally {
-      if (own) rmSync4(join8(path, ".."), { force: true, recursive: true });
+      if (own) rmSync4(join9(path, ".."), { force: true, recursive: true });
     }
   }
 };
@@ -1274,7 +1394,7 @@ var typecheckErrors = {
 };
 
 // src/counters/walk.ts
-import { existsSync as existsSync10, readFileSync as readFileSync11 } from "fs";
+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([
@@ -1328,7 +1448,7 @@ var walkFindings = {
     }
     let report;
     try {
-      report = JSON.parse(readFileSync11(path, "utf8"));
+      report = JSON.parse(readFileSync12(path, "utf8"));
     } catch (error) {
       throw new CounterError(
         "walkFindings",
@@ -1383,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}`;
@@ -1396,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."
@@ -1419,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}`;
     }
@@ -1433,6 +1560,11 @@ var formatProve = ({ proofs, proven }) => {
 };
 
 export {
+  ENVELOPES_DIR,
+  envelopePath,
+  UnbalancedEnvelope,
+  writeEnvelope,
+  versionOf,
   heavyLockPath,
   acquireExclusive,
   CONFIG_FILE,

package/dist/cli.js

@@ -4,8 +4,10 @@ import {
   formatProve,
   formatReport,
   runProve,
-  runRatchet
-} from "./chunk-HBM6F3GO.js";
+  runRatchet,
+  versionOf,
+  writeEnvelope
+} from "./chunk-ESN6ULZZ.js";
 
 // src/cli.ts
 import process from "process";
@@ -100,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) {
@@ -112,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

@@ -76,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. */
@@ -134,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
@@ -157,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;
 };
@@ -178,6 +207,80 @@ declare const loadConfig: (cwd: string) => RatchetConfig;
  */
 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;
 
@@ -251,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;
 
 /**
@@ -270,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, resolveBaseline, 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,8 +2,11 @@ import {
   CONFIG_FILE,
   COUNTERS,
   CounterError,
+  ENVELOPES_DIR,
+  UnbalancedEnvelope,
   acquireExclusive,
   counterById,
+  envelopePath,
   formatProve,
   formatReport,
   heavyLockPath,
@@ -12,14 +15,19 @@ import {
   resolveBaseline,
   runCommand,
   runProve,
-  runRatchet
-} from "./chunk-HBM6F3GO.js";
+  runRatchet,
+  versionOf,
+  writeEnvelope
+} from "./chunk-ESN6ULZZ.js";
 export {
   CONFIG_FILE,
   COUNTERS,
   CounterError,
+  ENVELOPES_DIR,
+  UnbalancedEnvelope,
   acquireExclusive,
   counterById,
+  envelopePath,
   formatProve,
   formatReport,
   heavyLockPath,
@@ -28,5 +36,7 @@ export {
   resolveBaseline,
   runCommand,
   runProve,
-  runRatchet
+  runRatchet,
+  versionOf,
+  writeEnvelope
 };

package/package.json

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