Implementation plan for the spec committed in
`docs/superpowers/specs/2026-05-25-minifier-eliminate-changed-flag-design.md`.

Decomposes the migration into 18 PRs: PR 1 adds the four mutation
helpers and migrates the per-pass false-reset; PRs 2-17 mechanically
convert one peephole module each, ordered smallest-first; PR 18 is the
final lockdown that makes `MinifierState::changed` `pub(crate)` and
adds two CI checks (a grep for direct field writes plus an ast-grep
rule that catches the `*slot = new; ctx.notice_change();` bypass).

Each per-file task includes baseline + post counts so executing
engineers can verify zero drift, and `minimize_statements.rs` (Task
17) flags the `dead_drop_mutates_ast` gate that, if removed, would
spin the peephole fixed-point loop forever.

The per-file breakdown summed to 188 but the actual count is 187 — the
minimize_statements.rs entry was 45 but is actually 44. Update both the
spec and the plan to match the real numbers grep produces.

…r re-export

Clippy 1.95.0 flags the `pub(crate) use` at `lexer/mod.rs:38` because the
`mod lexer` declaration is private in the default build. But the feature-gated
`pub mod lexer` (cfg(feature = "benchmarking")) means widening to `pub` would
change visibility under benchmarking. Annotate with `#[expect(...)]` instead.

Unblocks the pre-commit clippy hook for any crate that depends on oxc_parser.

Introduces `replace_expression`, `replace_statement`, `notice_change`,
and `reset_changed` as the sanctioned API for marking a peephole pass as
having mutated the AST. Migrates the single `state.changed = false`
reset in `enter_program` to `reset_changed()`; all `= true` sites
will be migrated in subsequent PRs in this stack.

The legacy field stays `pub` for now so unmigrated modules can keep
writing to it directly. The final PR (`refactor(minifier): lock down
state.changed writes`) makes the field `pub(crate)` and adds the CI
check.

…ion helpers

…pers

Adds rule 1a to the Site classification rule: field assignments to
`Statement<'a>` / `Expression<'a>` fields (e.g. `for_stmt.body = X`)
count as slot replacements and must use the typed `replace_*` helpers,
not `notice_change()`. The ast-grep CI rule only catches deref-write
bypasses, so reviewers enforce the broader semantic contract.

Caught during PR 4 spec review where both sites had been migrated to
`notice_change()` based on a literal reading of the syntactic rule.
Fixing PR 4's commit follows in the next commit on this branch.

…inimize_for_statement.rs

Spec review on PR 4 flagged that for_stmt.body = drop_first_statement(...)
is a slot replacement (`for_stmt.body` is `Statement<'a>`), not an
in-place tweak — replace_statement applies, not notice_change. Plan
rule 1a (added in commit d18379e) makes this explicit.

…n helpers

…lpers

…helpers

… to mutation helpers

…elpers

…n helpers

Preserves the `dead_drop_mutates_ast` gate at line 22 — dropping
that gate would let the peephole fixed-point loop spin forever on
`var x;` declarations that `KeepVar` re-emits unchanged.

…pass sites

Pre-Commit-5 prerequisite for the incremental scoping refresh. The 4
Pattern A field-write bypasses in try_fold_if (test rewrite + alternate
install + consequent install + consequent empty) were deferred during
the Commit 2 bypass sweep because routing them through the typed helpers
(which bump state.mutations) would prevent fixed-point convergence.

Two distinct non-idempotency causes, each gated separately:

1. Test rewrite (was line 78): NumericLiteral(1.0 or 0.0) still
   re-evaluates to Some(true)/Some(false) via the enclosing
   evaluate_value_to_boolean predicate. Skip the rewrite when the test
   is already the canonical numeric form matching `boolean`, then route
   through replace_expression.

2. Var-hoisting (was lines 99/101): KeepVar re-extracts the same names
   from a fresh `var x, y;` it produced on the prior iteration, yielding
   a structurally-equivalent fresh allocation. Skip when the target slot
   is already in canonical KeepVar output shape (a `var` declaration
   whose declarators all lack initializers) -- new is_keep_var_canonical
   helper -- then route through replace_statement.

