rigortype 0.1.18 → 0.2.0

data/lib/rigor/inference/statement_evaluator.rb

@@ -6,7 +6,10 @@ require_relative "../reflection"
 require_relative "../type"
 require_relative "../analysis/fact_store"
 require_relative "../source/node_walker"
+require_relative "../source/constant_path"
 require_relative "block_parameter_binder"
+require_relative "body_fixpoint"
+require_relative "struct_fold_safety"
 require_relative "closure_escape_analyzer"
 require_relative "indexed_narrowing"
 require_relative "method_dispatcher"
@@ -98,10 +101,36 @@ module Rigor
         Prism::SingletonClassNode => :eval_singleton_class,
         Prism::CallNode => :eval_call,
         Prism::BlockNode => :eval_block,
+        Prism::ReturnNode => :eval_return,
+        Prism::BreakNode => :eval_break,
         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
+
+      # Thread-local sink (an Array of `[BreakNode, Scope]`) collecting the
+      # scope at each `break` reached while evaluating a loop body, so
+      # `eval_loop` / `eval_for` can join a `break`-path binding (`flag = true;
+      # break`) into the loop continuation that the fall-through would
+      # otherwise drop. Stacks like the return sink: a nested loop installs its
+      # own sink, restored on exit, so an inner loop's break does not leak to
+      # the outer one. A `break` inside a block / nested loop targets that
+      # inner construct, not the lexical loop — filtered out by the
+      # directly-targeting break set, see {#directly_targeting_breaks}.
+      # See docs/notes/20260615-loop-break-binding-propagation-design.md.
+      BREAK_SINK_KEY = :rigor_break_sink
+      private_constant :BREAK_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 +150,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 +236,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
@@ -304,9 +381,7 @@ module Rigor
       end
 
       # `receiver[key] ||= default` — the Redmine `Query#as_params`
-      # idiom (ROADMAP § Future cycles / Type-language / engine —
-      # "Indexed-collection narrowing through `Hash[k] ||= default`").
-      # After the `||=`, the next read at `receiver[key]` is known
+      # idiom. After the `||=`, the next read at `receiver[key]` is known
       # non-nil; the next `<<` / `[]=` / other mutator runs against
       # a Tuple / Hash carrier instead of the `Constant[nil]` an
       # empty `HashShape{}` lookup would otherwise fold to.
@@ -419,10 +494,24 @@ module Rigor
         # then-branch unconditionally exits (return / next /
         # break / raise) and there is no else, the post-scope
         # is the falsey edge of the predicate (subsequent
-        # statements observe the predicate-was-false world).
+        # statements observe the predicate-was-false world). The
+        # then-body is the *skipped* path, so the bare narrowing
+        # (no body assignments) is the correct continuation.
         return [Type::Combinator.union(then_type, else_type), falsey_scope] \
           if branch_terminates?(node.statements, then_type) && node.subsequent.nil?
