@polymorphism-tech/morph-spec 8.42.0 → 8.43.0

package/src/lib/mutation/commands.js

@@ -0,0 +1,60 @@
+import { dotnetBuildCommandFor, resolveTestBuildTargets } from '../tasks/test-runner.js';
+
+const FILTER = /--filter(?:[ =:])(?:"([^"]*)"|'([^']*)'|(\S+))/;
+const quote = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
+
+export function declaredFilter(command) {
+  const m = FILTER.exec(command);
+  return m ? (m[1] ?? m[2] ?? m[3]) : null;
+}
+
+export function withFilter(command, expression) {
+  const declared = declaredFilter(command);
+  if (declared === null) return `${command} --filter ${quote(expression)}`;
+  return command.replace(FILTER, () => `--filter ${quote(`(${declared})&(${expression})`)}`);
+}
+
+export function withTrx(command, { dir, name }) {
+  return `${command} --results-directory ${quote(dir)} --logger ${quote(`trx;LogFileName=${name}`)}`;
+}
+
+export function withoutBuild(command) {
+  return /(?:^|\s)--no-build(?:\s|$)/.test(command) ? command : `${command} --no-build`;
+}
+
+const CONFIGURATION = /(?:^|\s)(?:-c|--configuration)[ =:]?(?:"([^"]*)"|(\S+))/;
+const VERBOSITY = /\s(?:-v|--verbosity)[ =:]?\S+/g;
+
+/**
+ * The verify's build command per target. The test command's `-c` follows it, and
+ * verbosity is minimal: at `quiet` the `Project -> dll` line the binary proof reads is gone.
+ */
+export function dotnetBuildCommands(node, projectPath) {
+  const configuration = CONFIGURATION.exec(node.command ?? '');
+  const flag = configuration ? ` -c ${configuration[1] ?? configuration[2]}` : '';
+  return resolveTestBuildTargets(node)
+    .map((target) => dotnetBuildCommandFor(target, projectPath))
+    .filter(Boolean)
+    .map((command) => `${command.replace(VERBOSITY, '')} -v m${flag}`);
+}
+
+const BUILT = /^\s*(?<project>\S.*?) -> (?<dll>.+\.dll)\s*$/gm;
+
+export function parseBuiltDlls(output) {
+  const dlls = new Map();
+  for (const m of String(output).matchAll(BUILT)) dlls.set(m.groups.project, m.groups.dll.trim());
+  return dlls;
+}
+
+const VITEST_RUN = /(vitest(?:\.mjs|\.js)?)\s+run\b/;
+
+export function relatedCommand(runner, command, files) {
+  const list = files.map(quote).join(' ');
+  if (runner === 'vitest' && VITEST_RUN.test(command)) {
+    return `${command.replace(/\s+run\b/, ' related')} ${list} --run`;
+  }
+  if (runner === 'jest' && /\bjest\b/.test(command) && !/[;&|]/.test(command)) {
+    return `${command} --findRelatedTests ${list}`;
+  }
+  return null;
+}

package/src/lib/mutation/manifest.js

