probatio 0.1.3 → 0.3.0

package/README.md

@@ -20,19 +20,61 @@ Each command prints one JSON object and exits 0 only when `ok` is true.
 
 ```json
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "ok": true,
   "summary": "0 no coverage, 0 survived, 1 killed, 0 flaky, 0 timed out, 0 errored, of 1 finished.",
   "next": "No survivor in this batch.",
-  "nextCall": { "argv": ["mutate", "tally", "--out", ".probatio/runs"] }
+  "nextCall": null
 }
 ```
 
+Every command's output has a JSON Schema in [schemas/](schemas/), and `probatio schema <command>` prints it. `schemaVersion` is 2. It changes when a field is renamed, removed, or changes meaning, and a new field does not change it.
+
 Agents changing this repo should read [AGENTS.md](AGENTS.md). The MCP server is `probatio mcp`. Snippets are in the MCP section below. People building Probatio should read [docs/builders.md](docs/builders.md). Small suites live in [examples/](examples/).
 
 ## Status
 
-Status (2026-10-06): `mutate run` discovers the project suite and scores it. Node, pytest, C (when the binary was built with LLVM coverage), Go, Maven/Java, Rust, C#, and Mocha collect a line map on the baseline. Mocha's map comes from its own root hooks. Loading the node:test collector under Mocha does not name Mocha tests. A line no test executes is `no coverage`, and the suite is not started. A plain Node script can write the lines it ran, and the parent test that reads that dump stores them under its own name. A child the parent does not read stays `no coverage`, and the suite is not started. A suite with no line map, a baseline of 5 seconds or more, and more than 30 mutants stops before the first mutant. `verify-change` names the tests the line map ran. It scores `src/`, a `lib/` file when the package tests import `lib/`, and a Go file beside `go.mod`. Tests, docs, `dist/`, and `node_modules` stay unseen. `ran` stays the direct-importer list. Covered mutants of one Node file run one after another inside the suite process that is already running. `--workers` stays 1. A Node test that sets its own `timeout` keeps that time when `--test-timeout-ms` is shorter. A mutant that crashes or leaves that process dirty ends it, and the next mutant starts clean. An uncovered line still does not start the suite. `mutate tally` does not delete a test. A kill is an assertion the suite already had. A sealed miss means the suite did not see the bug. The kill count is not a merge gate. On Commons CSV (Apache-2.0, commit `2c83a308`), two sealed runs agreed: with the new test file hidden, `CSVFormatTest.testFormatThrowsNullPointerException` failed on the reverted printer. `deletedTests` stayed 0. That older JUnit platform did not write a line map, so the first pass was the whole suite and confirm reran the older test. Auspex, markupsafe, and a hand-planted fixture are not that result. The package version in this repository is 0.1.3. npm latest is 0.1.2 (`29301bc`). The BugsInPy search row is still open, and the rows that apply only when a sealed run misses do not apply, because this catch held. The MCP server speaks one JSON object per line and returns the same JSON as the CLI.
+What a result means:
+
+- **killed**: a test the suite already had failed an assertion on the mutant. It is not proof the change is safe, and the count is not a merge gate.
+- **survived**: a test ran the line and did not notice. That is a gap. Add a test that fails on the mutant, then rerun.
+- **no coverage**: no test executed that line, so the suite was not started. It is not a pass and not a gap.
+- **did not build** (`unviable`): the compiler rejected the mutant, or on Node a test file no longer links (a removed export, a missing module, a file that does not parse). No test code ran, so it is not a kill and not a gap. Java, Rust, Go, and C# reject the same change at compile time, so every language gets the same verdict. For a ledger fix it means the reverted commit cannot be a regression check as it stands: write a hand-made mutant (`source=hand`) that keeps the API and puts the old behaviour back.
+- **timed out**: the baseline clock ran out. It is not a kill.
+- A red baseline, or a baseline with no test report, stops before the first mutant.
+
+What runs today:
+
+- Discovery finds the project's own suite: `run_tests.sh`, Cargo, Go, Swift, Maven, dotnet, pytest, unittest, node:test, Mocha, and `make test` for COBOL. An unknown layout asks for `--suite-command`.
+- Node, pytest, Go, Maven/Java, Rust, C#, Mocha, and C with LLVM coverage collect a line map on the baseline. A mutant runs only the tests that hit its line.
+- A Node child process started by a test is mapped under that test, with no import in the child and even when it ends with `process.exit`. A child started with a cleared environment cannot be seen and stays `no coverage`.
+- A slow suite with no line map (baseline 5 seconds or more, more than 30 mutants pending) stops before the first mutant.
+- A project that needs its own environment or test-line format says so in `.probatio.json` (below). Probatio does not patch a project's files or environment to make one repository pass.
+
+Sealed runs. A sealed run hides the test that came with a fix, puts the bug back, and asks whether the rest of the suite notices. Seven subjects are recorded (2026-10-05 and 10-06):
+
+| Subject | Result |
+|---|---|
+| QuixBugs, Python program | no coverage: the planted line was not executed |
+| QuixBugs, Java program | survived |
+| Commons CSV, one bug | survived |
+| tqdm, one bug | survived |
+| First one-command `mutate sealed` run | survived, both runs |
+| Commons CSV `c15a06ee` (CSV-288) | the suite stayed green with the test hidden |
+| Commons CSV `2c83a308` (CSV-271) | killed on 10-06 with no line map; survived on 10-08 with the map; see below |
+
+The CSV-271 kill came from `CSVFormatTest.testFormatThrowsNullPointerException`. The fix commit itself edited that test: it changed the asserted stack-frame class from `CSVFormat` to `java.util.Objects`. With the test as it was before the fix, all 92 `CSVFormatTest` tests pass on the reverted code, and no other test fails because of the bug. So no older test caught it. The honest record is that these suites did not notice a hidden real bug, which is what a sealed run is for. A kill that pins an internal detail, such as which class threw, is not the same as a test that checks behaviour.
+
+A blind run of the whole loop (gaps, new tests, then a hidden real bug) on Commons CSV is written up in [docs/demo-commons-csv.md](docs/demo-commons-csv.md). The new tests closed real gaps, and they did not catch the hidden bug. The page says why.
+
+Known limits:
+
+- The sealed list (`seal`) is a plain id list in the state dir. An agent that can read that directory can see it. Keep the state dir and every `mutate sealed` label file outside the workspace of the agents being scored.
+- `mutate sealed` checks whether the fix commit edited the killing test (`fixEdited`, `olderTestCatch`). The fix commit is the scored commit, or `--fix <commit>` when later work sits on top of it. It matches a kill to a file by path, class name, or a test name written in that file. A test renamed by the fix can slip past that match.
+- The Java line map comes from JaCoCo, which does not count a line as executed when a call on that line throws. A test that reaches a line only through an exception is not selected for it, so a mutant there can survive a test that would fail. On Commons CSV-271 the map leaves out `testFormatThrowsNullPointerException` at `CSVPrinter.java:284`, and the sealed run reports survived.
+- The default operator set (`core`) is small: condition swaps, relational swaps, booleans, a dropped `!`. `--operators wide` adds arithmetic, integer constants, and (TypeScript only) a dropped call statement, so a clean batch means more. A summary says which set ran.
+
+The package version in this repository is in `package.json`. The npm badge above is the published version.
 
 ## mutate
 