-        return [Type::Combinator.union(then_type, else_type), truthy_scope] \
+        # Symmetric case: the else / elsif-chain (`node.subsequent`)
+        # unconditionally exits, so the only surviving path is the
+        # then-branch that RAN. The continuation must therefore carry
+        # `then_scope` — the predicate-truthy narrowing PLUS the
+        # then-body's assignments — not the bare `truthy_scope`.
+        # Returning `truthy_scope` drops every local the then-body
+        # bound, leaving it unbound for any enclosing merge to
+        # spuriously nil-inject: e.g. the inner `elsif … else raise`
+        # of `if a then x=… elsif b then x=… else raise end` would
+        # return with `x` unbound, and the outer if's join would then
+        # read `x` as `… | nil` and fire a false `possible-nil-receiver`
+        # (liquid v5.x sweep, Event 3).
+        return [Type::Combinator.union(then_type, else_type), then_scope] \
           if branch_terminates?(node.subsequent, else_type) && node.statements
 
         [
@@ -457,10 +546,17 @@ module Rigor
         else_type, else_scope = eval_branch_or_nil(node.else_clause, truthy_scope)
         # Slice 7 phase 14 — same early-return narrowing as
         # `if`: when the body unconditionally exits and there
-        # is no else, the post-scope is the truthy edge.
+        # is no else, the post-scope is the truthy edge (the body
+        # is the skipped path, so the bare narrowing is correct).
         return [Type::Combinator.union(then_type, else_type), truthy_scope] \
           if branch_terminates?(node.statements, then_type) && node.else_clause.nil?
-        return [Type::Combinator.union(then_type, else_type), falsey_scope] \
+        # Symmetric to the `if` else-exits fix: when the else-clause
+        # exits, the surviving path is the unless-body that RAN, so the
+        # continuation carries `then_scope` (the predicate-falsey
+        # narrowing PLUS the body's assignments), not the bare
+        # `falsey_scope` — otherwise body-bound locals are dropped and
+        # an enclosing merge nil-injects them.
+        return [Type::Combinator.union(then_type, else_type), then_scope] \
           if branch_terminates?(node.else_clause, else_type) && node.statements
 
         [
@@ -506,12 +602,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
@@ -810,13 +927,294 @@ 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.
+        #
+        # The pass runs under a break sink so a `break`-path binding
+        # (`flag = true; break`) the fall-through `body_scope` drops is
+        # collected for the continuation join below.
+        break_targets, break_sink, body_scope = capture_loop_body_breaks(node.statements, post_pred)
+        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
 
-        _body_type, body_scope = sub_eval(node.statements, post_pred)
-        [
-          Type::Combinator.constant_of(nil),
-          join_with_nil_injection(post_pred, body_scope)
-        ]
+        post_loop = converged_loop_scope(node, post_pred, base_scope, names, body_first)
+        # Recover `break`-path bindings the fall-through dropped (`flag = true;
+        # break` -> `flag` is `false | true`, not the stale `false`).
+        post_loop = join_break_scopes(post_loop, break_sink, break_targets, names)
+        post_loop = narrow_loop_exit_edge(node, post_loop)
+        [Type::Combinator.constant_of(nil), post_loop]
+      end
+
+      # The continuation scope for a loop whose body rebinds locals: the
+      # ADR-56 slice-B rebind fixpoint overlaid on `base_scope`, then the
+      # slice-C receiver-content writeback.
+      def converged_loop_scope(node, post_pred, base_scope, names, body_first)
+        # 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 degrades it to `T | nil`, matching the 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.
+        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; join the appended/stored
+        # types into the continuation collection (pre-state read from
+        # `post_loop` so a local both rebound and content-mutated composes).
+        loop_content_writeback(node.statements, 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
+
+      # A `break` inside one of these nested constructs targets the inner
+      # construct (an inner loop, a block's method, a nested def), NOT the
+      # lexical loop — so the directly-targeting break scan does not descend
+      # into them.
+      BREAK_BOUNDARY_NODES = [
+        Prism::ForNode, Prism::WhileNode, Prism::UntilNode,
+        Prism::BlockNode, Prism::LambdaNode, Prism::DefNode,
+        Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode
+      ].freeze
+      private_constant :BREAK_BOUNDARY_NODES
+
+      # The `BreakNode`s that lexically target THIS loop — reachable from the
+      # body without crossing a nested loop / block / def boundary. An
+      # identity-keyed Hash used as a membership set to filter the collected
+      # break scopes (the thread-local sink also collects breaks from nested
+      # blocks that did not install their own sink).
+      def directly_targeting_breaks(statements)
+        found = {}.compare_by_identity
+        collect_direct_breaks(statements, found)
+        found
+      end
+
+      def collect_direct_breaks(node, found)
+        return if node.nil?
+
+        found[node] = true if node.is_a?(Prism::BreakNode)
+        node.compact_child_nodes.each do |child|
+          next if BREAK_BOUNDARY_NODES.any? { |klass| child.is_a?(klass) }
+
+          collect_direct_breaks(child, found)
+        end
+      end
+
+      # Installs a fresh thread-local break sink around `yield` (a loop-body
+      # evaluation), returning `[collected, yield_result]`. Stacks: the
+      # previous sink is restored on exit so a nested loop's breaks do not
+      # leak to the enclosing loop.
+      def collect_break_scopes
+        previous = Thread.current[BREAK_SINK_KEY]
+        sink = []
+        Thread.current[BREAK_SINK_KEY] = sink
+        begin
+          result = yield
+        ensure
+          Thread.current[BREAK_SINK_KEY] = previous
+        end
+        [sink, result]
+      end
+
+      # Runs a loop body's single pass under a break sink. Returns the
+      # directly-targeting break set, the collected break scopes, and the
+      # fall-through body scope — the three inputs the continuation's
+      # {#join_break_scopes} needs. Shared by `eval_loop` and `eval_for`.
+      def capture_loop_body_breaks(statements, entry)
+        targets = directly_targeting_breaks(statements)
+        sink, (_type, body_scope) = collect_break_scopes { sub_eval(statements, entry) }
+        [targets, sink, body_scope]
+      end
+
+      # Joins each directly-targeting break's body-written local bindings into
+      # the loop continuation, so a `break`-path binding the fall-through
+      # dropped is recovered (`flag = true; break` -> `flag` becomes `false |
+      # true`). Only loop-body-written names are joined — an unchanged local
+      # unions to itself; a break-only-written local is already present via the
+      # fixpoint / nil-injection seed, so the union reflects its break value.
+      def join_break_scopes(continuation, sink, targeting, names)
+        return continuation if sink.empty? || names.empty?
+
+        breaks = sink.select { |(node, _scope)| targeting.key?(node) }
+        breaks.reduce(continuation) do |cont, (_node, break_scope)|
+          names.reduce(cont) do |acc, name|
+            break_value = break_scope.local(name)
+            next acc if break_value.nil?
+
+            current = acc.local(name)
+            joined = current ? Type::Combinator.union(current, break_value) : break_value
+            acc.with_local(name, joined)
+          end
+        end
+      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,
@@ -834,11 +1232,19 @@ module Rigor
         element_type = for_iteration_element_type(coll_type)
         body_entry = bind_for_index(node.index, element_type, post_coll)
 
-        body_scope = node.statements ? sub_eval(node.statements, body_entry).last : body_entry
-        [
-          Type::Combinator.constant_of(nil),
-          join_with_nil_injection(post_coll, body_scope)
-        ]
+        if node.statements.nil?
+          return [Type::Combinator.constant_of(nil), join_with_nil_injection(post_coll, body_entry)]
+        end
+
+        # Run the body pass under a break sink so a `break`-path binding the
+        # fall-through drops is recovered into the continuation (the `for`
+        # sibling of `eval_loop`'s break join; `for` has no fixpoint, so the
+        # single-pass join is the only continuation).
+        break_targets, break_sink, body_scope = capture_loop_body_breaks(node.statements, body_entry)
+        continuation = join_with_nil_injection(post_coll, body_scope)
+        pre_existing, body_first = loop_body_local_writes(node.statements, post_coll)
+        continuation = join_break_scopes(continuation, break_sink, break_targets, pre_existing + body_first)
+        [Type::Combinator.constant_of(nil), continuation]
       end
 
       # `for x in coll` is semantically `coll.each { |x| ... }`. We
@@ -1005,7 +1411,7 @@ module Rigor
       # (`Constant[nil]` for an empty body); we discard the body's
       # post-scope.
       def eval_class_or_module(node)
-        name = qualified_name_for(node.constant_path)
+        name = Source::ConstantPath.qualified_name(node.constant_path)
         new_context = @class_context + [ClassFrame.new(name: name, singleton: false)]
         body_type, _body_scope = eval_class_body(node, new_context)
         [body_type, scope]
@@ -1046,8 +1452,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
 
@@ -1069,6 +1485,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
@@ -1086,6 +1507,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)
@@ -1096,14 +1525,28 @@ 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)
-        # 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
-        # propagation step the outer `arr` keeps its pre-mutation
-        # binding. Sound for the same reason — only ever LOSES
-        # precision — so blindly applying is safe regardless of
-        # whether the block actually runs.
+        # 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)
+        # Same always-safe rationale as `widen_after_call` above —
+        # propagates outer-scope local / ivar widening from block body
+        # mutations (`items.each { |x| arr << x }`).
         post_scope = MutationWidening.widen_after_block(call_node: node, outer_scope: post_scope)
+        # ADR-56 slice C — receiver-content element-type join. Joins
+        # appended / stored element / key / value types into the
+        # continuation collection so `out = [0]; arr.each { |x| out << x }`
+        # types `Array[0 | Integer]`, not `Array[0]`. Same always-safe
+        # rationale (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
@@ -1130,9 +1573,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
@@ -1255,7 +1736,7 @@ module Rigor
         args = matcher.arguments&.arguments || []
         return nil unless args.size == 1
 
-        class_name = constant_node_name(args.first)
+        class_name = Source::ConstantPath.qualified_name_or_nil(args.first)
         return nil if class_name.nil?
 
         { local: local_name, kind: :class, class_name: class_name, exact: exact }
@@ -1311,35 +1792,6 @@ module Rigor
         matcher.arguments.nil? || matcher.arguments.arguments.empty?
       end
 
-      # Decodes a `Prism::ConstantReadNode` /
-      # `Prism::ConstantPathNode` into a colon-joined class
-      # name string, or returns nil for any other node
-      # shape. Mirrors the conservative envelope used by the
-      # `is_a?` / `kind_of?` predicate narrower.
-      def constant_node_name(node)
-        case node
-        when Prism::ConstantReadNode
-          node.name.to_s
-        when Prism::ConstantPathNode
-          flatten_constant_path(node)
-        end
-      end
-
-      def flatten_constant_path(node)
-        parts = []
-        cursor = node
-        while cursor.is_a?(Prism::ConstantPathNode)
-          parts.unshift(cursor.name.to_s)
-          cursor = cursor.parent
-        end
-        case cursor
-        when Prism::ConstantReadNode then parts.unshift(cursor.name.to_s)
-        when nil then nil # ::Foo absolute root — preserve as-is
-        else return nil
-        end
-        parts.join("::")
-      end
-
       # Slice 4b-2 (ADR-7 § "Slice 4-A/4-B") — applies the
       # post-return facts the merger produces for an
       # `RBS::Extended`-annotated call. Reads through
@@ -1348,9 +1800,8 @@ module Rigor
       # rows for `:always` assert directives (the slice-4a
       # routing places conditional asserts on `truthy_facts` /
       # `falsey_facts`, which `Narrowing.predicate_scopes`
-      # consumes). Future plugin contributions that add
-      # `:always` assertions at the same call site flow through
-      # the same merger and land here.
+      # consumes). Plugin `:always` assertions are handled by
+      # the sibling `apply_plugin_assertions`, not this path.
       def apply_rbs_extended_assertions(call_node, current_scope)
         method_def = resolve_call_method(call_node, current_scope)
         return current_scope if method_def.nil?
@@ -1416,16 +1867,9 @@ module Rigor
       EMPTY_CONTRIBUTIONS = [].freeze
       private_constant :EMPTY_CONTRIBUTIONS
 
-      # 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` = 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.
+      # Fast-exit guard: skip if no plugin declares a `type_specifier`, or if
+      # no registered method-name gate matches the call. See
+      # `collect_gated_statement_contributions` for the full consultation.
       def collect_plugin_contributions(registry, call_node, current_scope)
         index = registry.contribution_index
         relevant = index.for_statement
@@ -1437,8 +1881,10 @@ module Rigor
         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.
+      # ADR-37 slice 2 / ADR-52 WD1 — post-gate walk in registry order.
+      # Visits only plugins in `for_statement` (declare a `type_specifier`),
+      # further gated by the method-name Set probe so the common no-candidate
+      # case is a single lookup. Accumulates lazily; caller is read-only.
       def collect_gated_statement_contributions(index, relevant, name, call_node, current_scope)
         result = nil
         relevant.each do |plugin|
@@ -1606,12 +2052,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,
@@ -1623,6 +2082,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(
@@ -1649,6 +2326,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?
@@ -1656,7 +2349,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)
 
@@ -1665,6 +2358,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
@@ -1769,6 +2769,12 @@ module Rigor
           source_path: scope.source_path
         )
         bindings = binder.bind(def_node)