@@ -0,0 +1,138 @@
+import { isAbsolute, normalize, sep } from 'node:path';
+
+export const MUTANT_ID = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+export const MODES = ['schemata', 'rebuild'];
+export const BACKSLASH_TOKEN = '{{BS}}';
+
+const expandBackslash = (s) => (typeof s === 'string' ? s.split(BACKSLASH_TOKEN).join(String.fromCharCode(92)) : s);
+
+export class ManifestError extends Error {
+  constructor(problems) {
+    super(`manifesto de mutantes inválido:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+    this.name = 'ManifestError';
+    this.problems = problems;
+  }
+}
+
+export function eolOf(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+const toEol = (s, eol) => s.replace(/\r?\n/g, eol);
+
+function lineBounds(text, line) {
+  let start = 0;
+  for (let n = 1; n < line; n++) {
+    const nl = text.indexOf('\n', start);
+    if (nl === -1) return null;
+    start = nl + 1;
+  }
+  const nl = text.indexOf('\n', start);
+  return { start, end: nl === -1 ? text.length : nl };
+}
+
+/**
+ * Where `find` begins: it must start on `line` and occur there exactly once,
+ * so the `arquivo:linha` of the report is a fact the tool derived, not typed.
+ */
+export function locate(text, { line, find }) {
+  const bounds = lineBounds(text, line);
+  if (!bounds) return { error: `o arquivo tem menos de ${line} linhas` };
+  const needle = toEol(find, eolOf(text));
+  const at = text.indexOf(needle, bounds.start);
+  if (at === -1) return { error: `\`find\` não aparece a partir da linha ${line}` };
+  if (at > bounds.end) {
+    const first = text.slice(0, at).split('\n').length;
+    return { error: `\`find\` começa na linha ${first}, não na ${line}` };
+  }
+  const again = text.indexOf(needle, at + 1);
+  if (again !== -1 && again <= bounds.end) {
+    return { error: `\`find\` aparece mais de uma vez na linha ${line}: estenda-o até ficar único` };
+  }
+  return { start: at, end: at + needle.length, needle };
+}
+
+export function validateManifest(manifest, { fileExists } = {}) {
+  const problems = [];
+  const list = manifest?.mutants;
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new ManifestError(['`mutants` precisa ser um array com ao menos um mutante']);
+  }
+  const seen = new Set();
+  const mutants = list.map((raw, index) => {
+    const at = `mutants[${index}]${typeof raw?.id === 'string' ? ` (${raw.id})` : ''}`;
+    const m = raw ?? {};
+    if (typeof m.id !== 'string' || !MUTANT_ID.test(m.id)) problems.push(`${at}: \`id\` inválido (letra + letras/dígitos/_/-, até 32)`);
+    else if (seen.has(m.id)) problems.push(`${at}: \`id\` repetido`);
+    else seen.add(m.id);
+    if (typeof m.file !== 'string' || m.file === '') problems.push(`${at}: \`file\` ausente`);
+    else if (isAbsolute(m.file) || normalize(m.file).split(sep).includes('..')) problems.push(`${at}: \`file\` tem de ser relativo à raiz do projeto, sem \`..\``);
+    else if (fileExists && !fileExists(m.file)) problems.push(`${at}: \`file\` não existe: ${m.file}`);
+    if (!Number.isInteger(m.line) || m.line < 1) problems.push(`${at}: \`line\` tem de ser inteiro >= 1`);
+    if (typeof m.find !== 'string' || m.find === '') problems.push(`${at}: \`find\` ausente`);
+    if (typeof m.replace !== 'string') problems.push(`${at}: \`replace\` ausente (use string vazia para apagar)`);
+    else if (m.replace === m.find) problems.push(`${at}: \`replace\` igual a \`find\` não é mutação`);
+    if (m.mode !== undefined && !MODES.includes(m.mode)) problems.push(`${at}: \`mode\` tem de ser ${MODES.join(' | ')}`);
+    return {
+      id: m.id, file: typeof m.file === 'string' ? m.file.replace(/\\/g, '/') : m.file,
+      line: m.line, find: expandBackslash(m.find), replace: expandBackslash(m.replace), mode: m.mode ?? null,
+      note: typeof m.note === 'string' ? m.note : null,
+    };
+  });
+  if (problems.length > 0) throw new ManifestError(problems);
+  return mutants;
+}
+
+/**
+ * Resolves every mutant against the file text and refuses overlaps: two
+ * regions of one file inside each other cannot both be a switch in one build.
+ */
+export function resolveRegions(mutants, readText) {
+  const problems = [];
+  const byFile = new Map();
+  for (const m of mutants) {
+    const text = readText(m.file);
+    if (text === null) { problems.push(`${m.id}: não consegui ler ${m.file}`); continue; }
+    const at = locate(text, m);
+    if (at.error) { problems.push(`${m.id}: ${at.error}`); continue; }
+    const eol = eolOf(text);
+    const region = {
+      ...m, start: at.start, end: at.end, eol,
+      findText: at.needle, replaceText: toEol(m.replace, eol),
+    };
+    if (!byFile.has(m.file)) byFile.set(m.file, []);
+    byFile.get(m.file).push(region);
+  }
+  for (const regions of byFile.values()) {
+    regions.sort((a, b) => a.start - b.start);
+    for (let i = 1; i < regions.length; i++) {
+      if (regions[i].start < regions[i - 1].end) {
+        problems.push(`${regions[i].id} e ${regions[i - 1].id} se sobrepõem em ${regions[i].file}: rode-os em manifestos separados`);
+      }
+    }
+  }
+  if (problems.length > 0) throw new ManifestError(problems);
+  return mutants.map((m) => [...byFile.values()].flat().find((r) => r.id === m.id));
+}
+
+export function applyRegions(text, regions, produce) {
+  let out = '';
+  let cursor = 0;
+  const spans = new Map();
+  for (const region of [...regions].sort((a, b) => a.start - b.start)) {
+    out += text.slice(cursor, region.start);
+    const from = out.split('\n').length;
+    out += produce(region);
+    spans.set(region.id, { from, to: out.split('\n').length });
+    cursor = region.end;
+  }
+  return { text: out + text.slice(cursor), spans };
+}
+
+export function diffOf(m, limit = 160) {
+  const one = (s) => {
+    const flat = s.replace(/\r?\n\s*/g, ' ').replace(/\|/g, '\\|');
+    return flat.length > limit ? `${flat.slice(0, limit)}…` : flat;
+  };
+  return `\`- ${one(m.find)}\` / \`+ ${one(m.replace)}\``;
+}