Two more sites in the test-has-side-effects branch:

3. `alternate = None` (was line 108) -> switched to Option::take +
   ctx.drop_statement; naturally idempotent (no-op when already None).

4. `consequent = empty` (was line 110) -> route through replace_statement
   gated on the consequent not already being EmptyStatement.

This closes the last 4 Pattern A bypasses in remove_dead_code.rs so
Commit 5 can delete LiveUsageCollector without leaking dead refs into
Scoping.

Verification:
- cargo build -p oxc_minifier -- clean
- cargo test -p oxc_minifier -- 504 pass
- cargo test -p oxc_mangler -- pass
- cargo clippy -p oxc_minifier -- pass (with #[expect(clippy::float_cmp)]
  on try_fold_if, matching the pre-existing convention in fold_constants.rs)
- just minsize -- zero delta (gate is invisible to output)
- ./tools/check_state_changed.sh -- pass
- cd crates/oxc_minifier && ast-grep scan -- pass
- Existing test_fold_if_statement case "if (false) { var a; console.log(a) }"
  -> "if (0) var a" exercises the previously-non-idempotent var-hoist path
  and converges (would have hit "Ran loop more than 10 times" debug_assert
  in compressor.rs otherwise).

…lector

Stop walking the entire live program in `exit_program` to rebuild resolved
references and direct-eval flags. Each `replace_*` / `drop_*` helper now feeds
a per-pass `PassDirty` accumulator that `exit_program` consumes directly:
dead resolved-reference ids are batch-removed from `Scoping` without any walk,
unresolved-by-name entries are confirmed via a small `NamedRefCollector` walk
only when any such candidate exists, and the direct-eval-flag refresh's
`LiveDirectEvalCollector` walk fires only when at least one direct eval call
was dropped this pass.

Implementation:

- `oxc_semantic::Scoping` grows two methods: `retain_resolved_references_excluding`
  (batch removal complementing the existing `retain_resolved_references` bitset
  variant) and `remove_unresolved_reference` (name-keyed pruning).
- `PeepholeOptimizations::exit_program` rewritten to consume `PassDirty`
  directly. `LiveUsageCollector` is gone; the bitset-of-all-refs allocation
  it built each pass is gone with it.
- `MinifierState::changed: bool` and `TraverseCtx::reset_changed` are removed;
  the fixed-point loop driver already snapshot-compares `state.mutations` from
  commit 3, and `exit_program` no longer needs the bool. Every walking helper
  now bumps just `mutations`.

Four leaked-reference sites that `LiveUsageCollector`'s whole-program walk
was silently covering were uncovered while bringing `just minsize` to zero
delta — they had to be fixed in this commit for the new path to be sound:

- `fold_constants.rs` `fold_chain_expr` `ChainFold::Collapse`: when the base
  has no side effects, the `take_in`'d base was thrown away instead of being
  preserved in the new expression. Added `ctx.drop_expression(&base)` before
  the discard.
- `minimize_conditional_expression.rs::minimize_conditional`: the transient
  `ConditionalExpression` built on the stack was being mutated by the fold
  (slot `take_in`s) and then discarded without any walk, leaking refs in
  untouched slots. Wrap the transient in an `Expression` slot so a successful
  fold can be installed via `ctx.replace_expression`, whose walks pair up
  correctly. This pattern ("transient AST node mutated then discarded")
  generalises to any future helper that materialises a fresh node only to
  destructure it.
- `remove_unused_expression.rs::fold_arguments_into_needed_expressions`: the
  filter_map drain dropped `Argument`s whose unwrapped expression
  `remove_unused_expression` collapsed to nothing — silently leaking refs in
  e.g. `pure(x)` where the manual-pure call is treeshaken and `x` would
  otherwise stay live in the symbol's resolved-references list. Replaced the
  filter_map with an explicit loop that `drop_expression`s discarded args.