+        # ADR-67 WD3 — override an undeclared parameter with its call-site
+        # inferred type (precision-additive; an RBS-declared parameter wins,
+        # the table is empty on a normal `check` run). The inferred type lives
+        # only as a body local, never as an RBS contract, so it cannot fire a
+        # parameter-boundary diagnostic (WD1, satisfied by construction).
+        bindings = seed_inferred_param_types(bindings, def_node, singleton)
 
         # Method bodies do NOT see the outer scope's locals. They start
         # from a fresh scope with the same environment, then receive
@@ -1782,9 +2788,47 @@ module Rigor
         fresh = seed_instance_ivars(fresh, singleton: singleton)
         fresh = seed_class_cvars(fresh)
         fresh = seed_program_globals(fresh)
+        # ADR-48 Struct slice 3 — install the method body's fold-safe-local set
+        # so a member read off a mutation-free local folds during the in-body
+        # walk (the call-return inference path is seeded separately).
+        fresh = fresh.with_struct_fold_safe(
+          StructFoldSafety.fold_safe_locals(
+            def_node.body, ->(name) { scope.struct_member_layout(name)&.[](:members) }
+          )
+        )
         bindings.reduce(fresh) { |acc, (name, type)| acc.with_local(name, type) }
       end
 
+      # ADR-67 WD3 — consult the call-site parameter-inference table for this
+      # `def` and replace each undeclared (untyped) parameter binding with its
+      # inferred type. Keyed by `[class_name, method_name, kind]`, reconstructed
+      # from the lexical class path — the same triple
+      # {Inference::ParameterInferenceCollector} records. An RBS-declared
+      # parameter (a non-untyped binding) always wins. No-op when the table is
+      # empty (the normal `check` path), so the seed is byte-identical there.
+      def seed_inferred_param_types(bindings, def_node, singleton)
+        inferred = scope.param_inferred_types
+        return bindings if inferred.empty?
+
+        path = current_class_path
+        return bindings if path.nil?
+
+        table = inferred[[path, def_node.name, singleton ? :singleton : :instance]]
+        return bindings if table.nil? || table.empty?
+
+        merged = bindings.dup
+        table.each do |name, type|
+          merged[name] = type if merged.key?(name) && untyped_binding?(merged[name])
+        end
+        merged
+      end
+
+      # True for the `Dynamic[Top]` carrier `MethodParameterBinder` leaves on an
+      # undeclared parameter — the only bindings ADR-67 WD3 overrides.
+      def untyped_binding?(type)
+        type.is_a?(Type::Dynamic) && type.static_facet.is_a?(Type::Top)
+      end
+
       def seed_instance_ivars(body_scope, singleton:)
         return body_scope if singleton
 
