oxmutate 0.0.0-stage → 1.0.0

package/dist/reports.js

@@ -0,0 +1,225 @@
+/**
+ * The three readers of a run: Stryker's JSON report (dashboards, the HTML elements, burgee's
+ * ratchet), SARIF 2.1.0 (code scanning annotates the pull request), and a terminal summary that
+ * ends with what to do next.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+/** The package's own version, read from its manifest so `--version` and the reports never drift from it. */
+// Stryker disable next-line StringLiteral: with no encoding readFileSync returns a Buffer, which JSON.parse reads as the same UTF-8 text
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+/** A replacement longer than this is cut, in the SARIF message and in the terminal list. */
+const REPLACEMENT_WIDTH = 60;
+const ELLIPSIS = '...';
+const MS_PER_S = 1000;
+/** Survivors the terminal summary lists before it says how many it left out. */
+const DEFAULT_SURVIVORS_SHOWN = 10;
+/** `mutation-testing-report-schema` 2, the format Stryker writes (`jsonReporter`). */
+export function strykerReport(r) {
+    const files = {};
+    for (const [file, source] of Object.entries(r.sources)) {
+        const mutants = r.mutants.filter((m) => m.file === file);
+        if (!mutants.length)
+            continue;
+        files[file] = {
+            language: /\.(ts|tsx|mts|cts)$/.test(file) ? 'typescript' : 'javascript',
+            source,
+            mutants: mutants.map((m) => ({
+                id: m.id,
+                mutatorName: m.mutatorName,
+                replacement: m.replacement,
+                location: { start: m.start, end: m.end },
+                status: m.status,
+                statusReason: m.statusReason,
+                coveredBy: m.coveredBy,
+                killedBy: m.killedBy,
+                testsCompleted: m.testsCompleted,
+                static: m.static ?? false,
+            })),
+        };
+    }
+    const testFiles = new Map();
+    for (const t of r.tests) {
+        // Forward slashes on every OS, as Stryker's report keys its files.
+        const file = path.relative(r.root, t.file).split(path.sep).join('/');
+        // Stryker disable next-line OptionalChaining: the get after a set always finds the entry; `?.` is only for the type
+        (testFiles.get(file) ?? testFiles.set(file, { tests: [] }).get(file))?.tests.push({ id: t.id, name: t.name });
+    }
+    return {
+        schemaVersion: '2',
+        thresholds: { high: r.options.thresholds.high, low: r.options.thresholds.low },
+        projectRoot: r.root,
+        files,
+        testFiles: Object.fromEntries(testFiles),
+        framework: { name: 'oxmutate', version: VERSION, branding: { homepageUrl: 'https://www.npmjs.com/package/oxmutate' } },
+        'x-oxmutate': { stats: r.stats, score: r.score, unusedConfig: r.options.unused, frozenOracle: r.frozen, specOracles: r.spec },
+    };
+}
+/** SARIF 2.1.0: one result per surviving or uncovered mutant, fingerprinted by stable id. */
+export function sarifReport(r) {
+    const reported = r.mutants.filter((m) => m.status === 'Survived' || m.status === 'NoCoverage');
+    const rules = [...new Set(reported.map((m) => m.mutatorName))].sort();
+    return {
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'oxmutate',
+                        version: VERSION,
+                        informationUri: 'https://www.npmjs.com/package/oxmutate',
+                        rules: rules.map((id) => ({
+                            id,
+                            name: id,
+                            shortDescription: { text: `${id} mutant no test detected` },
+                            helpUri: 'https://stryker-mutator.io/docs/mutation-testing-elements/supported-mutators/',
+                            defaultConfiguration: { level: 'warning' },
+                        })),
+                    },
+                },
+                results: reported.map((m) => ({
+                    ruleId: m.mutatorName,
+                    ruleIndex: rules.indexOf(m.mutatorName),
+                    level: m.status === 'Survived' ? 'warning' : 'note',
+                    message: { text: describe(m) },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: m.file },
+                                region: { startLine: m.start.line, startColumn: m.start.column, endLine: m.end.line, endColumn: m.end.column },
+                            },
+                        },
+                    ],
+                    partialFingerprints: { mutationId: m.id },
+                    properties: { status: m.status, replacement: m.replacement, coveredBy: m.coveredBy.length },
+                })),
+            },
+        ],
+    };
+}
+export function describe(m) {
+    const change = m.replacement.length > REPLACEMENT_WIDTH ? `${m.replacement.slice(0, REPLACEMENT_WIDTH - ELLIPSIS.length)}${ELLIPSIS}` : m.replacement;
+    if (m.status === 'NoCoverage')
+        return `No test reaches this code: changing it to \`${change}\` (${m.mutatorName}) would go unnoticed. fix: add a test that executes ${m.file}:${String(m.start.line)}.`;
+    return `${String(m.coveredBy.length)} test(s) run this code, and all still pass when it becomes \`${change}\` (${m.mutatorName}). fix: assert the behaviour this line decides.`;
+}
+/** What the run had to correct, one phrase per kind of correction that happened. */
+function corrections(s) {
+    return [
+        s.watchdogKills && `${String(s.watchdogKills)} runaway(s) stopped`,
+        s.pollutionRestarts && `${String(s.pollutionRestarts)} polluted context(s) restarted (in ${String(s.canaryFiles)} file(s))`,
+        s.flakyMutants && `${String(s.flakyMutants)} flaky verdict(s)`,
+        s.survivorsOverturned && `${String(s.survivorsOverturned)} survivor(s) killed by a whole-file re-run`,
+        s.timeoutsOverturned && `${String(s.timeoutsOverturned)} timeout(s) that finished given 3x the time`,
+        s.compileErrors && `${String(s.compileErrors)} survivor(s) that do not type-check, out of the score`,
+        s.reused && `${String(s.reused)} verdict(s) reused`,
+        s.crashes && `${String(s.crashes)} worker crash(es)`,
+    ].filter((c) => Boolean(c));
+}
+/** One line per spec oracle: its F metrics (metrics.md §6). */
+function specLines(r) {
+    return (r.spec ?? []).map((o) => `  spec ${o.name} (${o.backend}, ${String(o.traces)} traces): kills ${o.specKillShare.toFixed(1)}% of ${String(o.modelled)} modelled mutants, reaches ${o.mappingCoverage.toFixed(1)}%; ${String(o.testSpecGap.length)} test-spec gap(s), ${String(o.specEscapes.length)} escape(s)`);
+}
+/** The frozen oracle's line, when the change edited tests. */
+function frozenLine(r) {
+    const f = r.frozen;
+    if (!f?.changedTests.length)
+        return [];
+    const sign = f.delta >= 0 ? '+' : '';
+    return [`  frozen oracle vs ${f.base}: ${f.headScore.toFixed(2)}% with the change's tests, ${f.baseScore.toFixed(2)}% with the base's (${sign}${f.delta.toFixed(2)}), ${String(f.weakened.length)} mutant(s) the change stopped detecting`];
+}
+/** The terminal summary: the score, what to look at first, what the run corrected. */
+export function textSummary(r, opts = {}) {
+    const count = (s) => r.mutants.filter((m) => m.status === s).length;
+    const s = r.stats;
+    if (r.dryRunOnly) {
+        const covered = r.mutants.filter((m) => m.static || m.coveredBy.length > 0).length;
+        return `oxmutate ${VERSION}: dry run only, ${(s.wallMs / MS_PER_S).toFixed(1)} s\n  ${String(r.tests.length)} tests passed with every mutant compiled in and none active; ${String(covered)} of ${String(r.mutants.length)} mutants are reached by a test\n`;
+    }
+    const lines = [
+        `oxmutate ${VERSION}: ${String(r.mutants.length)} mutants in ${String(s.files)} files, ${(s.wallMs / MS_PER_S).toFixed(1)} s`,
+        `  mutation score ${r.score.mutationScore.toFixed(2)}% (covered ${r.score.covered.toFixed(2)}%)`,
+        `  killed ${String(count('Killed'))} · timeout ${String(count('Timeout'))} · survived ${String(count('Survived'))} · no coverage ${String(count('NoCoverage'))} · ignored ${String(count('Ignored'))} · errors ${String(count('RuntimeError') + count('CompileError'))}`,
+        `  instrument ${s.instrumentMs.toFixed(0)} ms · dry run ${(s.dryRunMs / MS_PER_S).toFixed(1)} s · mutants ${(s.mutationMs / MS_PER_S).toFixed(1)} s · isolated ${(s.isolatedMs / MS_PER_S).toFixed(1)} s`,
+    ];
+    const corrected = corrections(s);
+    if (corrected.length)
+        lines.push(`  corrected: ${corrected.join(' · ')}`);
+    lines.push(...frozenLine(r));
+    lines.push(...specLines(r));
+    const survivors = r.mutants.filter((m) => m.status === 'Survived' || m.status === 'NoCoverage');
+    const limit = opts.survivors ?? DEFAULT_SURVIVORS_SHOWN;
+    if (survivors.length) {
+        lines.push('', `Survivors (${String(survivors.length)}${survivors.length > limit ? `, first ${String(limit)}` : ''}):`);
+        for (const m of survivors.slice(0, limit))
+            lines.push(`  ${m.file}:${String(m.start.line)}:${String(m.start.column)}  ${m.mutatorName}  → ${m.replacement.replace(/\s+/g, ' ').slice(0, REPLACEMENT_WIDTH)}${m.flaky ? '  (flaky)' : ''}`);
+        lines.push('', 'fix: run `oxmutate survivors --json` to hand the list to an agent, or kill the first one above with a test.');
+    }
+    if (r.options.unused.length && r.options.warnUnused)
+        lines.push('', `Config keys not used: ${r.options.unused.map((u) => u.key).join(', ')} (see the JSON report for why)`);
+    return `${lines.join('\n')}\n`;
+}
+/** The web component Stryker's HTML report renders with, at the version Stryker 10.0.0 ships. */
+const ELEMENTS = 'mutation-testing-elements/dist/mutation-test-elements.js';
+const ELEMENTS_CDN = 'https://cdn.jsdelivr.net/npm/mutation-testing-elements@3.8.4/dist/mutation-test-elements.js';
+/** sha384 of that file, the same bytes as the npm tarball's (both measured 2026-10-27). */
+const ELEMENTS_SRI = 'sha384-xebNisAYQHHbrYIm991U9KOZ96oO+vRACR8kd+zHzWkU3pcRuigrsI7XS2tj3rqq';
+/**
+ * Stryker's HTML report: the JSON report rendered by `mutation-testing-elements`. The component is
+ * inlined from the project's own install when it has one (Stryker brings it), so the page works
+ * offline as Stryker's does; otherwise the page loads that exact version from a CDN. oxmutate does
+ * not depend on it.
+ */
+export function htmlReport(r) {
+    let script;
+    try {
+        const elements = createRequire(path.join(r.root, 'package.json')).resolve(ELEMENTS);
+        // Stryker disable next-line StringLiteral: without an encoding readFileSync returns a Buffer, which the template turns into the same UTF-8 text
+        const component = readFileSync(elements, 'utf8');
+        script = `<script>${component}</script>`;
+    }
+    catch {
+        script = `<script src="${ELEMENTS_CDN}" integrity="${ELEMENTS_SRI}" crossorigin="anonymous"></script>`;
+    }
+    // `<` as \u003c: still the same JSON, and no `</script>` inside a source file can end the tag.
+    const report = JSON.stringify(strykerReport(r)).replaceAll('<', '\\u003c');
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>oxmutate report</title>
+  ${script}
+</head>
+<body>
+  <mutation-test-report-app titlePostfix="oxmutate">Your browser does not support custom elements.</mutation-test-report-app>
+  <script>
+    const app = document.querySelector('mutation-test-report-app');
+    app.report = ${report};
+    const theme = () => { document.body.style.backgroundColor = app.themeBackgroundColor; };
+    app.addEventListener('theme-changed', theme);
+    theme();
+  </script>
+</body>
+</html>
+`;
+}
+export function writeReports(r) {
+    if (r.dryRunOnly)
+        return [];
+    const written = [];
+    const write = (file, body) => {
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, typeof body === 'string' ? body : JSON.stringify(body, null, 2));
+        written.push(file);
+    };
+    if (r.options.reporters.includes('json'))
+        write(r.options.jsonReport, strykerReport(r));
+    if (r.options.reporters.includes('sarif'))
+        write(r.options.sarifReport, sarifReport(r));
+    if (r.options.reporters.includes('html'))
+        write(r.options.htmlReport, htmlReport(r));
+    return written;
+}
+//# sourceMappingURL=reports.js.map

package/dist/resolve.js

@@ -0,0 +1,43 @@
+/**
+ * Resolve a bare specifier the way `import` would, from the project under test (not from this
+ * package). `createRequire().resolve` follows the `require` condition and lands on Vitest's
+ * CommonJS entry, which Vitest refuses to load; this follows `import`, then `default`.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+function pick(entry) {
+    if (typeof entry === 'string')
+        return entry;
+    // Stryker disable next-line ConditionalExpression: a number or boolean entry has no condition properties, so the loop below returns undefined too
+    if (!entry || typeof entry !== 'object')
+        return undefined;
+    for (const condition of ['import', 'node', 'default']) {
+        const found = pick(entry[condition]);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+export function resolveEsm(specifier, fromDir) {
+    const parts = specifier.split('/');
+    const name = specifier.startsWith('@') ? parts.slice(0, 2).join('/') : (parts[0] ?? specifier);
+    const subpath = `.${specifier.slice(name.length)}`;
+    const req = createRequire(path.join(fromDir, 'package.json'));
+    const pkgJson = req.resolve(`${name}/package.json`);
+    // A string `exports` exports no `./package.json`, so the resolve above has already thrown: here
+    // `exports` is a map or absent.
+    // Stryker disable next-line StringLiteral: without an encoding readFileSync returns a Buffer, which JSON.parse reads as UTF-8 text all the same
+    const pkg = JSON.parse(readFileSync(pkgJson, 'utf8'));
+    const exportsMap = pkg.exports;
+    let target;
+    if (exportsMap)
+        target = pick(exportsMap[subpath]);
+    else
+        target = subpath === '.' ? (pkg.module ?? pkg.main) : subpath;
+    if (!target)
+        throw new Error(`oxmutate: cannot resolve ${specifier} from ${fromDir}`);
+    return pathToFileURL(path.join(path.dirname(pkgJson), target)).href;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/runner.d.ts

@@ -0,0 +1,49 @@
+type AnyTask = {
+    id: string;
+    name: string;
+    type: string;
+    file?: {
+        filepath: string;
+    };
+    /** A file task's own path. */
+    filepath?: string;
+    suite?: AnyTask | undefined;
+    result?: {
+        state?: string;
+        duration?: number;
+    };
+    tasks?: AnyTask[] | undefined;
+};
+/** The family's refusal shape for a missing optional peer (as `controlroom/ink`'s): a code and a fix. */
+export declare class PeerMissingError extends Error {
+    readonly code = "E_PEER_MISSING";
+    readonly fix = "npm install vitest \u2014 oxmutate runs the project's own Vitest, so the project brings it";
+    constructor(cause: unknown);
+}
+declare const OxmutateRunner_base: new (config: unknown) => {
+    onCollectStart?(file: unknown): unknown;
+    onBeforeTryTask?(test: AnyTask, options: {
+        retry: number;
+        repeats: number;
+    }): unknown;
+    onAfterRunFiles?(files: AnyTask[]): unknown;
+};
+export default class OxmutateRunner extends OxmutateRunner_base {
+    /**
+     * Import-time hits (static mutants) are attributed to the test file being collected, so a static
+     * mutant is later re-run against the files that load its module, not the whole suite (Stryker
+     * re-runs everything for each one).
+     */
+    onCollectStart(file: AnyTask): unknown;
+    onBeforeTryTask(test: AnyTask, options: {
+        retry: number;
+        repeats: number;
+    }): unknown;
+    runTask(test: AnyTask & {
+        context?: unknown;
+    }): Promise<void>;
+    /** Reset per-try state (snapshot counters, assertion counts) the way Vitest does for a retry. */
+    private retryReset;
+    onAfterRunFiles(files: AnyTask[]): unknown;
+}
+export {};

package/dist/runner.js

@@ -0,0 +1,270 @@
+/**
+ * oxmutate's Vitest runner: loaded by Vitest (`test.runner`) inside its own worker, so hooks,
+ * `expect`, `vi`, `vi.mock` and the environment stay Vitest's.
+ *
+ * Three modes, set by the coordinator through the environment (`OXMUTATE_MODE`):
+ *
+ * - `dry`: run the suite unmutated once, recording which tests reach which mutant (the
+ *   instrumented code counts hits into the namespace while `currentTestId` is set).
+ * - `mutant`: for each test, re-invoke the test's own function once per covering mutant with
+ *   the switch flipped, each invocation bracketed by the suite's `beforeEach`/`afterEach` and the
+ *   runner's own per-try reset (the mechanism Vitest uses for retries, so snapshot counters
+ *   start over). Then run the test once more, unmutated: that run is what Vitest reports, and a
+ *   failure there means an earlier mutant polluted shared state (the canary).
+ * - `isolated`: one mutant was armed before import (static mutants and canary re-runs). Run
+ *   normally; any failed test kills it.
+ *
+ * Before each mutant the runner writes a progress line synchronously, so the coordinator can
+ * attribute and kill a worker stuck in a synchronous loop that the hit counter cannot break.
+ */
+import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { resolveEsm } from './resolve.js';
+import { ACTIVE_MUTANT_ENV, FILE_KEY, NAMESPACE, cwd, env } from './runtime.js';
+/**
+ * The project's own Vitest, never the one beside this file: two Vitest instances in one worker
+ * disagree about the current test, the snapshot state and `expect`.
+ */
+const fromProject = async (specifier, dir = cwd()) => import(resolveEsm(specifier, dir));
+/** The family's refusal shape for a missing optional peer (as `controlroom/ink`'s): a code and a fix. */
+export class PeerMissingError extends Error {
+    code = 'E_PEER_MISSING';
+    fix = "npm install vitest — oxmutate runs the project's own Vitest, so the project brings it";
+    constructor(cause) {
+        super('oxmutate/runner needs `vitest`, an optional peer that is not installed', { cause });
+        this.name = 'PeerMissingError';
+    }
+}
+const missing = (cause) => {
+    const code = cause?.code;
+    return code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND';
+};
+/** Vitest 5 exports `TestRunner` from `vitest`; Vitest 4 from `vitest/runners` + `@vitest/runner`. */
+async function loadBase() {
+    const vitest = (await fromProject('vitest').catch((cause) => {
+        if (missing(cause))
+            throw new PeerMissingError(cause);
+        throw new Error('oxmutate/runner could not load the project\'s Vitest', { cause });
+    }));
+    const v5 = vitest['TestRunner'];
+    if (v5 && typeof v5.getTestFn === 'function' && typeof v5.getSuiteHooks === 'function') {
+        return { Base: v5, statics: { getTestFn: v5.getTestFn, getSuiteHooks: v5.getSuiteHooks } };
+    }
+    const runners = (await fromProject('vitest/runners'));
+    const vitestDir = path.dirname(createRequire(path.join(cwd(), 'package.json')).resolve('vitest/package.json'));
+    const core = (await fromProject('@vitest/runner', vitestDir));
+    return { Base: runners.VitestTestRunner, statics: { getTestFn: core.getFn, getSuiteHooks: core.getHooks } };
+}
+const { Base, statics } = await loadBase();
+const mode = env['OXMUTATE_MODE'] ?? 'dry';
+const resultsPath = env['OXMUTATE_RESULTS'];
+const progressPath = env['OXMUTATE_PROGRESS'];
+const ns = (globalThis[NAMESPACE] ??= {});
+ns.mutantCoverage ??= { static: {}, perTest: {} };
+const plan = mode === 'mutant' && env['OXMUTATE_PLAN'] ? JSON.parse(readFileSync(env['OXMUTATE_PLAN'], 'utf8')) : { tests: {}, hitLimits: {}, skip: [] };
+const decided = new Set(plan.skip);
+/** The replay tests' own bail: a mutant the tests killed is still replayed, and the reverse. */
+const specTests = new Set(plan.specTests ?? []);
+const decidedBySpec = new Set();
+/** `isolated`: when set, only these tests run (the mutant's covering tests); the rest pass untouched. */
+const only = mode === 'isolated' && env['OXMUTATE_ONLY_TESTS'] ? new Set(JSON.parse(env['OXMUTATE_ONLY_TESTS'])) : undefined;
+/** Set when a mutant left state behind; the rest of this context runs no mutants. */
+let polluted = false;
+/** Mutants between canaries; doubles while the canary stays clean, back to 1 when it fails. */
+let canaryEvery = 1;
+const MAX_CANARY_EVERY = 8;
+/** How much of a test's error a `polluted` record keeps, and of a file's collection error. */
+const POLLUTION_ERROR_CHARS = 300;
+const FILE_ERROR_CHARS = 500;
+function emit(record) {
+    if (resultsPath)
+        appendFileSync(resultsPath, `${JSON.stringify(record)}\n`);
+}
+function chain(test) {
+    const suites = [];
+    for (let s = test.suite; s; s = s.suite)
+        suites.unshift(s);
+    return suites;
+}
+async function beforeEach(test, context) {
+    const cleanups = [];
+    for (const suite of chain(test)) {
+        for (const hook of statics.getSuiteHooks(suite).beforeEach) {
+            const cleanup = await hook(context, suite);
+            if (typeof cleanup === 'function')
+                cleanups.push(cleanup);
+        }
+    }
+    return cleanups;
+}
+async function afterEach(test, context, cleanups) {
+    for (const suite of chain(test).reverse()) {
+        for (const hook of statics.getSuiteHooks(suite).afterEach)
+            await hook(context, suite);
+    }
+    for (const cleanup of cleanups.reverse())
+        await cleanup();
+}
+const isHitLimit = (e) => e instanceof Error && /Hit count limit/.test(e.message);
+function fullName(t) {
+    const parts = [t.name];
+    for (let s = t.suite; s && s.type === 'suite' && s.name; s = s.suite)
+        parts.unshift(s.name);
+    return parts.join(' > ');
+}
+export default class OxmutateRunner extends Base {
+    /**
+     * Import-time hits (static mutants) are attributed to the test file being collected, so a static
+     * mutant is later re-run against the files that load its module, not the whole suite (Stryker
+     * re-runs everything for each one).
+     */
+    onCollectStart(file) {
+        if (mode === 'dry')
+            ns.currentTestId = `${FILE_KEY}${file.filepath ?? file.file?.filepath ?? ''}`;
+        return super.onCollectStart?.call(this, file);
+    }
+    onBeforeTryTask(test, options) {
+        if (mode === 'dry')
+            ns.currentTestId = test.id;
+        return super.onBeforeTryTask?.(test, options);
+    }
+    async runTask(test) {
+        const fn = statics.getTestFn(test);
+        if (!fn)
+            throw new Error(`oxmutate: no function for test ${test.name}`);
+        if (mode !== 'mutant') {
+            if (only && !only.has(test.id))
+                return;
+            await fn();
+            return;
+        }
+        const context = test.context;
+        // Once a mutant has polluted this context, no further verdict from it can be trusted: the
+        // rest of the unit is left unrun, and the coordinator re-queues it into a fresh context.
+        const spec = specTests.has(test.id);
+        const done = spec ? decidedBySpec : decided;
+        const ids = polluted ? [] : (plan.tests[test.id] ?? []).filter((id) => !done.has(id));
+        let cleanups = [];
+        let attempt = 0;
+        const fresh = async () => {
+            await afterEach(test, context, cleanups);
+            cleanups = await beforeEach(test, context);
+            await this.retryReset(test, ++attempt);
+        };
+        // Mutants run since the last clean canary. The first of them started from a clean state, so its
+        // verdict stands whatever the next canary says; the rest are suspects if it fails.
+        let unchecked = [];
+        const canary = async () => {
+            if (!unchecked.length)
+                return true;
+            await fresh();
+            try {
+                await fn();
+                unchecked = [];
+                canaryEvery = Math.min(MAX_CANARY_EVERY, canaryEvery * 2);
+                return true;
+            }
+            catch (e) {
+                polluted = true;
+                canaryEvery = 1;
+                emit({ type: 'polluted', id: unchecked[0], suspects: unchecked.slice(1), test: test.id, file: test.file?.filepath, error: e instanceof Error ? e.message.slice(0, POLLUTION_ERROR_CHARS) : String(e) });
+                return false;
+            }
+        };
+        for (const id of ids) {
+            if (done.has(id))
+                continue;
+            if (attempt > 0)
+                await fresh();
+            if (progressPath)
+                writeFileSync(progressPath, `${id} ${String(Date.now())}\n`);
+            const t0 = performance.now();
+            ns.activeMutant = id;
+            ns.hitCount = 0;
+            ns.hitLimit = plan.hitLimits[id] ?? Number.MAX_SAFE_INTEGER;
+            let status = 'Survived';
+            try {
+                await fn();
+            }
+            catch (e) {
+                status = isHitLimit(e) ? 'Timeout' : 'Killed';
+            }
+            finally {
+                ns.activeMutant = undefined;
+                ns.hitCount = undefined;
+                ns.hitLimit = undefined;
+            }
+            if (status !== 'Survived')
+                done.add(id);
+            emit({ type: 'mutant', id, test: test.id, status, ms: performance.now() - t0, ...(spec ? { spec: true } : {}) });
+            unchecked.push(id);
+            // The canary: the same test, unmutated, must still pass. If it fails, a mutant left state
+            // behind (a cache, a registry, a fixture) that would decide the next verdicts. Run after every
+            // mutant at first, then every 2, 4, 8 while it stays clean: pollution is rare per test, and the
+            // canary was half of all executions (burgee/paratext, 2026-10-27).
+            if (unchecked.length >= canaryEvery && !(await canary()))
+                break;
+        }
+        if (!polluted)
+            await canary();
+        if (progressPath && ids.length)
+            writeFileSync(progressPath, '');
+        if (attempt > 0)
+            await fresh();
+        try {
+            await fn();
+        }
+        finally {
+            for (const cleanup of cleanups.reverse())
+                await cleanup();
+        }
+    }
+    /** Reset per-try state (snapshot counters, assertion counts) the way Vitest does for a retry. */
+    async retryReset(test, attempt) {
+        await super.onBeforeTryTask?.(test, { retry: attempt, repeats: 0 });
+    }
+    onAfterRunFiles(files) {
+        if (mode === 'dry') {
+            const tests = [];
+            const visit = (t, file) => {
+                if (t.type === 'test')
+                    tests.push({ id: t.id, file, name: fullName(t), state: t.result?.state ?? 'skip', ms: t.result?.duration ?? 0 });
+                for (const c of t.tasks ?? [])
+                    visit(c, file);
+            };
+            const fileErrors = [];
+            for (const f of files) {
+                const filepath = (f.file?.filepath ?? f.filepath);
+                visit(f, filepath);
+                // A file that fails to collect has no failing test to show for it: report the file.
+                const result = f.result;
+                if (result?.state === 'fail' && !f.tasks?.length)
+                    fileErrors.push({ file: filepath, error: (result.errors?.[0]?.message ?? 'failed to collect').slice(0, FILE_ERROR_CHARS) });
+            }
+            emit({ type: 'dry', tests, coverage: ns.mutantCoverage, fileErrors });
+        }
+        else if (mode === 'isolated') {
+            const failed = [];
+            let ran = 0;
+            const visit = (t) => {
+                if (t.type === 'test' && (t.result?.state === 'pass' || t.result?.state === 'fail'))
+                    ran++;
+                if (t.type === 'test' && t.result?.state === 'fail')
+                    failed.push(t.id);
+                for (const c of t.tasks ?? [])
+                    visit(c);
+            };
+            for (const f of files) {
+                visit(f);
+                // A file that failed with no failing test (it threw at import, or in a hook) failed under
+                // the mutant: a kill, as Stryker scores it. Its id stands in for the test that failed.
+                if (f.result?.state === 'fail' && !failed.length)
+                    failed.push(f.id);
+            }
+            emit({ type: 'isolated', id: env[ACTIVE_MUTANT_ENV] ?? ns.activeMutant, killed: failed.length > 0, failed, ran });
+        }
+        return super.onAfterRunFiles?.(files);
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/runtime.js

@@ -0,0 +1,24 @@
+/**
+ * The contract between instrumented code and the runner. The native core emits calls to
+ * `oxmAct(id)` and `oxmCov(...ids)` that read and write this namespace on `globalThis`
+ * (`native/src/instrument.rs`, `NAMESPACE`). Changing a field here without changing the emitter
+ * breaks every instrumented file.
+ */
+export const NAMESPACE = '__oxmutate__';
+/**
+ * Coverage key prefix for hits that happen while a test file is being collected (imports): the
+ * runner writes `file:<path>` keys, and the coordinator reads them back as static mutants' loaders.
+ */
+export const FILE_KEY = 'file:';
+/** Arms one mutant from process start, for static mutants and isolated re-runs. */
+export const ACTIVE_MUTANT_ENV = '__OXMUTATE_ACTIVE_MUTANT__';
+// ── The process seam ────────────────────────────────────────────────────────────────────────────
+// The one file in the package that names the process (burgee's `process-reference-lock.test.ts`):
+// the coordinator, the servers, the runner and the CLI read it here, so a test can see every
+// place the package touches it. `env` is the live object: a write here is a write to the process.
+export const env = process.env;
+export const argv = process.argv;
+export const cwd = () => process.cwd();
+export const stderr = process.stderr;
+export const exit = (code) => process.exit(code);
+//# sourceMappingURL=runtime.js.map