evilution 1.2.0 → 1.4.0

data/README.md

@@ -21,9 +21,15 @@ Add to `Gemfile`:
 gem "evilution", group: :test
 ```
 
-Then: `bundle install`
+Then:
+```shell
+bundle install
+```
 
-Or standalone: `gem install evilution`
+Or standalone:
+```shell
+gem install evilution
+```
 
 Requires `prism >= 1.5, < 2`. Older Rails apps (e.g. Rails 7.1 pins `prism 0.19`) must upgrade prism — the gemspec constraint forces bundler to resolve a compatible 1.x version. If your app pins `prism 2.x`, bundler will reject the install until evilution widens its upper bound.
 
@@ -88,7 +94,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `init`               | Generate `.evilution.yml` config file               |         |
 | `version`            | Print version string                                |         |
 | `subjects [files]`   | List mutation subjects with locations and counts    |         |
-| `tests list [files]` | List spec files mapped to source files              |         |
+| `tests list [files]` | List the spec files `run` would use for each source (layout, `spec_mappings`, `spec_pattern`) |         |
 | `session list`       | List saved session results                          |         |
 | `session show FILE`  | Display detailed session results                    |         |
 | `session diff A B`   | Compare two sessions (fixed/new/persistent)         |         |
@@ -103,7 +109,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 |------------------------------|---------|--------------|---------------------------------------------------|
 | `-t`, `--timeout N`          | Integer | 30           | Per-mutation timeout in seconds.                   |
 | `-f`, `--format FORMAT`      | String  | `text`       | Output format: `text`, `json`, or `html`.         |
-| `--target EXPR`              | String  | _(none)_     | Only mutate matching methods. Supports method name (`Foo::Bar#calculate`), class (`Foo`), namespace wildcards (`Foo::Bar*`), method-type selectors (`Foo#`, `Foo.`), descendants (`descendants:Foo`), and source globs (`source:lib/**/*.rb`). |
+| `--target EXPR`              | String  | _(none)_     | Only mutate matching subjects. Supports method name (`Foo::Bar#calculate`), class (`Foo`, which also matches a value-object constant named `Foo`), namespace wildcards (`Foo::Bar*`), method-type selectors (`Foo#`, `Foo.`), descendants (`descendants:Foo`), and source globs (`source:lib/**/*.rb`). |
 | `--output FILE`              | String  | _(stdout)_   | Write the report to FILE instead of stdout. Useful when a preloaded spec helper writes to stdout on exit. |
 | `--min-score FLOAT`          | Float   | 0.0          | Minimum mutation score (0.0–1.0) to pass.         |
 | `--spec FILES`               | Array   | _(none)_     | Spec files to run (comma-separated). Defaults to auto-detection via `SpecResolver`, which also resolves non-mirrored (`spec/unit`, `test/unit`), dir-grouped (`test/unit/<class>/*_test.rb`), and flat `test_`-prefixed (`test/test_connection_pool_timed_stack.rb`) layouts. |
@@ -113,7 +119,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `--example-targeting MODE`   | String  | `lexical`    | How targeting picks examples: `lexical` (name-grep example bodies for the mutated method/class), `coverage` (run only the examples that actually execute the mutated line, from a cached line-coverage map), or `full_file` (run all resolved examples). |
 | `--example-targeting-fallback MODE` | String | `full_file` | Behavior when no example matches: `full_file` (run the whole spec file) or `unresolved` (skip the mutation as `:unresolved`). |
 | `-j`, `--jobs N`             | Integer | 1            | Number of parallel workers. Uses demand-driven work distribution with pipe-based IPC. |
-| `--no-baseline`              | Boolean | _(enabled)_  | Skip baseline test suite check. By default, a baseline run detects pre-existing failures and marks those mutations as `neutral`. |
+| `--no-baseline`              | Boolean | _(enabled)_  | Skip baseline test suite check. By default, a baseline run detects pre-existing failures, so that a mutation whose tests fail only on those is recorded `neutral` rather than killed. |
 | `--[no-]canary`              | Boolean | _(enabled)_  | Run a proof-of-life synthetic mutation at session start; abort the run if the pipeline misreports it. Catches misconfigured isolation, broken autoload, and reporter-plugin eviction before any real score is produced. Pass `--no-canary` to skip (e.g. CI speed, or when the canary itself is the thing under test). |
 | `--fail-fast [N]`            | Integer | _(none)_     | Stop after N surviving mutants (default 1 if no value given). |
 | `-v`, `--verbose`            | Boolean | false        | Verbose output with RSS memory and GC stats per phase and per mutation; also prints error class, message, and first 5 backtrace lines for errored mutations. |
@@ -129,13 +135,14 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `--isolation MODE`           | String  | `auto`       | Isolation strategy: `auto`, `fork`, or `in_process`. `auto` selects `fork` for Rails projects and packaged gems (`*.gemspec`), `in_process` otherwise. See [docs/isolation.md](docs/isolation.md). |
 | `--preload FILE`             | String  | _(auto)_     | File to require in parent before forking workers. Auto-detect chain for Rails projects: `spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb`. For non-Rails gems: `spec/spec_helper.rb` → `test/test_helper.rb` → `test/helper.rb`, falling back to the gem entry `lib/<gem>.rb` (with a warning naming the searched paths). Pass `--no-preload` to opt out. |
 | `--no-preload`               | Boolean | _(enabled)_  | Disable parent-process preload.                     |
