All notable changes to mutagen_ex are recorded here.

The format follows Keep a Changelog; this project uses Semantic Versioning.

The released and Unreleased sections describe user-visible behavior. The engineering log is preserved as an appendix at the end of this file for traceability.

[Unreleased]

0.2.0 - 2026-11-20

First Hex release. Mutagen changes one expression at a time and runs the selected tests to show which changes they catch.

Breaking changes since the development snapshot

  • Reports use schema "2". Mutation IDs use a new scheme. Start a fresh comparison when moving from earlier output.
  • Exit 0 means the run produced a report, including partial runs and survivors. Exit 2 means the tool aborted. Check completeness in the report.
  • Use --json PATH for machine-readable output. Stdout is best effort because host code and the VM can write to it directly.

Features

  • Audit a module to rank its functions by kill rate. Use --summary PATH for a Markdown report and --site ID to rerun a finding.
  • Use --since REF to inspect changed code since the merge base. Mutagen selects relevant tests automatically. Use --escalate to try more tests.
  • Runs load the host test setup and report startup failures. Per-mutant deadlines and an optional run budget bound the mutation phase.
  • Execution probes distinguish confirmed misses from sites where coverage cannot tell whether an expression ran.

Known limits

  • A survivor may be equivalent to the original code. Review it before writing a test. Automatic selection can miss relevant tests.
  • Some expressions, including guards and patterns, cannot host execution probes. Mutagen reports uncertainty when it lacks execution evidence.
  • Run serially for reliable results. Parallel mutants share VM state and can produce incorrect verdicts.

0.1.0 (unpublished development snapshot, 2026-05-13)

Version 0.1.0 was never published on Hex or tagged.

Added

  • mix mutagen Mix task — the sole CLI entry point.
    • --scope <target> (required, repeatable): file path, module name, or Module.fun/arity.
    • --tests <target> (required, repeatable): test file path, file:line, or tag:<name>.
    • --timeout-ms <int> (default 5000): per-mutation wall-clock budget.
    • --seed <int> (default 0): ExUnit seed, propagated to every test-running phase.
    • --json <path>: redirect the final JSON document from stdout to a file.
  • Orchestration state machine for the run pipeline: CLI → scope → tests → AST cache → coverage → enumeration → baseline → mutation → reporter. Every phase is dispatch-table-driven for test substitution.
  • Single-process, serial-execution model (no worker pool, no shelled subprocess).
  • Coverage phase using :cover, scoped to in-scope modules, with the :cover_server torn down cleanly between runs.
  • Mutation enumeration restricted to covered lines, with content-addressed mutation IDs so they stay stable across mix format runs.
  • Mutators present in the snapshot: arith, compare, boolean, case_drop, else_removal, withblock_with_swap, withblock_else_removal, literal. (See Known limitations for the literal gap.)
  • Mutation runner with per-site sandboxed compile, ExUnit re-run, and module restoration. Per-site outcomes classify as :killed, :survived, :timeout, :error, or :compile_error.
  • JSON reporter emitting the v1 document shape (success and error variants), terminated by a single newline. Golden fixtures under test/mutagen_ex/golden/ serve as the schema-by-example.
  • Exit-code discipline: 0 on completion (even at 0.0 kill rate), non-zero on any abort. Every non-zero exit emits an error-JSON document.
  • Refusals (each with a stable reason: atom):
    • :missing_scope, :missing_tests, :invalid_timeout — bad input.
    • :flag_not_supported_in_v1 — explicit reject of --no-json.
    • :colon_syntax_unsupported — explicit reject of file.ex:Module.
    • :self_mutation_refused — refuses to mutate MutagenEx.* or Mix.Tasks.Mutagen.
    • :baseline_red — aborts before any mutation phase if the cited tests do not all pass against unmodified source.
  • mix help mutagen output with Synopsis, Flags, Examples, Constraints, Exit Codes, JSON Schema Pointer, and Known Caveats sections.
  • README.md with quick-start, flag reference, exit-code table, JSON-schema pointer, and known-limitations list.

Known limitations

