# For agents

> What a coding agent reads from oxmutate: one survivor record per mutant with a fix line, the --json envelope, an MCP server with run and survivors as tools, the schema, and exit codes that say whether to rewrite the command.

Source: https://oxmutate.interlace.tools/docs/agents

A coding agent asked to strengthen a test suite needs three things from a mutation tester: the
lines no test checks, what to assert about each, and a signal it can act on without parsing
prose. oxmutate's CLI is declared once on [burgee](https://burgee.interlace.tools), and every
surface below is projected from that declaration.

## The survivor list

`oxmutate survivors --json` reads the last report and prints one record per survivor. Here it
reads the report from [Getting started](/docs/getting-started):

```text title="npx oxmutate survivors --report mutation.json --json"
{"ok":true,"data":{"survivors":[{"id":"1","file":"src/age.ts","line":1,"column":50,"mutator":"EqualityOperator","replacement":"age > 18","status":"Survived","coveredBy":1,"flaky":false,"fix":"1 test(s) run this code, and all still pass when it becomes `age > 18` (EqualityOperator). fix: assert the behaviour this line decides."}]},"meta":{"provenance":{"report":{"source":"flag","location":"--report"}}}}
```

`coveredBy` is how many tests run the line. A survivor with `coveredBy: 0` is `NoCoverage`: no
test reaches it, and the fix is a test, not an assertion. `flaky: true` marks a verdict whose
covering tests behaved differently across two dry runs.

