# `MutagenEx.Mutators.Dispatch`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/mutators/dispatch.ex#L1)

Static, order-preserving head-atom dispatch table for the mutator catalog.

Implements `mutagen.decision.static_mutator_dispatch`: the
`MutagenEx.MutationEnumerator` consults `mutators_for_node/1` BEFORE
calling `match?/1` on each catalog entry. The table maps an AST node's
head atom to the (small) sub-sequence of mutators that could possibly
match a node with that head; mutators that match shapes which are NOT
3-tuples (bare literals, `{:ok, _}` / `{:error, _}` 2-tuples) live in a
separate `@any_mutators` list and are always considered.

## Why this exists (and why it is a static table, not a behaviour callback)

The enumerator's `try_mutators/6` used to run every mutator's `match?/1`
against every AST node — `O(nodes × catalog_size)`. For files with even
modest size this means asking ten mutators "do you match this `:+` node?"
when only one possibly could. The dispatch table makes it
`O(nodes × applicable_mutators)`.

The scope auditor for `mutagen-wrd.25` flagged the alternative design —
an `@optional_callback head_atoms/0` on the `MutagenEx.Mutators`
behaviour — as bloat:

  * The mutator catalog is closed (`mutagen.mutators.r7`). No external
    mutator authors. The list of head atoms is small and trivially
    captured in one place.
  * An optional callback opens a drift surface: a future mutator could
    forget to declare its head atoms, dispatch would silently fall back
    to `:any` for it, and the optimisation would be defeated without
    anyone noticing.

See `.spec/decisions/static_mutator_dispatch.md` for the full rationale.

## Determinism contract

`mutators_for_node/1` returns a **sub-sequence** of
`MutagenEx.Mutators.all/0`. The relative order of any two mutators in
the result is identical to their relative order in `Mutators.all/0`.
This is the property that preserves byte-identity of the JSON output
across runs (`mutagen.mutation_enumeration.r1` and the technical
red-team determinism finding called out in the decision file).

Concretely: `Dispatch` builds the table by filtering
`Mutators.all/0` — it never re-orders. The equivalence test
(`test/mutagen_ex/head_atom_dispatch_test.exs`) locks both the
correctness property (same mutators get tried per node) AND the
order-preserving property (the filtered sub-sequence equals the
result of the legacy "iterate `Mutators.all/0`" path applied to the
same node).

# `mutators_for_node`

```elixir
@spec mutators_for_node(Macro.t()) :: [module()]
```

Returns the sub-sequence of `MutagenEx.Mutators.all/0` whose `match?/1`
could possibly match `node`, preserving `Mutators.all/0` order.

The contract is:

  * Result is a list of mutator modules.
  * Result is a subset of `Mutators.all/0`.
  * The relative order of any two mutators in the result matches their
    relative order in `Mutators.all/0` (the order-preserving / byte-
    identity property required by
    `mutagen.mutation_enumeration.r1`).
  * Every mutator that would `match?(node)` is included in the
    result. (The converse is allowed: the result MAY include a mutator
    whose `match?/1` then returns `false` — `mutators_for_node/1` is a
    cheap **pre-filter**, not a full classifier. The enumerator still
    calls `match?/1` on each candidate.)

The equivalence test in
`test/mutagen_ex/head_atom_dispatch_test.exs` locks both properties
against the legacy "iterate `Mutators.all/0`" path for a corpus of
representative AST nodes.

---

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