Known in the development snapshot:

  • File-cited --tests (a bare _test.exs path) produced a filter that excluded every test.
  • The production mix task wired the mutation runner with an empty test module list.
  • A per-site timeout could leave the code server holding a module-load lock, occasionally corrupting the tail of a run.
  • The :case_drop mutator on a guarded base case classifies as killed (a CaseClauseError) rather than timeout.
  • The literal mutator never fired, because atomic literals were wrapped in a way the mutator did not recognise.

(Several of these were fixed in 0.2.0.)


Internal development log

  • Archive-installed CLI runtime self-heal. Fixed the archive adoption path where invoking mix mutagen from a host project without :mutagen_ex in deps, but with the task installed globally via mix archive.install, could crash with a MatchError at lib/mix/tasks/mutagen.ex:236 instead of emitting the CLI's structured error surface. The runtime preamble now gates repair on the Application.ensure_all_started(:mutagen_ex) failure tuple, calls Mix.Local.append_archives/0, retries, then defensively scans Mix.path_for(:archives) for an archive ebin containing mutagen_ex.app before a final retry. If the archive remains unrecoverable, the task emits error JSON with abort_reason: "runtime_load_failed" rather than leaking a traceback. Regression coverage lives in test/integration/archive_install_test.exs under tag :archive_integration; the spec records mutagen.cli.r16, scenarios mutagen.cli.s14c / mutagen.cli.s14d, and verification mutagen.cli.v11. The existing path: / Hex / git dependency adoption paths are preserved byte-for-byte because they succeed on the first runtime-start attempt and never enter the archive repair branch.

  • .25 epic capstone: bench harness, large-scope memory test, and measured speedup. The .25 AST/perf epic (S1–S6) is complete. This entry summarises what the epic shipped, the perf number the bench harness produced before vs. after the epic, and the byte- identity contract the refactor preserves.

    Bench harness — scripts/helper_scripts/bench_ast_perf.exs is no longer a skeleton: it drives the real Mix.Tasks.Mutagen.run/2 pipeline against the wrd25_200sites fixture (S1), captures wall-clock + :erlang.memory/0 snapshots + SHA-256 of the emitted NDJSON, supports --baseline <path> / --compare <path> for before/after scoring, and uses a stable tmp-ebin so the SHA is reproducible across invocations. Two minor wrd25 fixture asserts (mix4, chain2) were corrected so baseline runs green; the fixture's lib/ is unchanged.

    Measured speedup (wrd25_200sites, scope lib/arith_dense.ex, Elixir 1.19.5 / OTP 28):

    metricbefore (978a995, pre-.25 main merge)after (78b022f, post-.25.6)
    sites/run8787
    wall_ms2179.531314.00
    per_site_us25052.0515103.49

    Wall-clock speedup: 1.66×. Per-site speedup: 1.66×. This is below the epic's documented 2–4× target — see the follow-up note below.

    Byte-identity: the SHA-256 of the full NDJSON document differs between commits (state-drift warning text and "redefining module" paths embed run-time process state), but when those advisory diagnostics are normalised the documents are byte-identical: 3534443176dd9e2c673b21703085b1b02b2ddac0f2d6e3f7598542d5723df57a on both commits. The mutation results — site IDs, before/after source slices, killed/survived verdicts, kill_rate — are byte-for-byte the same; the .25 refactor changes timing, not outcomes. The full per-commit document SHAs (advisory: mix run scripts/helper_scripts/bench_ast_perf.exs reproduces them):

    • before: d878975d19112378f3598cb32c452c7c55b90b810156316335f13c9e5e8bee85
    • after: 46292518ccecca161161f278e3df58dc05d1031a47b9bff9ff7137af499b8b2a

    Speedup-shortfall triage — the measured 1.66× falls short of the spec's lower bound. Trace through the epic's deliverables:

    • S2 (Ast lift) removed duplicated helpers — wins compile time and code clarity, not per-site runtime.
    • S3 (AstCache categorised load) cut redundant File.read/1 for cited test files in the Baseline async-warning path — runs once per pipeline, sub-millisecond impact at this scope.
    • S4 (head-atom dispatch table) pre-filters mutators per node — the O(nodes × catalog) → O(nodes × applicable) win is real but proportional to catalog size; with 10 mutators it's a 2-3× win on the enumeration phase, which is a small slice of wall time vs. the per-site test-execution cost.
    • S5 (batched grouped-by-file prewalk) replaced per-site Macro.prewalk/2 with O(depth) path descent — the headline win. Its impact is O(sites × file_ast_size) saved, but on the wrd25 fixture the file AST is small (~40 lines/file), so the win is modest. On a real codebase with multi-thousand-line scope files the win compounds.
    • S6 (BeamCache binary-swap restore) replaced Code.compile_quoted/2 on the cached AST with :code.load_binary/3. This is per-site and should be a strong contributor; the bench shows it delivered.

    The bench fixture exposes hot AST machinery, but the per-site cost is dominated by the test-execution phase (one ExUnit.run/0 per mutation, with :cover instrumentation) — and that's untouched by .25. Mutators.normalize/1 (out of scope per the epic's Out of Scope) and the per-site ExUnit boot also dominate. A follow-up considered replacing the per-site ExUnit boot with a longer-lived test runner to close the gap to the 2–4× target.

    Large-scope memory test — new test/mutagen_ex/memory_test.exs (tagged :e2e_slow) generates a 1000-site synthetic fixture in System.tmp_dir!/0 at runtime (NOT committed to disk), drives the full pipeline against it with a 60s --budget-ms cap, and asserts the run completes without OOM. The assertion is deliberately weak per the epic's Out of Scope (intent) — it passes either on a clean completion (aborted: false) or a graceful budget-cap (truncated: true); a non-graceful abort (any reason outside budget_exceeded / too_many_sites) fails the test. Heap-size assertions are not pinned (brittle across BEAM versions).

    Epic summary — one line per feature shipped:

    • MutagenEx.Ast helper lift: canonical alias_to_module/1, find_module_body/2, node_line/1
    • AstCache.load/2 categorised input + Baseline cache consumer
    • MutagenEx.Mutators.Dispatch head-atom table + enumerator pre-filter
    • Batched grouped-by-file prewalk for the per-site AST swap
    • MutagenEx.BeamCache per-run ETS + binary-swap restore
    • Bench harness, memory test, this CHANGELOG entry
  • BeamCache per-run ETS + binary-swap restore. MutagenEx.MutationRunner.run/1 no longer restores via Code.compile_quoted/2 on the cached AST. Restore is now a binary swap via :code.load_binary/3 against a per-run MutagenEx.BeamCache snapshot: a :set, :public ETS table owned by run/1 itself (created at entry, deleted in after — no GenServer, no supervisor child, no cross-invocation staleness). A serial snapshot pre-pass runs BEFORE async_stream_nolink/4 dispatch and captures every scoped module's currently-loaded .beam via :code.get_object_code/1, closing the TOCTOU window two parallel workers would otherwise open. Snapshot order vs. cover instrumentation matters: the pre-pass runs AFTER :cover.compile_directory/1, so the cached binary IS the cover-instrumented binary and restore preserves coverage between sites. The new MutagenEx.Test.CodeServerFacade behaviour (with default impl MutagenEx.Test.CodeServer) is the test seam — mirrors the existing MutagenEx.Test.CompilerFacade shape exactly. The with_restore/4 wrapper's signature and external contract are preserved; only its internal restore call moved off Code.compile_quoted/2. MutagenEx.Application's supervisor child list is unchanged. Revised requirement mutagen.mutation_pipeline.r6 + new scenarios s16/s17 + verification stub v9. Two new decisions: mutagen.decision.per_run_beam_cache (ETS-via-cfg, not GenServer) and mutagen.decision.code_server_facade (testability seam).

  • Batched grouped-by-file prewalk for the per-site AST swap. MutagenEx.MutationRunner.run/1 now pre-computes a per-file path index once before the per-site loop begins (one Macro.prewalk/2 per distinct file in cfg.sites, regardless of how many sites that file carries). Each site's swap then descends along the cached path in O(depth) via apply_swap_at_path/3 instead of running a fresh Macro.prewalk/2 over the whole file AST per site. Path entries are keyed by site.id (content-addressed) so duplicate-position sites do not collide. Bare-literal sites (Literal mutator on bare integers/booleans; ResultTuple targeting bare booleans) carry no static AST coordinates and fall back to the existing ambient-threading walker (replace_bare_site/2); the legacy per-site Macro.prewalk is also retained as a defensive fallback. Byte-identity property pinned by test/mutagen_ex/mutation_runner_batched_test.exs: for every site, the mutated file AST produced by the batched path equals the file AST that an unconditional per-site Macro.prewalk/2 would have produced. Closes F16 (HIGH, F-PERF-02). New requirement mutagen.mutation_pipeline.r16 + scenarios s14 / s15 + verification stub v8.