@@ -44,15 +86,35 @@ npx probatio mutate run --package . --patches .probatio/generate/mutants --out .
 npx probatio mutate tally --out .probatio/runs
 ```
 
+`--operators wide` (on `generate`, `verify-change`, and `golden compare`) adds arithmetic swaps (`+`/`-`, `*`/`/`, `%`), integer constants (`0`→`1`, `1`→`0`, `n`→`n+1`), and a dropped statement. In TypeScript a call statement becomes `void 0`. In Java, C, C++, C#, JavaScript, and Rust, a call, an assignment, or an increment that is a whole statement on its own line becomes `;`. Text languages need the operator spaced on both sides, so `++`, `+=`, `->`, `//`, `**`, unary minus, and pointer stars are left alone. A `+` beside a string literal is concatenation and is left alone. Hex, float, and suffixed literals are not constants. COBOL and assembly get no wide operators, and Python gets no dropped statement. `core` is the default, so ids and counts from earlier runs do not move. `mutants.json` records the set.
+
 `generate` writes operator mutants (conditions, `&&`/`||`, `===`/`!==`, boundaries, booleans, a dropped `!`). The same class is written for COBOL (`.cob`, `.cbl`), Rust, C, C++, Java, Go, Python, JavaScript, and C#. Strings and comments are not mutated. A COBOL `*>` comment and a fixed-format line whose column 7 is `*` or `/` are comments. Each patch is forward: apply it to introduce the bug, and the file says so. When mutants were written, `next` states the count, the suite command if one was discovered, and whether the first run collects a line map.
 
 `run` discovers the suite: `run_tests.sh`, Cargo, Go, Swift, Maven, dotnet, pytest, unittest, node:test, Mocha, then `make test` when COBOL tests sit under that Makefile. An unknown layout stops and asks for `--suite-command`. It does not compile one file and call that the suite. `make test` that would curl or wget a missing file stops, and nothing is fetched. A worktree that has no `node_modules` uses the main checkout's. Omitting `--build` runs no build. Pass `--build` with a command when the suite needs one first.
 