On paratext, an agent read 326 bytes per survivor from this list, and 4,094 from Stryker's report
for the same survivor (`A5` in
[`m1-results.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/oxmutate/m1-results.md)).

## The MCP server

```bash
npx oxmutate --mcp
```

serves `run` and `survivors` as MCP tools over stdio, each with an input schema built from the
same options the CLI takes. An MCP client config:

```json
{
  "mcpServers": {
    "oxmutate": { "command": "npx", "args": ["oxmutate", "--mcp"] }
  }
}
```

## The rest of the contract

- **`--json`** on any command prints one envelope on stdout: `{ "ok": true, "data": … }`, or
  `{ "error": { "kind", "code", "message" } }`.
- **`--schema`** prints every command, option, default and exit code as one JSON document.
- **`--explain <option>`** says where an option's value came from: a flag, an environment
  variable, a config file or the default.
- **Exit codes:** `0` ok; `1` it ran and a gate failed (a score under `--break`, or a change that
  weakened its tests); `2` a usage error, so rewrite the command; `3` the config or the suite did
  not load, so fix the project, not the command.
- **Every error carries a `fix:`** line the agent can act on as written.

## Machine-readable docs

This site serves [`/llms.txt`](/llms.txt), a map of every page, and
[`/llms-full.txt`](/llms-full.txt), the whole corpus in one file. Every page has a Markdown twin
at its URL plus `.md`.

---

# CI lanes

> Run oxmutate in CI the way the work is shaped: only the lines a pull request touched, a run split across a matrix, verdicts reused between runs, and a gate that fails a change which weakened its own tests.

Source: https://oxmutate.interlace.tools/docs/ci-lanes

A whole-project run is the slowest way to use a mutation tester and rarely the one CI needs.
Each lane below is a flag on `oxmutate run`, and they compose.

## The pull-request lane: `--since`

```bash
npx oxmutate run --since origin/main --reporter clear-text,json,sarif
```

Only mutants on lines changed since the ref are scored; the rest of the project is not mutated.
`--reporter sarif` writes `reports/mutation/mutation.sarif`, which GitHub's code scanning shows
as an annotation on each surviving line of the diff:

```yaml
- run: npx oxmutate run --since origin/${{ github.base_ref }} --reporter clear-text,json,sarif
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: reports/mutation/mutation.sarif
```

Check out with enough history for the ref to exist (`fetch-depth: 0`, or a fetch of the base
branch).

## A gate on weaker tests: `--frozen-oracle`

```bash
npx oxmutate run --since origin/main --frozen-oracle origin/main
```

The mutants are scored twice: against the change's tests, and against the base ref's versions of
the test files the change edited. A mutant the base's tests killed that the change's tests let
survive means the change removed or loosened an assertion. The run then exits 1 and names those
mutants, whatever the score.

## A matrix: `--shard i/n`

```yaml
strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: npx oxmutate run --shard ${{ matrix.shard }}/4 --report-dir reports/shard-${{ matrix.shard }}
```

Shards partition the mutants exactly: every mutant is in one shard and no mutant is in two, and
the split is deterministic, so a re-run of shard 2 scores the same mutants.

## Reuse between runs: `--incremental`

```bash
npx oxmutate run --incremental
```

A verdict is reused when neither its source file nor any of its covering tests changed since the
run that recorded it (`reports/oxmutate-incremental.json`, or `incrementalFile`). Cache that file
between CI runs to make a nightly full run pay only for what moved.

## Fail on a score: `--break`

```bash
npx oxmutate run --break 80
```

Exit 1 below a mutation score of 80, the same as `thresholds.break` in the config. The flag wins.

## Exit codes

| Code | Meaning |
| :-- | :-- |
| 0 | The run completed, and passed its gates |
| 1 | It ran, and a gate failed: the score is under `--break`, or the change weakened its tests |
| 2 | A usage error: an unknown flag or a malformed value; rewrite the command |
| 3 | The config or the suite did not load: the dry run failed, or an instrumented file did not parse |

## Where the published numbers will come from

`oxmutate-bench.yml` runs oxmutate and Stryker against the same burgee packages on a runner
nothing else shares, and its numbers are the ones to quote. It is added in M1 and has not run
yet; the figures measured so far are from a shared laptop, and
[`m1-results.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/oxmutate/m1-results.md)
says how far they can be trusted.

---

# Coming from Stryker

> Move a Stryker project to oxmutate by changing one command: it reads stryker.config.* unchanged, writes Stryker's JSON report, and runs Stryker's 17 mutator families. What differs on purpose, which keys it does not use, and how closely its verdicts agree with Stryker's.

Source: https://oxmutate.interlace.tools/docs/coming-from/stryker

oxmutate is built to replace `stryker run` in a project that tests with Vitest, without touching
the project. The config stays, the report format stays, the disable comments stay. The command
changes.

## The switch

```diff
- npx stryker run
+ npx oxmutate run
```

```diff
  "scripts": {
-   "test:mutation": "stryker run"
+   "test:mutation": "oxmutate run"
  },
  "devDependencies": {
-   "@stryker-mutator/core": "^10.0.0",
-   "@stryker-mutator/vitest-runner": "^10.0.0",
+   "oxmutate": "^0.1.0",
    "vitest": "^4.1.0"
  }
```

Both write `reports/mutation/mutation.json` by default. To run them side by side and compare,
give oxmutate a directory of its own: `npx oxmutate run --report-dir reports/oxmutate`.

## What carries over unchanged

- **`stryker.config.{mjs,js,cjs,json}`**, read as it stands. Every key oxmutate uses is on
  [Configuration](/docs/configuration), and every key it does not use is listed in the run's
  output with the reason.
- **The JSON report** (schema 2), so `mutation-testing-elements`, the HTML report and any tool
  that reads Stryker's report read oxmutate's.
- **The mutant set**: Stryker 10.0.0's 17 mutator families. The Regex family gives the same
  mutants as weapon-regex on 928 of 932 real patterns.
- **`// Stryker disable next-line <Mutator>: <reason>`** comments, honoured as written.
- **`thresholds`**, including `break`, and `mutator.excludedMutations`.

## What differs, on purpose

- **Code inside TypeScript `as` casts and enums is mutated.** Stryker 10.0.0 skips it.
  `--stryker-compat` (or `strykerCompat: true`) gives Stryker's mutant set exactly.
- **The default per-mutant slack is 500 ms, not 5,000 ms.** A warm in-process run has no process
  start-up to absorb. Set `timeoutMS` to keep Stryker's.
- **Static mutants are scored, not skipped.** Each is re-run with the mutant armed from process
  start, in its own Vitest start, scoped to the test files that load it. `ignoreStatic: true`
  skips them, as Stryker does.
- **Plugins are data.** There are no runtime plugins: an ignorer plugin becomes an `ignore` rule,
  `{ call: 'console.*', reason: '…' }`.
- **The checker reads the original sources.** `checkers: ['typescript']` compiles each survivor
  with the project's own compiler; instrumented files carry `// @ts-nocheck` and are never
  type-checked.

## What is not there yet

The Stryker Dashboard reporter, `eventReporter`, `logLevel` and `fileLogLevel`. A config that
sets them runs, and lists each as unused.

## How closely the verdicts agree

No Stryker suite is graded through compat-oracle, so in this family's sense the switch is not
graded: compat-oracle grades an import by the incumbent's own test suite, and a mutation tester
produces a verdict per mutant rather than a passing test. What is measured instead is verdict
agreement: the same project scored by Stryker 10.0.0 and by oxmutate, each mutant's verdict
compared against Stryker's own JSON report. Measured on 2026-10-27:

| Subject | Mutants | Same verdict as Stryker |
| :-- | --: | --: |
| es-toolkit `src/array` | 720 | 99.58–100% (an earlier build; re-measured on CI before it is quoted as a result) |
| burgee/paratext | 1,332 | 99.92% |
| burgee/controlroom | 997 | 99.90% |

On paratext one mutant disagreed: Stryker called it a timeout, and its covering tests pass with
it, because Stryker's hit limit stopped a loop that ends. On controlroom Stryker's worker errored
on one mutant, so there is no Stryker verdict to compare it with; it has not been checked by hand
yet. The method, the subjects and the speed measured on the same runs are in
[`m1-results.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/oxmutate/m1-results.md).

---

# Configuration

> Every key oxmutate reads: Stryker's keys, read from stryker.config.* as they stand, the keys only oxmutate reads, and the Stryker keys it does not use, each with the reason.

Source: https://oxmutate.interlace.tools/docs/configuration

oxmutate reads two files from the project root, and a command-line flag beats both:

1. `stryker.config.{mjs,js,cjs,json,mts,ts}`, as it stands. A JS config may export an object or a
   function that returns one.
2. `oxmutate.config.*` (the same extensions), which wins where both set a key. `--config <file>`
   names a different file.

The keys only oxmutate reads belong in `oxmutate.config.*`. Stryker never opens that file, so a
project can run both tools while it compares them.

## Stryker's keys oxmutate uses

| Key | Default | What it does |
| :-- | :-- | :-- |
| `mutate` | `src/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}`, minus `*.test.*`, `*.spec.*` and `*.d.ts` | The files to mutate, as globs; a `!` glob excludes |
| `testRunner` | Vitest | `'command'` runs `commandRunner.command` once per mutant instead of the warm Vitest runner |
| `commandRunner` | `{ command: 'npm test' }` | The command for `testRunner: 'command'`; any non-zero exit kills the mutant |
| `vitest` | — | `{ configFile }`: the Vitest config to run, when it is not the default one |
| `concurrency` | cores − 1, at most 8 | Worker processes (`--concurrency`) |
| `timeoutMS` | 500 | Absolute slack per mutant, in ms; Stryker's default is 5000 (`--mutant-timeout`) |
| `timeoutFactor` | 1.5 | The multiple of a test's dry-run time a mutant may take before the slack |
| `thresholds` | `{ high: 80, low: 60, break: null }` | Score bands for the report; below `break` the run exits 1 (`--break`) |
| `mutator` | — | `{ excludedMutations }`: mutator names never generated |
| `ignoreStatic` | `false` | Skip static mutants (code that runs at import) instead of scoring them |
| `reporters` | `['clear-text', 'json']` | Any of `clear-text`, `json`, `html`, `sarif` (`--reporter`) |
| `jsonReporter` | `reports/mutation/mutation.json` | `{ fileName }` of the JSON report |
| `htmlReporter` | `reports/mutation/mutation.html` | `{ fileName }` of the HTML report |
| `incremental` | `false` | Reuse verdicts whose source and covering tests did not change (`--incremental`) |
| `incrementalFile` | `reports/oxmutate-incremental.json` | Where those verdicts are kept |
| `dryRunOnly` | `false` | Stop after the dry run: proves the suite runs under oxmutate |
| `dryRunTimeoutMinutes` | 5 | Budget for the dry run; over it the run stops with exit 3 |
| `buildCommand` | — | Run once before the dry run, split on spaces, with no shell |
| `testRunnerNodeArgs` | `[]` | Node flags for every Vitest worker |
| `allowEmpty` | `false` | A dry run that finds no tests scores nothing instead of failing |
| `warnings` | `true` | `false` (or `{ unknownOptions: false }`) hides the line that lists unused keys |
| `checkers` | `[]` | `['typescript']` type-checks each survivor; one that does not compile is not counted |
| `tsconfigFile` | `tsconfig.json` | The tsconfig that type check uses |

`// Stryker disable next-line <Mutator>[,<Mutator>]: <reason>` comments are honoured, and
`// oxmutate disable next-line …` is the same directive. A directive with no reason is an error,
because a mutant switched off without one cannot be reviewed.

## Keys only oxmutate reads

| Key | Default | What it does |
| :-- | :-- | :-- |
| `ignore` | `[]` | Calls whose subtrees are not mutated, as data: `{ call: 'console.*', reason: '…' }`. `*` stops at a dot, `**` does not |
| `specOracles` | `[]` | Formal models whose traces are replayed against each mutant ([Spec oracles](/docs/spec-oracles)) |
| `strykerCompat` | `false` | Reproduce Stryker 10.0.0's skips: no mutants inside `as` casts or enums (`--stryker-compat`) |
| `flakyReruns` | 2 | Re-runs for a verdict whose covering tests behaved differently across two dry runs; 0 disables |
| `sarifReport` | `reports/mutation/mutation.sarif` | Where the SARIF report goes |
| `typeChecker` | the project's `tsgo`, else `npx tsc` | The compiler command the type check runs |

`--report-dir <dir>` writes `mutation.json`, `mutation.sarif` and `mutation.html` into one
directory, whatever the config says.

## Stryker's keys oxmutate does not use

Each is listed in the run's output with its reason, so a config written for Stryker is never
misread in silence.

| Key | Why |
| :-- | :-- |
| `inPlace`, `tempDirName`, `cleanTempDir`, `symlinkNodeModules`, `ignorePatterns` | oxmutate never copies or rewrites the project; instrumented sources are served from memory |
| `plugins`, `appendPlugins`, `ignorers` | No runtime plugin loading: mutators and ignore rules are data (`ignore`) |
| `coverageAnalysis` | Always `perTest` |
| `disableBail` | oxmutate always stops a mutant at its first killing test |
| `maxTestRunnerReuse` | Workers are replaced on pollution and runaways, automatically |
| `testFiles` | Test files come from the Vitest config |
| `packageManager` | oxmutate never installs anything |
| `disableTypeChecks` | Always on: instrumented files carry `// @ts-nocheck`, and the checker reads the original sources |
| `allowConsoleColors` | Colour follows the terminal |
| `clearTextReporter` | The summary is always printed |
| `force` | Use a run without `--incremental` |
| `dashboard` | The Stryker Dashboard reporter is not built yet |
| `eventReporter`, `logLevel`, `fileLogLevel`, `checkerNodeArgs` | Not implemented |

---

# Getting started

> Install oxmutate, see the config it reads from your project, run it, and read the survivors back: the lines your tests run but do not check.

Source: https://oxmutate.interlace.tools/docs/getting-started

oxmutate is a mutation tester. It changes your code one small step at a time and runs the tests
that cover each change. A change that every covering test still passes is a **survivor**: the
tests run that line, and nothing they assert depends on it.

## Install

```bash
npm install --save-dev oxmutate
```

It needs Node 20.19 or later on the 20 line, or 22.13 or later, and Vitest 4.1 or later in the
project for its default runner. Vitest is an optional peer: oxmutate runs the project's own copy
and never installs a second. The prebuilt native core for your platform is an optional
dependency that npm picks by `os`, `cpu` and `libc`; nothing runs at install time.

## The config it reads

There is nothing to write if the project already has a Stryker config: oxmutate reads
`stryker.config.{mjs,js,cjs,json}` as it stands. `loadOptions` is the reader the CLI uses, so a
program can show what a run would use:

```js title="options.mjs"
import { writeFileSync } from 'node:fs';
import { loadOptions } from 'oxmutate';

// The Stryker config a project already has, written here so the program runs anywhere.
writeFileSync('stryker.config.json', JSON.stringify({
  mutate: ['src/**/*.ts', '!src/**/*.test.ts'],
  thresholds: { high: 90, low: 70, break: 80 },
  coverageAnalysis: 'perTest',
}));

const options = await loadOptions(process.cwd());
console.log(options.mutate);
console.log(options.thresholds);
for (const { key, why } of options.unused) console.log(`${key}: ${why}`);
```

```text title="node options.mjs"
[ 'src/**/*.ts', '!src/**/*.test.ts' ]
{ high: 90, low: 70, break: 80 }
coverageAnalysis: always perTest
```

A key oxmutate does not use is listed with the reason, never dropped in silence. Every key is on
[Configuration](/docs/configuration).

## Run it

```bash
npx oxmutate run
```

The run has three phases. A **dry run** executes the suite once, unmutated, and records which
tests reach which mutant; if it fails, nothing is scored and the run exits 3. Then every mutant
is scored by re-running only its covering tests inside warm Vitest workers. Last, each survivor
is confirmed in isolation, so a verdict that depended on another test's state is not reported.

It prints a summary and writes Stryker's JSON report to `reports/mutation/mutation.json`. Add
`--reporter clear-text,json,html,sarif` for the HTML report and a SARIF file as well.

## Read the survivors

`oxmutate survivors` reads the last report and prints one line per survivor, with what to
assert. Here it reads a two-mutant report: one killed, one that survived.

```json title="mutation.json"
{
  "schemaVersion": "2",
  "thresholds": { "high": 80, "low": 60 },
  "files": {
    "src/age.ts": {
      "language": "typescript",
      "source": "export const isAdult = (age: number): boolean => age >= 18;\n",
      "mutants": [
        { "id": "1", "mutatorName": "EqualityOperator", "replacement": "age > 18", "status": "Survived", "location": { "start": { "line": 1, "column": 50 }, "end": { "line": 1, "column": 59 } }, "coveredBy": ["0"] },
        { "id": "2", "mutatorName": "BooleanLiteral", "replacement": "false", "status": "Killed", "location": { "start": { "line": 1, "column": 50 }, "end": { "line": 1, "column": 59 } }, "coveredBy": ["0"] }
      ]
    }
  }
}
```

```text title="npx oxmutate survivors --report mutation.json"
src/age.ts:1  1 test(s) run this code, and all still pass when it becomes `age > 18` (EqualityOperator). fix: assert the behaviour this line decides.
```

`age >= 18` and `age > 18` differ only at 18, so the survivor says no test asks about an
18-year-old. `expect(isAdult(18)).toBe(true)` kills it.

## Next

- [Configuration](/docs/configuration): every key, Stryker's and oxmutate's own.
- [CI lanes](/docs/ci-lanes): a pull-request lane, a sharded nightly, and a gate on tests that
  got weaker.
- [For agents](/docs/agents): `survivors --json`, the MCP server and the exit codes.
- [Spec oracles](/docs/spec-oracles): a formal model's traces as a second verdict.
- [Coming from Stryker](/docs/coming-from/stryker): what changes, and the three things that differ.

---

# oxmutate

> Mutation testing for JavaScript and TypeScript on the oxc engine, run warm inside the project's own Vitest, with CI lanes, SARIF and an agent surface. No dependency outside the burgee family. A Stryker migration path.

Source: https://oxmutate.interlace.tools/docs

**oxmutate** changes your code one small step at a time (`a < b` becomes `a <= b`, a block
becomes empty, `true` becomes `false`) and runs the tests that cover each change. A change no
test notices is a **survivor**: a line your suite runs but does not check. Each one is reported
with its file, its line, the change and a `fix:` line that says what to assert, the same record
for a person, for `--json` and for a coding agent.

Coming from **Stryker**, nothing in the project changes but the command: oxmutate reads
`stryker.config.*` as it stands, writes Stryker's JSON report (schema 2, so
`mutation-testing-elements` renders it), and runs Stryker's 17 mutator families. Where you ran
`npx stryker run`, run `npx oxmutate run`.

