rigortype 0.1.17 → 0.1.19

data/lib/rigor/inference/statement_evaluator.rb

@@ -7,6 +7,7 @@ require_relative "../type"
 require_relative "../analysis/fact_store"
 require_relative "../source/node_walker"
 require_relative "block_parameter_binder"
+require_relative "body_fixpoint"
 require_relative "closure_escape_analyzer"
 require_relative "indexed_narrowing"
 require_relative "method_dispatcher"
@@ -98,10 +99,22 @@ module Rigor
         Prism::SingletonClassNode => :eval_singleton_class,
         Prism::CallNode => :eval_call,
         Prism::BlockNode => :eval_block,
+        Prism::ReturnNode => :eval_return,
         Prism::MatchWriteNode => :eval_match_write
       }.freeze
       private_constant :HANDLERS
 
+      # Thread-local sink (an Array) collecting the value types of explicit
+      # `return value` nodes reached while evaluating a method body, so
+      # `ExpressionTyper#infer_user_method_return` can join them into the
+      # method's inferred return type. The flow value of a `return` is still
+      # `Bot` (it transfers control rather than producing a value); the sink
+      # only records what the method *returns* through that edge. nil means
+      # "not collecting" — a top-level / DSL-block walk, or inside a nested
+      # `def` barrier (whose returns belong to the inner method).
+      RETURN_SINK_KEY = :rigor_return_sink
+      private_constant :RETURN_SINK_KEY
+
       # Lexical class frame: the `name:` field is the qualified class
       # name as it would render in Ruby (e.g., `"Foo::Bar"`); the
       # `singleton:` field is `true` for `class << self` frames so
@@ -121,11 +134,40 @@ module Rigor
       #   by {#eval_def} to look up the method's RBS signature. Each
       #   `ClassNode`/`ModuleNode` entry pushes a frame; `SingletonClassNode`
       #   over `self` flips the innermost frame to singleton mode.
-      def initialize(scope:, tracer: nil, on_enter: nil, class_context: [].freeze)
+      # @param converged_loop_recording [Boolean] when true (and an
+      #   `on_enter` recorder is installed), {#eval_loop} re-evaluates a
+      #   fixpoint-tracked loop body ONE extra time from the CONVERGED
+      #   bindings so the last-visit-wins per-node scope index reflects
+      #   the post-writeback state instead of the cap-N intermediate
+      #   assumption (`result *= i` annotating `1 | 2` rather than
+      #   `Integer`). Display-path only — `rigor check` leaves it off,
+      #   keeping its diagnostics and wall-clock unchanged.
+      def initialize(scope:, tracer: nil, on_enter: nil, class_context: [].freeze,
+                     converged_loop_recording: false)
         @scope = scope
         @tracer = tracer
         @on_enter = on_enter
         @class_context = class_context.freeze
+        @converged_loop_recording = converged_loop_recording
+      end
+
+      # Runs `block` with a fresh return sink installed, then yields the
+      # collected explicit-`return` value types to the caller. The sink is
+      # an array of `Rigor::Type`. Nested invocations stack: the previous
+      # sink is restored on exit so a `def` evaluated inside another method's
+      # body (which itself installed a sink) does not corrupt the outer one.
+      # Used by `ExpressionTyper#infer_user_method_return` to join the
+      # explicit returns into the inferred method-return type.
+      def self.with_return_sink
+        previous = Thread.current[RETURN_SINK_KEY]
+        sink = []
+        Thread.current[RETURN_SINK_KEY] = sink
+        begin
+          result = yield
+        ensure
+          Thread.current[RETURN_SINK_KEY] = previous
+        end
+        [result, sink]
       end
 
       # Evaluate `node` under the receiver scope. Returns `[type, scope']`
@@ -178,9 +220,28 @@ module Rigor
       # default branch in {#evaluate}.
       def eval_local_write(node)
         rhs_type, post_rhs = sub_eval(node.value, scope)
+        # ADR-58 WD1 — `r = @right` where `@right`'s optionality is purely
+        # declaration-sourced makes `r` declaration-sourced too (the survey's
+        # exact rotation/traversal shape `r = @right; r.key`). The mark is
+        # computed on the RHS *value*'s provenance — a pure ivar read of a
+        # currently declaration-sourced ivar — so it survives the local copy.
+        # Any other RHS (a call result, a method-local-nil-bearing value)
+        # leaves the local flow-live and the diagnostic fires as before.
+        if declaration_sourced_ivar_read?(node.value, post_rhs)
+          return [rhs_type, post_rhs.with_declaration_sourced_local(node.name, rhs_type)]
+        end
+
         [rhs_type, post_rhs.with_local(node.name, rhs_type)]
       end
 
+      # True when `value_node` is a bare instance-variable read whose binding
+      # in `scope_at_read` is currently marked declaration-sourced.
+      def declaration_sourced_ivar_read?(value_node, scope_at_read)
+        return false unless value_node.is_a?(Prism::InstanceVariableReadNode)
+
+        scope_at_read.declaration_sourced?(:ivar, value_node.name)
+      end
+
       # Slice 7 phase 1 — instance/class/global variable
       # writes. Each handler evaluates the rvalue under the
       # entry scope and binds the named variable into the
@@ -476,31 +537,19 @@ module Rigor
       # carriers like `Nominal[Integer]` (Integer is always truthy
       # in Ruby — including 0) also collapse the dead else.
       def live_branch_for_if(node, pred_type, post_pred)
-        case predicate_certainty(pred_type)
-        when :always_truthy then eval_branch_or_nil(node.statements, post_pred)
-        when :always_falsey then eval_branch_or_nil(node.subsequent, post_pred)
+        case Narrowing.predicate_certainty(pred_type)
+        when :truthy then eval_branch_or_nil(node.statements, post_pred)
+        when :falsey then eval_branch_or_nil(node.subsequent, post_pred)
         end
       end
 
       def live_branch_for_unless(node, pred_type, post_pred)
-        case predicate_certainty(pred_type)
-        when :always_truthy then eval_branch_or_nil(node.else_clause, post_pred)
-        when :always_falsey then eval_branch_or_nil(node.statements, post_pred)
+        case Narrowing.predicate_certainty(pred_type)
+        when :truthy then eval_branch_or_nil(node.else_clause, post_pred)
+        when :falsey then eval_branch_or_nil(node.statements, post_pred)
         end
       end
 
-      def predicate_certainty(pred_type)
-        return nil if pred_type.nil? || pred_type.is_a?(Type::Bot)
-
-        truthy_bot = Narrowing.narrow_truthy(pred_type).is_a?(Type::Bot)
-        falsey_bot = Narrowing.narrow_falsey(pred_type).is_a?(Type::Bot)
-
-        return :always_falsey if truthy_bot && !falsey_bot
-        return :always_truthy if !truthy_bot && falsey_bot
-
-        nil
-      end
-
       def eval_else(node)
         return [Type::Combinator.constant_of(nil), scope] if node.statements.nil?
 
@@ -518,12 +567,33 @@ module Rigor
         else_result = eval_case_else(node.else_clause, falsey_scope)
 
         all_results = [*branch_results, else_result]
+        branch_nodes = [*node.conditions, node.else_clause]
         [
           Type::Combinator.union(*all_results.map(&:first)),
-          reduce_scopes_with_nil_injection(all_results.map(&:last))
+          join_case_branch_scopes(all_results, branch_nodes)
         ]
       end
 