package/src/lib/mutation/plan.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isInside } from '../tasks/test-runner.js';
+import { isDotnetSource } from '../tasks/dotnet-test-introspection.js';
+import { resolveRegions, validateManifest } from './manifest.js';
+
+const JS_RUNNERS = new Set(['vitest', 'jest', 'node-test']);
+
+export function loadPlan({ root, planPath }) {
+  const manifest = JSON.parse(readFileSync(planPath, 'utf8').replace(/^/, ''));
+  const mutants = validateManifest(manifest, { fileExists: (f) => existsSync(join(root, f)) });
+  return resolveRegions(mutants, (f) => {
+    try { return readFileSync(join(root, f), 'utf8'); } catch { return null; }
+  });
+}
+
+export function pickNode(file, nodes, root) {
+  const abs = resolve(root, file);
+  if (isDotnetSource(file)) return nodes.find((n) => n.runner === 'dotnet') ?? null;
+  const owners = nodes
+    .filter((n) => JS_RUNNERS.has(n.runner) && isInside(abs, resolve(root, n.cwd || '.')))
+    .sort((a, b) => resolve(root, b.cwd || '.').length - resolve(root, a.cwd || '.').length);
+  return owners[0] ?? null;
+}
+
+export function groupByNode(regions, nodes, root) {
+  const groups = new Map();
+  const orphans = [];
+  for (const region of regions) {
+    const node = pickNode(region.file, nodes, root);
+    if (!node) { orphans.push(region); continue; }
+    if (!groups.has(node.id)) groups.set(node.id, { node, regions: [] });
+    groups.get(node.id).regions.push(region);
+  }
+  return { groups: [...groups.values()], orphans };
+}

package/src/lib/mutation/report.js