@@ -1794,7 +2838,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
@@ -1868,7 +2919,7 @@ module Rigor
         when Prism::ConstantReadNode
           receiver.name.to_s == prefix.last
         when Prism::ConstantPathNode
-          rendered = render_constant_path(receiver)
+          rendered = Source::ConstantPath.render(receiver)
           return false unless rendered
 
           path = rendered.split("::")
@@ -1908,25 +2959,6 @@ module Rigor
         end
       end
 
-      def qualified_name_for(constant_path_node)
-        case constant_path_node
-        when Prism::ConstantReadNode
-          constant_path_node.name.to_s
-        when Prism::ConstantPathNode
-          render_constant_path(constant_path_node)
-        end
-      end
-
-      def render_constant_path(node)
-        prefix =
-          case node.parent
-          when Prism::ConstantReadNode then "#{node.parent.name}::"
-          when Prism::ConstantPathNode then "#{render_constant_path(node.parent)}::"
-          else ""
-          end
-        "#{prefix}#{node.name}"
-      end
-
       def singleton_context_for(node)
         case node.expression
         when Prism::SelfNode
@@ -1965,7 +2997,7 @@ module Rigor
         when Prism::ConstantReadNode
           expression.name.to_s
         when Prism::ConstantPathNode
-          render_constant_path(expression)
+          Source::ConstantPath.render(expression)
         end
       end
 
@@ -1985,12 +3017,57 @@ 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
+
+      # A `break` transfers control to the loop exit (its flow value is `Bot`,
+      # like `return`). It records the current scope into the active loop's
+      # break sink so the loop join can recover a `break`-path binding the
+      # fall-through would drop (`flag = true; break` -> `flag` is `false |
+      # true` after the loop). nil sink = a `break` not inside an inferred
+      # loop body (a block targeting a method, or top-level) — left to the
+      # existing escaping-block / no-op handling.
+      def eval_break(node)
+        sink = Thread.current[BREAK_SINK_KEY]
+        sink << [node, scope] 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