Added

  • Head-atom dispatch table for the mutator catalog. New module MutagenEx.Mutators.Dispatch carries a static, order-preserving mapping from AST head atom (:+, :case, :with, …) to mutator list, plus an :any bucket for mutators that match non-3-tuple shapes (Literal for bare scalars / {:__block__, _, [v]} wrappers; ResultTuple for {:ok, _} / {:error, _} 2-tuples). MutagenEx.MutationEnumerator.try_mutators/6 consults Dispatch.mutators_for_node/1 to pre-filter the catalog before calling match?/1 per node — O(nodes × catalog) becomes O(nodes × applicable_mutators). No mutator behaviour change; the ten mutator modules are untouched. Per mutagen.decision.static_mutator_dispatch. The :dispatch_mode option on enumerate/4 (:head_atom default, :legacy for the equivalence test) is an internal test seam — it is NOT documented in the public API and NOT exposed via mix mutagen. New requirement mutagen.mutation_enumeration.r9 and equivalence test test/mutagen_ex/head_atom_dispatch_test.exs lock the correctness (same mutators consulted per node) and order- preservation (byte-identity / r1) properties.

Changed

  • AstCache.load/2 accepts categorised input. A new opts[:categories] map (e.g. categories: %{scope: scope_files, test: test_files}) lets callers partition the flat files list for diagnostic visibility without changing the cache entry shape. Entries remain {Macro.t(), String.t()} 2-tuples per mutagen.decision.ast_cache_facade_preserved; the Pipeline.AstCacheFacade @callback load/2 signature is preserved verbatim. Per-category counts are logged at debug level. The phase_ast_cache step of mix mutagen now loads scope files AND cited test files (test_filter.files) in one pass. New requirement mutagen.coverage.r9. Closes F18 / F40.
  • Baseline.detect_async_modules/1 consumes the AST cache when provided. When Baseline.run/1's input map carries :ast_cache, the async-warning path looks each cited test file up via AstCache.get/2 and consumes the cached {ast, _source} directly — no re-read of test files from disk. On cache miss the implementation falls back to File.read/1 + parse (pre-.25 behaviour) and logs the miss for diagnostics.
  • Shared AST helpers lifted into MutagenEx.Ast. The alias_to_module/1, find_module_body/2, and node_line/1 helpers — previously duplicated across MutagenEx.ScopeResolver, MutagenEx.MutationEnumerator, MutagenEx.MutationRunner, and MutagenEx.TestModuleDiscovery — now live in one canonical module (lib/mutagen_ex/ast.ex). Behaviour is byte-identical to the donors (pinned by test/mutagen_ex/ast_donor_equivalence_test.exs). Closes F21 / CF10. New subject mutagen.ast carries the contract; see .spec/specs/ast.spec.md.
  • ScopeResolver sorts the default `lib//.ex` wildcard result* before searching for module-shaped targets. Closes the F30 / CF7 determinism risk: Path.wildcard/1's order is file-system-dependent, so two hosts could otherwise pick a different match. New requirement mutagen.scope_resolution.r9.