-Node, pytest, Go, Maven/Java, Rust, C#, and Mocha collect a line map on the baseline. C collects one when LLVM coverage was instrumented. Mocha writes its own `{ files }` record from root hooks, keyed by the Mocha title. The node:test collector is a different file and does not name Mocha tests. The map stores the file, the line, and the test names that hit that line. A later mutant runs only those tests (`go test -run`, Maven `-Dtest`, `cargo test`, `dotnet test --filter`, Mocha `--grep`). A line no test executed is `no coverage`, and the suite is not started. A plain Node script can leave a nameless list of the lines it ran. The parent test that reads that list stores them under its own name. A child the parent does not read stays `no coverage`. Covered mutants of one Node file are applied one after another in the suite process already running, and the line map is reset between them. `--workers` stays 1. A crash or a process left dirty ends that process. The next mutant starts clean. A baseline of 5 seconds or more, with no line map and more than 30 mutants still pending, stops before the first mutant. `next` names that baseline and tells you to narrow `--src` or pass a smaller patch directory. A one-file C, C++, Java, COBOL, or assembly launcher is not a suite discovery returns.
+Discovery reads the package root. An example project inside it, such as a directory with its own `go.mod` or `pytest.ini`, is a different project and is not collected. Go needs a `go.mod` at or above the package.
+
+Node, pytest, Go, Maven/Java, Rust, C#, and Mocha collect a line map on the baseline. C collects one when LLVM coverage was instrumented. Mocha writes its own `{ files }` record from root hooks, keyed by the Mocha title. The node:test collector is a different file and does not name Mocha tests. The map stores the file, the line, and the test names that hit that line. A later mutant runs only those tests (`go test -run`, Maven `-Dtest`, `cargo test`, `dotnet test --filter`, Mocha `--grep`). A line no test executed is `no coverage`, and the suite is not started. A Node child process started by a mapped test loads a small collector through `NODE_OPTIONS`. It writes the lines it ran when it exits, including after `process.exit`, and the parent test stores them under its own name. Each test process has its own dump directory, so parallel test files do not take each other's children. A child started with a cleared environment stays `no coverage`. On Node, a test filter that matches nothing is an error, not a survivor, and only the requested tests can be credited with a kill. A test file that fails before any test runs is one of two things. If it does not link or parse (a removed export, a missing module), no code ran, and the mutant is `unviable` unless some other test failed. If its own top-level code ran the mutated program and threw, that is a kill by that file, and confirm reruns the whole file. Covered mutants of one Node file are applied one after another in the suite process already running, and the line map is reset between them. `--workers` stays 1. A crash or a process left dirty ends that process. The next mutant starts clean. A baseline of 5 seconds or more, with no line map and more than 30 mutants still pending, stops before the first mutant. `next` names that baseline and tells you to narrow `--src` or pass a smaller patch directory. A one-file C, C++, Java, COBOL, or assembly launcher is not a suite discovery returns.
+
+The mutant timeout is the baseline duration times 5, and at least 20 seconds, capped by `--suite-timeout-ms`. A timeout is not a kill. `--budget-ms` stops mutant work after the baseline. The first mutant still runs, except for that no-line-map stop. A kill is the test that failed. A mutant the compiler rejects is `unviable`: the summary says `N did not build`, `unviable` and `unviableIds` list them, and they are neither kills nor gaps. Confirm is on by default and reruns the failing names. Pytest names that `-k` cannot express are passed as node ids. A usage error, including pytest exit 4, is not a kill. `verify-change` does not confirm a second time. Add `--affected` to limit the file list to tests that can see the change. The default, once a line map exists, runs the tests on the changed line.
 