+      # Joins the post-scopes of every `when`/`in`/`else` branch, dropping
+      # the scope of any branch that terminates (raises / returns / throws /
+      # types to `Bot`) before the merge — control never falls through such
+      # a branch, so its half-bound locals must not nil-inject the names a
+      # live sibling branch assigned. Mirrors the `branch_terminates?` rule
+      # `eval_if`/`eval_unless` already apply to the if/else merge: e.g.
+      # `case x; when 1 then v="a"; when 2 then v="b"; else raise; end`
+      # keeps `v: "a" | "b"` instead of `... | nil`. When every branch
+      # terminates the merge is itself unreachable; fall back to the full
+      # join so the continuation scope stays well-formed.
+      def join_case_branch_scopes(results, nodes)
+        live = []
+        results.each_with_index do |(type, branch_scope), i|
+          live << branch_scope unless branch_terminates?(nodes[i], type)
+        end
+
+        live = results.map(&:last) if live.empty?
+        reduce_scopes_with_nil_injection(live)
+      end
+
       def eval_case_when_branches(subject, conditions, entry_scope)
         results = []
         falsey_scope = entry_scope
@@ -822,13 +892,204 @@ module Rigor
       # common case where no `break VALUE` is observed.
       def eval_loop(node)
         _pred_type, post_pred = sub_eval(node.predicate, scope)
-        return [Type::Combinator.constant_of(nil), post_pred] if node.statements.nil?
-
+        return [Type::Combinator.constant_of(nil), narrow_loop_exit_edge(node, post_pred)] if node.statements.nil?
+
+        # The historical single body pass joined with the pre-loop scope.
+        # This continues to carry everything the fixpoint does NOT track:
+        # receiver-mutation widening of non-rebound locals (`buf.push(i)`
+        # widens `buf`'s Tuple), body-introduced locals' nil-injection, and
+        # the loop value itself. The fixpoint then OVERLAYS only the
+        # rebound-local bindings it corrects.
         _body_type, body_scope = sub_eval(node.statements, post_pred)
-        [
-          Type::Combinator.constant_of(nil),
-          join_with_nil_injection(post_pred, body_scope)
-        ]
+        base_scope = join_with_nil_injection(post_pred, body_scope)
+
+        rebound, body_first = loop_body_local_writes(node.statements, post_pred)
+        names = rebound + body_first
+
+        # Fast path: a loop whose body rebinds no local skips the rebind
+        # fixpoint, but still needs the slice-C content writeback (a loop may
+        # content-mutate a collection without rebinding any local — `acc <<
+        # x`), so apply it to the single-pass join before returning.
+        if names.empty?
+          fast = loop_content_writeback(node.statements, base_scope)
+          return [Type::Combinator.constant_of(nil), narrow_loop_exit_edge(node, fast)]
+        end
+
+        # ADR-56 slice B — loop-body fixpoint. The body runs 0..N times and
+        # may compound (`d *= 2`), so the historical single body pass joined
+        # with the pre-loop scope kept stale folded constants
+        # (`d = 1; while …; d *= 2; end` → `1 | 2`, never reaching `4, 8`).
+        # Fold each body-written local's continuation binding through the
+        # same capped fixpoint slice A uses for non-escaping block captures.
+        #
+        # Seed: a pre-existing local seeds with its post-predicate binding;
+        # a local FIRST assigned inside the body seeds with `nil` so the
+        # 0-iteration path (the body may never run) degrades it to
+        # `T | nil`, matching the historical nil-injection treatment.
+        result = loop_rebind_fixpoint(node, post_pred, names, body_first)
+        # Display-path re-record: the fixpoint's body re-evaluations fire
+        # `on_enter` with the cap-N INTERMEDIATE assumptions, so the
+        # last-visit-wins scope index would annotate loop-body lines with
+        # stale pre-convergence constants. One extra pass from the
+        # converged bindings (result discarded) re-records the body's
+        # entry scopes post-writeback.
+        record_converged_loop_body(node, post_pred, result, names, body_first)
+        post_loop = result.reduce(base_scope) { |acc, (name, type)| acc.with_local(name, type) }
+        # ADR-56 slice C — loop-body receiver-content element-type join. A
+        # loop that content-mutates a collection (`acc << n`) keeps only the
+        # seed's element types after the single-pass widen (B1 unsoundness:
+        # `acc = [0]; while …; acc << n; end` → `Array[0]`, runtime
+        # `[0, n, …]`). Join the appended/stored types into the continuation
+        # collection. Pre-state is read from `post_loop` so a local both
+        # rebound and content-mutated composes.
+        post_loop = loop_content_writeback(node.statements, post_loop)
+        post_loop = narrow_loop_exit_edge(node, post_loop)
+        [Type::Combinator.constant_of(nil), post_loop]
+      end
+
+      # Item 4 — loop-exit predicate narrowing. A `while pred` / `until pred`
+      # loop exits PRECISELY on the predicate's exit edge: `while` exits when
+      # `pred` is falsey, `until` when `pred` is truthy. So after the loop the
+      # predicate-assignment target carries the exit polarity — `until line =
+      # io.gets; …; end; line.foo` reads `line` non-nil because the loop ran
+      # until `gets` returned a truthy (non-nil) line. Apply the exit edge of
+      # `Narrowing.predicate_scopes` to the continuation scope.
+      #
+      # Guarded against `break`: a `break` exits the loop WITHOUT the predicate
+      # ever going false (`while line = gets; break if done; end` can leave
+      # `line` truthy on a `while`, or exit before the `until` predicate fires),
+      # so the exit-edge proof does not hold and the loop is left un-narrowed.
+      # `break` inside a NESTED loop/block does not target this loop, but a
+      # nested-loop `break` is rare in predicate-assignment loops and the
+      # conservative bail only costs precision, never soundness.
+      def narrow_loop_exit_edge(node, post_loop)
+        return post_loop if loop_body_breaks?(node.statements)
+
+        truthy_scope, falsey_scope = Narrowing.predicate_scopes(node.predicate, post_loop)
+        node.is_a?(Prism::UntilNode) ? truthy_scope : falsey_scope
+      end
+
+      # True when the loop body can `break` out of THIS loop. Conservatively
+      # treats any `BreakNode` under the body as a break for this loop (a
+      # break inside a nested loop/block actually targets the inner construct,
+      # but bailing is precision-only).
+      def loop_body_breaks?(statements)
+        return false if statements.nil?
+
+        found = false
+        Source::NodeWalker.each(statements) do |descendant|
+          found = true if descendant.is_a?(Prism::BreakNode)
+        end
+        found
+      end
+
+      # Joins loop-body content mutations into the continuation collection
+      # bindings. The mutator arguments are typed against `post_loop`, whose
+      # locals already carry the loop-body fixpoint widening (so an
+      # appended `n` that the loop decrements types `Integer`, not its
+      # entry `Constant[3]` — otherwise only the first iteration's value
+      # would be captured, an unsound under-approximation). Pre-state is
+      # read from `post_loop` too. A loop body shares the surrounding scope,
+      # so the receiver is any `LocalVariableReadNode` (no depth filter).
+      def loop_content_writeback(statements, post_loop)
+        return post_loop if statements.nil?
+
+        mutations = Hash.new { |h, k| h[k] = [] }
+        Source::NodeWalker.each(statements) do |descendant|
+          name, node = content_mutation_target(descendant) { |_r| true }
+          mutations[name] << node unless name.nil?
+        end
+        return post_loop if mutations.empty?
+
+        mutations.reduce(post_loop) do |acc, (name, calls)|
+          joined = join_content_for_local(name, calls, acc, post_loop)
+          joined.nil? ? acc : acc.with_local(name, joined)
+        end
+      end
+
+      # Re-evaluates the loop body once from the converged fixpoint
+      # bindings, solely for the `on_enter` side effect of re-recording
+      # the body's per-node entry scopes. Gated behind the
+      # display-path-only `converged_loop_recording` flag so the check
+      # path neither pays the extra body evaluation nor risks any
+      # diagnostic drift.
+      def record_converged_loop_body(node, post_pred, bindings, names, body_first)
+        return unless @converged_loop_recording && @on_enter
+
+        loop_body_exit_bindings(node, post_pred, bindings, names, body_first)
+        nil
+      end
+
+      # Runs the slice-B loop-body rebind fixpoint, returning the per-name
+      # continuation binding. Seed: a pre-existing local seeds with its
+      # post-predicate binding; a local FIRST assigned inside the body seeds
+      # with `nil` so the 0-iteration path (the body may never run) degrades
+      # it to `T | nil`, matching the historical nil-injection treatment.
+      def loop_rebind_fixpoint(node, post_pred, names, body_first)
+        nil_const = Type::Combinator.constant_of(nil)
+        seed = names.to_h { |name| [name, post_pred.local(name) || nil_const] }
+        BodyFixpoint.converge(
+          names: names,
+          seed_bindings: seed,
+          widen: Type::Combinator.method(:widen_value_pinned),
+          evaluate_body: ->(bindings) { loop_body_exit_bindings(node, post_pred, bindings, names, body_first) }
+        )
+      end
+
+      # Names of locals the loop body can rebind, partitioned into those
+      # already bound in `base_scope` (their pre-loop binding seeds the
+      # fixpoint) and those FIRST assigned inside the body (no pre-state, so
+      # they seed with `nil` for 0-iteration soundness). A loop body
+      # introduces no new binding scope — every write leaks to the
+      # surrounding scope — so unlike a block there is no introduced-name
+      # filter; every local-write form under the body node counts.
+      def loop_body_local_writes(statements, base_scope)
+        pre_existing = []
+        body_first = []
+        Source::NodeWalker.each(statements) do |descendant|
+          next unless LOCAL_WRITE_NODES.any? { |klass| descendant.is_a?(klass) }
+
+          name = descendant.name
+          if base_scope.locals.key?(name)
+            pre_existing << name
+          else
+            body_first << name
+          end
+        end
+        [pre_existing.uniq, body_first.uniq - pre_existing.uniq]
+      end
+
+      # Evaluates the loop body once with each fixpoint-tracked local bound
+      # to the supplied running assumption and returns the per-name exit
+      # binding. Used as the {BodyFixpoint} body-evaluator for `eval_loop`.
+      #
+      # The body runs from `post_pred` overlaid with the assumptions, then
+      # narrowed by the predicate's loop-entry edge: a `while` body only
+      # runs when the predicate is TRUTHY, an `until` body only when it is
+      # FALSEY. Re-applying that narrowing per iteration keeps loop-carried
+      # narrowing sound — without it, an accumulator whose rebind can
+      # introduce `nil` (`prefix = idx ? prefix[0, idx] : nil` under
+      # `while prefix && …`) would re-enter the body with `nil` un-narrowed
+      # and false-fire `possible nil receiver` on the guarded re-read. The
+      # historical single body pass (which seeds these locals from their
+      # never-nil pre-loop binding) did not need this; the fixpoint, which
+      # feeds the widened assumption back in, does.
+      #
+      # A body-FIRST local (no pre-loop binding) is deliberately NOT overlaid
+      # into the body-entry scope: when the body runs it assigns the local
+      # before any use, exactly as the historical single body pass saw it.
+      # Its `nil` seed exists only to model the 0-iteration path and is kept
+      # as a join constituent by {BodyFixpoint#converge}; feeding that `nil`
+      # back into the body re-evaluation would leak it past a condition-form
+      # assignment the engine does not thread into the branch (`if exps.size
+      # > (count = 3)`), false-firing `+`/nil-receiver on the guarded use.
+      def loop_body_exit_bindings(node, post_pred, bindings, names, body_first)
+        overlaid = bindings.except(*body_first)
+        entry = overlaid.reduce(post_pred) { |acc, (name, type)| acc.with_local(name, type) }
+        truthy_scope, falsey_scope = Narrowing.predicate_scopes(node.predicate, entry)
+        body_entry = node.is_a?(Prism::UntilNode) ? falsey_scope : truthy_scope
+        _type, exit_scope = sub_eval(node.statements, body_entry)
+        names.to_h { |name| [name, exit_scope.local(name)] }
       end
 
       # `for index in collection; body; end`. Unlike `each {}` blocks,
