# `MutagenEx.MutationRunner`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/mutation_runner.ex#L1)

Per-mutation execution: swap → run → classify → restore. Aggregates the
per-site outcomes into a result block the JSON reporter (S6) can
serialise.

Contract: [`mutagen.mutation_pipeline`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/specs/mutation_pipeline.spec.md)
r3-r11.

## Invariants summary

  * **r3** — refuses to mutate `MutagenEx.*` or `Mix.Tasks.Mutagen`
    modules (see [`mutagen.decision.self_mutation_refused`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/decisions/self_mutation_refused.md)).
  * **r4** — per-site test runs wrap `ExUnit.run/0` in the timeout
    structure owned by `MutagenEx.MutationRunner.MutationLoop`. The
    timeout uses the two-phase cooperative-cancellation path
    documented in `mutagen.decision.timeout_handling` (trappable
    `:shutdown` first, brutal_kill only as escalation). The runner
    classifies a deadline hit as `:timeout` unless fail-fast already
    recorded a failure. The following site carries
    `tainted_predecessors: true` either way. Before
    restore, the runner calls `:code.purge/1` on the site's scoped
    modules to release any orphaned Code.Server load lock left by
    a brutal-killed task — the per-mutation hardening that
    bw mutagen-wrd.13 fixed.
  * **r5** — exactly five outcomes: `:killed`, `:survived`, `:timeout`,
    `:compile_error`, `:error`. `:compile_error` does not count toward
    the kill-rate denominator.
  * **r6** — after every per-site run, the original module is restored
    via `:code.load_binary/3` from a per-run ETS snapshot owned by
    `MutagenEx.BeamCache`. The snapshot is taken once before the
    per-site loop dispatches, in a serial pre-pass over every scoped
    module — closing the TOCTOU window a per-site snapshot would
    open under `--max-concurrency > 1`. The cache lives only for the
    duration of `run/1` (created at the start, deleted in the
    `after` clause). On restore failure the runner aborts with
    `{:error, :unrecoverable_restore_failure, ...}`. See
    [`mutagen.decision.per_run_beam_cache`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/decisions/per_run_beam_cache.md)
    and
    [`mutagen.decision.code_server_facade`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/decisions/code_server_facade.md).
  * **r12** — a raise, throw, or exit propagating out of the
    loaded-mutation window (from successful compile of the mutated
    AST through the test run and `:code.purge/1` settle) triggers
    restore before re-propagation. The original kind/value/stacktrace
    surfaces to the caller; restore failure during such propagation
    is best-effort and never masks the original cause. Implemented
    via `with_restore/4`, mirroring
    `MutagenEx.CoverageRunner`'s `with_cover_lifecycle/2`.
  * **r7** — pre/post state snapshots
    (`Process.registered/0`, `:ets.all/0`, `:persistent_term.get/0`).
    Growth flags `tainted_predecessors: true` for subsequent results
    and emits a warning naming the new entities (best-effort —
    `Process.registered/0` is the named-process surface; anonymous
    leaks are documented as a known caveat per
    [`mutagen.decision.timeout_handling`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/decisions/timeout_handling.md)).
  * **r8** — modules whose AST contains `use SomeModule` get a
    `state_drift_warning` listing the used modules.
  * **r9** — stderr is captured via `ExUnit.CaptureIO` and attached
    to each result's `warnings` field.
  * **r10** — test files are loaded once (the orchestrator's
    responsibility upstream); per-site cycles re-register modules via
    `ExUnit.Server.add_module/2` from `MutationLoop`.
  * **r11** — no file on disk is modified by the runner. All AST
    compilation is in-memory via `Code.compile_quoted/2`; restore is
    an in-memory binary swap via `:code.load_binary/3` against the
    per-run BeamCache snapshot (no disk writes either).

## Input shape

`run/1` takes a map:

  * `:seed` — `non_neg_integer`. Forwarded to ExUnit.configure for the
    duration of the runner.
  * `:timeout_ms` — `pos_integer`. Per-site wall-clock budget.
  * `:test_filter` — `%MutagenEx.TestSelector.TestFilter{}`.
  * `:ast_cache` — `%{file => {ast, source_text}}` from
    `MutagenEx.AstCache.load/1`.
  * `:sites` — `[%MutagenEx.MutationEnumerator.Site{}, ...]`.
  * `:scope_records` — `[%MutagenEx.ScopeResolver.Scope{}]`, used for
    r8 (state-drift detection over `use SomeModule` in scoped modules).
  * `:test_modules` — `[{module, exunit_module_cfg}]` to re-register
    between per-site runs. Built by the orchestrator from the test
    filter once before the runner starts.