-The mutant timeout is the baseline duration times 5, and at least 20 seconds, capped by `--suite-timeout-ms`. A timeout is not a kill. `--budget-ms` stops mutant work after the baseline. The first mutant still runs, except for that no-line-map stop. A kill is the test that failed, or a compiler token when the mutant did not build. Confirm is on by default and reruns the failing names. Pytest names that `-k` cannot express are passed as node ids. A usage error, including pytest exit 4, is not a kill. `verify-change` does not confirm a second time. Add `--affected` to limit the file list to tests that can see the change. The default, once a line map exists, runs the tests on the changed line.
+`tally` reads that run directory. The summary leads with the no-coverage count, then the survivors. `keep` names each test that killed a mutant, once, as an id `--only-test` can run. `noKillsYet` names tests that saw no mutant die in this batch. That is not a reason to delete them: one batch is not evidence, and the Auspex experiment caught 10 of 18 sealed bugs after pruning by kill evidence. `pruning.advice` stays empty and `deletedTests` is 0. A gap is a survivor. An unseen line is not a gap and not a pass. A timeout is neither a kill nor a gap.
 
-`tally` reads that run directory. The summary leads with the no-coverage count, then the survivors. It names tests that killed a mutant and tests that killed nothing. A gap is a survivor. An unseen line is not a gap and not a pass. A timeout is neither a kill nor a gap. `deletedTests` is 0. It does not delete a file.
+`nextCall` writes to a fresh out dir next to the old one, because the old out dir would skip every finished mutant and repeat the old result. With a gap, it reruns the batch on `HEAD` (`<out>.after-gaps`) once the new test is committed. With no gap, it rescores the keep ids at the same commit with `--only-test` (`<out>.rescore`).
+
+## .probatio.json
+
+A project can say how its suite runs. The file sits at the package root and is read even when it is not committed.
+
+```json
+{
+  "env": { "ARCH_NATIVE": "1" },
+  "testLine": "^(Testing .+|Running .+)$",
+  "passLine": "All done, tests as expected"
+}
+```
+
+`env` is added to the suite's environment, for a flag the project's own CI sets. `testLine` names the tests of a `run_tests.sh` suite: each matching line is a test, and the first capture group is the name when there is one. When the suite exits non-zero, the last test line is the one that failed, unless `passLine` was printed. Without `testLine`, a shell suite that prints TAP (`ok 1 - name`, `not ok 2 - name`) is read as TAP. Otherwise it is one command: exit 0 passes, and a failure is `::command`, not an invented test name. An invalid file stops the run and names the field.
 
 ## ledger
 