@@ -1058,8 +1319,18 @@ module Rigor
         # like a singleton-side call. Observed surfacing 915 false
         # positives in `prism-1.9.0`'s auto-generated `copy`
         # methods alone.
-        sub_eval(node.parameters, body_scope, class_context: @class_context) if node.parameters
-        sub_eval(node.body, body_scope, class_context: @class_context) if node.body
+        # A nested `def` is a return barrier: its body's `return`s belong to
+        # the inner method, not the one currently being inferred. Suspend the
+        # return sink across the nested body so `eval_return` does not record
+        # them into the outer method's return type.
+        outer_sink = Thread.current[RETURN_SINK_KEY]
+        Thread.current[RETURN_SINK_KEY] = nil
+        begin
+          sub_eval(node.parameters, body_scope, class_context: @class_context) if node.parameters
+          sub_eval(node.body, body_scope, class_context: @class_context) if node.body
+        ensure
+          Thread.current[RETURN_SINK_KEY] = outer_sink
+        end
         [Type::Combinator.constant_of(node.name), scope]
       end
 
@@ -1081,6 +1352,11 @@ module Rigor
       # observe the outer scope, matching Ruby evaluation order.
       def eval_call(node)
         call_type = scope.type_of(node, tracer: tracer)
+        # ADR-56 slice C (B3) — `each_with_object(memo) { |x, acc| acc << … }`
+        # returns the memo; the engine otherwise types the call `Dynamic[top]`.
+        # Compute the joined memo type from the block's content mutations of
+        # the memo block-param and adopt it as the call's return type.
+        call_type = each_with_object_return(node, call_type)
         evaluate_block_if_present(node)
         # `ruby2_keywords def foo(...)` (and similar wrappers like
         # `private def`, `public def`, `module_function def`) parse
@@ -1098,6 +1374,14 @@ module Rigor
         # `self_type` for the def's body.
         evaluate_def_arguments(node)
         post_scope = record_closure_escape_if_any(node)
+        # ADR-56 slice A — non-escaping block captured-local write-back.
+        # A `:non_escaping` block (each / times / upto / map …) that
+        # rebinds an outer local must not leave that local's pre-call
+        # binding unmodified in the continuation scope; the spec MUST in
+        # § "Fact stability and mutation" names captured locals a
+        # first-class invalidation category. (The escaping / unknown path
+        # already widened to Dynamic[top] via `record_closure_escape_if_any`.)
+        post_scope = write_back_block_captures(node, post_scope)
         post_scope = apply_rbs_extended_assertions(node, post_scope)
         post_scope = apply_plugin_assertions(node, post_scope)
         post_scope = apply_rspec_matcher_narrowing(node, post_scope)
@@ -1108,6 +1392,18 @@ module Rigor
         # justification when the value is mutated. Always-safe
         # (loses precision, never invents facts).
         post_scope = MutationWidening.widen_after_call(call_node: node, current_scope: post_scope)