- `remove_unused_declaration.rs::remove_unused_variable_declaration` +
  the matching for-statement-init retain in `minimize_statements.rs`: the
  `retain` predicate silently drops declarators whose init has refs (e.g.
  `var y = pure(x)` where the symbol is unused). Switched to `retain_mut`
  with an explicit `drop_expression(&init)` for removed declarators.

Allocs-snapshot drift is expected per spec §6.6 — `PassDirty`'s reusable
`FxHashSet`s replace the per-pass arena `BitSet`. `tasks/minsize/` shows
zero delta, confirming `PassDirty` is now sound for the full size-test
corpus.

BREAKING CHANGE: `MinifierState::changed: bool` and
`TraverseCtx::reset_changed` are removed; downstream consumers that read or
write `state.changed` should snapshot-compare `state.mutations` instead.

… to helpers

After rebasing onto origin/main, three new `state.changed = true` writes
added by upstream #22722 (dead-after-throw drop) survived the auto-merge
into our migrated `minimize_statements.rs`. The lockdown gate at
`tools/check_state_changed.sh` flags them.

Convert each to its appropriate per-helper equivalent:

- Dead-stmt-drop site: `ctx.drop_statement(&stmt)` — walks the dropped
  subtree to record dead references in PassDirty, satisfies the Pattern E
  contract this site was named after in the spec.
- Coalesced identity drops: `ctx.notice_change()` — the underlying
  mutations were already accounted for by `stmts.push` and inside
  `remove_unused_variable_declaration`; this is a pure 'flag the loop'
  intent.
- Re-hoist-then-remove None branch: `ctx.notice_change()` — same
  reasoning.

506 minifier tests pass (504 baseline + 2 new upstream tests:
dead_after_throw_drop_triggers_unused_declarator_removal and
test_preserve_cjs_module_lexer_hint).

Swaps `PassDirty::dead_refs` from `FxHashSet<ReferenceId>` to
`oxc_allocator::BitSet` sized at `enter_program` to
`scoping.references_len()`. The `dead_refs` lifetime is one pass —
arena allocation is the right shape.

Per-ident hot-path cost drops from `FxHashSet::insert/remove` (~25
cycles, hashed, heap) to `BitSet::set_bit/unset_bit` (~5 cycles,
direct array store, arena). System allocs drop on every workload.

Bench recovery on the regressing `react.development.js` case was
smaller than spec §6.3 Tier 1 predicted — the per-ident leaf cost
is not the dominant factor; the `DropDiff` traversal frequency (1.49×
more visits than the old single `LiveUsageCollector` walk) dominates.
Net measured improvement on react.dev: ~1pp (within noise). Other
workloads unchanged within noise. Worth landing as a correctness-
neutral micro-improvement; further work to reduce walk frequency
tracked separately.