Added

  • wrd25 bench fixture at scripts/helper_scripts/bench_fixtures/wrd25_200sites/ — a small self-contained Mix project (5 modules + colocated tests) used by the .25 AST-perf bench harness skeleton (scripts/helper_scripts/bench_ast_perf.exs, completed in S6) and by the determinism safety-net test (test/mutagen_ex/determinism_test.exs, re-targeted from the lane fixture).

  • Parallel mutation loop, NDJSON streaming, and progress feedback. The mutation runner now dispatches per-site work through Task.Supervisor.async_stream_nolink/4 under MutagenEx.TaskSup with :ordered: true, so results are collected in input order regardless of which task body finished first. Configurable via the new --max-concurrency <int> flag (default 1 for v1.0-equivalent serial execution; set explicitly to System.schedulers_online() to opt in). New requirement: mutagen.mutation_pipeline.r15.

    • :telemetry events at well-defined points: run.start/stop, coverage.start/stop, baseline.start/stop, enumeration.stop, and per-site site.start/stop. Superseded and removed (see the [Unreleased] Removed section): the producer-only event API and the :telemetry runtime dependency were dropped so the archive install is dependency-free; per-site observation now rides the runner's :on_site_completed callback.
    • --stream enables NDJSON-per-site emission via the new MutagenEx.JsonStreamer. Each line carries a "kind" discriminator ("start", "result", "compile_error", "end") and a per-site wire shape byte-equal to the equivalent entry in the aggregate document. New requirements: mutagen.json_schema.r10, mutagen.json_schema.r11.
    • --no-progress suppresses the human-readable per-site progress feed on stderr; the default is auto-on when stderr is a TTY, auto-off otherwise. See the new MutagenEx.Progress module.
    • New dependency: :telemetry ~> 1.0 (lightweight, no transitive deps). The runner emits events through the standard :telemetry.execute/3 and :telemetry.span/3 surfaces. The runtime is now dependency-free.