+        # ADR-57 slice 3 work-item 1 (cross-method-boundary variant). When a
+        # self-call resolves to a user method that CONTENT-mutates one of its
+        # parameters inside an escaping block (the `build_option_parser(opts)`
+        # idiom — the callee returns an `OptionParser` whose
+        # `opts.on { o[:k] = v }` blocks close over the passed-in hash), floor
+        # the matching caller-argument local. The callee's escape is invisible
+        # across the boundary, so without this the caller's `options` keeps its
+        # seed and `options.fetch(:mode)` folds to a wrong constant. Precise:
+        # fires only when the resolved callee actually escape-mutates that
+        # parameter (not for every self-call), and sound — only loses
+        # precision on the floored argument.
+        post_scope = widen_callee_escaped_argument_captures(node, post_scope)
         # And the same widening for outer-scope locals / ivars
         # mutated inside the block body (`items.each { |x| arr << x }`):
         # the block lives in a child scope so without an explicit
@@ -1116,6 +1412,14 @@ module Rigor
         # precision — so blindly applying is safe regardless of
         # whether the block actually runs.
         post_scope = MutationWidening.widen_after_block(call_node: node, outer_scope: post_scope)
+        # ADR-56 slice C — receiver-content element-type join. The widening
+        # above forgets a content-mutated collection's literal arity but
+        # keeps only the seed's element types (the B1 unsound under-
+        # approximation for a non-empty seed). Join the appended / stored
+        # element / key / value types into the continuation collection's
+        # parameter so `out = [0]; arr.each { |x| out << x }` types
+        # `Array[0 | Integer]`, not `Array[0]`. Always sound — only widens.
+        post_scope = content_writeback_block_captures(node, post_scope)
         # Indexed-collection narrowing — drop any
         # `receiver[key] ||= default` narrowing the analyzer
         # recorded earlier when an intervening `[]=` writes the
@@ -1142,9 +1446,47 @@ module Rigor
         # new facts). See [`docs/CURRENT_WORK.md`](../../../docs/CURRENT_WORK.md)
         # § "Flow-folding" — G2 intervening-call case.
         post_scope = invalidate_ivars_for_intervening_call(node, post_scope)
+        # C1 — regex match-data globals (`$~`, `$1..$9`, `$&`, …) are
+        # narrowed to non-nil on a successful-match edge; a later call
+        # that itself runs a regex match rebinds them, so the narrowed
+        # facts must be dropped. We forget them only when the call is
+        # match-CAPABLE (a regex-matching method, or an implicit-self /
+        # unknown-receiver call whose body we cannot prove match-free).
+        # A call provably match-free on a known receiver — `$3.to_i`,
+        # `year < 50` — does NOT clobber, so the multi-statement
+        # `m = /…/ =~ s; …; use($2)` stdlib idiom keeps its precision
+        # while a genuinely interposed match still invalidates.
+        post_scope = post_scope.forget_match_globals if match_capable_call?(node)
         [call_type, post_scope]
       end
 
+      # Method names that (may) run a regex match and therefore rebind
+      # the `$~` family. Conservative over-approximation — a few set
+      # globals only with a Regexp argument, but we do not inspect args.
+      MATCH_CAPABLE_METHODS = %i[
+        =~ match match? gsub gsub! sub sub! scan split slice slice!
+        [] partition rpartition index rindex === grep grep_v
+      ].freeze
+      private_constant :MATCH_CAPABLE_METHODS
+
+      # True when `node` could rebind the regex match-data globals:
+      # a known regex-matching method by name, or an implicit-self /
+      # self-receiver call whose body we cannot inspect for an internal
+      # match. An explicit-receiver call to a non-matching method
+      # (`$3.to_i`, `year < 50`, `buf << c`) is treated as match-free so
+      # the multi-statement `m = /…/ =~ s; …; use($2)` idiom keeps the
+      # narrowed globals. The over-approximation is one-directional: a
+      # user method that secretly matches on an explicit receiver is the
+      # only escape, and re-narrowing on the next real guard recovers —
+      # weighed against the false-positive cost, precision wins here.
+      def match_capable_call?(node)
+        return true unless node.is_a?(Prism::CallNode)
+        return true if MATCH_CAPABLE_METHODS.include?(node.name)
+
+        receiver = node.receiver
+        receiver.nil? || receiver.is_a?(Prism::SelfNode)
+      end
+
       # Returns a scope with each ivar's narrowed local binding
       # widened back to its class-ivar seed value when the call
       # is one that could plausibly mutate ivars on the enclosing
@@ -1421,10 +1763,9 @@ module Rigor
         end
       end
 
-      # ADR-37 slice 2 — gathers each plugin's post-return narrowing from
-      # BOTH the narrow `type_specifier` DSL (method-gated, wrapped as a
-      # facts-only `FlowContribution`) and the legacy
-      # `flow_contribution_for` escape valve, swallowing per-plugin
+      # ADR-37 slice 2 / ADR-52 WD3 — gathers each plugin's post-return
+      # narrowing from the method-gated `type_specifier` DSL, wrapped as
+      # a facts-only `FlowContribution`, swallowing per-plugin
       # exceptions so a buggy plugin can't abort the assertion path.
       EMPTY_CONTRIBUTIONS = [].freeze
       private_constant :EMPTY_CONTRIBUTIONS
@@ -1432,8 +1773,11 @@ module Rigor
       # Per-dispatch collection of plugin narrowing contributions. Mirrors
       # `MethodDispatcher#collect_plugin_contributions`: visit only the
       # registry-ordered subset of plugins that implement a per-call path
-      # (`for_statement` = overrides `flow_contribution_for` or declares a
-      # `type_specifier`), gate each path by membership, and accumulate
+      # (`for_statement` = declares a `type_specifier`), gate each path
+      # by membership AND by the ADR-52 WD1 method-name gates (every
+      # `type_specifier` rule is `methods:`-gated, so the common
+      # no-candidate case is a single Set probe; a pruned
+      # consultation could only have returned `[]`), and accumulate
       # lazily (shared frozen empty array otherwise). Same contributions in
       # the same order as visiting every plugin; the caller is read-only.
       def collect_plugin_contributions(registry, call_node, current_scope)
@@ -1441,16 +1785,21 @@ module Rigor
         relevant = index.for_statement
         return EMPTY_CONTRIBUTIONS if relevant.empty?
 
+        name = call_node.respond_to?(:name) ? call_node.name : nil
+        return EMPTY_CONTRIBUTIONS unless index.statement_candidate?(name)
+
+        collect_gated_statement_contributions(index, relevant, name, call_node, current_scope)
+      end
+
+      # The post-gate walk, in registry order — the same order the
+      # ungated walk used.
+      def collect_gated_statement_contributions(index, relevant, name, call_node, current_scope)
         result = nil
         relevant.each do |plugin|
-          if index.flow?(plugin)
-            legacy = plugin.flow_contribution_for(call_node: call_node, scope: current_scope)
-            (result ||= []) << legacy if legacy.is_a?(Rigor::FlowContribution)
-          end
-          if index.type_specifier?(plugin)
-            facts = plugin.type_specifier_facts(call_node: call_node, scope: current_scope)
-            (result ||= []) << Rigor::FlowContribution.new(post_return_facts: facts) if facts && !facts.empty?
-          end
+          next unless index.type_specifier_candidate_for?(plugin, name)
+
+          facts = plugin.type_specifier_facts(call_node: call_node, scope: current_scope)
+          (result ||= []) << Rigor::FlowContribution.new(post_return_facts: facts) if facts && !facts.empty?
         rescue StandardError
           next
         end
@@ -1611,12 +1960,25 @@ module Rigor
       # A `:non_escaping` classification (or any block-less call)
       # leaves the post-call scope unchanged.
       def record_closure_escape_if_any(node)