Residual risk: mid-pass-created `ReferenceId` (e.g.
`substitute_chain_call_expression`'s `create_unbound_reference`) could
exceed the bitset capacity if later dropped in the same pass. The
`Scoping::retain_resolved_references_excluding` consumer ignores
out-of-range indices, but the `DropDiff::visit_identifier_reference`
hot path uses `debug_assert!` for the bounds check — verified safe by
probe `assert!` over the test corpus and `just minsize` corpus, no
trips. A proper overflow set is left as a follow-up if the assertion
ever trips in CI.

`mod lexer` is `pub(crate)` in the default build but `pub` under the
`benchmarking` feature. `clippy::redundant_pub_crate` therefore only fires
in the non-benchmarking build. Commit a486e42 added an unconditional
`#[expect]` to silence that; CI runs clippy with `--all-features`, where the
lint doesn't fire and the expectation becomes unfulfilled.

Gate the `#[expect]` with `#[cfg_attr(not(feature = "benchmarking"), …)]` so
both configurations are clean.

…places an identifier

Before the minifier's incremental-scoping refactor (#22736), the per-pass
`LiveUsageCollector` walked the live program at `exit_program` and rebuilt
`Scoping::resolved_references` from scratch. That walk silently masked the
fact that `ReplaceGlobalDefines` never told `Scoping` about the identifier
references it was replacing — the next minifier pass would simply recompute
them and find that the replaced identifier had no surviving occurrences.

With the LiveUsageCollector gone, only references that the minifier itself
drops via `replace_*`/`drop_*` helpers are pruned. References that callers
drop before `dead_code_elimination_with_scoping` get to run are now visible
as stale entries in `resolved_references`, and `symbol_is_unused` returns
`false` for symbols whose every textual occurrence has been replaced.

Concretely, the existing `replace_global_defines::declare_const` integration
test (added by #12427 to align with rollup) fails: the test expects the
`declare const IS_PROD: boolean;` line to be DCE'd after every reference to
`IS_PROD` is replaced with `true`, but the leaked references keep DCE from
seeing IS_PROD as unused.

The fix delegates reference deletion to the plugin: when
`replace_identifier_define_impl` returns a replacement value, the caller
captures the old identifier's `(reference_id, symbol_id, name)` BEFORE the
replacement and calls `Scoping::delete_reference` (resolved case) or
`delete_root_unresolved_reference` (truly global case) only AFTER the AST
mutation actually commits. The split matters at the assignment-target site —
`replace_define_with_assignment_expr` may bail when the replacement value
isn't a valid LHS (e.g. `IS_PROD = 0` with define `IS_PROD -> true` would
need `true = 0`, which `assignment_target_from_expr` rejects); the
reference must stay in that case.

New test `declare_const_assignment_target_bailout` pins the bail path.

… into PassDirty

After the incremental-scoping refactor, two peephole sites were still
silently dropping AST subtrees without telling `PassDirty` — so their
identifier references stayed in `Scoping::resolved_references` across
passes. The next pass would either inline what should have been a
multi-reference symbol (idempotency failure) or skip an inline that
should have fired (also idempotency failure).

Both surface as new test262 conformance failures only revealed when
`LiveUsageCollector` was deleted in commit 0856533:

- `expressions/await/syntax-await-in-ConditionalExpression` — the
  object literal `{ then: function() { x = 'unexpected'; … } }` gets
  removed via `let z = …` DCE, but the unused property values inside
  the object are dropped via `remove_unused_object_expr` without a
  `drop_expression` walk. Reference to `x` inside the dropped `then`
  function body leaks; `x`'s write-references count stays at 1 on the
  next pass; the constant-value inline for `let x = 'initial value'`
  is blocked. The second `dead_code_elimination` call then sees the
  correct count and inlines, producing different output.
- `expressions/in/private-field-presence-{accessor,method}-shadowed`,
  `class/elements/private-{accessor,field}-is-visible-in-computed-…`
  — `remove_unused_private_members` drops class elements via
  `Vec::retain` without walking the removed method/accessor bodies.
  Refs to outer-scope identifiers inside those bodies (e.g.
  `parentCount += 1` inside a removed `#method`) leak; the same
  idempotency-via-ref-count-drift effect ensues.

Fix:

1. `remove_unused_object_expr` calls `ctx.drop_expression` on each
   dropped property key (computed) and value before letting it fall
   off the end of the iteration.
2. `remove_unused_private_members` calls a new
   `TraverseCtx::drop_class_element` helper for every element it
   removes inside the `retain` predicate. The helper threads through a
   new `DropDiff::walk_old_class_element` entry that uses the default
   `Visit` walk to record refs and direct-eval calls.

Conformance: `cargo coverage -- minifier` returns to the main-branch
44795/44799 pass rate. Unit tests (506 + 2 doctests) all pass.
`allocs_minifier.snap` shifts by 2 sys allocs / -3 arena reallocs on
kitchen-sink.tsx — small, expected drift from the new
`drop_class_element` walk paths in classes-heavy files.

…s into PassDirty

Two more silent reference-drop sites surfaced by Codex adversarial
review of #22736, same bug class as the four fixed in 0856533 and
the two fixed in faaa4ba. Both sites mutated the AST through
`notice_change` only, even though the mutation discarded a subtree
that could carry identifier references — leaving stale entries in
`Scoping::resolved_references` across passes.

1. `remove_unused_array_expr` (`peephole/remove_unused_expression.rs`):
   the `retain_mut` predicate dropped a side-effect-free
   `ArrayExpressionElement::SpreadElement` without walking its
   `argument`. The `may_have_side_effects` check still uses the
   `ArrayExpressionElement` impl (so `[...ident]` is still treated as
   side-effecting via the iterator protocol and kept), but when the
   spread IS elided the argument now routes through
   `ctx.drop_expression`.

2. `fold_object_exp` (`peephole/fold_constants.rs`) had three skipped
   drop paths:
   - the `is_expression_undefined` short-circuit, which discarded the
     spread argument with `continue`,
   - the `should_fold_spread_element` branch, which dropped the
     argument with a bare `// skip` comment,
   - the inlined-object `__proto__` filter, which used
     `filter(...).collect` to drop non-computed `__proto__` properties
     and their value expressions.
   The first two now call `ctx.drop_expression(&spread.argument)`
   before continuing. The filter chain is rewritten as an explicit loop
   that calls `ctx.drop_expression(&p.value)` on each elided
   `__proto__` property; the property key is always a non-computed
   static name and carries no references.

Regression tests:

- `test_array_spread_drop_walks_argument_refs` in
  `tests/peephole/remove_unused_expression.rs` covers the elided
  spread path through nested array literals
  (`[...[function(){}]]`). Existing `MayHaveSideEffects` rules treat
  every spread shape that retains identifier refs as side-effecting,
  so there is no source-level case where the new walk is observable
  on stable inputs — the test is documented as defensive and
  conformance is the live discriminator.
- `test_fold_object_spread_drop_walks_argument_refs` in
  `tests/peephole/fold_constants.rs` covers the two
  ref-bearing fold paths: `{...function(){ x = 'b' }}` (path 2) and
  `{...{__proto__: function(){ x = 'b' }}}` (path 3). Without the
  fix, the stale write-reference on `x` blocks the constant inline
  on the follow-up pass and the test fails; with the fix, the inline
  fires.

Verification: `cargo coverage -- minifier` returns 44795/44799 (matches
main). Unit tests pass (508 + 2 doctests). `just minsize` shows zero
delta against the corpus snapshots. Clippy/fmt/ast-grep clean.

`replace_*` walked the replacement value to un-mark resolved references
that `walk_old_*` had marked dead. When `walk_old_*` marked nothing —
the common case, since survivors are moved out via `take_in`, leaving
reference-id-less dummies — that walk is a provable no-op over an often
large moved-in subtree. On react.development.js it was ~99% of the
per-mutation walk cost and the source of the incremental-scoping
regression.

Skip the walk when nothing was marked. Resurrect still runs at the only
id-aliasing site (the `clone_in_with_semantic_ids` fold), where the
original is marked dead, so the surviving clone is un-marked there.

minifier[react.development.js] -17.6%, kitchen-sink.tsx -2.8%,
cal.com.tsx -7.2%, binder.ts -9.9% vs branch HEAD. Output unchanged:
minsize bit-identical and conformance snapshots untouched.

Draining a catch body via clear() skipped the incremental dirty walk, so references removed from an unreachable catch block could remain live in scoping and block later DCE.

Route the dropped statements through drop_statement, and keep optional catch binding conservative when the rewrite leaves a same-name var in the catch body.

The per-pass `prune_unresolved_refs` walk (a full-program `NamedRefCollector`
pass) kept `Scoping::root_unresolved_references` accurate, but nothing observes
the result:

- `build_with_scoping` / `dead_code_elimination_with_scoping` take `scoping` by
  value and return `u8`, so the compressor's pruned scoping never escapes to any
  caller; `MinifierReturn.scoping` comes from the mangler's rebuilt semantic,
  not the compressor's.
- The only in-loop reader of `root_unresolved_references` is the UID generator,
  which is never invoked during minify (the `is_global_reference` checks read
  per-reference `symbol_id()`, not the map).
- main never pruned it (the prune and `remove_unresolved_reference` are new in
  this branch) yet minsize is bit-identical; disabling the walk leaves all unit
  tests, conformance snapshots, and minsize unchanged.

Remove the walk plus the now-unused `dead_unresolved` tracking,
`NamedRefCollector`, and `Scoping::remove_unresolved_reference`. This drops the
largest residual per-pass scoping cost on bundler/CJS inputs:
kitchen-sink.tsx -16.2%, cal.com.tsx -7.5%; react/binder unchanged (they never
trigger it). Output is unchanged (minsize bit-identical, conformance untouched).

Resolved-reference refresh (`dead_refs`) and direct-eval-flag refresh stay --
both are read in-loop and affect optimization decisions.

…prune

Removing `prune_unresolved_refs` and the `dead_unresolved` FxHashSet
(commit "drop unobserved unresolved-reference pruning") eliminates a few
per-file heap allocations. Sys allocs only: checker.ts 172->170, App.tsx
123->119, pdf.mjs 3937->3929, antd.js 3093->3084, kitchen-sink.tsx
1768->1756. Sys reallocs and arena allocs unchanged.

Values taken from the CI (Linux) run; not regenerated locally because
macOS reports different sys-alloc counts than the CI environment.

Add a debug-only check in `exit_program`: before
`retain_resolved_references_excluding` prunes the references marked dead this
pass, assert none of them still appear in the live program. A still-live
reference being pruned is the unsafe direction -- it leaves a symbol
under-referenced so a later pass can wrongly drop it, producing incorrect
output.

The resurrect-walk skip and the unresolved-prune removal both rest on
scoping-state invariants that minsize/conformance only check indirectly via
output. This walk runs once per dirty pass in debug builds only, so the unit
tests and the `cargo coverage -- minifier` corpus double as an over-prune
detector at zero release cost. Verified sound (forcing the resurrect walk to
skip makes it fire on test_fold_is_object_and_not_null) and silent across the
test262/babel/typescript corpus.

A >=3 element sequence kept in indirect-access position (e.g.
`(sideEffect(), 0, foo.bar)()`) re-wrapped its already-`0` second-to-last
element on every pass. Routing that through `replace_expression` bumps the
mutation counter each iteration, so the fixed-point loop never converges
and trips the 10-iteration debug_assert.

Skip the rewrite when the element is already `0`, mirroring the `len == 2`
guard above. `0` is side-effect-free so output is unchanged; this only
restores convergence (the spin is pre-existing on main).

The incremental scoping refresh trusts that the incoming `Scoping`
exactly matches the program; the deleted full walk used to self-heal any
staleness. Document this precondition on the `*_with_scoping` entry points
so external callers (e.g. rolldown) know they must keep scoping in sync
after mutating the program — a missing reference can cause incorrect
output, not just a missed optimization.

Also correct the resurrect-skip comment in drop_diff.rs: there are two
id-preserving sites (`clone_in_with_semantic_ids` and
`expression_identifier_with_reference_id`), not one, both harmless because
they install within a single `replace_expression` call.

Design for replacing the per-pass dead-ref bitset + batch list compaction
with a persistent, eagerly-initialized, live-maintained per-symbol
reference-count store inside SymbolValues. Counts are derived from the live
program once (self-healing), then maintained incrementally by the existing
DropDiff walk; Scoping's reference lists are left untouched.

Supersedes the consumption model from the incremental-scoping work on this
branch; gated on a minsize re-snapshot and a single-file benchmark.

Six-task implementation plan for the live-reference-counts design: add the
count store + eager program-walk init, maintain it in DropDiff as a shadow
validated by a count-drift debug assertion, switch consumers off Scoping's
lists, then delete the dead-ref bitset + batch retain. Benchmark-gated.