Security

  • Bound stderr / exception / Macro.to_string output flowing into the JSON report; added opt-in :redact config knob. Stderr captured during per-mutation runs, exception messages from compile/restore paths, and Elixir source slices in compiler diagnostics flowed verbatim into mutation.results[].warnings[], mutation.compile_errors[].message, and abort-detail message fields. Combined with the lax --json <path> write, secrets archived in those reports became file-system-resident. Fixed by:
    • A new MutagenEx.JsonReporter.Sanitizer module truncates every free-form text field at a 4 KiB cap, appending the literal marker ... <N bytes truncated> when truncation occurs. Truncation splits on a codepoint boundary so the emitted string is always valid UTF-8. New requirement: mutagen.json_schema.r10.
    • Opt-in :redact application config (a list of %Regex{} or binary regex sources, read via Application.get_env(:mutagen_ex, :redact, [])) — each match in any sanitized field is replaced with the literal [REDACTED]. Redaction runs BEFORE truncation so secrets near or past the 4 KiB cap are still replaced rather than silently dropped. Default :redact is [] (no-op). New requirement: mutagen.json_schema.r11.
    • Wired into all sanitization choke points: MutagenEx.AstCache file-read + parse error messages; MutagenEx.Baseline test-file load + ExUnit.run failure messages; MutagenEx.MutationRunner compile-error / restore-failure / unrecoverable-restore-failure messages and per-result warnings (via compose_warnings/1).