@@ -0,0 +1,66 @@
+const cell = (s) => String(s ?? '').replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
+const short = (md5) => (md5 ? md5.slice(0, 12) : '—');
+const seconds = (ms) => `${(ms / 1000).toFixed(1)} s`;
+
+function countCell(m) {
+  const scope = m.scope === 'subset' ? 'subconjunto' : 'suíte inteira';
+  switch (m.verdict) {
+    case 'killed': return m.scope === 'subset' ? `≥${m.killers} de ${m.executed} (${scope})` : `${m.killers} de ${m.executed ?? '?'} (${scope})`;
+    case 'survived': return `**0 de ${m.executed ?? '?'} (SOBREVIVEU, ${scope})**`;
+    case 'build-error': return '— (o mutante não compila: não é morte)';
+    default: return '— (inconclusivo: não conta como morte nem como sobrevivência)';
+  }
+}
+
+function reasonCell(m) {
+  if (m.verdict === 'survived') return m.reason || 'nenhum teste falhou na suíte inteira, com o mutante compilado de verdade';
+  const how = m.demoted ? ` [rebuild: ${m.demoted}]` : '';
+  return `${m.reason || '—'}${how}`;
+}
+
+const BINARY = {
+  md5: 'DLL do rebuild final idêntica (md5) à DLL construída da árvore limpa antes de qualquer mutante',
+  rebuilt: 'DLL recompilada DEPOIS da restauração e sem a chave de schemata, mas com md5 diferente da baseline — o build não é determinístico neste projeto, então o conteúdo não se compara',
+  unavailable: 'sem etapa de build neste runner: nada a provar sobre binário',
+  unlocated: 'ATENÇÃO — o build não informou a DLL dos projetos mutados, então o binário final NÃO pôde ser provado',
+  mismatch: 'ATENÇÃO — a DLL do rebuild final NÃO bate com a baseline e ainda carrega a chave de schemata',
+};
+
+export function renderSection(result, { head = null, date = null, subset = null, note = null } = {}) {
+  const lines = ['## Mutações', ''];
+  const { method } = result;
+  const where = subset?.usable
+    ? `${subset.classes.length} classe(s) de teste (${subset.files.changed?.length ?? 0} alterada(s) pela feature, ${subset.files.mentions?.length ?? 0} citando os tipos mutados)`
+    : (subset?.reason ?? 'nenhum');
+  lines.push(`**Método:** \`morph-spec mutate\`${head ? ` sobre ${head.slice(0, 8)}` : ''}${date ? ` em ${date}` : ''}.`);
+  lines.push(`- ${method.schemata} mutante(s) por chave em UM build (schemata), ${method.rebuild} por rebuild real${(method.jobs ?? 1) > 1 ? `; rodadas de escopo rápido em ${method.jobs} workers` : ''}.`);
+  lines.push(`- Escopo rápido: ${method.subset.live ? where : `desligado (${method.subset.note ?? subset?.reason ?? 'sem subconjunto'})`}.`);
+  lines.push('- Morto = falha nova (ausente na rodada-base do mesmo escopo) com o motivo abaixo; na suíte inteira, a falha também tem de se repetir. Sobrevivente de escopo rápido é SEMPRE refeito com o mutante compilado de verdade e a suíte inteira; "sobreviveu" só sai desse caminho.');
+  if (result.baseline.subset) lines.push(`- Rodada-base do subconjunto: ${result.baseline.subset.executed} executados, ${result.baseline.subset.failed} falhando.`);
+  if (result.baseline.full) lines.push(`- Rodada-base da suíte inteira: ${result.baseline.full.executed} executados, ${result.baseline.full.failed} falhando.`);
+  if (note) lines.push(`- ${note}`);
+  lines.push('');
+  lines.push('| # | Arquivo:linha | Mutação (diff) | md5 antes | md5 depois | Testes derrubados | Motivo da falha |');
+  lines.push('|---|---|---|---|---|---|---|');
+  for (const m of result.mutants) {
+    lines.push(`| ${m.id} | ${cell(`${m.file}:${m.line}`)} | ${m.diff} | ${short(m.md5Before)} | ${short(m.md5After)} | ${cell(countCell(m))} | ${cell(reasonCell(m))} |`);
+  }
+  lines.push('');
+  const r = result.restore;
+  const bad = r.files.filter((f) => !f.ok).map((f) => f.file);
+  lines.push(`**Reversão:** snapshot/restore de bytes, md5 de cada arquivo conferido${bad.length ? ` — FALHOU em ${bad.join(', ')}` : ' (todos iguais ao original)'}; sem \`git checkout\`. Escrita nova a cada restauração, então o arquivo é mais novo que qualquer binário de mutante e o build recompila.`);
+  lines.push(`**Binário:** ${BINARY[result.binary.proof]}.`);
+  lines.push(`**Árvore:** \`git status --porcelain\` ${r.treeClean ? 'idêntico ao de antes da rodada (vazio em src/)' : 'DIFERENTE do de antes da rodada — investigar antes de qualquer nota'}.`);
+  const sum = result.timings.reduce((acc, t) => acc + t.ms, 0);
+  const jobs = method.jobs ?? 1;
+  const wall = result.wallMs ?? sum;
+  lines.push(`**Tempo:** ${seconds(wall)} de relógio${jobs > 1 ? ` com ${jobs} workers` : ''}; soma das ${result.timings.length} etapas de build+teste: ${seconds(sum)}.`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function summarize(result) {
+  const tally = { killed: 0, survived: 0, 'build-error': 0, inconclusive: 0 };
+  for (const m of result.mutants) tally[m.verdict] = (tally[m.verdict] ?? 0) + 1;
+  return tally;
+}

package/src/lib/mutation/runner.js

@@ -0,0 +1,351 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { applyRegions, diffOf } from './manifest.js';
+import { blame, parseCompilerErrors, patchFile, switchClassName, switchSource, SWITCH_ENV } from './schemata.js';
+import { md5Of, md5OfFile, openSnapshot, restoreSnapshot, trackGenerated } from './snapshot.js';
+import { parseBuiltDlls } from './commands.js';
+import { firstLines, methodOf } from './trx.js';
+import { nearestProjectOf } from '../tasks/dotnet-test-introspection.js';
+
+const posix = (p) => p.replace(/\\/g, '/');
+const MAX_SCHEMATA_ATTEMPTS = 3;
+const MAX_REPRODUCE = 5;
+
+const envWithout = (env) => { const { [SWITCH_ENV]: _drop, ...rest } = env; return rest; };
+const failedNames = (result) => new Set(result.failedTests.map((t) => t.name));
+
+function newFailures(result, baseline) {
+  const known = baseline ? failedNames(baseline) : new Set();
+  return result.failedTests.filter((t) => !known.has(t.name));
+}
+
+function reasonOf(failures) {
+  const [first] = failures;
+  if (!first) return '';
+  const text = firstLines(first.message);
+  return text ? `${first.name}: ${text}` : first.name;
+}
+
+/**
+ * Judges one test result against the same scope's baseline: killed needs a
+ * failure the pristine run did not have; a run that executed nothing or died
+ * proves nothing either way.
+ */
+export function judge(result, baseline) {
+  if (result.outcome === 'crash') return { state: 'inconclusive', reason: result.note ?? 'a rodada não terminou' };
+  if (result.executed === 0) return { state: 'inconclusive', reason: 'nenhum teste foi executado neste escopo' };
+  if (result.outcome === 'red') {
+    const fresh = newFailures(result, baseline);
+    if (fresh.length > 0) return { state: 'killed', failures: fresh, reason: reasonOf(fresh) };
+  }
+  return { state: 'survived' };
+}
+
+const carriesSwitch = (dll) => readFileSync(dll).includes(Buffer.from(SWITCH_ENV, 'utf16le'));
+
+/**
+ * Equal bytes against the DLL built from the clean tree is the proof. A non-deterministic
+ * build can only show it was rebuilt AFTER the restore and carries no switch.
+ */
+export function proveBinary({ pristine, dlls, restoredAt, hashes }) {
+  const projects = [...pristine].map(([name, md5]) => {
+    const dll = dlls.get(name);
+    const final = hashes.get(name) ?? null;
+    const rebuilt = Boolean(dll) && statSync(dll).mtimeMs >= restoredAt - 50;
+    return { name, pristine: md5, final, equal: final === md5, rebuilt, switchLeft: Boolean(dll) && carriesSwitch(dll) };
+  });
+  if (projects.length === 0) return { proof: 'unlocated', projects };
+  if (projects.some((p) => p.switchLeft)) return { proof: 'mismatch', projects };
+  if (projects.every((p) => p.equal)) return { proof: 'md5', projects };
+  return { proof: projects.every((p) => p.rebuilt) ? 'rebuilt' : 'mismatch', projects };
+}
+
+async function pool(items, size, worker) {
+  const queue = [...items];
+  await Promise.all(Array.from({ length: Math.min(size, queue.length) }, async () => {
+    while (queue.length > 0) await worker(queue.shift());
+  }));
+}
+
+function mergeBaselines(copies) {
+  const [first] = copies;
+  const broken = copies.find((c) => c.outcome === 'crash');
+  if (broken) return broken;
+  const seen = new Map();
+  for (const c of copies) for (const t of c.failedTests) if (!seen.has(t.name)) seen.set(t.name, t);
+  const failedTests = [...seen.values()];
+  return { ...first, outcome: failedTests.length > 0 ? 'red' : 'green', failed: failedTests.length, failedTests };
+}
+
+export async function runMutation(input) {
+  const { root, node, regions, workDir, runId, exec, adapter, gate, git, log = () => {}, options = {} } = input;
+  const timeoutMs = options.timeoutMs ?? node.timeoutMs ?? 900_000;
+  const startedAt = Date.now();
+  let workerCount = 1;
+  const timings = [];
+  const timed = async (label, fn) => {
+    const at = Date.now();
+    try { return await fn(); } finally { timings.push({ label, ms: Date.now() - at }); }
+  };
+
+  const files = [...new Set(regions.map((r) => r.file))];
+  const originals = new Map(files.map((f) => [f, readFileSync(join(root, f), 'utf8')]));
+  const porcelainBefore = git.porcelain();
+  const snapshot = openSnapshot({ dir: join(workDir, 'snapshot'), root, files, runId });
+  const projectOf = (file) => {
+    const csproj = nearestProjectOf(join(root, file), root);
+    return csproj ? { rel: posix(relative(root, csproj)), dir: dirname(csproj), name: basename(csproj).replace(/\.[a-z]+proj$/i, '') } : null;
+  };
+
+  const results = new Map(regions.map((r) => [r.id, {
+    id: r.id, file: r.file, line: r.line, diff: diffOf(r), note: r.note,
+    md5Before: md5Of(readFileSync(join(root, r.file))),
+    md5After: md5Of(applyRegions(originals.get(r.file), [r], (x) => x.replaceText).text),
+    mode: r.mode === 'rebuild' || adapter.kind !== 'dotnet' || !/\.cs$/i.test(r.file) ? 'rebuild' : 'schemata',
+    demoted: null, verdict: null, scope: null, killers: 0, executed: null, reason: '', durationMs: 0,
+  }]));
+  const byId = new Map(regions.map((r) => [r.id, r]));
+
+  const build = async (label) => {
+    const dlls = new Map();
+    for (const command of adapter.buildCommands) {
+      const r = await timed(label, () => exec(command, { cwd: adapter.cwd, env: process.env, timeoutMs, label }));
+      const output = `${r.stdout}\n${r.stderr}`;
+      if (r.status !== 0) return { ok: false, output };
+      for (const [name, dll] of parseBuiltDlls(output)) dlls.set(name, dll);
+    }
+    return { ok: true, dlls };
+  };
+
+  const dllHashes = (dlls) => new Map(
+    [...new Set(files.map((f) => projectOf(f)?.name).filter(Boolean))]
+      .filter((name) => dlls.has(name) && existsSync(dlls.get(name)))
+      .map((name) => [name, md5OfFile(dlls.get(name))]),
+  );
+
+  const run = (scope, label, env) => timed(label, () => adapter.runTests({ scope, label, env }));
+
+  const confirmKill = async (id, verdict, env) => {
+    if (!adapter.reproduce) return verdict;
+    const names = [...new Set(verdict.failures.map((f) => f.name))].slice(0, MAX_REPRODUCE);
+    const again = await timed(`${id}-reproduce`, () => adapter.reproduce({ names, label: `${id}-reproduce`, env }));
+    if (again.outcome === 'crash' || !again.executed) {
+      return { state: 'inconclusive', reason: `a falha de ${names[0]} não pôde ser confirmada na repetição (${again.note ?? 'nenhum teste executado'})` };
+    }
+    const wanted = new Set(names.map(methodOf));
+    const held = again.failedTests.filter((t) => wanted.has(methodOf(t.name)));
+    if (held.length > 0) return { ...verdict, reason: reasonOf(held) };
+    const whole = await timed(`${id}-reproduce-full`, () => adapter.runTests({ scope: 'full', label: `${id}-reproduce-full`, env }));
+    if (whole.outcome === 'crash' || !whole.executed) {
+      return { state: 'inconclusive', reason: `a falha de ${names[0]} não pôde ser confirmada na repetição (${whole.note ?? 'nenhum teste executado'})` };
+    }
+    const heldWhole = whole.failedTests.filter((t) => wanted.has(methodOf(t.name)));
+    if (heldWhole.length > 0) return { ...verdict, reason: reasonOf(heldWhole) };
+    const which = names.length === 1 ? names[0] : `${names.length} testes`;
+    return { state: 'survived', reason: `nenhum teste falhou de forma reproduzível: ${which} falhou uma vez e passou isolado e na suíte inteira repetida (instável, não prova o mutante)` };
+  };
+
+  const record = (id, patch) => Object.assign(results.get(id), patch);
+  const applyOnDisk = (id) => {
+    const region = byId.get(id);
+    writeFileSync(join(root, region.file), applyRegions(originals.get(region.file), [region], (x) => x.replaceText).text);
+  };
+
+  let pristine = new Map();
+  let binary = { proof: 'unavailable', projects: [] };
+  let baselineSubset = null;
+  let baselineFull = null;
+  let subsetLive = adapter.hasSubset;
+  let subsetNote = null;
+  const needFullBaseline = [];
+  let restoreReport = [];
+
+  try {
+    gate?.enter('mutate');
+
+    if (adapter.buildCommands.length > 0) {
+      restoreSnapshot(snapshot);
+      const first = await build('build-pristine');
+      if (!first.ok) throw Object.assign(new Error('a árvore não compila ANTES da mutação — nada foi mutado'), { code: 'baseline-build-failed', output: first.output });
+      pristine = dllHashes(first.dlls);
+    }
+
+    const compileErrorOf = (output, fallback) => firstLines(parseCompilerErrors(output).map((e) => `${e.code} ${e.message}`)[0] ?? fallback);
+
+    const screenLiteral = async (ids) => {
+      let remaining = ids;
+      for (let attempt = 0; attempt < MAX_SCHEMATA_ATTEMPTS && remaining.length > 0; attempt++) {
+        const patched = [];
+        for (const file of files) {
+          const own = remaining.map((id) => byId.get(id)).filter((r) => r.file === file);
+          if (own.length === 0) continue;
+          const { text, spans } = applyRegions(originals.get(file), own, (r) => r.replaceText);
+          writeFileSync(join(root, file), text);
+          patched.push({ abs: join(root, file), file, spans });
+        }
+        const b = await build('build-literal');
+        restoreSnapshot(snapshot);
+        if (b.ok) return remaining;
+        const { blamed, unmapped } = blame(parseCompilerErrors(b.output), patched);
+        const demote = unmapped.length > 0 || blamed.length === 0 ? [...remaining] : blamed;
+        const note = `a forma literal não compila (${compileErrorOf(b.output, 'erro de compilação')})`;
+        for (const id of demote) record(id, { mode: 'rebuild', demoted: note });
+        remaining = remaining.filter((id) => !demote.includes(id));
+      }
+      for (const id of remaining) record(id, { mode: 'rebuild', demoted: 'a triagem da forma literal não convergiu' });
+      return [];
+    };
+
+    let schemataIds = [...results.values()].filter((r) => r.mode === 'schemata').map((r) => r.id);
+    if (adapter.buildCommands.length > 0) schemataIds = await screenLiteral(schemataIds);
+    let schemataBuilt = false;
+    for (let attempt = 0; attempt < MAX_SCHEMATA_ATTEMPTS && schemataIds.length > 0; attempt++) {
+      const patched = [];
+      const classes = new Map();
+      for (const file of files) {
+        const own = schemataIds.map((id) => byId.get(id)).filter((r) => r.file === file);
+        if (own.length === 0) continue;
+        const project = projectOf(file);
+        const className = switchClassName(project.rel);
+        const { text, spans } = patchFile(originals.get(file), own, className);
+        writeFileSync(join(root, file), text);
+        patched.push({ abs: join(root, file), file, spans });
+        if (!classes.has(project.rel)) {
+          const generated = posix(relative(root, join(project.dir, `${className}.g.cs`)));
+          writeFileSync(join(root, generated), switchSource(className));
+          trackGenerated(snapshot, generated);
+          classes.set(project.rel, generated);
+        }
+      }
+      const b = await build('build-schemata');
+      if (b.ok) { schemataBuilt = true; break; }
+      const { blamed, unmapped } = blame(parseCompilerErrors(b.output), patched);
+      restoreSnapshot(snapshot);
+      const note = `schemata recusou — ${compileErrorOf(b.output, 'o build de schemata falhou')}`;
+      const demote = unmapped.length > 0 || blamed.length === 0 ? [...schemataIds] : blamed;
+      for (const id of demote) record(id, { mode: 'rebuild', demoted: note });
+      schemataIds = schemataIds.filter((id) => !demote.includes(id));
+    }
+    if (!schemataBuilt) {
+      for (const id of schemataIds) record(id, { mode: 'rebuild', demoted: 'schemata recusou — o build não convergiu' });
+      schemataIds = [];
+    } else {
+      restoreSnapshot(snapshot);
+    }
+
+    const hasRebuild = [...results.values()].some((r) => r.mode === 'rebuild');
+    const jobs = Math.max(1, Math.min(options.jobs ?? 1, gate?.jobs ?? options.jobs ?? 1));
+    if (subsetLive && (schemataIds.length > 0 || hasRebuild)) {
+      const copies = schemataIds.length > 0 ? jobs : 1;
+      baselineSubset = mergeBaselines(await Promise.all(Array.from({ length: copies }, (_, i) => (
+        run('subset', i === 0 ? 'baseline-subset' : `baseline-subset-${i + 1}`, envWithout(process.env))))));
+      if (baselineSubset.outcome === 'crash' || baselineSubset.executed === 0) {
+        subsetLive = false;
+        subsetNote = baselineSubset.executed === 0 ? 'o filtro do subconjunto não selecionou teste algum' : (baselineSubset.note ?? 'a rodada-base do subconjunto não terminou');
+      }
+    }
+    if (!subsetLive && schemataIds.length > 0) baselineFull = await run('full', 'baseline-full', envWithout(process.env));
+
+    const scopeOf = subsetLive ? 'subset' : 'full';
+    const scopeBaseline = () => (subsetLive ? baselineSubset : baselineFull);
+    const routed = [];
+    const scopeJobs = subsetLive ? jobs : 1;
+    workerCount = schemataIds.length > 0 ? scopeJobs : 1;
+    const outcomes = new Map();
+    await pool(schemataIds, scopeJobs, async (id) => {
+      outcomes.set(id, await run(scopeOf, `${id}-${scopeOf}`, { ...process.env, [SWITCH_ENV]: id }));
+    });
+    for (const id of schemataIds) {
+      const result = outcomes.get(id);
+      const first = judge(result, scopeBaseline());
+      const verdict = first.state === 'killed' && scopeOf === 'full' ? await confirmKill(id, first, { ...process.env, [SWITCH_ENV]: id }) : first;
+      const base = { scope: scopeOf, executed: result.executed, durationMs: result.durationMs };
+      if (verdict.state === 'killed') {
+        record(id, { ...base, verdict: 'killed', killers: verdict.failures.length, reason: verdict.reason });
+      } else {
+        record(id, { ...base, verdict: null, reason: verdict.reason ?? '' });
+        routed.push({ id, needs: 'full' });
+      }
+    }
+    for (const r of results.values()) if (r.mode === 'rebuild') routed.push({ id: r.id, needs: subsetLive ? 'subset-then-full' : 'full' });
+
+    for (const { id, needs } of routed) {
+      applyOnDisk(id);
+      try {
+        if (adapter.buildCommands.length > 0) {
+          const b = await build(`build-${id}`);
+          if (!b.ok) {
+            const err = parseCompilerErrors(b.output)[0];
+            record(id, { verdict: 'build-error', reason: err ? `${err.code} ${err.message}` : 'o mutante não compila', scope: null });
+            continue;
+          }
+        }
+        if (needs === 'subset-then-full') {
+          const sub = await run('subset', `${id}-subset`, envWithout(process.env));
+          const verdict = judge(sub, baselineSubset);
+          if (verdict.state === 'killed') {
+            record(id, { verdict: 'killed', scope: 'subset', killers: verdict.failures.length, executed: sub.executed, reason: verdict.reason, durationMs: sub.durationMs });
+            continue;
+          }
+        }
+        const full = await run('full', `${id}-full`, envWithout(process.env));
+        const first = judge(full, baselineFull);
+        const verdict = first.state === 'killed' ? await confirmKill(id, first, envWithout(process.env)) : first;
+        const base = { scope: 'full', executed: full.executed, durationMs: full.durationMs };
+        if (verdict.state === 'inconclusive') record(id, { ...base, verdict: 'inconclusive', reason: verdict.reason });
+        else if (verdict.state === 'survived') record(id, { ...base, verdict: 'survived', reason: verdict.reason ?? '' });
+        else { record(id, { ...base, verdict: 'killed', killers: verdict.failures.length, reason: verdict.reason }); if (!baselineFull) needFullBaseline.push({ id, full }); }
+      } finally {
+        restoreSnapshot(snapshot);
+      }
+    }
+
+    const restoredAt = Date.now();
+    restoreReport = restoreSnapshot(snapshot);
+    if (adapter.buildCommands.length > 0) {
+      const last = await build('build-final');
+      if (!last.ok) throw Object.assign(new Error('o rebuild final da árvore restaurada falhou'), { code: 'final-build-failed', output: last.output });
+      binary = proveBinary({ pristine, dlls: last.dlls, restoredAt, hashes: dllHashes(last.dlls) });
+    }
+
+    if (needFullBaseline.length > 0) {
+      baselineFull = await run('full', 'baseline-full', envWithout(process.env));
+      for (const { id, full } of needFullBaseline) {
+        const verdict = judge(full, baselineFull);
+        if (verdict.state === 'killed') record(id, { killers: verdict.failures.length, reason: verdict.reason });
+        else record(id, { verdict: 'survived', killers: 0, reason: '' });
+      }
+    }
+  } finally {
+    restoreReport = restoreSnapshot(snapshot, { rewrite: false });
+    gate?.release();
+  }
+
+  const porcelainAfter = git.porcelain();
+  const mutants = regions.map((r) => results.get(r.id));
+  return {
+    runId,
+    method: {
+      adapter: adapter.kind,
+      schemata: mutants.filter((m) => m.mode === 'schemata').length,
+      rebuild: mutants.filter((m) => m.mode === 'rebuild').length,
+      subset: { requested: adapter.hasSubset, live: subsetLive, note: subsetNote },
+      jobs: workerCount,
+    },
+    wallMs: Date.now() - startedAt,
+    mutants,
+    baseline: {
+      subset: baselineSubset ? { executed: baselineSubset.executed, failed: baselineSubset.failed } : null,
+      full: baselineFull ? { executed: baselineFull.executed, failed: baselineFull.failed } : null,
+    },
+    binary,
+    restore: {
+      files: restoreReport,
+      ok: restoreReport.every((f) => f.ok),
+      porcelainBefore,
+      porcelainAfter,
+      treeClean: porcelainBefore === porcelainAfter,
+    },
+    timings,
+  };
+}