@geonosis/ratchet 0.2.0 → 0.3.0

package/README.md

@@ -11,13 +11,61 @@ pnpm add -D @geonosis/ratchet
 ```
 
 ```bash
-geonosis-ratchet              # every counter
+geonosis-ratchet --prove      # first: prove every counter CAN report a finding
+geonosis-ratchet              # then: every counter
 geonosis-ratchet --tier fast  # only the counters in that tier
+geonosis-ratchet --exclusive  # one heavy run at a time on this machine
 geonosis-ratchet --cwd apps/web
 ```
 
 Exit 1 when a number grew, 2 when a counter could not measure at all, 0 otherwise.
 
+## `--prove` is the first thing to run after installing
+
+A counter that reads 0 because the tree is clean and a counter that reads 0 because it can no longer
+read the tool are the same number. The second is worse than no gate at all: it reports green, and
+when it shrinks the ratchet writes the lie into the baseline.
+
+This is not hypothetical. On one day, 2026-08-29, five gates were found reporting green while
+measuring nothing: this package's own `oxlintErrors` read 0 under the `--format=unix` its config
+asked for, and had since it was written; a lint rule sat at `"error"` for months with no
+configuration to fire on; a parity run said PASS about rules it never exercised; a test runner
+exited 0 over failing suites for weeks; and a `git rebase | tail` hid a conflict behind a pipe's
+exit status.
+
+So every counter ships a **probe**: a known-bad input it must be able to read.
+
+```bash
+geonosis-ratchet --prove
+```
+
+```
+  PROVEN oxlintErrors: reads 1 on a planted finding
+  PROVEN typecheckErrors: reads 1 on a planted finding
+  PROVEN lawLineCount: reads 3 on a planted finding
+
+prove PASS — every counter read the finding its probe planted.
+```
+
+Each configured counter's probe plants its input in a temp directory — never in your repo — and the
+counter runs there exactly as it runs in a real measurement. The tools come from your repo's
+`node_modules/.bin`, so what is proven is the toolchain you will actually measure with.
+
+- `PROVEN <key>: reads N on a planted finding` — the gate has been seen red.
+- `CANNOT FAIL <key>: read 0` — the input was planted and the counter still read nothing.
+- `CANNOT MEASURE <key>: <error>` — the probe threw, or the counter ships none.
+
+The run stops at the first counter that reads 0 or throws, and exits **2**. Put it in front of the
+ratchet in whatever script your CI runs:
+
+```jsonc
+{ "verify": "… && geonosis-ratchet --prove && geonosis-ratchet" }
+```
+
+A counter you wrote yourself takes a `probe` beside its `run`: `{ input: (dir) => void, command?:
+(dir) => string, params?, expect: number }`. `expect` is what the planted input is worth, and it is
+at least 1 — a probe that plants nothing proves nothing.
+
 ### A baseline is not proof the gate still gates
 
 The ratchet compares a number against a number. Swapping the tool that produces it — a vendored lint
@@ -34,6 +82,33 @@ npx geonosis-lint-parity --a oxlintrc.old.json --b oxlintrc.new.json --out proof
 
 Reach first — parity between two configs that both fire nothing is perfect parity — then the tree.
 
+## `--exclusive`: one heavy run at a time on a machine
+
+Three sessions on one laptop each started their own verify, and a 25-minute run took two hours and
+came back with failures that were about the load, not the code. "Announce before anything heavy" is
+a habit that works right up until the moment somebody is concentrating; `--exclusive` is the same
+agreement as code.
+
+```bash
+geonosis-ratchet --exclusive --exclusive-timeout 1800
+```
+
+It takes `~/.cache/geonosis/heavy.lock` before measuring anything, writing the pid, cwd and start
+time into it, and gives it back in a `finally` and on SIGINT/SIGTERM. A second run waits instead of
+contending, and says every 15 seconds who has the lock and for how long. A holder whose process is
+gone — killed, crashed, a lid closed mid-run — is stale, and is taken over with a printed note
+rather than making everyone wait for a pid that no longer exists. The wait is bounded:
+`--exclusive-timeout` seconds (default 1800) and then exit 2, because a run that hangs silently
+looks exactly like a run that is broken.
+
+**Put it on the script your sessions actually run**, so nothing has to remember:
+
+```jsonc
+{ "verify": "… && geonosis-ratchet --prove && geonosis-ratchet --exclusive" }
+```
+
+`GEONOSIS_HEAVY_LOCK` moves the lock file — for a sandbox with no writable home, or for a test.
+
 ## Config
 
 `geonosis.ratchet.json` at the repo root names the counters and how to run them:
@@ -141,17 +216,46 @@ of hidden inside a lump sum that a different rule's warning could mask. dielime
   packages first.** In a fresh worktree the `dist/*.d.ts` files do not exist yet, and `tsc` reports
   a false +N of missing-module errors that has nothing to do with the change under test. `pnpm build
   && geonosis-ratchet` is the shape; a bare `geonosis-ratchet` in a clean checkout is not.
+
+  The counter no longer reports that number. When tsc's TS2307 or TS2305 diagnostics name a package
+  of this workspace — read from `pnpm-workspace.yaml`, or `workspaces` in the root `package.json` —
+  it refuses:
+
+  ```
+  geonosis-ratchet: typecheckErrors: workspace packages not built: @dielime/shared —
+  build them before measuring typecheckErrors
+  ```
+
+  Mixed output refuses too. Counting the readable half would produce a number that is neither the
+  debt nor the build error, banked into the baseline as though somebody had measured it. An
+  unresolved module that is NOT a workspace package — `lodash` — is counted as before: that is a
+  dependency to fix, not a build to run.
 - **A release-age cooldown will refuse a package published minutes ago.** If pnpm's
   `minimumReleaseAge` blocks `@geonosis/*`, exclude the scope for that project — pnpm writes
   `minimumReleaseAgeExclude` into `pnpm-workspace.yaml` — rather than lowering the cooldown. The
   cooldown is protecting every other dependency in the tree; the exclusion is scoped to the one you
   chose to trust.
-- **Bumping to a new version: keep both exclusions until the install is done, then drop the old one
-  in the same commit.** `minimumReleaseAgeExclude` is matched against what the lockfile is being
-  asked to resolve, so removing the old pair first makes the resolver walk back through the version
-  it is replacing and refuse it — an install that fails for the version you are leaving, not the one
-  you are taking. Old and new together, install, then delete the old line before committing: an
-  exclusion left behind is a cooldown quietly off for a package nobody is watching any more.
+- **Bumping to a new version: keep BOTH exclusion pairs — old and new — through the install, then
+  drop the old one and re-verify.** The policy check is applied to the entries in the LOCKFILE, not
+  only to what you asked for, so removing the old pair first makes the resolver walk back through
+  the version you are leaving and refuse it — an install that fails for the version you are
+  replacing, not the one you are taking. The order that works, learned under load on dielime's 0.2.0
+  bump:
+
+  ```bash
+  # both pairs in pnpm-workspace.yaml's minimumReleaseAgeExclude
+  pnpm install
+  grep -c "@geonosis/.*@<old>" pnpm-lock.yaml   # must be 0 before the old pair goes
+  # now delete the old pair
+  pnpm install --frozen-lockfile
+  ```
+
+  An exclusion left behind is a cooldown quietly off for a package nobody is watching any more, so
+  the deletion belongs in the same commit as the bump.
+
+- **That policy check walks every entry in the lockfile and looks hung. It is not.** ~2,300 entries
+  took ~90 seconds on a loaded laptop with no output while it worked. Wait for it rather than
+  killing the install and re-running into the same wait.
 
 ## Counters
 
@@ -161,7 +265,7 @@ Every counter takes its `command` from the config, so the toolchain stays the re
 | --- | --- | --- |
 | `oxlintErrors` / `oxlintWarnings` | findings under any shape oxlint prints — `--format=unix`, the compact `agent` format, the graphical `default` — cross-checked against the tool's own summary | `command`, `expectFormat` |
 | `oxlintRule` | one named rule's findings, counted only on lines the run reported as findings and refused when none of them attributes itself readably; with `config`, after forcing the rule to `error` in a temp copy — `"warn"`, `"off"` and the `["off", { … }]` array form alike — so debt cannot grow behind a downgrade | `rule`, `config`, `command`, `expectFormat` |
-| `typecheckErrors` | `error TS` occurrences | `command` |
+| `typecheckErrors` | `error TS` occurrences, refusing when TS2305/TS2307 name a workspace package of this repo — an unbuilt sibling is a missing build, not debt | `command` |
 | `testFailures` | the runner's own failure summary; throws when neither a pass nor a fail count is readable | `command` |
 | `unformattedFiles` | paths `--list-different` names that exist on disk | `command` |
 | `cloneCount` | jscpd's `Found N clones` | `command` |

package/dist/{chunk-BTWIR7DK.js → chunk-XYTUTPQI.js}

@@ -23,9 +23,23 @@ var stringsParam = (params, name, fallback) => {
 var countMatches = (text, pattern) => text.match(new RegExp(pattern.source, `${pattern.flags.replace("g", "")}g`))?.length ?? 0;
 var escapeForRegex = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
+// src/counters/plant.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+var plant = (dir, relative, contents) => {
+  const path = join(dir, relative);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, contents);
+};
+var captured = (sample) => ({
+  command: () => "cat sample.txt",
+  input: (dir) => plant(dir, "sample.txt", sample)
+});
+
 // src/counters/arch.ts
 var archViolations = {
   id: "archViolations",
+  probe: { ...captured("\u2717 cell imports cell\nok\n"), expect: 1 },
   run: async ({ params, run }) => {
     const command = stringParam("archViolations", params, "command");
     const match = new RegExp(stringParam("archViolations", params, "match", "^\u2717"));
@@ -37,6 +51,7 @@ var archViolations = {
 var CLONES = /Found (\d+) clones?/;
 var cloneCount = {
   id: "cloneCount",
+  probe: { ...captured("Found 1 clone.\n"), expect: 1 },
   run: async ({ params, run }) => {
     const command = stringParam("cloneCount", params, "command", "npx jscpd .");
     const output = run(command).output;
@@ -60,6 +75,7 @@ var DEFAULT_HEADINGS = [
 ];
 var knipIssues = {
   id: "knipIssues",
+  probe: { ...captured("Unused files (1)\nsrc/gone.ts\n"), expect: 1 },
   run: async ({ params, run }) => {
     const command = stringParam("knipIssues", params, "command", "npx knip --reporter compact");
     const output = run(command).output;
@@ -69,6 +85,7 @@ var knipIssues = {
 var ISSUES = /(\d+) issues? found/;
 var boundaryIssues = {
   id: "boundaryIssues",
+  probe: { ...captured("Checking...\n1 issue found\n"), expect: 1 },
   run: async ({ params, run }) => {
     const command = stringParam("boundaryIssues", params, "command", "npx turbo boundaries");
     return Number(run(command).output.match(ISSUES)?.[1] ?? 0);
@@ -80,6 +97,11 @@ import { existsSync } from "fs";
 import { resolve } from "path";
 var unformattedFiles = {
   id: "unformattedFiles",
+  probe: {
+    command: () => "oxfmt --list-different .",
+    expect: 1,
+    input: (dir) => plant(dir, "a.ts", "export const a    =   {b:1,\n   c:2}\n")
+  },
   run: async ({ cwd, params, run }) => {
     const command = stringParam(
       "unformattedFiles",
@@ -96,6 +118,11 @@ import { existsSync as existsSync2, readFileSync } from "fs";
 import { resolve as resolve2 } from "path";
 var lawLineCount = {
   id: "lawLineCount",
+  probe: {
+    expect: 3,
+    input: (dir) => plant(dir, "CLAUDE.md", "one\ntwo\nthree\n"),
+    params: { path: "CLAUDE.md" }
+  },
   run: async ({ cwd, params }) => {
     const relative = stringParam("lawLineCount", params, "path", "CLAUDE.md");
     const path = resolve2(cwd, relative);
@@ -105,9 +132,23 @@ var lawLineCount = {
 };
 
 // src/counters/oxlint.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, rmSync, writeFileSync } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "fs";
 import { resolve as resolve3 } from "path";
 var DEFAULT_COMMAND = "npx oxlint --format=unix --config .oxlintrc.json .";
+var PROBE_COMMAND = "oxlint --format=unix --config .oxlintrc.json .";
+var oxlintProbe = (severity, rule, source) => ({
+  command: () => PROBE_COMMAND,
+  input: (dir) => {
+    plant(
+      dir,
+      ".oxlintrc.json",
+      JSON.stringify({ plugins: ["typescript"], rules: { [rule]: severity } })
+    );
+    plant(dir, "src/a.ts", source);
+  }
+});
+var ONE_ANY = "export const cast = (value: any): string => String(value)\n";
+var ONE_LOOSE = "export const loose = (a: unknown, b: unknown): boolean => a == b\n";
 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;
@@ -177,6 +218,11 @@ ${output.trim()}`);
 };
 var oxlintErrors = {
   id: "oxlintErrors",
+  probe: {
+    ...oxlintProbe("error", "typescript/no-explicit-any", ONE_ANY),
+    expect: 1,
+    params: { expectFormat: "unix" }
+  },
   run: async ({ params, run }) => {
     const command = stringParam("oxlintErrors", params, "command", DEFAULT_COMMAND);
     const expect = expectedFormat("oxlintErrors", params);
@@ -185,6 +231,13 @@ var oxlintErrors = {
 };
 var oxlintWarnings = {
   id: "oxlintWarnings",
+  // A warning, so the run exits 0 — the window `expectFormat` exists to close is also the window a
+  // probe has to survive.
+  probe: {
+    ...oxlintProbe("warn", "eqeqeq", ONE_LOOSE),
+    expect: 1,
+    params: { expectFormat: "unix" }
+  },
   run: async ({ params, run }) => {
     const command = stringParam("oxlintWarnings", params, "command", DEFAULT_COMMAND);
     const expect = expectedFormat("oxlintWarnings", params);
@@ -206,6 +259,13 @@ ${result.output.trim()}`
 };
 var oxlintRule = {
   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.
+  probe: {
+    ...oxlintProbe("error", "typescript/no-explicit-any", ONE_ANY),
+    expect: 1,
+    params: { expectFormat: "unix", rule: "no-explicit-any" }
+  },
   run: async ({ cwd, key, params, run }) => {
     const rule = stringParam("oxlintRule", params, "rule");
     const command = stringParam("oxlintRule", params, "command", DEFAULT_COMMAND);
@@ -219,7 +279,7 @@ var oxlintRule = {
       new RegExp(`("[^"]*${escapeForRegex(rule)}"\\s*:\\s*\\[?\\s*)"(warn|off)"`),
       '$1"error"'
     );
-    writeFileSync(resolve3(cwd, strictName), strict);
+    writeFileSync2(resolve3(cwd, strictName), strict);
     try {
       return countRule(run(command.replace("{config}", strictName)), rule, expect);
     } finally {
@@ -233,6 +293,9 @@ var DEFAULT_PATTERNS = ["^(apps|packages)/[^/]+/src/"];
 var NOT_RUNTIME = /(\.test\.|\.spec\.|__tests__\/|__fixtures__\/|\.d\.ts$)/;
 var runtimeCodeShipped = {
   id: "runtimeCodeShipped",
+  // Its failing reading is 1, not 0: the finding to plant is a diff of documentation with no
+  // runtime file in it, which is exactly the tick this counter exists to refuse.
+  probe: { ...captured("docs/design.md\nplans/019.md\n"), expect: 1 },
   run: async ({ params, run }) => {
     const command = stringParam(
       "runtimeCodeShipped",
@@ -251,10 +314,11 @@ var runtimeCodeShipped = {
 // src/counters/sum-of-counts.ts
 var sumOfCounts = {
   id: "sumOfCounts",
+  probe: { ...captured("src/a.ts:1\nsrc/b.ts:0\n"), expect: 1 },
   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(([, captured]) => Number(captured ?? 0)).filter((count) => Number.isFinite(count)).reduce((sum, count) => sum + count, 0);
+    return [...run(command).output.matchAll(match)].map(([, digits]) => Number(digits ?? 0)).filter((count) => Number.isFinite(count)).reduce((sum, count) => sum + count, 0);
   }
 };
 
@@ -263,6 +327,7 @@ var FAILED = /(\d+)\s+fail(?:ed|ing|s)?\b/;
 var PASSED = /(\d+)\s+pass(?:ed|ing|es)?\b/;
 var testFailures = {
   id: "testFailures",
+  probe: { ...captured("  Tests  1 failed | 0 passed (1)\n"), expect: 1 },
   run: async ({ params, run }) => {
     const command = stringParam("testFailures", params, "command", "npx vitest run");
     const output = run(command).output;
@@ -277,12 +342,102 @@ ${output.trim().slice(-500)}`
   }
 };
 
+// src/counters/workspace.ts
+import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync3 } from "fs";
+import { join as join2, resolve as resolve4 } from "path";
+var SKIP = /^(node_modules|\.)/;
+var childDirs = (dir) => {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !SKIP.test(entry.name)).map((entry) => join2(dir, entry.name));
+  } catch {
+    return [];
+  }
+};
+var descendants = (dir, depth) => depth === 0 ? [dir] : [dir, ...childDirs(dir).flatMap((child) => descendants(child, depth - 1))];
+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) => join2(dir, segment)).filter((dir) => existsSync4(dir));
+  }
+  return dirs;
+};
+var QUOTED = /^['"]|['"]$/g;
+var cleaned = (value) => value.replace(/#.*$/, "").trim().replaceAll(QUOTED, "");
+var pnpmPatterns = (path) => {
+  const lines = readFileSync3(path, "utf8").split("\n");
+  const at = lines.findIndex((line) => line.startsWith("packages:"));
+  if (at === -1) return [];
+  const inline = lines[at]?.slice("packages:".length).trim() ?? "";
+  if (inline.startsWith("[")) {
+    return inline.replace(/^\[|\]$/g, "").split(",").map(cleaned).filter((one) => one !== "");
+  }
+  const patterns = [];
+  for (const line of lines.slice(at + 1)) {
+    const item = /^\s*-\s*(.+)$/.exec(line);
+    if (item?.[1] !== void 0) {
+      patterns.push(cleaned(item[1]));
+      continue;
+    }
+    if (line.trim() !== "") break;
+  }
+  return patterns;
+};
+var npmPatterns = (path) => {
+  const parsed = JSON.parse(readFileSync3(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 = join2(dir, "package.json");
+  if (!existsSync4(manifest)) return void 0;
+  try {
+    const { name } = JSON.parse(readFileSync3(manifest, "utf8"));
+    return typeof name === "string" && name !== "" ? name : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var workspacePackageNames = (cwd) => {
+  const root = resolve4(cwd);
+  const pnpm = join2(root, "pnpm-workspace.yaml");
+  const manifest = join2(root, "package.json");
+  const patterns = existsSync4(pnpm) ? pnpmPatterns(pnpm) : existsSync4(manifest) ? npmPatterns(manifest) : [];
+  const names = patterns.filter((pattern) => !pattern.startsWith("!")).flatMap((pattern) => expand(root, pattern)).map((dir) => nameOf(dir)).filter((name) => name !== void 0);
+  return [...new Set(names)];
+};
+
 // src/counters/typecheck.ts
+var UNRESOLVED = /error TS(?:2305|2307): ([^\n]*)/g;
+var SPECIFIER = /'([^']+)'/g;
+var specifiersIn = (message) => [...message.matchAll(SPECIFIER)].map(([, quoted]) => (quoted ?? "").replaceAll('"', ""));
+var unbuiltIn = (cwd, output) => {
+  const messages = [...output.matchAll(UNRESOLVED)].map(([, message]) => message ?? "");
+  if (messages.length === 0) return [];
+  const packages = workspacePackageNames(cwd);
+  const named = messages.flatMap((message) => specifiersIn(message)).flatMap(
+    (specifier) => packages.filter((name) => specifier === name || specifier.startsWith(`${name}/`))
+  );
+  return [...new Set(named)].toSorted();
+};
 var typecheckErrors = {
   id: "typecheckErrors",
-  run: async ({ params, run }) => {
+  probe: {
+    command: () => "tsc --noEmit a.ts",
+    expect: 1,
+    input: (dir) => plant(dir, "a.ts", "export const n: number = 'not a number'\n")
+  },
+  run: async ({ cwd, params, run }) => {
     const command = stringParam("typecheckErrors", params, "command", "npx tsc --noEmit");
-    return countMatches(run(command).output, /error TS/);
+    const output = run(command).output;
+    const unbuilt = unbuiltIn(cwd, output);
+    if (unbuilt.length > 0) {
+      throw new CounterError(
+        "typecheckErrors",
+        `workspace packages not built: ${unbuilt.join(", ")} \u2014 build them before measuring typecheckErrors`
+      );
+    }
+    return countMatches(output, /error TS/);
   }
 };
 
@@ -312,17 +467,104 @@ var counterById = (id) => {
   return counter;
 };
 
+// src/lock.ts
+import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync4, rmSync as rmSync2, writeSync } from "fs";
+import { homedir } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+var heavyLockPath = () => process.env.GEONOSIS_HEAVY_LOCK ?? join3(homedir(), ".cache", "geonosis", "heavy.lock");
+var sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+var holderOf = (path) => {
+  try {
+    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    return typeof parsed.pid === "number" ? {
+      cwd: parsed.cwd ?? "somewhere",
+      pid: parsed.pid,
+      startedAt: parsed.startedAt ?? "unknown"
+    } : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+};
+var heldFor = (holder) => {
+  const since = Date.parse(holder.startedAt);
+  if (Number.isNaN(since)) return "an unknown time";
+  return `${Math.round((Date.now() - since) / 1e3)}s`;
+};
+var write = (path) => {
+  mkdirSync2(dirname2(path), { recursive: true });
+  try {
+    const handle = openSync(path, "wx");
+    const mine = {
+      cwd: process.cwd(),
+      pid: process.pid,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    writeSync(handle, JSON.stringify(mine));
+    closeSync(handle);
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST") return false;
+    throw error;
+  }
+};
+var acquireExclusive = async ({
+  noticeMs = 15e3,
+  path = heavyLockPath(),
+  pollMs = 250,
+  say = (line) => process.stderr.write(`${line}
+`),
+  timeoutSeconds = 1800
+} = {}) => {
+  const until = Date.now() + timeoutSeconds * 1e3;
+  let told = 0;
+  const release = () => {
+    if (holderOf(path)?.pid === process.pid) rmSync2(path, { force: true });
+  };
+  for (; ; ) {
+    if (write(path)) return release;
+    const holder = holderOf(path);
+    if (holder === void 0 || !alive(holder.pid)) {
+      say(
+        `geonosis-ratchet: taking over a stale heavy lock (pid ${holder?.pid ?? "unreadable"} is gone)`
+      );
+      rmSync2(path, { force: true });
+      continue;
+    }
+    if (Date.now() >= until) {
+      throw new Error(
+        `waited ${timeoutSeconds}s for the heavy lock held by pid ${holder.pid} in ${holder.cwd} (${heldFor(holder)}) \u2014 give it longer with --exclusive-timeout, or stop that run`
+      );
+    }
+    const now = Date.now();
+    if (now - told >= noticeMs) {
+      told = now;
+      say(
+        `geonosis-ratchet: waiting for the heavy lock \u2014 pid ${holder.pid} in ${holder.cwd}, held for ${heldFor(holder)}`
+      );
+    }
+    await sleep(pollMs);
+  }
+};
+
 // src/config.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
-import { resolve as resolve4 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { resolve as resolve5 } from "path";
 var CONFIG_FILE = "geonosis.ratchet.json";
 var keyOf = (entry) => entry.key ?? entry.counter;
 var loadConfig = (cwd) => {
-  const path = resolve4(cwd, CONFIG_FILE);
-  if (!existsSync4(path)) {
+  const path = resolve5(cwd, CONFIG_FILE);
+  if (!existsSync5(path)) {
     throw new Error(`no ${CONFIG_FILE} in ${cwd} \u2014 the ratchet has nothing to count`);
   }
-  const parsed = JSON.parse(readFileSync3(path, "utf8"));
+  const parsed = JSON.parse(readFileSync5(path, "utf8"));
   if (!Array.isArray(parsed.counters)) {
     throw new Error(`${CONFIG_FILE} has no "counters" array`);
   }
@@ -352,11 +594,12 @@ var loadConfig = (cwd) => {
 // src/shell.ts
 import { execSync } from "child_process";
 var ANSI = /\[[0-9;]*m/g;
-var runCommand = (cwd, counterId) => (command) => {
+var runCommand = (cwd, counterId, env) => (command) => {
   try {
     const output = execSync(`${command} 2>&1`, {
       cwd,
       encoding: "utf8",
+      env,
       maxBuffer: 64 * 1024 * 1024,
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -376,9 +619,99 @@ ${output.trim()}`
   }
 };
 
+// src/prove.ts
+import { existsSync as existsSync6, mkdtempSync, rmSync as rmSync3 } from "fs";
+import { tmpdir } from "os";
+import { delimiter, dirname as dirname3, join as join4, resolve as resolve6 } from "path";
+var toolPath = (cwd) => {
+  const dirs = [];
+  let dir = resolve6(cwd);
+  for (; ; ) {
+    const bin = join4(dir, "node_modules", ".bin");
+    if (existsSync6(bin)) dirs.push(bin);
+    const parent = dirname3(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return [...dirs, process.env.PATH ?? ""].join(delimiter);
+};
+var NO_PROBE = "no probe \u2014 a counter nobody has seen read a planted finding has not been shown to measure";
+var proofOf = async (counter, key, path) => {
+  const probe = counter.probe;
+  if (probe === void 0)
+    return { counter: counter.id, key, reason: NO_PROBE, verdict: "cannot-measure" };
+  const dir = mkdtempSync(join4(tmpdir(), "geonosis-prove-"));
+  try {
+    probe.input(dir);
+    const command = probe.command?.(dir);
+    const reading = await counter.run({
+      cwd: dir,
+      key,
+      params: { ...probe.params, ...command === void 0 ? {} : { command } },
+      run: runCommand(dir, counter.id, { ...process.env, PATH: path })
+    });
+    if (reading === 0) return { counter: counter.id, key, reading, verdict: "cannot-fail" };
+    if (reading < probe.expect) {
+      return { counter: counter.id, expected: probe.expect, key, reading, verdict: "misread" };
+    }
+    return { counter: counter.id, key, reading, verdict: "proven" };
+  } catch (error) {
+    return { counter: counter.id, key, reason: error.message, verdict: "cannot-measure" };
+  } finally {
+    rmSync3(dir, { force: true, recursive: true });
+  }
+};
+var outsideTier = (entry, tier) => entry.tiers !== void 0 && !entry.tiers.includes(tier);
+var runProve = async ({
+  counters,
+  cwd,
+  tier
+}) => {
+  const config = loadConfig(cwd);
+  const byId = new Map(counters.map((one) => [one.id, one]));
+  const path = toolPath(cwd);
+  const proofs = [];
+  for (const entry of config.counters) {
+    const counter = byId.get(entry.counter);
+    if (counter === void 0) {
+      throw new Error(
+        `no counter implements "${entry.counter}" \u2014 known ids: ${[...byId.keys()].toSorted().join(", ")}`
+      );
+    }
+    const key = keyOf(entry);
+    if (tier !== void 0 && outsideTier(entry, tier)) {
+      proofs.push({ key, tier, verdict: "skipped" });
+      continue;
+    }
+    const proof = await proofOf(counter, key, path);
+    proofs.push(proof);
+    if (proof.verdict !== "proven" && proof.verdict !== "skipped") {
+      return { proofs, proven: false };
+    }
+  }
+  return { proofs, proven: true };
+};
+var formatProve = ({ proofs, proven }) => {
+  const lines = proofs.map((one) => {
+    if (one.verdict === "skipped") return `  SKIP ${one.key}: not measured by --tier ${one.tier}`;
+    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 === "misread") {
+      return `  MISREAD ${one.key}: read ${one.reading} where its probe planted ${one.expected}`;
+    }
+    return `  PROVEN ${one.key}: reads ${one.reading} on a planted finding`;
+  });
+  lines.push(
+    "",
+    proven ? "prove PASS \u2014 every counter read the finding its probe planted." : "prove FAIL \u2014 a gate that has never been seen red has not been shown to measure."
+  );
+  return `${lines.join("\n")}
+`;
+};
+
 // src/ratchet.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
-import { resolve as resolve5 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
+import { resolve as resolve7 } from "path";
 var EVIDENCE_LINES = 10;
 var recorded = (run) => {
   let output = "";
@@ -396,18 +729,18 @@ var verdictOf = (now, baseline) => {
   if (now < baseline) return "shrank";
   return "held";
 };
-var outsideTier = (entry, tier) => entry.tiers !== void 0 && !entry.tiers.includes(tier);
+var outsideTier2 = (entry, tier) => entry.tiers !== void 0 && !entry.tiers.includes(tier);
 var runRatchet = async ({
   counters,
   cwd,
   tier
 }) => {
   const config = loadConfig(cwd);
-  const baselinePath = resolve5(cwd, config.baseline);
-  if (!existsSync5(baselinePath)) {
+  const baselinePath = resolve7(cwd, config.baseline);
+  if (!existsSync7(baselinePath)) {
     throw new Error(`no ${config.baseline} in ${cwd} \u2014 nothing to ratchet against`);
   }
-  const baseline = JSON.parse(readFileSync4(baselinePath, "utf8"));
+  const baseline = JSON.parse(readFileSync6(baselinePath, "utf8"));
   const byId = new Map(counters.map((one) => [one.id, one]));
   const measurements = [];
   for (const entry of config.counters) {
@@ -418,7 +751,7 @@ var runRatchet = async ({
       );
     }
     const key = keyOf(entry);
-    if (tier !== void 0 && outsideTier(entry, tier)) {
+    if (tier !== void 0 && outsideTier2(entry, tier)) {
       measurements.push({ key, tier, verdict: "skipped" });
       continue;
     }
@@ -446,7 +779,7 @@ var runRatchet = async ({
     for (const one of measurements) {
       if (one.verdict !== "skipped") next[one.key] = one.now;
     }
-    writeFileSync2(baselinePath, `${JSON.stringify(next, null, 2)}
+    writeFileSync3(baselinePath, `${JSON.stringify(next, null, 2)}
 `);
     return { measurements, rewritten: true };
   }
@@ -485,10 +818,14 @@ export {
   CounterError,
   COUNTERS,
   counterById,
+  heavyLockPath,
+  acquireExclusive,
   CONFIG_FILE,
   keyOf,
   loadConfig,
   runCommand,
+  runProve,
+  formatProve,
   runRatchet,
   formatReport
 };

package/dist/cli.js

@@ -1,21 +1,52 @@
 import {
   COUNTERS,
+  acquireExclusive,
+  formatProve,
   formatReport,
+  runProve,
   runRatchet
-} from "./chunk-BTWIR7DK.js";
+} from "./chunk-XYTUTPQI.js";
 
 // src/cli.ts
 var cwdFlag = process.argv.indexOf("--cwd");
 var cwd = cwdFlag === -1 ? process.cwd() : process.argv[cwdFlag + 1] ?? process.cwd();
 var tierFlag = process.argv.indexOf("--tier");
 var tier = tierFlag === -1 ? void 0 : process.argv[tierFlag + 1];
+var proving = process.argv.includes("--prove");
+var exclusive = process.argv.includes("--exclusive");
+var timeoutFlag = process.argv.indexOf("--exclusive-timeout");
+var timeoutSeconds = timeoutFlag === -1 ? void 0 : Number(process.argv[timeoutFlag + 1] ?? Number.NaN);
+var measure = async () => {
+  if (proving) {
+    const proof = await runProve({ counters: COUNTERS, cwd, tier });
+    process.stdout.write(formatProve(proof));
+    return proof.proven ? 0 : 2;
+  }
+  const result = await runRatchet({ counters: COUNTERS, cwd, tier });
+  process.stdout.write(formatReport(result));
+  return result.measurements.some((one) => one.verdict === "grew") ? 1 : 0;
+};
 try {
   if (tierFlag !== -1 && (tier === void 0 || tier.startsWith("--"))) {
     throw new Error("--tier needs a tier name");
   }
-  const result = await runRatchet({ counters: COUNTERS, cwd, tier });
-  process.stdout.write(formatReport(result));
-  process.exit(result.measurements.some((one) => one.verdict === "grew") ? 1 : 0);
+  if (timeoutSeconds !== void 0 && !(timeoutSeconds > 0)) {
+    throw new Error("--exclusive-timeout needs a number of seconds");
+  }
+  const release = exclusive ? await acquireExclusive({ timeoutSeconds }) : () => void 0;
+  const giveBack = () => {
+    release();
+    process.exit(130);
+  };
+  process.on("SIGINT", giveBack);
+  process.on("SIGTERM", giveBack);
+  let code = 2;
+  try {
+    code = await measure();
+  } finally {
+    release();
+  }
+  process.exit(code);
 } catch (error) {
   process.stderr.write(`geonosis-ratchet: ${error.message}
 `);

package/dist/index.js

@@ -2,21 +2,29 @@ import {
   CONFIG_FILE,
   COUNTERS,
   CounterError,
+  acquireExclusive,
   counterById,
+  formatProve,
   formatReport,
+  heavyLockPath,
   keyOf,
   loadConfig,
   runCommand,
+  runProve,
   runRatchet
-} from "./chunk-BTWIR7DK.js";
+} from "./chunk-XYTUTPQI.js";
 export {
   CONFIG_FILE,
   COUNTERS,
   CounterError,
+  acquireExclusive,
   counterById,
+  formatProve,
   formatReport,
+  heavyLockPath,
   keyOf,
   loadConfig,
   runCommand,
+  runProve,
   runRatchet
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/ratchet",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Debt as a number that may only shrink — one ratchet, pluggable counters.",
   "keywords": [
     "ratchet",