-        return scope unless node.block.is_a?(Prism::BlockNode)
+        # ADR-57 slice 3 work-item 1: an escaping block can also be attached
+        # to a RECEIVER call in a chain rather than to `node` itself — the
+        # canonical `OptionParser.new do |opts| opts.on { o[:k] = v } end
+        # .parse!(argv)` idiom, where the content-mutating block hangs off
+        # `OptionParser.new` but the statement-level call node is the chained
+        # `.parse!`. A receiver call is evaluated as an expression, never as a
+        # statement, so its block never reaches this escape handler on its own.
+        # Fold each escaping receiver-chain block's content widening into the
+        # continuation here so the captured collection is floored regardless of
+        # how deep in the receiver chain its mutating block lives.
+        post_scope = widen_escaping_receiver_chain_captures(node, scope)
+
+        return post_scope unless node.block.is_a?(Prism::BlockNode)
 
         classification = classify_closure_escape(node)
-        return scope if classification == :non_escaping
+        return post_scope if classification == :non_escaping
 
-        post_scope = drop_captured_narrowing(node.block, scope)
+        post_scope = drop_captured_narrowing(node.block, post_scope)
+        post_scope = widen_escaping_content_captures(node.block, post_scope)
         post_scope.with_fact(
           Analysis::FactStore::Fact.new(
             bucket: :dynamic_origin,
@@ -1628,6 +1990,224 @@ module Rigor
         )
       end
 
+      # Floor each caller-argument local whose matching parameter the resolved
+      # callee escape-mutates (see the call-site comment). Only self-dispatch
+      # calls resolving to a discovered user def are considered; the per-def
+      # "which parameters escape-mutate" set is memoised on the def node.
+      def widen_callee_escaped_argument_captures(node, base_scope)
+        # Apply to the statement call AND every call in its receiver chain: the
+        # `build_option_parser(options).parse!(argv)` idiom puts the escape-
+        # mutating helper call in the RECEIVER position, where its argument is
+        # never the statement node's own argument.
+        acc = floor_callee_escaped_args_for_call(node, base_scope)
+        receiver = node.receiver
+        while receiver.is_a?(Prism::CallNode)
+          acc = floor_callee_escaped_args_for_call(receiver, acc)
+          receiver = receiver.receiver
+        end
+        acc
+      end
+
+      def floor_callee_escaped_args_for_call(node, base_scope)
+        return base_scope unless self_dispatch_call?(node)
+        # Fast path — the floor only ever touches a local passed as an
+        # argument, so a call with no arguments cannot floor anything. Skip the
+        # def resolution + body scan entirely (the overwhelming common case).
+        return base_scope unless call_passes_local_argument?(node)
+
+        def_node = resolve_self_callee_def(node)
+        return base_scope if def_node.nil?
+
+        escaped = escaped_content_parameters(def_node)
+        return base_scope if escaped.empty?
+
+        floor_arguments_at_positions(node, escaped, base_scope)
+      end
+
+      # The user def a self-dispatch `node` resolves to in the enclosing class,
+      # or nil. Reuses the discovery index `Scope#user_def_for` reads; no
+      # ancestor walk (the boundary-escape idiom is same-class), keeping this
+      # off the hot path for the overwhelming majority of self-calls that
+      # resolve to nothing escaping.
+      def resolve_self_callee_def(node)
+        class_name = enclosing_class_name_for(scope.self_type)
+        return scope.top_level_def_for(node.name) if class_name.nil?
+
+        scope.user_def_for(class_name, node.name)
+      end
+
+      def self_dispatch_call?(node)
+        return false unless node.is_a?(Prism::CallNode)
+
+        node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
+      end
+
+      # The set of `[name, position]` parameters of `def_node` whose content a
+      # block in the body escape-mutates. Memoised per def node (the body walk
+      # is otherwise repeated at every call site). A parameter is "escape-
+      # mutated" when a `param[k] = v` / `param << x` mutation on it appears
+      # inside a block whose receiving call is not proven non-escaping.
+      def escaped_content_parameters(def_node)
+        cache = (@escaped_param_cache ||= {}.compare_by_identity)
+        cache[def_node] ||= compute_escaped_content_parameters(def_node)
+      end
+
+      def compute_escaped_content_parameters(def_node)
+        positions = positional_parameter_positions(def_node)
+        return {} if positions.empty?
+
+        mutated = Set.new
+        Source::NodeWalker.each(def_node.body) do |descendant|
+          next unless descendant.is_a?(Prism::CallNode) && descendant.block.is_a?(Prism::BlockNode)
+          next if syntactically_non_escaping_call?(descendant)
+
+          collect_content_mutations(descendant.block.body).each_key do |name|
+            mutated << name if positions.key?(name)
+          end
+        end
+        positions.slice(*mutated)
+      end
+
+      # A receiver-independent over-approximation of `ClosureEscapeAnalyzer`'s
+      # non-escaping verdict, used when scanning a callee body where the block-
+      # owning call's receiver TYPE is not available. A call whose method name
+      # is a known structural iterator (`each` / `map` / `tap` / …) runs its
+      # block synchronously and does not retain it, so its captured mutations
+      # are not a cross-boundary escape. Any other name (`on`, `subscribe`,
+      # `define_method`, an unknown DSL hook) is treated as escaping — sound,
+      # since mis-classifying a truly-non-escaping call only floors an argument
+      # that was about to be precise.
+      SYNTACTIC_NON_ESCAPING_BLOCK_METHODS = (
+        ClosureEscapeAnalyzer::ENUMERABLE_NON_ESCAPING +
+        ClosureEscapeAnalyzer::OBJECT_NON_ESCAPING +
+        ClosureEscapeAnalyzer::ARRAY_EXTRA +
+        ClosureEscapeAnalyzer::HASH_EXTRA +
+        ClosureEscapeAnalyzer::RANGE_EXTRA +
+        ClosureEscapeAnalyzer::INTEGER_EXTRA
+      ).to_set.freeze
+      private_constant :SYNTACTIC_NON_ESCAPING_BLOCK_METHODS
+
+      def syntactically_non_escaping_call?(call_node)
+        SYNTACTIC_NON_ESCAPING_BLOCK_METHODS.include?(call_node.name)
+      end
+
+      # `{ name => position }` for the required / optional positional
+      # parameters of a def. Keyword / rest / block parameters are skipped —
+      # the boundary-escape idiom passes a plain positional collection.
+      def positional_parameter_positions(def_node)
+        params = def_node.parameters
+        return {} if params.nil?
+
+        ordered = (params.requireds || []) + (params.optionals || [])
+        positions = {}
+        ordered.each_with_index do |param, index|
+          positions[param.name] = index if param.respond_to?(:name)
+        end
+        positions
+      end
+
+      # True when at least one argument of `node` is a bare local-variable read
+      # (positional or keyword value) bound in the current scope — a cheap
+      # pre-filter so the def resolution / body scan only runs for calls that
+      # could actually floor something.
+      def call_passes_local_argument?(node)
+        args = node.arguments
+        return false unless args.respond_to?(:arguments)
+
+        args.arguments.any? do |arg|
+          case arg
+          when Prism::LocalVariableReadNode
+            scope.locals.key?(arg.name)
+          when Prism::KeywordHashNode
+            arg.elements.any? do |pair|
+              pair.is_a?(Prism::AssocNode) &&
+                pair.value.is_a?(Prism::LocalVariableReadNode) &&
+                scope.locals.key?(pair.value.name)
+            end
+          else
+            false
+          end
+        end
+      end
+
+      def floor_arguments_at_positions(node, positions, base_scope)
+        args = node.arguments
+        return base_scope unless args.respond_to?(:arguments)
+
+        argument_nodes = args.arguments
+        positions.values.uniq.reduce(base_scope) do |acc, index|
+          arg = argument_nodes[index]
+          next acc unless arg.is_a?(Prism::LocalVariableReadNode) && acc.locals.key?(arg.name)
+
+          floored = content_floor_for(acc.local(arg.name))
+          floored.nil? ? acc : acc.with_local(arg.name, floored)
+        end
+      end
+
+      # Walk the receiver chain of `node` and fold the escaping-content
+      # widening of every block-bearing, escaping receiver call into
+      # `base_scope`. Only receiver calls are walked — `node` itself is handled
+      # by the caller. A `:non_escaping` receiver block is left to slice C's
+      # non-escaping write-back (which the receiver expression evaluation
+      # already drives), so we only floor the escaping / unknown ones here.
+      def widen_escaping_receiver_chain_captures(node, base_scope)
+        receiver = node.receiver
+        acc = base_scope
+        while receiver.is_a?(Prism::CallNode)
+          if receiver.block.is_a?(Prism::BlockNode) &&
+             classify_closure_escape(receiver) != :non_escaping
+            acc = widen_escaping_content_captures(receiver.block, acc)
+          end
+          receiver = receiver.receiver
+        end
+        acc
+      end
+
+      # ADR-57 slice 2 (ADR-56 mechanisms 2 / 8 extended to escaping blocks).
+      # An escaping / unknown block that CONTENT-mutates a captured outer
+      # local (`options[:k] = v` in an `OptionParser#on` block, `s << x` in a
+      # stored proc) previously left that local's content untouched — only its
+      # narrowing was dropped, so a constant seed (`options = {}`, `s = ""`)
+      # survived and its element fold (`options[:format]` -> `"text"`,
+      # `s.empty?` -> `true`) was unsoundly precise.
+      #
+      # An escaping block may run later and any number of times, so joining a
+      # bounded evidence set is not sound (unlike slice C's non-escaping
+      # join): the sound continuation is the bare-collection floor — Array ->
+      # `Array[Dynamic[top]]`, Hash -> `Hash[untyped, untyped]`, String ->
+      # `String`. The seed's element/key/value precision is forgotten; only
+      # the carrier survives. Read-only captures and locals the block merely
+      # rebinds (already floored by `drop_captured_narrowing`) are untouched.
+      def widen_escaping_content_captures(block_node, post_scope)
+        body = block_node.body
+        return post_scope if body.nil?
+
+        mutations = collect_content_mutations(body)
+        return post_scope if mutations.empty?
+
+        mutations.keys.reduce(post_scope) do |acc, name|
+          floored = content_floor_for(acc.local(name))
+          floored.nil? ? acc : acc.with_local(name, floored)
+        end
+      end
+
+      # The Dynamic-floor carrier for a content-mutated escaping capture, or
+      # nil when the pre-state is not a recognised mutable collection (leave
+      # it alone — e.g. an already-`Dynamic` binding or an unknown shape).
+      def content_floor_for(type)
+        return nil if type.nil?
+
+        if stringish?(type)
+          Type::Combinator.nominal_of("String")
+        elsif hashish?(type)
+          Type::Combinator.nominal_of("Hash",
+                                      type_args: [Type::Combinator.untyped,
+                                                  Type::Combinator.untyped])
+        elsif arrayish?(type)
+          Type::Combinator.nominal_of("Array", type_args: [Type::Combinator.untyped])
+        end
+      end
+
       def classify_closure_escape(call_node)
         receiver_type = call_node.receiver ? scope.type_of(call_node.receiver, tracer: tracer) : nil
         ClosureEscapeAnalyzer.classify(
@@ -1654,6 +2234,22 @@ module Rigor
         names.reduce(base_scope) { |acc, name| acc.with_local(name, Type::Combinator.untyped) }
       end
 
+      # Names of outer locals the block body can REBIND, across every
+      # local-write form: plain `=` (`LocalVariableWriteNode`), the
+      # operator / `||=` / `&&=` compound forms, and a multi-assign target
+      # (`x, y = ...` → `LocalVariableTargetNode` under `MultiWriteNode`).
+      # Block-introduced names (parameters, numbered params, `;`-locals) and
+      # names not bound in the outer scope are excluded — a write to either
+      # is not a captured rebind of an outer variable.
+      LOCAL_WRITE_NODES = [
+        Prism::LocalVariableWriteNode,
+        Prism::LocalVariableOperatorWriteNode,
+        Prism::LocalVariableOrWriteNode,
+        Prism::LocalVariableAndWriteNode,
+        Prism::LocalVariableTargetNode
+      ].freeze
+      private_constant :LOCAL_WRITE_NODES
+
       def captured_local_writes(block_node, base_scope)
         body = block_node.body
         return [] if body.nil?
@@ -1661,7 +2257,7 @@ module Rigor
         introduced = block_introduced_locals(block_node)
         outer_writes = []
         Source::NodeWalker.each(body) do |descendant|
-          next unless descendant.is_a?(Prism::LocalVariableWriteNode)
+          next unless LOCAL_WRITE_NODES.any? { |klass| descendant.is_a?(klass) }
           next if introduced.include?(descendant.name)
           next unless base_scope.locals.key?(descendant.name)
 
@@ -1670,6 +2266,313 @@ module Rigor
         outer_writes.uniq
       end
 
+      # ADR-56 slice A. For a `:non_escaping` block, fold the continuation
+      # binding of every outer local the body can rebind back into
+      # `post_scope`. The binding is a capped fixpoint (cap 3) over the
+      # block body re-evaluated under the running per-name assumption,
+      # joined with the pre-call binding (kept as a constituent so the
+      # 0-iteration path — `[].each { … }` — stays sound), value-pinned-
+      # widened on the final permitted iteration, and floored to
+      # `Dynamic[top]` on non-convergence (matching `drop_captured_narrowing`).
+      #
+      # Fast path: a block writing no outer local leaves `post_scope`
+      # byte-identical (the overwhelming majority of blocks), so this costs
+      # one extra `captured_local_writes` walk and nothing else.
+      def write_back_block_captures(call_node, post_scope)
+        block = call_node.block
+        return post_scope unless block.is_a?(Prism::BlockNode)
+        return post_scope unless classify_closure_escape(call_node) == :non_escaping
+
+        names = captured_local_writes(block, scope)
+        return post_scope if names.empty?
+
+        seed = names.to_h { |name| [name, scope.local(name)] }
+        result = BodyFixpoint.converge(
+          names: names,
+          seed_bindings: seed,
+          widen: Type::Combinator.method(:widen_value_pinned),
+          evaluate_body: ->(bindings) { block_exit_bindings(call_node, block, bindings, names) }
+        )
+
+        result.reduce(post_scope) { |acc, (name, type)| acc.with_local(name, type) }
+      end
+
+      # ADR-56 slice C — receiver-content element-type join. After the
+      # rebind write-back and `MutationWidening.widen_after_block` (which
+      # forgets a content-mutated collection's literal arity but keeps only
+      # the SEED's element types), join the appended/stored element / key /
+      # value types INTO the continuation collection's parameter, so
+      # `out = [0]; arr.each { |x| out << x }` types `out` as
+      # `Array[0 | Integer]` (sound) rather than `Array[0]` (the B1
+      # under-approximation: the runtime array is `[0, 1, 2, 3]`).
+      #
+      # Pre-state is read from `post_scope` so a local that is BOTH rebound
+      # and content-mutated composes: the rebind fixpoint result feeds the
+      # content join. The block body is typed once for argument evidence;
+      # the floor is `Array[Dynamic[top]]` / `Hash[untyped, untyped]` (the
+      # sound empty-seed behaviour). Always sound — only ever widens.
+      def content_writeback_block_captures(call_node, post_scope)
+        block = call_node.block
+        return post_scope unless block.is_a?(Prism::BlockNode)
+        return post_scope unless classify_closure_escape(call_node) == :non_escaping
+
+        body = block.body
+        return post_scope if body.nil?
+
+        mutations = collect_content_mutations(body)
+        return post_scope if mutations.empty?
+
+        entry = build_block_entry_scope(call_node, block)
+        mutations.reduce(post_scope) do |acc, (name, calls)|
+          joined = join_content_for_local(name, calls, acc, entry)
+          joined.nil? ? acc : acc.with_local(name, joined)
+        end
+      end
+
+      # ADR-56 slice C (B3). For `recv.each_with_object(memo) { |x, acc| … }`
+      # the return is the memo object after the block has mutated it through
+      # the `acc` alias. Compute the joined memo type the same way captured-
+      # local content mutations are joined: pre-state = the memo argument's
+      # type, added evidence = the content-mutator args on the memo block
+      # param. Returns `call_type` unchanged for any other call, a missing
+      # block, or a memo whose pre-state is not a collection.
+      def each_with_object_return(call_node, call_type)
+        return call_type unless call_node.name == :each_with_object
+
+        block = call_node.block
+        return call_type unless block.is_a?(Prism::BlockNode)
+
+        memo_arg = call_node.arguments&.arguments&.first
+        return call_type if memo_arg.nil?
+
+        memo_param = each_with_object_memo_param(block)
+        return call_type if memo_param.nil?
+
+        body = block.body
+        return call_type if body.nil?
+
+        # The memo alias is a block-local (depth 0) — collect content
+        # mutations on it directly rather than via the captured-local walk.
+        calls = body_content_mutations_on(body, memo_param)
+        return call_type if calls.empty?
+
+        pre_state = scope.type_of(memo_arg, tracer: tracer)
+        entry = build_block_entry_scope(call_node, block)
+        joined = join_content_for_param(calls, pre_state, entry)
+        joined || call_type
+      end
+
+      # The name of the memo block parameter (the SECOND positional param of
+      # an `each_with_object` block), or nil when the block does not bind a
+      # second positional param.
+      def each_with_object_memo_param(block)
+        params_root = block.parameters
+        return nil unless params_root.is_a?(Prism::BlockParametersNode)
+
+        params = params_root.parameters
+        return nil if params.nil?
+
+        requireds = params.requireds
+        return nil if requireds.size < 2
+
+        second = requireds[1]
+        second.respond_to?(:name) ? second.name : nil
+      end
+
+      # Content-mutator calls on a block-local receiver `var_name`
+      # (depth 0) within `body`.
+      def body_content_mutations_on(body, var_name)
+        calls = []
+        Source::NodeWalker.each(body) do |descendant|
+          next unless descendant.is_a?(Prism::CallNode)
+          next unless MutationWidening::CONTENT_ADDERS.include?(descendant.name)
+
+          receiver = descendant.receiver
+          next unless receiver.is_a?(Prism::LocalVariableReadNode)
+          next unless receiver.name == var_name
+
+          calls << descendant
+        end
+        calls
+      end
+
+      # Joins content evidence for a memo / param given its pre-state and a
+      # list of mutator calls, dispatching Array vs Hash by the mutator set.
+      def join_content_for_param(calls, pre_state, block_entry)
+        return nil if pre_state.nil?
+
+        if stringish?(pre_state)
+          # String carries no element parameter; mutating `<<`/`concat`
+          # makes the constant value unsound (`s = "a"; s << x` → runtime
+          # `"a…"`), so widen to the nominal base. Sound — only widens.
+          Type::Combinator.nominal_of("String")
+        elsif hashish?(pre_state) || (hash_mutations?(calls) && !arrayish?(pre_state))
+          join_hash_param(calls, pre_state, block_entry)
+        else
+          join_array_param(calls, pre_state, block_entry)
+        end
+      end
+
+      def join_hash_param(calls, pre_state, block_entry)
+        pairs = calls.flat_map { |c| hash_pair_types(c, block_entry) }
+        return nil if pairs.empty? && !hashish?(pre_state)
+
+        MutationWidening.join_hash_content(pre_state, pairs)
+      end
+
+      def join_array_param(calls, pre_state, block_entry)
+        return nil unless arrayish?(pre_state)
+
+        added = calls.flat_map do |c|
+          # Index-write on an array (`a[i] += v`) introduces no new element
+          # evidence we can cheaply attribute — the array-arity forget
+          # already widened the binding; contribute nothing.
+          next [] if index_write?(c)
+
+          MutationWidening.array_added_elements(c.name, content_arg_types(c, block_entry))
+        end
+        MutationWidening.join_array_content(pre_state, added)
+      end
+
+      # Walks the block body for content-mutator calls (`<<`, `push`,
+      # `[]=`, …) whose receiver is a captured outer local (depth >= 1),
+      # returning `{ name => [call_node, ...] }`. Mirrors the
+      # `MutationWidening.widen_after_block` walk (descends into nested
+      # blocks; the depth check keeps nested block-locals out).
+      def collect_content_mutations(body)
+        mutations = Hash.new { |h, k| h[k] = [] }
+        Source::NodeWalker.each(body) do |descendant|
+          name, node = content_mutation_target(descendant) { |r| r.is_a?(Prism::LocalVariableReadNode) && r.depth.positive? }
+          mutations[name] << node unless name.nil?
+        end
+        mutations
+      end
+
+      # Index-write forms (`h[k] ||= v`, `h[k] += v`, `h[k] = v` via a
+      # multi-assign target) that mutate a collection's CONTENT without a
+      # `[]=` CallNode. `h[k] ||= []; h[k] << v` mutates `h` through the
+      # OrWrite even though the appended values land on the nested array —
+      # leaving `h` an empty `{}` is unsound (`h.empty?` folds to `true`).
+      INDEX_WRITE_NODES = [
+        Prism::IndexOrWriteNode,
+        Prism::IndexAndWriteNode,
+        Prism::IndexOperatorWriteNode,
+        Prism::IndexTargetNode
+      ].freeze
+      private_constant :INDEX_WRITE_NODES
+
+      # `[receiver_name, node]` when `node` is a content mutation whose
+      # receiver is a local variable satisfying `accept` (depth predicate),
+      # else `[nil, nil]`. Covers `[]=`-style CallNode mutators and the
+      # index-write node forms.
+      def content_mutation_target(node)
+        is_call_mutator = node.is_a?(Prism::CallNode) && MutationWidening::CONTENT_ADDERS.include?(node.name)
+        return [nil, nil] unless is_call_mutator || index_write?(node)
+
+        receiver = node.receiver
+        return [nil, nil] unless receiver.is_a?(Prism::LocalVariableReadNode)
+        return [nil, nil] unless yield(receiver)
+
+        [receiver.name, node]
+      end
+
+      # Computes the joined continuation collection type for one captured
+      # local from its content-mutator calls. Returns `nil` (no overlay)
+      # when the pre-state is neither an Array-ish nor a Hash-ish binding —
+      # e.g. a String accumulator, whose `<<` carries no element parameter
+      # and whose binding already types as `String`.
+      def join_content_for_local(name, calls, post_scope, block_entry)
+        join_content_for_param(calls, post_scope.local(name), block_entry)
+      end
+
+      def hash_mutations?(calls)
+        calls.any? do |c|
+          index_write?(c) || (c.is_a?(Prism::CallNode) && MutationWidening::HASH_CONTENT_ADDERS.include?(c.name))
+        end
+      end
+
+      def index_write?(node)
+        INDEX_WRITE_NODES.any? { |k| node.is_a?(k) }
+      end
+
+      def arrayish?(type)
+        case type
+        when Type::Tuple then true
+        when Type::Nominal then type.class_name == "Array"
+        when Type::Union then type.members.any? { |m| arrayish?(m) }
+        else false
+        end
+      end
+
+      def hashish?(type)
+        case type
+        when Type::HashShape then true
+        when Type::Nominal then type.class_name == "Hash"
+        when Type::Union then type.members.any? { |m| hashish?(m) }
+        else false
+        end
+      end
+
+      def stringish?(type)
+        (type.is_a?(Type::Constant) && type.value.is_a?(String)) ||
+          (type.is_a?(Type::Nominal) && type.class_name == "String")
+      end
+
+      # `[key_type, value_type]` for a `h[k] = v` / `h.store(k, v)` call or
+      # an index-write node (`h[k] ||= v`), typed in the block-entry scope.
+      # For an index-write the stored value is opaque (the appended values
+      # often land on a NESTED collection via `h[k] << v`), so the value is
+      # floored to `untyped` — sound: it only ever widens the value param.
+      # Returns `[]` for other forms.
+      def hash_pair_types(node, block_entry)
+        if index_write?(node)
+          key = index_key_type(node, block_entry)
+          return [] if key.nil?
+
+          return [[key, Type::Combinator.untyped]]
+        end
+
+        args = content_arg_types(node, block_entry)
+        return [] if args.size < 2
+
+        [[args.first, args.last]]
+      end
+
+      # Type of the index expression of an index-write node (`h[k] ||= v`).
+      def index_key_type(node, block_entry)
+        args = node.arguments
+        return nil unless args.is_a?(Prism::ArgumentsNode)
+
+        first = args.arguments.first
+        first.nil? ? nil : block_entry.type_of(first, tracer: tracer)
+      rescue StandardError
+        nil
+      end
+
+      # Argument types for a content-mutator call, typed against the
+      # block-entry scope (block params bound). A sub-evaluator over
+      # `block_entry` keeps the argument typing flow-correct for params /
+      # `;`-locals without leaking into the outer scope.
+      def content_arg_types(call_node, block_entry)
+        arguments = call_node.arguments
+        return [] if arguments.nil?
+
+        arguments.arguments.map { |arg| block_entry.type_of(arg, tracer: tracer) }
+      rescue StandardError
+        []
+      end
+
+      # Evaluates `block`'s body once with each written outer local bound to
+      # the supplied `bindings` (block params / `;`-locals re-bound as
+      # usual) and returns the per-name exit binding for `names`. Used as
+      # the `BodyFixpoint` body-evaluator.
+      def block_exit_bindings(call_node, block, bindings, names)
+        entry = build_block_entry_scope(call_node, block)
+        entry = bindings.reduce(entry) { |acc, (name, type)| acc.with_local(name, type) }
+        _type, exit_scope = sub_eval(block, entry)
+        names.to_h { |name| [name, exit_scope.local(name)] }
+      end
+
       # Names introduced by the block itself (parameters, numbered
       # parameters via `BlockParameterBinder`, plus explicit
       # `;`-prefixed block-locals on `BlockParametersNode`). Writes
@@ -1799,7 +2702,14 @@ module Rigor
         seeded = scope.class_ivars_for(path)
         return body_scope if seeded.empty?
 
-        seeded.reduce(body_scope) { |acc, (name, type)| acc.with_ivar(name, type) }
+        # ADR-58 WD1 — the class-ivar index unions every `@x = …` write across
+        # the class flow-insensitively, so a ctor `@x = nil` seed makes a read
+        # in a *different* method type `T | nil`. That `nil` is
+        # declaration-sourced, not flow-live, so `seed_declaration_sourced_ivar`
+        # marks each seeded ivar: `possible-nil-receiver` then declines to fire
+        # on the cross-method invariant unless a method-local write or
+        # narrowing makes the nil flow-live (which drops the mark).
+        seeded.reduce(body_scope) { |acc, (name, type)| acc.seed_declaration_sourced_ivar(name, type) }
       end
 
       # Cvars are visible from BOTH instance and singleton method
@@ -1834,30 +2744,18 @@ module Rigor
       # ScopeIndexer-populated declaration overrides
       # (`Prism::ConstantReadNode` for `module Foo` headers, etc.)
       # remain reachable from inside nested bodies.
-      def build_fresh_body_scope # rubocop:disable Metrics/AbcSize
-        # Single allocation instead of a 13-deep `with_*` chain — this runs
-        # per class/method body on the main walk, so the chain's dozen
-        # throwaway intermediate Scopes were a top `Scope#rebuild` source.
-        # Local-empty by design; every field is a plain inherited reference
-        # and the unset fields default to the same empty bindings the chain
-        # (from `Scope.empty`) left them at, so the scope is identical (ADR-44).
+      def build_fresh_body_scope
+        # Single allocation instead of a deep `with_*` chain — this runs
+        # per class/method body on the main walk, so the chain's throwaway
+        # intermediate Scopes were a top `Scope#rebuild` source (ADR-44).
+        # Local-empty by design; the discovery index is inherited whole by
+        # reference (ADR-53 Track A), so a table added to the index can no
+        # longer be dropped here by a missed per-field copy.
         Scope.new(
           environment: scope.environment,
           locals: {}.freeze,
           source_path: scope.source_path,
-          declared_types: scope.declared_types,
-          discovered_classes: scope.discovered_classes,
-          in_source_constants: scope.in_source_constants,
-          class_ivars: scope.class_ivars,
-          class_cvars: scope.class_cvars,
-          program_globals: scope.program_globals,
-          discovered_methods: scope.discovered_methods,
-          discovered_def_nodes: scope.discovered_def_nodes,
-          discovered_def_sources: scope.discovered_def_sources,
-          discovered_superclasses: scope.discovered_superclasses,
-          discovered_includes: scope.discovered_includes,
-          discovered_class_sources: scope.discovered_class_sources,
-          discovered_method_visibilities: scope.discovered_method_visibilities
+          discovery: scope.discovery
         )
       end
 
@@ -2002,12 +2900,44 @@ module Rigor
 
       # ----- helpers -----
 
+      # Explicit `return value` (including `return` inside a block, which in
+      # Ruby returns from the *enclosing method*). The control-transfer value
+      # is `Bot` — a `return` produces no value at its own position — but the
+      # returned expression's type is recorded into the active return sink so
+      # the method-return inference joins it with the body's tail type.
+      # Returns inside a nested `def`/lambda are barriers: `eval_def` clears
+      # the sink around the nested body, so this handler only ever appends a
+      # return that genuinely exits the method currently being inferred.
+      def eval_return(node)
+        sink = Thread.current[RETURN_SINK_KEY]
+        record_return_value(node, sink) if sink
+        [Type::Combinator.bot, scope]
+      end
+
+      def record_return_value(node, sink)
+        args = node.arguments&.arguments || []
+        # `return` with no argument returns nil; `return a` records the
+        # argument's type; `return a, b, c` packs a Tuple — in Ruby a
+        # multi-value return yields the array `[a, b, c]`, so the inferred
+        # return contributes the corresponding Tuple element-by-element.
+        if args.empty?
+          sink << Type::Combinator.constant_of(nil)
+        elsif args.size == 1
+          type, = sub_eval(args.first, scope)
+          sink << type
+        else
+          element_types = args.map { |arg| sub_eval(arg, scope).first }
+          sink << Type::Combinator.tuple_of(*element_types)
+        end
+      end
+
       def sub_eval(node, with_scope, class_context: @class_context)
         StatementEvaluator.new(
           scope: with_scope,
           tracer: tracer,
           on_enter: @on_enter,
-          class_context: class_context
+          class_context: class_context,
+          converged_loop_recording: @converged_loop_recording
         ).evaluate(node)
       end