@@ -60,7 +122,15 @@ The mutant timeout is the baseline duration times 5, and at least 20 seconds, ca
 npx probatio ledger build --package . --commit HEAD --out .probatio/ledger
 ```
 
-A fix commit has a `Fixes-bug:` trailer, or it changes both `src` and a test. `ledger build` reverts that commit's src diff onto the tree you name. A diff that applies is written as a forward patch (`source=history`): apply it to put the bug back. A diff that does not apply is reported, and left for a hand-made patch in the same directory (`source=hand`, `fix=<commit>`). A rebuild keeps those hand-made files. Nothing is fuzzy-applied. A src diff over `--max-lines` (default 300) is skipped. `--max-commits N` reads only the newest N non-merge commits and says when older history was not scanned. The default reads the whole history. A tree is checked out only when a fix inside that cap has to be applied.
+A fix commit has a `Fixes-bug:` trailer, or it changes both `src` and a test. A commit that changes the version in `package.json`, `Cargo.toml`, `pyproject.toml`, or `setup.cfg` is a release, and it is not a fix unless it has the trailer: reverting it would put back several changes, not one bug. `ledger build` reverts that commit's src diff onto the tree you name. A diff that applies is written as a forward patch (`source=history`): apply it to put the bug back. A diff that does not apply is reported, and left for a hand-made patch in the same directory (`source=hand`, `fix=<commit>`). A rebuild keeps those hand-made files. Nothing is fuzzy-applied. A src diff over `--max-lines` (default 300) is skipped. `--max-commits N` reads only the newest N non-merge commits and says when older history was not scanned. The default reads the whole history. A tree is checked out only when a fix inside that cap has to be applied.
+
+### ledger check
+
+```bash
+npx probatio ledger check --package . --ledger ledger --out .probatio/ledger-check
+```
+
+Runs every ledger bug that applies (history reverts and hand-made mutants) against the suite, with confirm on, and compares each outcome with `ledger/<id>.golden.json`. A bug that was caught and is not caught now is a regression: `ok` is false and `next` says to find the test that stopped guarding it. Any other change (a survivor now caught, a patch that no longer applies) also fails until it is re-recorded with `--update`, and a changed row needs `Golden-Change: <id>: <why>` in `--message`. A bug with no golden yet is recorded by `--update`. A hand-made mutant whose header says `source=hand fix=<commit>` replaces that fix's history revert, which is how a revert that does not build still guards its bug. Run it where the toolchain is complete: a test that skips for a missing tool can turn a kill into a survivor. This repository's goldens are the outcomes on the CI toolchain job's tools. This repository runs it on every push to `main` and nightly (`.github/workflows/self-score.yml`).
 
 ## matrix
 
@@ -78,6 +148,17 @@ npx probatio golden check --recorded table.json --actual now.json --update wordi
 
 `next` and `nextLead` are wording. `ok`, `reason`, `status`, `hostChanged`, and `nextCall` are the contract. `--update wording` re-records a changed `next` or `nextLead` and leaves the contract fields alone. A file whose case names are the top-level keys is written back in that shape. A changed `ok` or `reason` also needs `Golden-Change: <row>: <why>` in `--message`. A home path, or `ok` without a reason, fails and nothing is written.
 
+### golden record and golden compare
+
+```bash
+npx probatio golden record --package . --module src/text.ts --tests tests/text.test.ts
+npx probatio golden compare --package . --module src/text.ts --tests tests/text.test.ts --golden tests/golden/text.golden.test.ts --out .probatio/golden-compare --operators wide
+```
+
+`golden record` runs those unit tests once, in a throwaway worktree, with every exported function of the module wrapped. Each call whose arguments and result are plain data becomes a row in `tests/golden/<module>.golden.json`: the function, the arguments, and what it returned, resolved, or threw. A module that reads the clock gets the recorded instant on each row, and the replay pins it. A call with a callback, a class instance, or another hidden input is counted and left out: the tests built on it stay as code. A call that answered two ways for the same arguments is left out as unstable. Recording from a red run is refused. It also writes `tests/golden/<module>.golden.test.ts`, a node:test file that replays every row and does not import Probatio. A changed row fails. That is a behaviour change: fix the code, or re-record and review the JSON diff.
+
+`golden compare` mutates the module and scores the same mutants twice, once with only the unit tests and once with only the replay, with confirm on. It reports how many of the unit tests' kills the table also makes, and lists the mutants only the unit tests kill. When that list is empty, the table catches what those tests catch on these mutants. Replacing them is still a decision: keep any test with hidden inputs, run a sealed or ledger check, and give the reason in the commit. Nothing is deleted. Node and TypeScript ESM modules only for now.
+
 ## status
 
 ```bash