Optional:

  * `:fail_fast` — `boolean`. Default `true`. Stops executing cited
    tests after the first failure. Use `false` for a full suite run.
  * `:ex_unit` — module implementing `MutagenEx.Test.ExUnitFacade`.
    Default `MutagenEx.Test.ExUnit`. Passed through to `MutationLoop`.
  * `:ex_unit_server` — module implementing
    `MutagenEx.Test.ExUnitServerFacade`. Default
    `MutagenEx.Test.ExUnitServer`. Passed through to `MutationLoop`.
  * `:capture_io` — module implementing
    `MutagenEx.Test.CaptureIoFacade`. Default
    `MutagenEx.Test.CaptureIo`. Used by both the swap-compile capture
    around `Code.compile_quoted/2` and the per-site `MutationLoop`
    stderr capture.
  * `:compiler` — module implementing `MutagenEx.Test.CompilerFacade`,
    OR a legacy `{module, function}` tuple for back-compat with the
    pre-bw mutagen-wrd.24 stubs. Default `MutagenEx.Test.Compiler`.
    The legacy tuple shape is honored so existing test stubs that
    pass `{CompilerStub, :compile_quoted}` keep working.
  * `:code_server` — module implementing
    `MutagenEx.Test.CodeServerFacade`. Default
    `MutagenEx.Test.CodeServer`. The restore path uses this facade to
    call `:code.get_object_code/1` (snapshot pre-pass) and
    `:code.load_binary/3` (per-site restore). Tests inject a stub
    that records calls and returns canned binaries; production
    callers leave the default. Mirrors the `:compiler` seam.
  * `:beam_cache_table` — `:ets.tab()`. The per-run snapshot table.
    Callers DO NOT pass this; `run/1` creates the table itself via
    `MutagenEx.BeamCache.new/0` at the start of `execute/2` and
    deletes it in the `after` clause. The field is documented here
    so internal helpers that read `cfg.beam_cache_table` have a
    named contract. Tests that bypass `execute/2` (and thread a
    hand-rolled cfg into deeper helpers) must populate this
    themselves.
  * `:cancel_grace_ms` — `non_neg_integer`. Grace window the
    cooperative-cancellation phase waits before escalating to
    brutal_kill on a timeout. Default `100`. Set to `0` in tests
    that need to exercise the brutal-only path. Passed through to
    `MutationLoop`.
  * `:code_purge` — `(module -> any)`. Test seam for the post-
    `:timeout` Code.Server settle pass. Default `&:code.purge/1`.
  * `:max_concurrency` — `pos_integer | nil`. Cap on the number of
    per-site tasks `Task.Supervisor.async_stream_nolink/4` will spawn
    in parallel. `nil` resolves to `1` (fully-serial, v1.0-equivalent
    execution) — this is also the Mix-task default when the user
    does not pass `--max-concurrency`. `N > 1` is the explicit
    opt-in path for callers with collision-free input. Regardless
    of value, results are collected in input order (the
    `async_stream` `:ordered` default) so the JSON document is
    byte-identical to the serial-equivalent run on deterministic
    scopes — taint, warnings, and per-site classification all fold
    sequentially over the ordered result list. See
    `mutagen.mutation_pipeline.r15`.
  * `:task_sup` — `atom | pid`. The `Task.Supervisor` the per-site
    tasks run under. Default `MutagenEx.TaskSup`. Tests can pass a
    one-off supervisor pid for isolation.
  * `:on_site_completed` — `(result_or_compile_error -> :ok)`. Called
    once per site as the result becomes available (in input order),
    before the runner accumulates it. This is the streaming-NDJSON
    seam: the Mix task wires this to emit one wire-shape JSON line
    per site. The runner only invokes it; it does no I/O itself
    (`mutagen.json_schema.r11`).

## Output shape

`{:ok, %{results: [...], compile_errors: [...], state_drift_warning: %{...}, warnings: [...]}}`
on full pipeline. `{:error, reason, details}` on `:self_mutation_refused`
or `:unrecoverable_restore_failure`.

# `compile_error_entry`

```elixir
@type compile_error_entry() :: %{
  id: String.t(),
  file: String.t(),
  function: String.t() | nil,
  line: pos_integer(),
  column: pos_integer(),
  mutator: atom(),
  message: String.t(),
  exception: module() | nil
}
```

Compile-error record (sites whose mutated AST refused to compile).

# `error_reason`

```elixir
@type error_reason() ::
  :self_mutation_refused | :unrecoverable_restore_failure | :invalid_input
```

Reasons the runner can abort with.

# `ok_result`

```elixir
@type ok_result() :: %{
  results: [site_result()],
  compile_errors: [compile_error_entry()],
  dropped: [
    %{
      id: String.t(),
      path: Path.t(),
      reason: :ast_cache_miss | :site_node_not_found
    }
  ],
  tainted: boolean(),
  truncated: boolean(),
  state_drift_warning: %{optional(module()) =&gt; [atom()]},
  warnings: [String.t() | {atom(), term()} | {:host_names, atom(), [term()]}]
}
```

Aggregated runner result.

# `site_result`

```elixir
@type site_result() :: %{
  id: String.t(),
  function: String.t() | nil,
  file: String.t(),
  line: pos_integer(),
  column: pos_integer(),
  mutator: atom(),
  original_ast: Macro.t(),
  mutated_ast: Macro.t(),
  status: :killed | :survived | :timeout | :error,
  tainted_predecessors: boolean(),
  warnings: [String.t() | {atom(), String.t()}],
  end_line: pos_integer() | nil,
  end_column: pos_integer() | nil,
  source_span: {non_neg_integer(), pos_integer()} | nil,
  source_line: pos_integer() | nil,
  source_text: String.t() | nil
}
```

Successful per-site result. `:compile_error` outcomes live in `compile_errors` instead.

# `run`

```elixir
@spec run(map()) :: {:ok, ok_result()} | {:error, error_reason(), map()}
```

Runs the mutation phase. See module doc for input shape.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