+| `--warmup NAME`              | String  | `none`       | After preload, warm lazily-initialised framework state once in the parent: `none` or `rails`. See [Warming up Rails before forking](#warming-up-rails-before-forking). |
 | `--skip-heredoc-literals`    | Boolean | false        | Skip all string literal mutations inside heredocs.  |
 | `--show-disabled`            | Boolean | false        | Report mutations skipped by `# evilution:disable` comments. |
 | `--fallback-full-suite`      | Boolean | false        | When no matching spec/test resolves for a mutation, run the whole test suite instead of marking it `:unresolved` and skipping. |
 | `--related-specs-heuristic`  | Boolean | false        | When a mutation removes an `includes(...)` call, also run matching specs from `spec/{requests,integration,features,system}` (Rails-style domain match on the source file's basename). Trades extra spec runs for higher kill rate on ORM mutations. |
 | `--baseline-session PATH`    | String  | _(none)_     | Saved session file for HTML report comparison.     |
 | `-e CODE`, `--eval CODE`     | String  | _(none)_     | Inline Ruby code for `util mutation` command.      |
-| `--profile NAME`             | String  | `default`    | Operator profile: `default` or `strict`. `strict` adds aggressive truthiness mutators (e.g. replaces `x.predicate?` with `nil`) intended for pre-merge audits. |
+| `--profile NAME`             | String  | `default`    | Operator profile: `default` or `strict`. `strict` adds aggressive mutators (e.g. replaces `x.predicate?` with `nil`, or appends `rescue nil` to a raising call) intended for pre-merge audits. |
 | `--strict`                   | Boolean | false        | Shortcut for `--profile=strict`.                    |
 
 ### Options (for `session` subcommands)
@@ -158,8 +165,14 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 
 Two profiles ship out of the box:
 
-- **`default`** — the 88 stable operators registered in `Mutator::Registry.default`. Suitable for everyday CI runs; balances coverage signal against survivor noise.
-- **`strict`** — adds extra truthiness mutators on top of `default`. Currently `PredicateToNil` (replaces every `x.predicate?` call with `nil` to surface tests that only assert truthiness rather than exact return values). Use for pre-merge audits where you want maximum sensitivity at the cost of more survivors.
+- **`default`** — the 136 stable operators registered in `Mutator::Registry.default`. Suitable for everyday CI runs; balances coverage signal against survivor noise.
+- **`strict`** — adds extra aggressive mutators on top of `default`:
+  - `PredicateToNil` replaces every `x.predicate?` call with `nil` to surface tests that only assert truthiness rather than exact return values.
+  - `ExceptionSwallow` appends `rescue nil` to a statement that raises by convention — a bang method, `fetch` without a default, `Integer` / `Float` / `Rational` — to surface tests that never make it fail and check the error comes out (`record.save!` -> `record.save! rescue nil`). It skips Ruby core in-place bangs (`uniq!`, `sort_by!`, …), `exit!`, statements already under a rescue, and `raise`; project bangs that mutate rather than raise will still show up as survivors.
+
+  - `StatementReorder` swaps two adjacent commands (`charge(card); send_receipt(user)` -> `send_receipt(user); charge(card)`) to surface side effects whose order is never asserted. It only swaps statements that both act — call a method, append, write an index, yield, call super — and leaves alone pairs that share a variable, contain control flow or a heredoc, involve a local or instance variable assignment, write different literal keys of the same receiver, or move the last statement of a body. Expect survivors where the order only shows up in help text or in the order a list is built.
+
+  Use for pre-merge audits where you want maximum sensitivity at the cost of more survivors.
 
 Set via `--profile=strict`, the `--strict` shortcut, or `profile: strict` in `.evilution.yml`.
 
@@ -202,6 +215,7 @@ schema_version: 1            # opts into strict validation (rejects unknown keys
 # isolation: auto          # auto | fork | in_process (auto selects fork for Rails + gems)
 # canary: true             # proof-of-life synthetic mutation at session start (false to skip)
 # preload: null            # path to preload before forking; false to disable; auto-detects for Rails + gems
+# warmup: none            # rails: warm I18n, routes, assets and templates once after preload (fork isolation)
 # skip_heredoc_literals: false  # skip string literal mutations inside heredocs (recommended for Rails: heredoc SQL/templates rarely have test coverage)
 # show_disabled: false     # report mutations skipped by disable comments
 # baseline_session: null   # path to session file for HTML comparison
@@ -246,7 +260,7 @@ All keys recognised under `schema_version: 1`:
 | `quiet`                      | Boolean                       | `false`                                | Suppress output.                                                                                                                         |
 | `jobs`                       | Integer                       | `1`                                    | Number of parallel workers.                                                                                                              |
 | `fail_fast`                  | Integer / null                | `null`                                 | Stop after N surviving mutants. `null` = disabled.                                                                                       |
-| `baseline`                   | Boolean                       | `true`                                 | Run baseline test suite to detect pre-existing failures (marked `:neutral`).                                                             |
+| `baseline`                   | Boolean                       | `true`                                 | Run baseline test suite to detect pre-existing failures (a mutation failing only on those is `:neutral`).                                                          |
 | `isolation`                  | String                        | `auto`                                 | Isolation strategy: `auto`, `fork`, `in_process`. `auto` selects `fork` for Rails projects and packaged gems (`*.gemspec`).              |
 | `incremental`                | Boolean                       | `false`                                | Cache killed/timeout results across runs.                                                                                                |
 | `suggest_tests`              | Boolean                       | `false`                                | Generate concrete test code in survivor suggestions (matches `integration`).                                                             |
@@ -261,6 +275,7 @@ All keys recognised under `schema_version: 1`:
 | `related_specs_heuristic`    | Boolean                       | `false`                                | Append related request/integration/feature/system specs for `includes(...)` mutations.                                                   |
 | `fallback_to_full_suite`     | Boolean                       | `false`                                | When no matching spec resolves, run the entire suite instead of marking the mutation `:unresolved`.                                      |
 | `preload`                    | String / Boolean / null       | `null`                                 | File to preload in parent before forking. `false` to disable. `null` to auto-detect for Rails projects and packaged gems.                |
+| `warmup`                     | String                        | `none`                                 | `rails` warms lazily-initialised Rails state once after preload so forks do not each pay it. `none` / `false` to skip.                  |
 | `spec_mappings`              | Hash&lt;String, String/Array&gt; | `{}`                                | Custom mapping from source path to spec path(s).                                                                                         |
 | `spec_pattern`               | String / null                 | `null`                                 | Glob restricting resolved spec candidates.                                                                                               |
 | `example_targeting`          | Boolean                       | `true`                                 | Per-mutation example-level targeting.                                                                                                    |
@@ -312,11 +327,14 @@ Schema:
     "survived": "integer — mutations NOT detected (test passed = gap in coverage)",
     "timed_out": "integer — mutations that exceeded timeout",
     "errors": "integer   — mutations that caused unexpected errors",
-    "neutral": "integer  — mutations whose tests already failed before mutation (baseline failure)",
+    "neutral": "integer  — mutations with no verdict: their tests failed only on examples that were already failing in the baseline, or the test process crashed on infrastructure",
     "equivalent": "integer — mutations proven to have identical behavior to the original",
     "unresolved": "integer — mutations where no spec file resolved (coverage gap, not a failure)",
     "unresolved_target_files": "array of strings (optional) — target files that resolved to no spec at all; present only when non-empty, and the run fails when it is",
     "infra_retried": "integer (optional) — mutations a parallel pass could not judge because the test process crashed on infrastructure, re-run serially afterwards; present only when non-zero",
+    "uncovered_code": "array (optional) — targeted lines that hold code outside every subject, so no mutation was generated for them: [{ file, lines: ['2-4', '9'] }]; checked for a line range as given, and for a whole file only when it has no subject at all; present only when non-empty",
+    "baseline_neutralized": "integer (optional) — kills not counted because only examples already failing in the baseline failed; those mutations are recorded neutral; present only when non-zero",
+    "baseline_failures": "array (optional) — one entry per spec file that was red in the baseline: { spec_file, error: string|null — what stopped the file outside any example (load error, runner exception, timeout, a baseline process that died), failing_examples: integer — every failing example, examples: [{ id, description, message }] — the first few of them }; present only when non-empty",
     "unparseable": "integer — mutations whose mutated source did not parse (short-circuited, never executed)",
     "score": "float      — killed / (total - errors - neutral - equivalent - unresolved - unparseable), range 0.0-1.0, rounded to 4 decimals",
     "duration": "float   — total wall-clock seconds, rounded to 4 decimals",
@@ -418,7 +436,7 @@ Compatibility policy for the `1.x` gem line:
 | `survived`   | No test failed — gap in coverage                                       | denominator only  |
 | `timeout`    | Test run exceeded `--timeout` — treated like survived for scoring     | denominator only  |
 | `error`      | Mutation caused an unexpected error (syntax error, boot failure, etc.) | excluded from denominator |
-| `neutral`    | Baseline tests already failed before mutation, or the test process crashed on infrastructure (DB lock, statement timeout) rather than on the mutation. Every neutral records which of the two, and the report groups them by it | excluded          |
+| `neutral`    | No verdict: the tests failed only on examples that were already failing in the baseline, or the test process crashed on infrastructure (DB lock, statement timeout) rather than on the mutation. Every neutral records which of the two, and the report groups them by it | excluded          |
 | `equivalent` | Mutation is provably identical to the original (e.g. no-op replacement) | excluded          |
 | `unresolved` | No spec file resolved for the mutated source — **coverage gap, not a failure**. Use `--fallback-full-suite` to run the full suite instead. | excluded |
 | `unparseable` | Mutated source failed to parse (e.g. dangling heredoc opener after `method_body_replacement`). Short-circuited — never executed. | excluded |
@@ -450,10 +468,15 @@ On evilution's own `lib/evilution/reporter/json/subjects.rb` this moved the repo
 
 ### Neutral Mutations
 
-Neutral covers two unrelated situations that want opposite responses: a spec file that was already red before any mutation ran, and a test process that died on infrastructure rather than on the mutation. Each neutral records which, and the report groups by it, naming the spec or the error class (GH #1606):
+Neutral means the run has no verdict on a mutation. It covers two unrelated situations that want opposite responses, and each neutral records which; the report groups by it, naming the spec or the error class (GH #1606):
+
+- **The tests failed, but only on examples that were already failing before any mutation ran.** Such an example fails whatever the mutation is, so its failure is not a kill. Nothing that was passing caught the mutation either, but the red example might have, once fixed.
+- **The test process died on infrastructure** rather than on the mutation.
 
 ```
 Score: 100.00% (10/10 verified of 17 mutations, 7 neutral)
+! 7 kills not counted for spec/tally_spec.rb: only examples already failing in the baseline failed, so those mutations have no verdict.
+    ./spec/tally_spec.rb[1:3] Tally adds -- NameError: undefined local variable or method 'tally'
 
 Neutral mutations (7, not verified):
   baseline already failing (spec/tally_spec.rb):
@@ -461,9 +484,17 @@ Neutral mutations (7, not verified):
     integer_literal: lib/tally.rb:9
 ```
 
-The score line names the remainder whenever the run left mutations out of the denominator, because full marks over a fraction of a run otherwise reads as a verdict on all of it. A clean run still prints the plain `Score: 100.00% (17/17)`.
+The score line names the remainder whenever the run left mutations out of the denominator, because full marks over a fraction of a run otherwise reads as a verdict on all of it. A clean run still prints the plain `Score: 100.00% (17/17)`. The line under it says how many kills were not counted, for which spec file, and why the baseline was red for it — the failing examples with their first error line, or the error that stopped the file before any example ran. The same detail is printed to stderr once per red spec file as soon as the baseline finishes, and is in JSON output as `summary.baseline_neutralized` and `summary.baseline_failures`.
+
+What a red baseline does not do:
 
-Those seven mutations were survivors until the spec file went red — a neutral of this kind is a hidden coverage gap, not a clean bill of health. JSON output carries `neutral_reason` as `{ kind, detail }` on neutral entries that have one; `detail` is null where no single spec can be named (an explicit `--spec` run), and the field is absent on a result recorded without a reason, which the text report shows as `reason not recorded`.
+- **It does not touch a kill in which something that was passing failed too.** That is a kill like any other.
+- **It does not touch survivors.** A mutation whose tests passed is a survivor whatever the baseline did — including when the baseline's failure did not happen again in the mutation run (a flaky example, a failure of the baseline process itself). Earlier versions recorded every survivor covered by a red spec file as neutral, which hid exactly those gaps.
+- **It does not second-guess a baseline failure with no failing example to name** — a file that did not load, a timeout, a baseline process that died. A mutation run that hits the same problem reports `error` or `timeout` itself.
+
+Recognising an already-failing example needs the test framework to name the examples that failed, the same way in the baseline and in a mutation run. RSpec examples are named by spec file and position, Minitest tests as `Class#test`, Test::Unit tests as `test(Class)`. Two Minitest test classes without a name that share a test method name cannot be told apart.
+
+JSON output carries `neutral_reason` as `{ kind, detail }` on neutral entries that have one; `detail` is null where no single spec can be named (an explicit `--spec` run), and the field is absent on a result recorded without a reason, which the text report shows as `reason not recorded`.
 
 ### Per-Subject Scores
 
@@ -481,7 +512,7 @@ Subjects needing attention (2 subjects in 1 file):
 
 A subject is listed when something survived, or when nothing reached it at all — zero verdicts, every mutation unresolved or neutral. Fully-killed subjects are not listed, so the section stays actionable. JSON output carries every subject under `subjects`, whether or not it needs attention, so a CI step can assert on `reached` or on a per-subject `score`.
 
-## Mutation Operators (88 total)
+## Mutation Operators (136 total)
 
 Each operator name is stable and appears in JSON output under `survived[].operator`.
 
@@ -508,12 +539,57 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `method_body_replacement` | Replace entire method body | Method body -> `nil`, `self`, `super` |
 | `negation_insertion` | Negate predicate methods | `x.empty?` -> `!x.empty?` |
 | `return_value_removal` | Strip return values | `return x` -> `return` |
+| `return_keyword_removal` | Drop the `return` keyword and keep its value, so control flow continues past a guard clause or early return (several values become an array; skips returns in tail position, where the value is the result anyway, and bare `return`) | `return :neg if x.negative?` -> `:neg if x.negative?` |
 | `collection_replacement` | Swap collection methods | `map` -> `each`, `select` <-> `reject` |
 | `collection_return` | Replace collection return values | `return [1]` -> `return []` |
 | `scalar_return` | Replace scalar return values | `return 42` -> `return 0` |
 | `method_call_removal` | Remove method calls, keep receiver | `obj.foo(x)` -> `obj` |
 | `argument_removal` | Remove individual arguments | `foo(a, b)` -> `foo(b)` |
 | `argument_nil_substitution` | Replace arguments with `nil` | `foo(a, b)` -> `foo(nil, b)` |
+| `call_to_nil` | Replace a method call with `nil` (skips void statements, receivers of another call, and attribute or index writes) | `user.name` -> `nil` |
+| `safe_navigation_removal` | Replace `&.` with a plain call (skips `self` and literal receivers) | `user&.name` -> `user.name` |
+| `attribute_write_to_read` | Replace an attribute or index write with the matching read (skips writes `statement_deletion` already removes) | `a.foo = b` -> `a.foo`, `a[i] = b` -> `a[i]` |
+| `argument_propagation` | Replace a call with its only positional argument (skips operator methods, attribute writes and void statements) | `normalize(value)` -> `value` |
+| `argument_list_removal` | Drop a call's whole argument list, keeping any block (skips operator methods and attribute writes) | `foo(a, b)` -> `foo`, `foo(a, &b)` -> `foo(&b)` |
+| `symbol_to_proc_replacement` | Apply the `send_mutation` and `collection_replacement` selector tables to a symbol block-pass (skips alias swaps) | `map(&:to_s)` -> `map(&:to_i)` |
+| `dynamic_dispatch_resolution` | Resolve `send` / `__send__` / `public_send` with a literal symbol into a direct call, only where visibility checks can differ | `obj.send(:m, a)` -> `obj.m(a)` |
+| `keyword_argument_removal` | Drop one `key: value` argument at a call site (keeps `**opts`; skips a lone keyword) | `f(a: 1, b: 2)` -> `f(b: 2)` |
+| `double_negation_removal` | Replace a double negation with its operand | `!!x` -> `x` |
+| `regexp_anchor_to_predicate` | Rewrite a match against an anchored literal regexp as a prefix / suffix predicate (skips `match?` with `\A` / `\z`, an exact equivalent) | `x =~ /^foo/` -> `x.start_with?("foo")` |
+| `reduce_to_sum` | Rewrite a `+` reduction (`reduce` / `inject` with `:+` or `&:+`) into `sum` | `xs.reduce(:+)` -> `xs.sum`, `xs.inject(0, :+)` -> `xs.sum(0)` |
+| `array_coercion_to_literal` | Replace an `Array()` coercion with an array literal | `Array(x)` -> `[x]` |
+| `to_i_to_integer` | Replace lenient `to_i` with strict `Integer()` (skips numeric literal receivers) | `x.to_i` -> `Integer(x)`, `x.to_i(16)` -> `Integer(x, 16)` |
+| `coercion_emptying` | Replace a conversion with an empty value of its type (`to_a` / `to_ary`, `to_h` / `to_hash`, `to_s` / `to_str`) | `x.to_s` -> `""`, `x.to_h` -> `{}` |
+| `const_get_to_constant_path` | Resolve `const_get` with a literal symbol into a constant path | `X.const_get(:Y)` -> `X::Y` |
+| `proc_to_lambda` | Turn `proc { }` / `Proc.new { }` into `lambda { }` (arity checks, local `return`) | `proc { \|x\| x }` -> `lambda { \|x\| x }` |
+| `dig_to_fetch_chain` | Make the first step of a multi-key `dig` strict | `x.dig(a, b)` -> `x.fetch(a).dig(b)` |
+| `inequality_to_negated_identity` | Rewrite `!=` with the stricter `eql?` / `equal?` (skips nil, boolean and symbol literals) | `a != b` -> `!a.eql?(b)`, `!a.equal?(b)` |
+| `binary_operand_promotion` | Replace an arithmetic or bitwise expression with one of its operands (skips integer identities and void statements) | `a + b` -> `a`, `b` |
+| `receiver_constructor_swap` | Swap `Date` / `DateTime` / `Time.parse` for a stricter sibling constructor on the same receiver | `Date.parse(s)` -> `Date.iso8601(s)`, `Date.strptime(s)`, ... |
+| `block_body_to_nil` | Replace a block body with `nil`, keeping the iteration (skips `loop` and endless `cycle` / `cycle(nil)`, which would hang) | `xs.each { \|x\| log(x) }` -> `xs.each { \|x\| nil }` |
+| `block_body_to_raise` | Replace a block body with `raise` to prove the block is invoked (skips bodies with a `rescue` clause, which would swallow it) | `xs.each { \|x\| log(x) }` -> `xs.each { \|x\| raise }` |
+| `block_body_promotion` | Replace a call with its parameter-less block body, run once (skips blocks with parameters or a `rescue` / `ensure` clause) | `Base.transaction { save! }` -> `save!`, `3.times { poll }` -> `poll` |
+| `data_struct_member` | Drop a member, or swap adjacent members, of a `Data.define` / `Struct.new` definition (a definition outside any method — `Point = Data.define(...)`, `class Coord < Struct.new(...)` — is its own subject, named after the constant; skips single-member and splatted lists) | `Data.define(:a, :b)` -> `Data.define(:b)`, `Data.define(:b, :a)` |
+| `pin_operator_removal` | Drop the pin of a pattern variable so it captures instead of comparing (local variables only; skips pins inside alternative patterns, where a capture is not allowed) | `in ^expected` -> `in expected` |
+| `rightward_assignment` | Turn a rightward pattern match into a pattern predicate, so a mismatch returns `false` instead of raising (skips a bare capture, which cannot fail) | `value => [a, b]` -> `value in [a, b]` |
+| `numbered_parameter_swap` | Swap neighbouring numbered block parameters that the body reads (skips blocks reading a single one; `it` has nothing to swap with) | `pairs.map { _1 - _2 }` -> `pairs.map { _2 - _1 }` |
+| `forwarded_argument_drop` | Stop forwarding one part of the arguments a method passes through unnamed; a `...` signature is spelled out so a single part can be left out (skips a lone anonymous argument and named splats) | `g(*, **, &)` -> `g(**, &)`, `def f(...) = g(...)` -> `def f(*, **, &) = g(*, **)` |
+| `pattern_wildcard_widening` | Widen a pattern so it accepts shapes it rejects: append a rest to an array pattern, wildcard or drop a hash-pattern pair, remove `**nil` (skips pairs that bind a variable and patterns that already have a rest) | `in [a, b]` -> `in [a, b, *]`, `in { age: Integer }` -> `in { age: _ }` |
+| `no_matching_pattern_else` | Add an empty `else` to a `case/in` that has none, so an unmatched value yields `nil` instead of raising (skips a `case/in` with a bare capture clause, which matches everything) | `case v; in Integer then 1; end` -> `case v; in Integer then 1; else; end` |
+| `argument_order_permutation` | Swap neighbouring positional arguments of a call, `super` or `yield` (keeps keywords, block and splats in place; skips identical neighbours, `raise` / `fail`, `format` / `sprintf` / `printf`, index writes, `start_with?` / `end_with?` and `Set[...]`). Calls that accept arguments in any order, such as `OptionParser#on`, can be silenced with `ignore_patterns`, e.g. `call{name=on, receiver=local_variable_read{name=opts}}` | `compute(a, b)` -> `compute(b, a)` |
+| `keyword_value_swap` | Swap the values of neighbouring keyword arguments, keeping the keys (keeps positional arguments, `**splat` and block in place; skips identical values and braced hash arguments; spells out shorthand keys) | `compute(x: a, y: b)` -> `compute(x: b, y: a)` |
+| `comparison_operand_swap` | Swap the operands of a spaceship comparison, reversing a sort block or a custom ordering (skips identical operands and safe navigation; `between?` / `clamp` bounds are swapped by `argument_order_permutation`) | `x.age <=> y.age` -> `y.age <=> x.age` |
+| `integer_division_to_fdiv` | Turn a division into `fdiv`, so integer division keeps its remainder (groups a compound dividend; skips float literals, `/=` and the explicit `./(...)` form) | `a / b` -> `a.fdiv(b)` |
+| `off_by_one_boundary` | Lower a count held in a variable by one: the receiver of `times`, the argument of `upto` / `downto` / `take` / `first` / `last` / `drop` / `each_slice` / `each_cons` (skips literal counts, which `integer_literal` shifts, and safe navigation) | `n.times` -> `(n - 1).times`, `items.first(n)` -> `items.first(n - 1)` |
+| `format_specifier_swap` | Loosen one conversion specifier of a literal format string in `format` / `sprintf` / `printf` / `String#%`: drop flags, width and precision, or render a non-integer number as `%s` (skips `%%`, `%{name}`, `*` widths, `%c`, `%p` and interpolated or heredoc strings) | `format("%05d", n)` -> `format("%d", n)`, `"%.2f"` -> `"%f"`, `"%s"` |
+| `alias_removal` | Drop an `alias` or `alias_method` declaration from a class, module or `class << self` body, attributed to the first method of that scope (skips aliases inside methods, `alias_method` sent to another receiver and global-variable aliases) | `alias length size` -> _(removed)_ |
+| `regexp_character_type_complement` | Flip a regexp character type or word boundary to its complement, one at a time (leaves `\X`, `\R` and Unicode properties alone) | `/\d+/` -> `/\D+/`, `/\bword/` -> `/\Bword/` |
+| `regexp_anchor_promotion` | Promote a regexp line anchor to a string anchor, so the pattern stops matching around newlines (`^` -> `\A`, `$` and `\Z` -> `\z`) | `/^admin$/` -> `/\Aadmin$/`, `/^admin\z/` |
+| `regexp_alternation_branch_deletion` | Delete one branch of a regexp alternation at a time (skips alternations of more than ten branches, which are lookup tables, and deletions that would break a reference inside the pattern) | `/cat\|dog/` -> `/dog/`, `/cat/` |
+| `regexp_quantifier_minimum_swap` | Swap a regexp quantifier between zero-or-more and one-or-more, keeping it lazy or possessive, so only the empty case changes | `/\A\d*\z/` -> `/\A\d+\z/`, `/a+?/` -> `/a*?/` |
+| `regexp_capture_to_passive` | Turn a regexp capture group into a passive group, so `$1`, `m[1]` or `\1` in a replacement loses its value (skips patterns passed to `match?` / `!~`, patterns with named groups, and patterns with numbered references) | `/id=(\d+)/` -> `/id=(?:\d+)/` |
+| `regexp_named_group_rename` | Rename a named regexp group, with its references inside the pattern, so `m[:name]` and the local bound by `/(?<name>…)/ =~ s` no longer find it (skips patterns passed to `match?` / `!~`) | `/(?<user>\w+)@/` -> `/(?<_user>\w+)@/` |
+| `regexp_option_removal` | Drop the `i` or `m` option of a regexp literal where it changes something: `i` with a cased letter in the pattern, `m` with a `.` outside a character class | `/admin/i` -> `/admin/`, `/a.b/m` -> `/a.b/` |
 | `keyword_argument` | Remove keyword defaults/params | `def foo(bar: 42)` -> `def foo(bar:)` |
 | `multiple_assignment` | Remove targets or swap order | `a, b = 1, 2` -> `b, a = 1, 2` |
 | `block_removal` | Remove blocks from method calls | `items.map { \|x\| x * 2 }` -> `items.map` |
@@ -522,7 +598,7 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `regexp_mutation` | Replace regexp with always/never matching | `/pat/` -> `/a\A/` |
 | `regex_simplification` | Simplify regex quantifiers, anchors, ranges | `/\d+/` -> `/\d/`, `/[a-z]/` -> `/[az]/` |
 | `receiver_replacement` | Drop explicit `self` receiver | `self.foo` -> `foo` |
-| `send_mutation` | Swap semantically related methods | `detect` -> `find`, `map` -> `flat_map` |
+| `send_mutation` | Swap semantically related methods | `detect` -> `find`, `map` -> `flat_map`, `round` -> `floor` / `ceil` |
 | `compound_assignment` | Swap compound assignment operators | `+=` -> `-=`, `&&=` -> `\|\|=` |
 | `local_variable_assignment` | Replace variable assignment with `nil` | `x = expr` -> `x = nil` |
 | `instance_variable_write` | Replace ivar assignment with `nil` | `@x = expr` -> `@x = nil` |
@@ -532,6 +608,9 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `superclass_removal` | Remove class inheritance | `class Foo < Bar` -> `class Foo` |
 | `rescue_removal` | Remove rescue clauses | Deletes rescue block |
 | `rescue_body_replacement` | Replace rescue body with `nil` | Rescue body -> `nil` |
+| `rescue_handler_promotion` | Run a rescue handler instead of the code it protects, so the happy path never runs: each handler of a `begin` / method / block rescue in turn, and the fallback of a rescue modifier (drops `else`, keeps `ensure`; skips handlers that read the exception, re-raise or retry) | `begin; fetch(id); rescue NotFound; default; end` -> `begin; default; end`, `fetch(id) rescue default` -> `default` |
+| `rescue_handler_concatenation` | Run a rescue handler after the protected code as well, keeping the rescue, so a successful run also does what the handler does (skips empty and value-only handlers, handlers that read the exception, re-raise or retry, and rescue modifiers) | `begin; fetch(id); rescue NotFound; rollback; end` -> `begin; fetch(id); rollback; rescue NotFound; rollback; end` |
+| `rescue_else_concatenation` | Move the `else` body of a rescue into the protected code, so an error it raises is now rescued (only under a bare `rescue` or one naming `StandardError` / `Exception`; keeps the rescue and `ensure`) | `begin; a; rescue; b; else; c; end` -> `begin; a; c; rescue; b; end` |
 | `inline_rescue` | Remove inline rescue fallback | `expr rescue val` -> `expr` |
 | `ensure_removal` | Remove ensure blocks | Deletes ensure block |
 | `break_statement` | Remove break statements | `break` -> removed |
@@ -550,7 +629,7 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `pattern_matching_alternative` | Remove/reorder alternatives | `pat1 \| pat2` -> `pat1` |
 | `pattern_matching_array` | Remove/wildcard array elements | `[a, b]` -> `[a, _]` |
 | `yield_statement` | Remove yield or its arguments | `yield(x)` -> `yield` |
-| `splat_operator` | Remove splat/double-splat | `foo(*args)` -> `foo(args)` |
+| `splat_operator` | Remove splat/double-splat (skips `**` in a hash literal, `**` after a keyword argument or another `**`, and the rest of a pattern) | `foo(*args)` -> `foo(args)` |
 | `defined_check` | Replace `defined?` with `true` | `defined?(x)` -> `true` |
 | `regex_capture` | Swap or nil-ify capture refs | `$1` -> `$2`, `$1` -> `nil` |
 | `loop_flip` | Swap while/until loops | `while cond` -> `until cond` |
@@ -559,7 +638,7 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `method_body_to_super` | Replace a method body with bare `super` where a super target exists | `def foo; body; end` -> `def foo; super; end` |
 | `typed_default_return` | Replace a single-expression body with the empty value of its inferred type | `def names(u); u.map(&:name); end` -> `def names(u); []; end` |
 | `block_parameter_drop` | Drop a block's single parameter | `users.each { |u| touch(u) }` -> `users.each { touch(u) }` |
-| `optional_parameter_to_required` | Drop an optional positional parameter's default | `def f(a = 1)` -> `def f(a)` |
+| `optional_parameter_to_required` | Drop an optional positional parameter's default; of several, only the ones Ruby lets become required: the first, and the last unless a `*rest` parameter follows | `def f(a = 1)` -> `def f(a)` |
 | `optional_default_injection` | Overwrite an optional parameter with its own default at the top of the body | `def f(a = 1); body; end` -> `def f(a = 1); a = 1; body; end` |
 | `block_destructuring_expansion` | Flatten a destructuring group in a block's parameters | `pairs.each_with_index { |(k, v), i| use(k, v, i) }` -> `pairs.each_with_index { |k, v, i| use(k, v, i) }` |
 | `forwarding_super_to_explicit` | Give a forwarding `super` an empty argument list | `def f(a); super; end` -> `def f(a); super(); end` |
@@ -589,15 +668,15 @@ Create a `.mcp.json` file in your project root:
   "mcpServers": {
     "evilution": {
       "type": "stdio",
-      "command": "evilution",
-      "args": ["mcp"],
+      "command": "bundle",
+      "args": ["exec", "evilution", "mcp"],
       "env": {}
     }
   }
 }
 ```
 
-If using Bundler, set the command to `bundle` and args to `["exec", "evilution", "mcp"]`.
+Run the server through `bundle exec` so the project's `Gemfile.lock` decides which versions of evilution, your test framework and their shared dependencies get loaded. Started outside Bundler, RubyGems picks the newest installed copy of each gem, which your test framework may refuse — the run then stops at the proof-of-life canary with a gem activation conflict. Projects without a Gemfile can use `"command": "evilution"` and `"args": ["mcp"]`.
 
 The server exposes the following tools:
 
@@ -605,7 +684,7 @@ The server exposes the following tools:
 |---|---|
 | `evilution-mutate` | Run mutation testing on target files with structured JSON results |
 | `evilution-session` | Inspect mutation testing history — `action: list` browses saved sessions, `action: show` displays one, `action: diff` compares two (fixed/new/persistent survivors, score delta) |
-| `evilution-info` | Discovery before mutation — `action: subjects` lists mutatable methods with mutation counts, `action: tests` resolves which specs cover given sources, `action: environment` dumps the effective config, `action: statuses` returns the mutation-result status glossary, `action: feedback` returns the public Discussions URL plus consent + privacy guidance for posting feedback |
+| `evilution-info` | Discovery before mutation — `action: subjects` lists the mutation subjects (methods, and class-body subjects such as scopes and callback declarations) with mutation counts, `action: tests` resolves which specs cover given sources, `action: environment` dumps the effective config, `action: statuses` returns the mutation-result status glossary, `action: feedback` returns the public Discussions URL plus consent + privacy guidance for posting feedback |
 
 ### Verbosity Control
 
@@ -623,7 +702,7 @@ What survives trimming matters when you are deciding whether to trust a score:
 
 - `neutral` entries — and with them each `neutral_reason` — are dropped at `summary` and `minimal`. Use `full` to see why mutations were neutralised.
 - `subjects` is kept at `full` and `summary`, and dropped at `minimal`, which keeps only `summary` and `survived`.
-- Everything inside `summary` survives at every level, including `unresolved_target_files`, `infra_retried` and the `neutral` count — so even a `minimal` response still says whether a target file went untested and how much of the run the score covers.
+- Everything inside `summary` survives at every level, including `unresolved_target_files`, `uncovered_code`, `infra_retried`, `baseline_neutralized`, `baseline_failures` and the `neutral` count — so even a `minimal` response still says whether a target file went untested and how much of the run the score covers.
 
 ### Enriched Survived Entries
 
@@ -772,6 +851,14 @@ Methods whose body overlaps the requested range are included. Mix targeted and w
 evilution run lib/foo.rb:15-30 lib/bar.rb --format json
 ```
 
+A range is matched against subjects, and not every line belongs to one. Methods are subjects, and so are scopes, AASM guards and callbacks, callback and validation declarations, and `Data.define` / `Struct.new` definitions (see step 2 under [Internals](#internals-for-context-not-for-direct-use)). Other class-body code — a constant list, a serializer attribute, a DSL call evilution does not know — is not. When the range holds such code, the run says so on stderr and in `summary.uncovered_code`:
+
+```
+[evilution] app/models/order.rb:12-14 holds code outside every subject (class-body code such as DSL calls and constants is not mutated); no mutations target those lines.
+```
+
+Read `0 mutations` next to that message as "not measured", not as "nothing to test".
+
 ### 4. Method-name targeted scan
 
 ```bash
@@ -798,13 +885,14 @@ Pass multiple file paths on a single invocation to amortise startup cost. The fr
 
 ### What to read before acting on a score
 
-A score describes only the mutations that got a verdict. Four fields say what it leaves out, and each points at a different action:
+A score describes only the mutations that got a verdict. Five fields say what it leaves out, and each points at a different action:
 
 | Field | Meaning | What to do |
 |---|---|---|
 | `summary.unresolved_target_files` | A file you named resolved to no spec and was never tested; the run fails on this alone | Write a spec, pass `--spec`, or map it in `spec_mappings` — do not trust the score until this is empty |
 | `subjects[].reached == false` | Mutations were generated for that method but none got a verdict | The method is untested even where its file scores well; start here rather than with `survived[]` |
-| `neutral[].neutral_reason.kind == "baseline_failure"` | The spec file was already red before any mutation ran; `detail` names it | Fix that spec first — nothing about these mutations is measurable until it is green |
+| `summary.uncovered_code` | Lines you targeted hold code outside every subject — class-body code such as constant lists or DSL calls evilution does not treat as a subject — so no mutation was generated for them; the same is printed to stderr | A run that reports `0 mutations` for those lines has not shown they are tested. Target the methods that code calls, or cover it with ordinary tests |
+| `neutral[].neutral_reason.kind == "baseline_failure"` | The mutation's tests failed only on examples that were already failing before any mutation ran; `detail` names the red spec file | Read `summary.baseline_failures` for why it was red, and fix that first — these mutations have no verdict until it is green |
 | `neutral[].neutral_reason.kind == "infra_error"` | The test process crashed on infrastructure (DB lock, timeout); `detail` names the class | Not a coverage gap. Give parallel workers their own database, or run `-j 1` |
 
 `summary.infra_retried` reports how many mutations had to be re-run serially because of the last case; a large number means the parallel run was fighting shared infrastructure rather than measuring your suite.
@@ -840,6 +928,17 @@ bundle exec evilution mutate lib/aasm/base.rb --spec spec/unit/event_spec.rb,spe
 bundle exec evilution mutate lib/aasm/base.rb --fallback-full-suite
 ```
 
+To make the mapping permanent, declare it once in `.evilution.yml` under `spec_mappings`; the run, its baseline and `tests list` all honour it. `evilution tests list <file>` prints exactly the spec files a run would use, so it is the quick way to check a mapping before spending a run on it:
+
+```yaml
+spec_mappings:
+  lib/aasm/base.rb:
+    - spec/unit/event_spec.rb
+    - spec/unit/callbacks_spec.rb
+```
+
+Without `--fallback-full-suite` an unresolved source is also left out of the baseline, which does not run the whole test directory for it.
+
 ### Long Minitest fork runs — not a hang
 
 Minitest projects under `--isolation=fork` re-bootstrap the test environment (`test_helper.rb`, plugins, runnable state) once per mutation. On constant-heavy files (e.g. Shopify/liquid's `lib/liquid/lexer.rb`, ~270 mutations) the wall-clock cost is dominated by that per-fork bootstrap and any mutations that hit a `--timeout` rather than killing the test fast. A single-worker run (`-j 1`) on a few hundred mutations can take 4+ minutes; combined with `--no-progress` and a non-TTY stderr (CI, redirected logs) the run looks silent the entire time.
@@ -853,7 +952,7 @@ RUBYOPT="-Itest" bundle exec evilution mutate lib/<file>.rb \
   --spec test/<dir>/<file>_test.rb
 ```
 
-`-j 4` parallelises across workers, `-t 10` caps any mutation that pathologically loops at 10 s. Expect the run to print progress only when stderr is a TTY (use `bundle exec evilution mutate ... 2>&1 | tee log` to get progress while still saving output). The historical "Minitest fork hangs on liquid" report (GH #1211) turned out to be a slow run + silent UX, not an actual deadlock — the worker logs show steady forward progress when captured via `--quiet-children --quiet-children-dir DIR`.
+`-j 4` parallelises across workers, `-t 10` caps any mutation that pathologically loops at 10 s. On a Rails app, add `--warmup rails` so each fork does not re-initialise I18n, routes and templates on its first request (see [Warming up Rails before forking](#warming-up-rails-before-forking)). Expect the run to print progress only when stderr is a TTY (use `bundle exec evilution mutate ... 2>&1 | tee log` to get progress while still saving output). The historical "Minitest fork hangs on liquid" report (GH #1211) turned out to be a slow run + silent UX, not an actual deadlock — the worker logs show steady forward progress when captured via `--quiet-children --quiet-children-dir DIR`.
 
 ### 8. CI gate
 
@@ -891,6 +990,21 @@ Output buckets:
 
 Use in CI to gate merges on `reintroduced` being empty, or to surface `new` survivors for reviewer attention without failing the build on `persistent` debt.
 
+## Warming up Rails before forking
+
+Under `isolation: fork` the parent preloads once and every mutation runs in a fresh fork, which inherits only what the parent had already initialised. Rails initialises a lot lazily on a process's first request: loading locale files, building route helpers, resolving asset paths, compiling templates. Without a warm-up, every forked mutation whose tests make a request pays that cold start again, often several hundred milliseconds each.
+
+`warmup: rails` (or `--warmup rails`) does that initialisation once in the parent, right after the preload:
+
+- `I18n.eager_load!`
+- the route set's `url_helpers` (and `eager_load!` for lazily drawn routes on Rails 8)
+- an asset path lookup through the controller helpers
+- template precompilation, only if the [`actionview_precompiler`](https://github.com/jhawthorn/actionview_precompiler) gem is installed
+
+Each step is skipped if its library is not loaded, and skipped with a one-line note if it raises, so an app that does not fit a step still runs normally.
+
+Do not warm up by sending a real request from your preload (`Rails.application.call(...)`). Controller callbacks change process-global state that every fork then inherits: `I18n.locale`, gem request stores such as PaperTrail's, a session row in the database. Tests that depend on that state then fail in every fork, and evilution reports their mutations as killed. The steps above make no request and leave that state untouched.
+
 ## Parallel Runs with SQLite
 
 Running with `-j N` forks worker processes. If your Rails app uses SQLite, every worker opens the same `db/test.sqlite3` file, and concurrent writers collide on the database-level lock. Symptoms: `ActiveRecord::StatementTimeout`, `SQLite3::BusyException`, and slow runs. Evilution classifies these crashes as `:neutral` (see [GH #814](https://github.com/marinazzio/evilution/issues/814)) so the mutation score is not polluted, but the wall-clock penalty remains.
@@ -944,9 +1058,9 @@ For the full contributor architecture — module map, data flow, and extension
 points — see [docs/architecture.md](docs/architecture.md).
 
 1. **Parse** — Prism parses Ruby files into ASTs with exact byte offsets
-2. **Extract** — Methods are identified as mutation subjects
+2. **Extract** — Methods are identified as mutation subjects, and so are value-object definitions outside any method (`Point = Data.define(:x, :y)`, `class Coord < Struct.new(:lat, :lng)`), which only the operators that apply to them mutate, and ActiveRecord scopes declared with a literal body in a class body (`scope :recent, -> { where(recent: true) }`), named after the class method they define (`Order.recent`) and mutated like a method body — also when declared in a concern's `included do ... end` block, where they are named after the concern (`Publishable.published`); likewise the guards and callbacks written out as lambdas or blocks inside an AASM `event` or `state` declaration (`event :ship, guard: -> { address? }`), named after the method that declaration defines (`Order#ship`, `Order#paid?`), or after the concern when the machine is declared in its `included do ... end` block (`Shippable#ship`); and the conditions and bodies written out in callback and validation declarations of a class body or of a concern's `included do ... end` block (`validate :credit_limit, if: -> { paid? }`, `before_save { ... }`), named the way the declaration reads (`Order.validate(:credit_limit)`, `Order.before_save`, `Publishable.validates(:title)`)
 3. **Filter** — Disable comments, Sorbet `sig` blocks, and AST ignore patterns exclude mutations before execution
-4. **Mutate** — 88 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default. Identical byte-mutations from different operators are deduplicated by `(file_path, mutated_source)` so the count is not inflated by overlap
+4. **Mutate** — 136 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default. Identical byte-mutations from different operators are deduplicated by `(file_path, mutated_source)` so the count is not inflated by overlap
 5. **Isolate** — Mutations are applied to temporary file copies (never modifying originals); load-path redirection ensures `require` resolves the mutated copy. Default isolation is in-process for plain Ruby projects (no gemspec) and fork for Rails projects and packaged gems (auto-detected); `--isolation fork` forces forked child processes. Both sequential and parallel (`--jobs N`) modes respect the configured isolation strategy
 6. **Test** — The configured test framework (RSpec, Minitest, or Test::Unit) executes against the mutated source
 7. **Collect** — Source strings and AST nodes are released after use to minimize memory retention

data/docs/architecture.md

@@ -12,7 +12,10 @@ For deeper dives on two subsystems that have their own docs, see
 ## The one-paragraph version
 
 Evilution parses each target file with [Prism](https://github.com/ruby/prism)
-into an AST with exact byte offsets. Every method becomes a *subject*. Each
+into an AST with exact byte offsets. Every method becomes a *subject*, and so
+does every value-object definition outside a method (`Point = Data.define(:x)`)
+and every scope declared with a literal body (`scope :recent, -> { ... }`),
+and every guard or callback written out inside an AASM `event` or `state`. Each
 mutation *operator* walks a subject's AST and emits *mutations* — byte-range
 edits applied by source-level surgery (no AST unparsing). For every mutation,
 evilution copies the file, applies the edit, runs the covering specs in an
@@ -48,7 +51,7 @@ Everything lives under `lib/evilution/`.
 | `Config`, `Config::*` | Merge `.evilution.yml` + CLI flags + env, validate, freeze. | `config.rb`, `config/sources.rb`, `config/validators/*` |
 | `Runner`, `Runner::*` | Orchestrate the whole run. Each stage is its own collaborator. | `runner.rb`, `runner/*` |
 | `AST`, `Subject` | Prism parse, find method subjects, source surgery, pattern matching, heredoc spans. | `ast/parser.rb`, `ast/source_surgeon.rb`, `subject.rb` |
-| `Mutator`, `Mutator::Operator::*` | 88 operators (default profile) that emit byte-edits; registry + profiles. | `mutator/base.rb`, `mutator/registry.rb`, `mutator/operator/*` |
+| `Mutator`, `Mutator::Operator::*` | 136 operators (default profile) that emit byte-edits; registry + profiles. | `mutator/base.rb`, `mutator/registry.rb`, `mutator/operator/*` |
 | `Mutation` | An immutable mutation record (original/mutated sources, slice, location, parse status). | `mutation.rb` |
 | `SpecResolver`, `SpecSelector` | Map a source file to its covering spec files (layout heuristics + explicit mappings). | `spec_resolver.rb`, `spec_selector.rb` |
 | `Isolation::{Fork,InProcess}`, `ProcessSupervisor` | Run one mutation's tests in isolation; process-group lifecycle, sandboxing, TERM/KILL ladder. | `isolation/fork.rb`, `process_supervisor.rb` |
@@ -60,6 +63,40 @@ Everything lives under `lib/evilution/`.
 | `Session`, `Compare` | Persist runs to `.evilution/results/*.json`; diff two sessions. | `session/store.rb`, `compare.rb` |
 | `Coverage`, `Equivalent`, `Baseline`, `Cache`, `Hooks`, `MCP` | Coverage-based example targeting, equivalent-mutation detection, baseline capture, incremental cache, lifecycle hooks, MCP server. | respective dirs |
 
+## Require conventions
+
+Most directories under `lib/evilution/` have a parent file of the same name
+(`runner.rb` next to `runner/`) that declares the namespace. The rules:
+
+- **Every child requires its parent.** A file in `runner/` starts with
+  `require_relative "../runner"`, a file in `cli/commands/` with
+  `require_relative "../commands"`, and so on down the tree.
+- **A parent declares its namespace before requiring its children.** Usually
+  the class or module is defined first and children are required at the
+  bottom. Where the parent's own body needs its children loaded first (for
+  example a constant built from them), it opens with an empty declaration —
+  `class Evilution::CLI; end` — then requires the children, then defines the
+  rest. `cli.rb` and `integration/rspec/state_guard.rb` do this.
+- **Top-level files (`lib/evilution/*.rb`) are the exception.** Their parent is
+  `lib/evilution.rb`, the gem's entry point, which loads everything. A
+  top-level file that only needs the root module requires `version.rb`, which
+  defines `module Evilution` and nothing else. Only a file that genuinely needs
+  the whole gem requires `../evilution` — `runner.rb`, whose collaborators
+  reach every operator through `Mutator::Registry`.
+
+The parent require and the parent's own `require_relative` of its children
+form a cycle (`runner.rb` → `runner/canary.rb` → `runner.rb`). It is inert:
+Ruby does not load a file twice, so a re-entrant require of a file already
+being loaded returns immediately, and the namespace already exists because the
+parent declared it first. Reviews flagging it as a circular require can be
+answered with this section.
+
+Loading an arbitrary file on its own (`require "evilution/cli/command"` in a
+fresh process) is not a goal. The parent requires make most files work that
+way, but not all: a base class whose subclasses are required by the parent
+(`cli/command.rb`) cannot finish defining itself before those subclasses load.
+Load the gem through `require "evilution"`.
+
 ## Data flow, source → result
 
 Driven entirely by `Evilution::Runner#call` (`runner.rb:24`). Each step names the
@@ -71,13 +108,34 @@ class that owns it.
 2. **Subjects** — `Runner::SubjectPipeline#call` resolves target files (explicit,
    `source:<glob>`, or `Git::ChangedFiles`), then `AST::Parser#call` runs
    `Prism.parse` and `AST::SubjectFinder` (a `Prism::Visitor`) emits one
-   `Evilution::Subject` per `def` node. Optional descendant/target/line-range filters follow.
+   `Evilution::Subject` per `def` node (kind `:method`), plus one per
+   `Data.define` / `Struct.new` assigned to a constant or used as a superclass
+   outside any method (kind `:constant`, named after the constant), plus one per
+   `scope :name, -> { }` / `lambda { }` / `proc { }` written directly in a class
+   body (kind `:scope`, named `Class.name` after the class method it defines;
+   it spans the declaration and its node is the body; a scope declared in a
+   concern's `included do ... end` is named after the concern), plus one per literal
+   callable inside an `event` or `state` of a class-body `aasm do ... end` --
+   keyword values (`guard: -> { }`, also inside arrays), those of the event's
+   `transitions`, and callback blocks (`before { }`) -- kind `:aasm`, named
+   `Class#event` / `Class#state?` after the method the declaration defines, so
+   one event may contribute several subjects of the same name (a machine in a
+   concern's `included do ... end` is found too, and named after the concern);
+   and one per
+   literal callable of a class-body callback or validation declaration
+   (`validate`, `validates`, `validates_*`, `before_*`, `after_*`, `around_*`)
+   -- an `if:` / `unless:` condition, or the callback itself as a block or
+   lambda -- kind `:callback`, named as the declaration reads
+   (`Order.validate(:credit_limit)`, `Order.before_save`; one in a concern's
+   `included do ... end` is named after the concern). Optional
+   descendant/target/line-range filters follow.
 3. **Baseline** — `Runner::BaselineRunner#call` builds the integration from
    `Runner::INTEGRATIONS` (`rspec`/`minitest`/`test_unit`) and records spec files
    that already fail *before* any mutation, so their mutations aren't miscounted.
    An optional `Runner::Canary` proves the pipeline can observe a known mutation.
 4. **Mutations** — `Runner::MutationPlanner#call` flat-maps subjects through
-   `Mutator::Registry#mutations_for`. The registry instantiates each operator and
+   `Mutator::Registry#mutations_for`. The registry instantiates each operator whose
+   `subject_kinds` include the subject's kind (`:method`, `:scope`, `:aasm` and `:callback` by default) and
    runs `operator.call(subject, filter:)`; each operator subclasses
    `Mutator::Base` and calls `add_mutation`, which runs `AST::SourceSurgeon` and
    builds an immutable `Evilution::Mutation`. The planner then **deduplicates**
@@ -108,11 +166,20 @@ class that owns it.
    `Isolation::Fork#classify_status`: `:timeout` → `:killed` (crash) →
    `:unresolved` → `:error` → `:survived` (tests passed) → default `:killed`.
    A `NeutralizationPipeline` can reclassify results into `:neutral` — either
-   because the covering spec already failed at baseline (`Neutralizer::BaselineFailed`)
-   or because the test process crashed on infrastructure rather than on the
-   mutation (`Neutralizer::InfraError`). Each records a `Result::NeutralReason`,
-   since the two want opposite responses. A survivor is re-run against its whole
-   spec file before it is reported (`Integration::RSpec#confirm_survivor?`), so a
+   because the tests failed on nothing but examples that were already failing
+   at baseline (`Neutralizer::BaselineFailed`) or because the test process
+   crashed on infrastructure rather than on the mutation
+   (`Neutralizer::InfraError`). Each records a `Result::NeutralReason`, since
+   the two want opposite responses. For the first, the baseline reports the
+   ids of its failing examples (`Integration::RSpec::ExampleIds`, absolute path
+   plus position, so they compare across working directories;
+   `Integration::Minitest::TestIds`, `Class#test`;
+   `Integration::TestUnit::TestIds`, `test(Class)`), the integration is built
+   with them (`known_failures:`, held as `Integration::KnownFailures`), and a
+   failed run whose failed examples are all among them comes back flagged
+   `known_failures_only`; a survivor is never neutralized. A survivor is re-run
+   against its whole spec file before it is reported
+   (`Integration::RSpec#confirm?`), as is a targeted run flagged that way, so a
    narrowed example set cannot invent one; after a parallel pass,
    `MutationExecutor::InfraRetry` re-runs the infrastructure-neutralised
    mutations serially, once the contention that caused them is gone.
@@ -159,6 +226,53 @@ A mutator is a `Prism::Visitor` subclass that emits byte-range edits.
    - The operator's registered name is auto-derived from the class name
      (`MyThing` → `my_thing`); that string is the `operator` field in JSON output
      and is part of the public contract, so name it deliberately.
+   - Operators see method, scope, aasm and callback subjects. One that also applies to value-object
+     definitions outside a method overrides `self.subject_kinds` to return
+     `%i[method constant]`; a constant subject's node is the definition's
+     `CallNode`.
+   - A scope subject's mutation only takes effect if the mutated file re-runs
+     its `scope` call, which `BodyCallNeutralizer` would otherwise blank: the
+     eval source keeps that one call (`keep_offset`). Its `restore_source` is
+     the original file with the same call kept; `Integration::Base#call`
+     evaluates it after the tests, since in-process runs restore methods only
+     by re-evaluating the next mutation's source, where scopes are blanked.
+   - A scope in a concern's `included` block has two audiences. The kept
+     `included` call registers the mutated block for classes that include the
+     concern later (`ConcernStateCleaner` clears the old one first, on apply
+     and on restore: a concern ignores a block handed to it twice from the
+     same place). For classes that include it already, the eval source guards
+     every other call of the block with `ConcernRedeclaration.skipping?` and
+     follows the block with `ConcernRedeclaration.call(self)`, which runs the
+     block on each of them with the guard up, so only the scope is declared
+     again. Both additions go on existing lines; no line number moves.
+   - A callback subject's declaration is kept too, wrapped in
+     `CallbackRedeclaration.call(self, __FILE__, lines) { ... }`. Callbacks do
+     not replace on re-declaration: a symbol callback moves to the end of its
+     chain, a block or validator is added beside the first. The helper reads
+     the chains, runs the declaration and rebuilds them through
+     `__update_callbacks`, so the new callbacks sit where the ones this
+     declaration registered before were. Those are found by the source
+     location of their procs the first time (`lines` is the declaration's
+     range in the file as loaded) and from the helper's own record afterwards,
+     since a mutation may add or remove lines. In a concern's `included` block
+     the declaration is wrapped the same way inside the kept block, whose
+     other calls are guarded: run on a class that includes the concern already
+     it replaces that class's callbacks in place, run by a class including it
+     later it simply declares. `BodyCallNeutralizer` leaves a blanked call's
+     line breaks behind, so the evaluated source keeps the file's line numbers
+     and a class loaded during one mutation can be matched by location in the
+     next.
+   - An aasm subject works the same way, one level down: the `aasm` call is
+     kept, and inside its block every declaration but the `event` or `state`
+     holding the mutation is blanked. AASM stores what an event or state holds
+     by value, so re-running one replaces it; the machine's own callbacks
+     (`after_all_transitions`) accumulate, which is why the rest of the block
+     must not run again and why they get no subjects. For a machine inside a
+     concern's `included` block the two mechanisms combine: the block is kept
+     and followed by `ConcernRedeclaration.call(self)`, and both its other
+     calls and the machine's other declarations are guarded with
+     `ConcernRedeclaration.skipping?` instead of blanked -- a class that
+     includes the concern later needs the whole machine.
 
 2. **Require it** in `lib/evilution.rb` alongside the other
    `require_relative "evilution/mutator/operator/..."` lines.