Performance

  • Macro.to_string/1 computed once per mutation result. The Mix task's render_result/1 (lib/mix/tasks/mutagen.ex) called Macro.to_string(r.original_ast) twice per result — once for before and once for before_source — wasting a full AST-to-string walk on every reported mutation. The render path now computes Macro.to_string(r.original_ast) exactly once and aliases the resulting binary into both before and before_source. Reference identity (:erts_debug.same/2) is the falsifiability check. Verbatim source-slice extraction for before_source (per the contract documented in lib/mutagen_ex/ast_cache.ex) is deferred to a follow-up since it requires extending the Site struct to carry {end_line, end_column} metadata. New requirement: mutagen.json_schema.r12.

  • Bound atom creation on CLI input. Three call sites converted attacker- or typo-controlled strings to atoms with no upper bound, making CI loops like mix mutagen --tests tag:$(uuidgen) a fast atom-table sink (atoms are not GC'd; the default cap is ~1M). Fixed by:

    • MutagenEx.CLI now applies a tag:NAME charset gate at the front door (~r/\A[a-z][a-z_0-9]{0,63}\z/); inputs outside the charset return {:error, :invalid_tag_name, _} before any test resolution runs. New requirement: mutagen.cli.r11.
    • MutagenEx.TestSelector.resolve/2 for tag:NAME no longer calls String.to_atom(name). Instead it walks the test corpus and compares the user's NAME string against Atom.to_string/1 of each @tag :ATOM literal found in the parsed AST; the matched AST-derived atom flows into include:. New requirement: mutagen.test_selection.r7.
    • MutagenEx.ScopeResolver.resolve/2 for Module.Name and Module.Name.fun/arity targets no longer calls String.to_atom on user input. Module matching uses canonical-string comparison ("Elixir.Foo.Bar" vs. Atom.to_string/1 of each AST defmodule atom); function-name matching uses string comparison against AST-derived def-head atoms. The matched module atom comes from the AST. details.module on :module_not_found is now the canonical string (e.g. "Elixir.Nope"); details.function on :function_not_found is the user's string segment. New requirement: mutagen.scope_resolution.r8.

Changed

Fixed

  • Scenario 7 (:ecto_user_scenario) un-skipped. The end-to-end Scenario 7 @tag :skip in test/mutagen_ex/end_to_end_test.exs was long blamed on a :cover + Ecto-style DSL interaction. The coverage spike (direct reproduction in scripts/helper_scripts/spike_19_repro.exs) showed every macro-injected callback — __schema_kind__/0, field/2-generated name/0 and age/0, the birthday/1 arithmetic helper, and the persisted :lane_schema_kind attribute — survives :cover.compile_beam/1 -> :cover.stop/0 -> :code.purge/1 -> :code.load_file/1 byte-for-byte. The actual baseline-red came from one assertion in test/fixtures/lane_project/test/lane_fixture/ecto_user_test.exs:30 (assert :registered in Keyword.get_values(attrs, :lane_schema_kind)) that fails because persist: true attributes serialise their value wrapped in a list — Keyword.get_values/2 returns [[:registered]], not [:registered], and :registered in [[:registered]] is false. The test fails identically with or without :cover. The assertion was rewritten to flatten the values plus an explicit Keyword.fetch!(attrs, :lane_schema_kind) == [:registered] check, Scenario 7's @tag :skip was removed, and README "Known limitations" item 5 was marked resolved. The Spike-I bytecode-identical-restore invariant is now exercised end-to-end against the hand-rolled DSL.

Security

  • --json <path> is canonicalised before any mutation runs. Closes F7 (HIGH, Security reviewer H2): mix mutagen --json <path> previously accepted any binary, which combined with the in-process compile-and- execute pipeline (mutagen.decision.in_process_pipeline) was an arbitrary-file-write primitive — a malicious mutated test could redirect the report into /etc/, ~/.ssh/, or any symlinked path. Two layers of check now run before any mutation phase:

    1. Parse-time pure-string check refuses paths with NUL bytes or any .. segment (abort_reason: "unsafe_json_path").
    2. Filesystem canonicalisation expands every component through File.read_link/1 and refuses paths whose fully-resolved target escapes the project root (also abort_reason: "unsafe_json_path"). CI integrations that need to write outside the project root pass --unsafe-json-outside-project explicitly; that flag emits a one-shot stderr warning naming the resolved target. New invariant: mutagen.cli.r10.
  • Resource caps on input and output volume. Closes F28 / CF11 (MEDIUM consensus from Security M1 + Performance F-PERF-07/12): the CLI previously accepted unlimited --scope / --tests repetition, the enumerator materialised every site in memory before the runner started, and there was no aggregate wall-clock budget — three avenues for runaway resource use.

    • --scope and --tests each cap at 100 occurrences; the 101st is refused at parse time with abort_reason: "too_many_targets".
    • --max-sites caps enumerated mutation sites (default 10_000). Exceeding the cap aborts the pipeline with abort_reason: "too_many_sites" BEFORE the mutation runner starts.
    • --budget-ms is an optional aggregate wall-clock budget for the mutation phase. When the budget elapses the runner stops dispatching new sites and emits a truncated: true partial JSON report (aborted: false; the per-site --timeout-ms still bounds the in-flight site). New invariants: mutagen.cli.r12, mutagen.cli.r13, mutagen.mutation_enumeration.r7.

Added

  • MutagenEx.JsonPath — single home for the --json path-safety contract. validate_literal/1 is the pure-string check the CLI parser calls at parse time; canonicalize/2 is the filesystem-aware check the mix task calls before any mutation phase. The project root is resolved through its own symlinks (handles macOS /var -> /private/var); the inside-root comparison uses the canonical form.

  • --unsafe-json-outside-project flag on mix mutagen. Boolean opt-in that bypasses the inside-root check while still resolving symlinks. Lands on Config.unsafe_json_outside_project.

  • MutagenEx.Application — a one-for-one supervisor (MutagenEx.Supervisor) whose only child is a named Task.Supervisor registered as MutagenEx.TaskSup. Declared via mod: {MutagenEx.Application, []} in mix.exs, so the supervision tree starts whenever :mutagen_ex boots — for both the mix mutagen CLI path and library callers depending on :mutagen_ex directly. New invariant: mutagen.mutation_pipeline.r13.

  • test/mutagen_ex/supervision_test.exs exercising start_link / terminate cycles, recursive-kill propagation across an OTP-supervised descendant subtree and an untrapped linked grandchild, and concurrent-caller rejection of CoverageRunner.run/1. Covers mutagen.mutation_pipeline.r13, mutagen.mutation_pipeline.r14, mutagen.coverage.r1, and mutagen.coverage.r8.

  • .spec/decisions/supervision_tree.md documenting the Application + named Task.Supervisor choice, the singleton-ownership contract for :cover_server / ExUnit.Server, and the v2 won't-haves (out-of-process workers, :cover.start/0 race arbiter).

  • test/support/disk_snapshot_helper.exs — disk-snapshot diffing helper used by the r11 / r7 "no disk writes" tests. Captures byte-identity across lib/**, _build/**/*.{beam,app}, cover/**, host project config (mix.exs, mix.lock, .formatter.exs), and mutagen_ex_- attributable entries under System.tmp_dir!().

Changed

  • Mix.Tasks.Mutagen.phase_scope/3 now accumulates per-target scope records in O(n) overall instead of O(n²). The previous acc ++ records pattern was quadratic in the cumulative record count — a measurable cost on broad --scope workloads. The new accumulator prepends chunks and flattens once via :lists.append(:lists.reverse(acc)). Closes F-PERF-12 (the half-overlap with F20). Order of records is preserved; a new regression test (test/mutagen_ex/mix_task_phase_scope_test.exs) asserts both ordering and a 2_000 ms ceiling for 10_000 records across 2_000 targets.

  • MutationRunner.safe_compile_quoted/3 and MutationLoop.capture_stderr/2 now use ExUnit.CaptureIO.with_io/3 — which returns {closure_result, captured_io} directly — instead of capture_io/2 paired with a make_ref/Process.put/Process.get smuggle to extract the closure's return value. Removes the dependency on the (undocumented) fact that capture_io/2 runs its closure in the calling process and deletes the per-call process-dictionary lifetime bookkeeping. Spec mutagen.mutation_pipeline.r9 updated to name with_io/3; behavior is byte-identical (same stderr capture, same suppression, same warning attachment). The :capture_io seam used by tests now requires with_io/3 (test stubs CaptureIoStub and RaisingCaptureIO updated in lock-step).

  • The r11 disk-write test in mutation_runner_test.exs and the r7 disk-write test in coverage_runner_test.exs now assert byte-identity across lib/, _build/, cover/, host project config, and mutagen_ex_-attributable tmp entries — not just lib/**/*.ex. Closes Testing-reviewer F13: the original tests would have shipped green if the runner accidentally rewrote mix.exs, dropped artifacts under _build/, or wrote a coverage report to cover/. The mutagen.mutation_pipeline.r11 and mutagen.coverage.r7 spec statements were updated to name the broader surface explicitly, with an allowed-write list of NONE.

  • MutationRunner.run_one_site/3 now routes the loaded-mutation window through a new with_restore/4 lifecycle helper that mirrors MutagenEx.CoverageRunner.with_cover_lifecycle/2. A raise, throw, or exit inside the window (e.g. a misbehaving :capture_io seam) now triggers restore before the exception re-propagates. The original {kind, value, stacktrace} is preserved via reraise/2 / :erlang.raise/3; restore failure during propagation is swallowed inside safe_restore/3 and never masks the original cause. New invariant: mutagen.mutation_pipeline.r12.

  • The :compile_error branch now surfaces defensive-restore failure as :unrecoverable_restore_failure (with both the restore failure and the original :compile_error message in details.message) instead of silently discarding it via _ = restore(...). Per mutagen.mutation_pipeline.r6.

  • MutationLoop.run/1 spawns its per-site task via Task.Supervisor.async_nolink(MutagenEx.TaskSup, ...) instead of Task.async/1. The two-phase cancel keeps Task.shutdown(task, cancel_grace_ms) for the mailbox-drain window, then escalates to Task.Supervisor.terminate_child(MutagenEx.TaskSup, task.pid) — which propagates Process.exit(_, :shutdown) through the task's link tree, reaping untrapped linked grandchildren and OTP-supervised descendant subtrees synchronously with respect to the direct task pid and asynchronously for the descendant fan-out. A Process.demonitor(task.ref, [:flush]) follows to prevent stale :DOWN messages accumulating in the runner's mailbox across timeout sites. The .13 :code.purge/1 post-timeout settle pass is retained on top. Per mutagen.mutation_pipeline.r4 / mutagen.mutation_pipeline.r14.

  • CoverageRunner.run/1's :cover_already_running rejection message now names MutagenEx.TaskSup as the documented singleton owner of :cover_server and ExUnit.Server during a MutagenEx mutation cycle, and points readers at .spec/decisions/supervision_tree.md. Per mutagen.coverage.r1 / mutagen.coverage.r8.

  • The C1/C2 integration spikes under test/mutagen_ex/integration/ are now tagged :spike and excluded from the default mix test run. test/test_helper.exs calls ExUnit.start(exclude: [:e2e_slow, :spike]). The spikes remain the gating decision artifact for the in-process pipeline (per mutagen.decision.in_process_pipeline) and are runnable on demand via mix test --only spike. Default mix test wall-clock drops from ~24s to ~1s; the smoke gate is no longer dominated by ~500 cover lifecycles every run.

  • The C2 spike's iteration count is now controlled by the MUTAGEN_SPIKE_ITERATIONS env var (default 10, original gating value 100). The invariants — failures == 0, process growth ≤ 50, memory growth ≤ 1.5× — hold at any positive N; the count is a cycle-time knob, not a contract. C1's 100-iteration count is unchanged because its loop count IS the contract (restore fidelity measured across cycles).

  • README.md documents the :spike opt-in and the MUTAGEN_SPIKE_ITERATIONS knob under a new "Test suite gates" subsection.

Notes

  • User-visible cancellation latency per timeout-classified site is dominated by cancel_grace_ms (100 ms by default). The supervisor's :shutdown_timeout (5_000 ms) bounds only a hypothetical scenario in which the per-site task itself traps :shutdown; in practice the task dies on the signal in microseconds and grandchild teardown is asynchronous afterwards.
  • Closes F2-arch for the common grandchild classes (untrapped linked processes, OTP-supervised subtrees). Hand-rolled trap-exit'd GenServers that swallow {:EXIT, _, :shutdown} info messages remain out of reach; the r7 snapshot-delta machinery continues to detect these as advisory growth signals.

Removed

  • lib/mutagen_ex.ex and test/mutagen_ex_test.exs (mix new placeholders) are deleted. The MutagenEx namespace is owned by its submodules; no top-level module body is necessary.
  • The README's .13 caveat ("re-run if the tail of the run looks wrong" after a timeout-classified mutation) is removed. The .18 supervised teardown + :code.purge settle pass + recursive shutdown through the link tree close the underlying Code.Server hang condition.