**Built on oxc.** The instrumentation is Rust: [oxc](https://oxc.rs) parses every file in
parallel and each mutant is a span edit. A community project, not affiliated with the oxc project.

## Install

```bash
npm install oxmutate
pnpm add oxmutate
yarn add oxmutate
bun add oxmutate
```

Install it as a dev dependency (`-D`) of the project whose tests it grades. The prebuilt native
core for your platform arrives as an optional dependency; nothing runs at install time. Vitest
4.1 or later is an optional peer: oxmutate runs the project's own Vitest and never brings a second
one.

## Quick start

```bash
npm install oxmutate
```

```js
import { writeFileSync } from 'node:fs';
import { loadOptions } from 'oxmutate';

// The Stryker config a project already has, written here so the program runs anywhere.
writeFileSync('stryker.config.json', JSON.stringify({
  mutate: ['src/**/*.ts', '!src/**/*.test.ts'],
  thresholds: { high: 90, low: 70, break: 80 },
  coverageAnalysis: 'perTest',
}));

const options = await loadOptions(process.cwd());
console.log(options.mutate);
console.log(options.thresholds);
for (const { key, why } of options.unused) console.log(`${key}: ${why}`);
```

```text
[ 'src/**/*.ts', '!src/**/*.test.ts' ]
{ high: 90, low: 70, break: 80 }
coverageAnalysis: always perTest
```

That is the config `npx oxmutate run` reads in that directory: the same file Stryker reads, with
each key oxmutate does not use listed and the reason beside it, never dropped in silence. In a
project with Vitest installed, `npx oxmutate run` then scores every mutant and writes
`reports/mutation/mutation.json`.

## What it does

```bash
npx oxmutate run                                     # every mutant, with stryker.config.* if there is one
npx oxmutate run --since origin/main --reporter sarif  # PR lane: lines the change touched, in code scanning
npx oxmutate run --shard 2/8                         # one cell of a CI matrix; shards partition exactly
npx oxmutate run --incremental                       # reuse verdicts whose source and tests did not change
npx oxmutate run --frozen-oracle origin/main         # exit 1 when the change weakened its tests
npx oxmutate run --break 80                          # exit 1 below this mutation score
npx oxmutate survivors --json                        # the list a coding agent writes tests from
```

- **Warm runs inside your Vitest.** Each covering test is re-run per mutant inside a live Vitest
  worker, with its hooks, `vi.mock` and environment, instead of a Vitest start per mutant.
- **Stryker's mutant set.** All 17 of Stryker 10.0.0's mutator families. The Regex family
  produces the same mutants as weapon-regex on 928 of 932 real patterns.
- **Reports a CI already reads.** Stryker's JSON report (schema 2), its HTML report, and SARIF
  for GitHub code scanning (`--reporter sarif`).
- **CI lanes.** `--since <ref>` scores only the lines a change touched, `--shard i/n` splits a run
  across a matrix, `--incremental` reuses verdicts that cannot have changed, and
  `--frozen-oracle <ref>` also scores the change against the base's tests and fails when a
  mutant those tests killed now survives: a change that weakened its own tests.
- **Any test command.** `testRunner: 'command'` with `commandRunner: { command: 'npm test' }` runs a
  command per mutant, for a suite that is not Vitest.
- **Type-checked survivors.** `checkers: ['typescript']` compiles each survivor with the project's
  own compiler, and a mutant that does not type-check is not counted against the tests.
- **Ignore rules as data.** `ignore: [{ call: 'console.*', reason: 'log text is not behaviour' }]`
  leaves those call subtrees unmutated, Stryker's ignorer plugins as a list in the config.
- **Spec oracles.** `specOracles` replays a formal model's traces against each mutant, `quint run
  --mbt` traces or any directory of ITF files, through a test that imports `oxmutate/spec`. The
  report lists each test-spec gap: a mutant the model's traces kill and the tests let survive.

## How it stays correct

| Guard | What it catches |
| :-- | :-- |
| Dry run must pass | A suite that fails with no mutant active scores nothing (exit 3) |
| Canary after every mutant | The same test, unmutated, must still pass; if a mutant left a cache, registry or fixture behind, the context restarts fresh |
| Watchdog | A synchronous runaway is stopped and counted as a timeout |
| Flaky detector | Tests that behave differently across two dry runs have their mutants re-run, and a verdict that changes is reported `flaky` |
| Static mutants | Code that runs at import is re-run with the mutant armed from process start |
| Instrument re-parse | Emitted code that does not parse stops the run (exit 3) instead of scoring a broken file |

## Migrating

The config stays where it is, unchanged. The command changes:

```diff
- npx stryker run
+ npx oxmutate run
```

```diff
  "scripts": {
-   "test:mutation": "stryker run"
+   "test:mutation": "oxmutate run"
  }
```

`// Stryker disable next-line <Mutator>: <reason>` comments are honoured as written. Three
differences are on purpose:

- Code inside TypeScript `as` casts and enums **is** mutated; Stryker 10.0.0 skips it.
  `--stryker-compat` gives Stryker's mutant set.
- The default per-mutant slack is 500 ms, not 5,000 ms: a warm in-process run has no process
  start-up to absorb. `timeoutMS` in your config wins.
- Static mutants are scored, not skipped.

[Coming from Stryker](https://github.com/ofri-peretz/burgee/blob/main/apps/docs-oxmutate/content/docs/coming-from/stryker.mdx)
maps every config key.

## Compatibility

**Not graded.** No suite is graded through `compat-oracle` for oxmutate, so it has no
compatibility row. That oracle grades an import path by running the incumbent's own test suite
against it, and a mutation tester's output is not a passing test but a verdict per mutant. So the
comparison is verdict agreement: the same project, scored by Stryker 10.0.0 and by oxmutate, each
mutant's verdict compared against Stryker's own JSON report. Measured on 2026-10-27
([`m1-results.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/oxmutate/m1-results.md)):

| Subject | Mutants | Same verdict as Stryker |
| :-- | --: | --: |
| es-toolkit `src/array` | 720 | 99.58–100% ¹ |
| burgee/paratext | 1,332 | 99.92% |
| burgee/controlroom | 997 | 99.90% |

¹ From an earlier build of the same day, before that document's fixes; it is re-measured on the
CI lane before it is quoted as a result.

Of the two disagreements left, one is a Stryker timeout on a loop that ends (its hit limit
stops it; the covering tests pass). The other is a mutant Stryker scored as a runtime error, so it
has no Stryker verdict to compare; it has not been checked by hand yet.

**Speed is not yet a published number.** On a shared laptop, paratext took 180.0 s under oxmutate
and 427.4 s under Stryker, at 0.375 and 0.620 CPU-seconds a mutant; on controlroom oxmutate used
less CPU (0.092 against 0.171 CPU-seconds a mutant) and was slower by the wall clock (107.2 s
against 94.3 s). The laptop's load moved a run by more than the difference, so the wall-clock
figures to publish will come from the `oxmutate-bench.yml` lane on a runner nothing else shares.

## Benchmarks

Every number here is produced by `npm run bench` and published at [burgee.interlace.tools/docs/benchmarks](https://burgee.interlace.tools/docs/benchmarks).

No suite is graded against this package yet, so there is no compatibility number to quote.

## For agents

- **`oxmutate survivors --json`** prints one record per survivor: file, line, column, mutator,
  replacement, how many tests cover it, whether it is flaky, and a `fix:` line. On paratext an
  agent read 326 bytes per survivor from it, and 4,094 from Stryker's report for the same
  survivor (`A5` in
  [`m1-results.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/oxmutate/m1-results.md)).
- **`--json`, `--schema` and an MCP server** come from one declaration on burgee:
  `oxmutate --mcp` serves `run` and `survivors` as tools, and `oxmutate --schema` prints every
  option, default and exit code as data.
- **Exit codes are the contract.** `0` ok; `1` it ran and the result failed (below `--break`, or
  the change weakened its tests); `2` a usage error, so rewrite the command; `3` the config or
  the suite did not load (a dry run that fails, an instrumented file that does not parse).
- **The docs are machine-readable** at
  [oxmutate.interlace.tools/llms.txt](https://oxmutate.interlace.tools/llms.txt) and
  [llms-full.txt](https://oxmutate.interlace.tools/llms-full.txt).

## Configuration

oxmutate reads `stryker.config.{mjs,js,cjs,json}` and `oxmutate.config.*`, which wins where both
set a key. Keys Stryker documents and oxmutate does not use are listed in the report with the
reason. The keys only oxmutate reads (`ignore`, `specOracles`, `strykerCompat`, `flakyReruns`,
`sarifReport`, `typeChecker`) belong in `oxmutate.config.*`, where Stryker never sees them.

## API

| Import | What it gives you |
| :-- | :-- |
| `oxmutate` | `run()` and `loadOptions()`, the run's result types, `strykerReport()`, `sarifReport()` and `textSummary()`, and the CI-lane helpers `changedLines()`, `parseShard()` and `shardOf()` |
| `oxmutate/spec` | `loadTraces()`, `readTrace()` and `decode()`: what a spec-oracle replay test imports to drive the code through a model's ITF traces |
| `oxmutate/runner` | the Vitest runner oxmutate starts inside each Vitest worker; Vitest loads it, a program does not |

The `oxmutate` bin is that API, declared once on burgee.

## Requirements

Node 20.19 or later on the 20 line, or 22.13 or later. Vitest 4.1 or later in the project, for
the default runner. A prebuilt native core for darwin-arm64, darwin-x64, linux-arm64-gnu,
linux-x64-gnu, linux-x64-musl or win32-x64-msvc.

## Where it sits

It hosts no plugin key of its own.

Nothing in this family builds on it yet, and it builds on `bellpull` and `burgee`.

## The family

Eleven packages, one repository, one release pipeline. Each installs and works on its own, and each
owns one job. Six of them — `bellpull`, `closeout`, `linegauge`, `paratext`, `roundel`, `seniority`
— depend on nothing; the others depend only on packages in this table, and every dependency points
one way, down the [layers](https://burgee.interlace.tools/docs/concepts/family).

No package declares a dependency from outside the family; `react` and `react-reconciler` are
optional peers of `controlroom`, which npm does not install; `vitest` is an optional peer of
`oxmutate`, which npm does not install.
[`package-shape-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/package-shape-lock.test.ts)
holds that for every manifest, and
[`independence-install-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/independence-install-lock.test.ts)
installs each package alone and finds nothing but the family packages it declares.

Releases are published by one workflow through npm trusted publishing: no npm token is used, and
each release carries SLSA provenance, which `npm view <package> dist.attestations` shows.
[`trusted-publishing-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/trusted-publishing-lock.test.ts)
keeps both true.

| Package | What it is | Migrates from |
| :-- | :-- | :-- |
| [burgee](https://burgee.interlace.tools/docs/packages/burgee) | The CLI framework: one declaration, every surface | commander, yargs and meow |
| [roundel](https://roundel.interlace.tools/docs) | Colour: one output policy, semantic tokens, a theme | chalk, colorette, kleur, picocolors, supports-color and yoctocolors |
| [flagstaff](https://flagstaff.interlace.tools/docs) | The frame loop: spinners, progress, boxes and tables | ora, log-update, boxen and cli-table3 |
| [caique](https://caique.interlace.tools/docs) | Prompts that are flags first, and never hang | @inquirer/core |
| [linegauge](https://linegauge.interlace.tools/docs) | Measuring, wrapping, truncating and slicing styled text | string-width, wrap-ansi, strip-ansi, slice-ansi, cli-truncate and widest-line |
| [paratext](https://paratext.interlace.tools/docs) | Hyperlinks, images, title, clipboard and notifications | ansi-escapes, terminal-link and term-img |
| [seniority](https://seniority.interlace.tools/docs) | Configuration precedence and discovery, with provenance | cosmiconfig, lilconfig, dotenv and rc |
| [closeout](https://closeout.interlace.tools/docs) | Exit handlers, terminal restore and a bounded shutdown | signal-exit, exit-hook, restore-cursor, cli-cursor and onetime |
| [bellpull](https://bellpull.interlace.tools/docs) | Subprocesses, and which executable actually ran | cross-spawn and which |
| [controlroom](https://controlroom.interlace.tools/docs) | Keyboard-driven terminal screens, inline or full-screen | ink |
| **oxmutate** (this package) | Mutation testing on the oxc engine, inside your own Vitest | Stryker |

Every migration guide, and the family-wide [compatibility](https://burgee.interlace.tools/docs/compatibility)
and [benchmarks](https://burgee.interlace.tools/docs/benchmarks) pages, are on
[burgee.interlace.tools](https://burgee.interlace.tools/docs/packages).

## Contributing

Issues and pull requests are welcome at [ofri-peretz/burgee](https://github.com/ofri-peretz/burgee/issues); read
[CONTRIBUTING.md](https://github.com/ofri-peretz/burgee/blob/main/CONTRIBUTING.md) first. Report a vulnerability privately, as
[SECURITY.md](https://github.com/ofri-peretz/burgee/blob/main/SECURITY.md) describes — never in a public issue.

## Licence

MIT © Ofri Peretz — see [LICENSE](https://github.com/ofri-peretz/burgee/blob/main/packages/oxmutate/LICENSE).

---

# Spec oracles

> Replay a formal model's traces against every mutant, as a second verdict beside the tests: Quint's quint run --mbt traces or any directory of ITF files, and a report of each mutant the model catches and the tests miss.

Source: https://oxmutate.interlace.tools/docs/spec-oracles

The tests are one oracle: they say whether a mutant changed behaviour they check. A formal model
is another. A **spec oracle** takes a model's traces (sequences of actions and the states they
lead to) and replays each one against the code with a mutant armed. A mutant a replay catches is
killed by the spec, whatever the tests say about it.

The interesting result is the disagreement. A mutant the spec kills and the tests let survive is
a **test-spec gap**: behaviour the model pins down and the suite does not. Each one is reported
with the trace that caught it.

## The config

In `oxmutate.config.json` (Stryker never reads it):

```json
{
  "specOracles": [
    {
      "name": "save-restore",
      "backend": "quint",
      "model": "models/save-restore.qnt",
      "traces": 200,
      "maxSteps": 20,
      "seed": "7",
      "replay": ["test/cursor-replay.test.ts"],
      "files": ["src/cursor.ts"]
    }
  ]
}
```

| Key | What it is |
| :-- | :-- |
| `name` | The oracle's name: the key a replay test loads its traces by |
| `backend` | `quint`: oxmutate runs `quint run --mbt` on `model`. `itf`: a directory of `*.itf.json` files any tool wrote, at `dir` |
| `model` | `quint`: the model file, relative to the project root |
| `traces`, `maxSteps`, `seed` | `quint`: how many traces (default 100), steps per trace (default 20), and a seed for a run that repeats |
| `quint` | `quint`: how to run it (default `npx -y @informalsystems/quint@0.33.0`) |
| `dir` | `itf`: the directory of traces. Apalache writes ITF, and a test can pin its traces this way |
| `replay` | The replay test files (globs): their tests are this oracle's, scored on a verdict track of their own |
| `files` | The source files the model describes (globs): the denominator of the metrics below |

## The replay test

A replay test is written once per modelled component. It loads the traces, performs each step's
action on the real code, and asserts the model's state after it. Outside an oxmutate run there
are no traces, so it skips:

```ts
import { loadTraces } from 'oxmutate/spec';
import { expect, it } from 'vitest';

const traces = loadTraces('save-restore');

it.skipIf(traces.length === 0).each(traces)('replays $name', (trace) => {
  const terminal = fakeTerminal();
  for (const step of trace.steps) {
    if (step.action === 'enterRaw') rawMode(terminal);
    expect(terminal.isRaw).toBe(step.state.raw);
  }
});
```

Each step carries the action the model took (`mbt::actionTaken`), the nondeterministic choices
it made (`mbt::nondetPicks`, with `Some`/`None` unwrapped) and the model's variables after it,
with ITF's `#bigint`, `#set`, `#tup` and `#map` decoded to numbers, arrays and `Map`s:

```json title="t1.itf.json"
{"vars":["saved","raw"],"states":[{"#meta":{"index":0},"mbt::actionTaken":"init","mbt::nondetPicks":{},"saved":false,"raw":false},{"#meta":{"index":1},"mbt::actionTaken":"enterRaw","mbt::nondetPicks":{"depth":{"tag":"Some","value":{"#bigint":"1"}}},"saved":true,"raw":true}]}
```

```js title="replay.mjs"
import { readTrace } from 'oxmutate/spec';

const trace = readTrace('t1.itf.json');
for (const step of trace.steps) console.log(step.action, step.picks, step.state);
```

```text title="node replay.mjs"
init {} { saved: false, raw: false }
enterRaw { depth: 1 } { saved: true, raw: true }
```

## What the report says

Per oracle, over the mutants in its `files`:

| Metric | What it measures |
| :-- | :-- |
| Spec-kill share | The share of those mutants a replay kills |
| Test-spec gap | Mutants the spec kills and the tests miss, each with the trace that killed it |
| Spec escapes | Mutants neither the spec nor the tests kill |
| Cost per replay | Milliseconds per replay with a mutant armed |
| Mapping coverage | The share of those mutants a replay test reaches at all |

On closeout's `src/cursor.ts`, scored by its own tests and by a 200-trace model of `rawMode`, the
gap was 0: the tests, held to a full line floor, already catch everything the model does. The
mapping coverage was 45.5%, because the file also holds code the model says nothing about
([`m1-results.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/oxmutate/m1-results.md),
"The spec oracle on a real component").