@@ -100,7 +181,7 @@ An item is `.probatio/queue/<id>.json`. `queue claim` renames it to `claimed/<ag
 
 ## MCP
 
-`probatio mcp` and the `probatio-mcp` bin speak stdio JSON-RPC, one JSON object per line. The tool name is `probatio`. `argv` is the CLI words. `ping` returns `{}`. An unknown method returns JSON-RPC `-32601` with the same id.
+`probatio mcp` and the `probatio-mcp` bin speak stdio JSON-RPC, one JSON object per line. The tool name is `probatio`. `argv` is the CLI words. `ping` returns `{}`. An unknown method returns JSON-RPC `-32601` with the same id. A tool call runs in the background, so `ping` and other calls are answered while a long `mutate run` works. `notifications/cancelled` with that call's `requestId` stops the command and its suite, removes its worktrees, and sends no reply. The server answers with the client's `protocolVersion` when it is `2024-11-05`, `2025-03-26`, or `2025-06-18`.
 
 ```json
 {
@@ -118,3 +199,7 @@ That block is the Claude, Cursor, and Grok shape. The tool runs the CLI and retu
 `mutate generate` reads the commit (`HEAD` unless you pass `--commit`). `--working-tree` reads the checkout on disk and says so. `mutate run` scores the commit either way.
 
 `verify-change` does not score uncommitted edits when `--base` and `--commit` are the same. A clean empty diff says `No diff-scoped mutant.`
+
+## Releases
+
+[docs/releasing.md](docs/releasing.md): green `test` and `self-score` on the version commit, a pushed `v<version>` tag, then `npm publish`. `prepublishOnly` refuses anything else.

package/dist/cli.js

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 import path from "node:path";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { SCHEMA_VERSION, render } from "./contract.js";
 import { bool, int, parseArgs, requireText, text, texts } from "./flags.js";
 import { asTable, checkGolden, goldenShape, readGolden, writeGolden } from "./golden/check.js";
+import { compareGoldens, recordGoldens } from "./golden/record.js";
 import { buildLedger } from "./ledger/build.js";
+import { checkLedger } from "./ledger/check.js";
 import { readKills, reportMatrix } from "./matrix/report.js";
 import { appendFinding, chooseSealed, fixGap, guardAllows, lineHash, loadState, parseGuard, readSourceLine, revertGap, saveState, sealIds, statusEnvelope, } from "./memory/state.js";
 import { git } from "./mutate/patch.js";
 import { generateMutants } from "./mutate/generate.js";
 import { runMutants } from "./mutate/run.js";
-import { LABEL_LEAK_SUMMARY, labelLeaked, readSealedLabel, sealedTreeLeaked } from "./mutate/sealed.js";
+import { fixEditedKillers, LABEL_LEAK_SUMMARY, labelLeaked, readSealedLabel, sealedTreeLeaked } from "./mutate/sealed.js";
 import { generateNext } from "./mutate/suite-decision.js";
 import { discoverSuite } from "./mutate/suites.js";
 import { tallyRun } from "./mutate/tally.js";
@@ -47,10 +50,16 @@ else
             finish(tallyCommand(parsed.flags), parsed.human);
         if (group === "ledger" && action === "build")
             finish(await ledgerCommand(parsed.flags), parsed.human);
+        if (group === "ledger" && action === "check")
+            finish(await ledgerCheckCommand(parsed.flags), parsed.human);
         if (group === "matrix" && action === "report")
             finish(matrixCommand(parsed.flags), parsed.human);
         if (group === "golden" && action === "check")
             finish(goldenCommand(parsed.flags), parsed.human);
+        if (group === "golden" && action === "record")
+            finish(await goldenRecordCommand(parsed.flags), parsed.human);
+        if (group === "golden" && action === "compare")
+            finish(await goldenCompareCommand(parsed.flags), parsed.human);
         if (group === "gap" && action === "fix")
             finish(gapFixCommand(parsed.flags), parsed.human);
         if (group === "gap" && action === "revert")
@@ -73,7 +82,9 @@ else
             finish(await checkKillCommand(parsed.flags, action), parsed.human);
         if (group === "verify-change")
             finish(await verifyCommand(parsed.flags), parsed.human);
-        finish(usage(false, "Use mutate, ledger, matrix, golden, gap, guard, findings, status, queue, check-kill, or verify-change."), parsed.human);
+        if (group === "schema")
+            finish(schemaCommand(action), parsed.human);
+        finish(usage(false, "Use mutate, ledger, matrix, golden, gap, guard, findings, status, queue, check-kill, verify-change, or schema."), parsed.human);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -112,6 +123,7 @@ async function generateCommand(flags) {
         skipFiles: texts(flags, "skip-file"),
         commit: text(flags, "commit") ?? "HEAD",
         workingTree: bool(flags, "working-tree", false),
+        operators: operatorSet(flags),
     });
     if (result.error) {
         return {
@@ -158,6 +170,7 @@ async function generateCommand(flags) {
             ? null
             : { argv: ["mutate", "run", "--package", packageDir, "--patches", patches, "--out", path.join(outDir, "runs")] },
         mutantCount: result.mutants.length,
+        operators: operatorSet(flags),
         stringLiteralMutants: 0,
         filesVisited: result.filesVisited,
         budgetHit: result.budgetHit,
@@ -256,6 +269,8 @@ async function runCommand(flags, hide = null) {
         next: report.next,
         nextCall: report.ok ? resume : null,
         killed: report.killed,
+        unviable: report.unviable,
+        unviableIds: report.unviableIds,
         survived: report.survived,
         flaky: report.flaky,
         timeouts: report.timeouts,
@@ -283,9 +298,32 @@ async function sealedCommand(flags) {
     const hide = texts(flags, "hide");
     const outDir = path.resolve(requireText(flags, "out"));
     const report = await runCommand(flags, hide);
-    const body = JSON.stringify(report);
+    const packageDir = path.resolve(requireText(flags, "package"));
+    const repoDir = path.resolve(text(flags, "repo") ?? gitRoot(packageDir));
+    const kills = Array.isArray(report.kills) ? report.kills : [];
+    // The fix commit is the scored commit unless --fix names an earlier one (new tests landed on top of it).
+    const scored = typeof report.commit === "string" ? report.commit : "";
+    const fixRef = text(flags, "fix");
+    const fixSha = fixRef ? git(repoDir, ["rev-parse", "--verify", `${fixRef}^{commit}`]) : null;
+    if (fixSha && fixSha.status !== 0)
+        throw new Error(`--fix ${fixRef} does not resolve`);
+    const commit = fixSha ? fixSha.stdout.trim() : scored;
+    const edited = report.ok && commit ? fixEditedKillers(repoDir, packageDir, commit, hide, kills) : { files: [], olderTestCatch: false };
+    const fromFix = kills.length > 0 && !edited.olderTestCatch;
+    const judged = {
+        ...report,
+        ...(fromFix
+            ? {
+                summary: `${report.summary} Every kill came from a test edited by the fix commit (${edited.files.join(", ")}). That is the fix's own test, so no older test caught the bug.`,
+                next: "Record this as a miss. Do not restore the hidden test.",
+            }
+            : {}),
+        fixEdited: edited.files,
+        olderTestCatch: edited.olderTestCatch,
+    };
+    const body = JSON.stringify(judged);
     if (!labelLeaked(body, label) && !sealedTreeLeaked(outDir, label))
-        return report;
+        return judged;
     return {
         schemaVersion: SCHEMA_VERSION,
         ok: false,
@@ -554,9 +592,53 @@ async function checkKillCommand(flags, id) {
         onProgress: (line) => process.stderr.write(`${line}\n`),
     });
 }
+async function ledgerCheckCommand(flags) {
+    const packageDir = path.resolve(requireText(flags, "package"));
+    return checkLedger({
+        packageDir,
+        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
+        commit: text(flags, "commit") ?? "HEAD",
+        ledgerDir: path.resolve(packageDir, text(flags, "ledger") ?? "ledger"),
+        outDir: path.resolve(requireText(flags, "out")),
+        update: bool(flags, "update", false),
+        message: text(flags, "message") ?? "",
+        concurrency: int(flags, "concurrency") ?? 3,
+        suiteTimeoutMs: int(flags, "suite-timeout-ms") ?? 600_000,
+        testTimeoutMs: int(flags, "test-timeout-ms") ?? 60_000,
+        onProgress: (line) => process.stderr.write(`${line}\n`),
+    });
+}
+async function goldenRecordCommand(flags) {
+    const packageDir = path.resolve(requireText(flags, "package"));
+    return recordGoldens({
+        packageDir,
+        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
+        commit: text(flags, "commit") ?? "HEAD",
+        modules: texts(flags, "module"),
+        tests: texts(flags, "tests"),
+        outDir: text(flags, "dir") ?? "tests/golden",
+        timeoutMs: int(flags, "suite-timeout-ms") ?? 600_000,
+    });
+}
+async function goldenCompareCommand(flags) {
+    const packageDir = path.resolve(requireText(flags, "package"));
+    return compareGoldens({
+        packageDir,
+        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
+        commit: text(flags, "commit") ?? "HEAD",
+        modules: texts(flags, "module"),
+        tests: texts(flags, "tests"),
+        golden: texts(flags, "golden"),
+        outDir: path.resolve(requireText(flags, "out")),
+        operators: operatorSet(flags),
+        timeoutMs: int(flags, "suite-timeout-ms") ?? 600_000,
+        onProgress: (line) => process.stderr.write(`${line}\n`),
+    });
+}
 async function verifyCommand(flags) {
     const packageDir = path.resolve(requireText(flags, "package"));
-    return verifyChange({
+    const operators = operatorSet(flags);
+    const envelope = await verifyChange({
         packageDir,
         repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
         outDir: path.resolve(requireText(flags, "out")),
@@ -565,8 +647,56 @@ async function verifyCommand(flags) {
         maxMutants: int(flags, "max-mutants") ?? 4,
         maxMinutes: int(flags, "max-minutes") ?? 3,
         maxTests: int(flags, "max-tests") ?? null,
+        operators,
         onProgress: (line) => process.stderr.write(`${line}\n`),
     });
+    return { ...envelope, operators };
+}
+/** `--operators core` (default) or `--operators wide`. Anything else is a usage error, not a silent default. */
+function operatorSet(flags) {
+    const value = text(flags, "operators") ?? "core";
+    if (value !== "core" && value !== "wide")
+        throw new Error("--operators must be core or wide");
+    return value;
+}
+/** The published JSON Schema of one command's output. MCP-only agents read the contract this way. */
+function schemaCommand(name) {
+    const dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "schemas");
+    const commands = existsSync(dir)
+        ? readdirSync(dir).filter((file) => file.endsWith(".schema.json")).map((file) => file.slice(0, -".schema.json".length)).sort()
+        : [];
+    if (!name) {
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            ok: commands.length > 0,
+            command: "schema",
+            summary: `${commands.length} commands have a published schema.`,
+            next: "Pass one name, for example: probatio schema mutate.run",
+            nextCall: null,
+            commands,
+        };
+    }
+    if (!commands.includes(name)) {
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            ok: false,
+            command: "schema",
+            summary: `No schema named ${name}.`,
+            next: `Use one of: ${commands.join(", ")}.`,
+            nextCall: null,
+            commands,
+        };
+    }
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        command: "schema",
+        summary: `JSON Schema for ${name}, schemaVersion ${SCHEMA_VERSION}.`,
+        next: "Validate a command's stdout against it. A new field does not change schemaVersion. A renamed or removed one does.",
+        nextCall: null,
+        commands,
+        schema: JSON.parse(readFileSync(path.join(dir, `${name}.schema.json`), "utf8")),
+    };
 }
 function gitRoot(cwd) {
     const result = git(cwd, ["rev-parse", "--show-toplevel"]);

package/dist/contract.js

@@ -1,5 +1,6 @@
 import { homedir } from "node:os";
-export const SCHEMA_VERSION = 1;
+/** Bumped when a field is renamed, removed, or changes meaning. 2: `drop` became `noKillsYet`, and a compile or link failure became `unviable`, not `killed`. */
+export const SCHEMA_VERSION = 2;
 /** Replace the home directory so a result never carries a user's name or home path. */
 export function scrub(value, home = homedir(), keepPaths = false) {
     if (typeof value === "string") {