rigortype 0.4.5 → 0.4.6

data/lib/rigor/inference/statement_evaluator.rb

@@ -14,6 +14,7 @@ require_relative "block_call_timing"
 require_relative "block_repetition"
 require_relative "block_parameter_binder"
 require_relative "body_fixpoint"
+require_relative "callee_mutation_chain"
 require_relative "captured_locals"
 require_relative "dynamic_origin"
 require_relative "error_info"
@@ -45,6 +46,8 @@ require_relative "narrowing"
 require_relative "operand_effects"
 require_relative "operand_walk"
 require_relative "optimistic_origin"
+require_relative "loop_value_record"
+require_relative "project_yielder"
 require_relative "return_barrier"
 require_relative "repeated_or_writes"
 require_relative "rewrite_mutation"
@@ -117,8 +120,8 @@ module Rigor
         # the default expression pair, so routing the or-writes here adds the body entry and nothing else.
         Prism::ConstantOrWriteNode => :eval_constant_write,
         Prism::ConstantPathOrWriteNode => :eval_constant_write,
-        Prism::IfNode => :eval_if,
-        Prism::UnlessNode => :eval_unless,
+        Prism::IfNode => :eval_recorded_if,
+        Prism::UnlessNode => :eval_recorded_unless,
         Prism::ElseNode => :eval_else,
         Prism::CaseNode => :eval_case,
         Prism::CaseMatchNode => :eval_case,
@@ -127,9 +130,9 @@ module Rigor
         Prism::BeginNode => :eval_begin_node,
         Prism::RescueNode => :eval_rescue,
         Prism::EnsureNode => :eval_ensure,
-        Prism::WhileNode => :eval_loop,
-        Prism::UntilNode => :eval_loop,
-        Prism::ForNode => :eval_repeating_for,
+        Prism::WhileNode => :eval_recorded_loop,
+        Prism::UntilNode => :eval_recorded_loop,
+        Prism::ForNode => :eval_recorded_for,
         Prism::AndNode => :eval_and_or,
         Prism::OrNode => :eval_and_or,
         Prism::ParenthesesNode => :eval_parentheses,
@@ -186,6 +189,40 @@ module Rigor
       RETURN_SINK_KEY = :rigor_return_sink
       private_constant :RETURN_SINK_KEY
 
+      # Thread-local flag: set while a side pass ({.provisional_returns}) re-types part of a body from a scope other
+      # than the one the statement walk holds, so the `return`s it reaches are filed as provisional ({ReturnSink}).
+      PROVISIONAL_RETURNS_KEY = :rigor_provisional_returns
+      private_constant :PROVISIONAL_RETURNS_KEY
+
+      # The `return` sink {.with_return_sink} installs. Issue #2299 — a `return` the statement walk records is typed
+      # with its real bindings; one a side pass records ({.provisional_returns}) may read a name the pass skipped the
+      # binding of as `Dynamic[top]`. A provisional record of a `ReturnNode` therefore yields to the walk's record of
+      # the SAME node, and stands only where the walk never reaches that node: a block in expression position (a call
+      # argument, an array element, a chain receiver, a `return` value, an endless-def body), whose tail the side pass
+      # is the only walk to type.
+      class ReturnSink
+        def initialize
+          @types = []
+          @recorded = Set.new.compare_by_identity
+          @provisional = []
+        end
+
+        def record(node, type)
+          if Thread.current[PROVISIONAL_RETURNS_KEY]
+            @provisional << [node, type]
+          else
+            @types << type
+            @recorded << node
+          end
+        end
+
+        # The walk's records, then each provisional record whose node the walk did not record.
+        def types
+          @types + @provisional.filter_map { |node, type| type unless @recorded.include?(node) }
+        end
+      end
+      private_constant :ReturnSink
+
       # Thread-local sink (an Array of `[NextNode, Type]`) collecting the value each `next` carries out of the block it
       # leaves, so `ExpressionTyper#type_block_body` can join those arms into the block's value type. Issue #841: the
       # block-return pass modelled only the fall-through tail, so `ops.all? { |o| next false unless o; true }` read as
@@ -313,14 +350,31 @@ module Rigor
       # method-return type.
       def self.with_return_sink
         previous = Thread.current[RETURN_SINK_KEY]
-        sink = []
+        previous_provisional = Thread.current[PROVISIONAL_RETURNS_KEY]
+        sink = ReturnSink.new
         Thread.current[RETURN_SINK_KEY] = sink
+        Thread.current[PROVISIONAL_RETURNS_KEY] = nil
         begin
           result = yield
         ensure
           Thread.current[RETURN_SINK_KEY] = previous
+          Thread.current[PROVISIONAL_RETURNS_KEY] = previous_provisional
+        end
+        [result, sink.types]
+      end
+
+      # Runs `block` with the `return`s it reaches filed as provisional ({ReturnSink}), restoring the previous state
+      # on exit. Issue #2299 — {ExpressionTyper#type_block_body}'s tail-only answer types `return r if r` without the
+      # `r = yield e` before it, so `r` read `Dynamic[top]` and that went into the enclosing method's return type
+      # although the statement walk of the same block recorded `r` with its real binding.
+      def self.provisional_returns
+        previous = Thread.current[PROVISIONAL_RETURNS_KEY]
+        Thread.current[PROVISIONAL_RETURNS_KEY] = true
+        begin
+          yield
+        ensure
+          Thread.current[PROVISIONAL_RETURNS_KEY] = previous
         end
-        [result, sink]
       end
 
       # Runs `block` with a fresh `next` sink installed, then yields the collected `[NextNode, Type]` pairs to the
@@ -452,19 +506,28 @@ module Rigor
         [type, fall_through, join_jump_scopes(fall_through, sink, JumpTargets.of(body, Prism::NextNode))]
       end
 
-      # ADR-89 WD2 — the sorted positions of the positional parameters whose CONTENT `def_node` mutates
+      # ADR-89 WD2 — the sorted slots of the parameters (positional, then keyword) whose CONTENT `def_node` mutates
       # (`callee_content_mutated_parameters`, the ADR-56 arg-flooring surface a caller consumes). A per-def
       # static property of the AST — this is a pure exposure of the existing private computation (it never
       # reads the scope), so the incremental session can compute it on any `StatementEvaluator` (an empty
       # scope suffices), persist it in a return summary, and re-check a callee's symbol dependents when it
       # moves (a caller's arg flooring changes even if the callee's return does not).
+      #
+      # Issue #2104 — a mutated keyword parameter reports its keyword symbol, after the positions. A parameter the
+      # def hands on to a self-call counts whether or not the callee resolves: the session's empty scope resolves no
+      # callee, and without it an edit that starts or stops forwarding a parameter to a mutating callee would leave
+      # the effects equal and the callers' floors stale.
       def content_mutated_parameter_positions(def_node)
-        callee_content_mutated_parameters(def_node).values.uniq.sort
+        slots = content_parameter_slots(def_node)
+        census = callee_content_mutated_parameters(def_node).values
+        each_forwarding_call(def_node, slots) { |_, forwarded| census += forwarded.map { |name, _| slots[name] } }
+        positions, keywords = census.uniq.partition { |slot| slot.is_a?(Integer) }
+        positions.sort + keywords.sort
       end
 
-      # The local-variable reads among `call_node`'s positional arguments whose matching parameter the callee
-      # content-mutates, when `call_node` is a self-dispatch call resolving to a user def in this evaluator's scope
-      # (`callee_content_mutated_parameters`); empty for any other call. These are the locals the straight-line
+      # The local-variable reads among `call_node`'s arguments (positional, or a keyword's value) whose parameter the
+      # callee content-mutates, when `call_node` is a self-dispatch call resolving to a user def in this evaluator's
+      # scope (`callee_content_mutated_parameters`); empty for any other call. These are the locals the straight-line
       # callee floor ({#widen_callee_escaped_argument_captures}) floors after the call, and the ones
       # {CapturedLocals.content_mutations} reports as a block's callee-mutated captures.
       def content_mutated_arguments(call_node)
@@ -480,12 +543,25 @@ module Rigor
         return NO_ARGUMENT_READS if mutated.empty?
 
         argument_nodes = call_node.arguments.arguments
-        mutated.values.uniq.filter_map do |index|
-          argument = argument_nodes[index]
+        mutated.values.uniq.filter_map do |slot|
+          argument = slot.is_a?(Symbol) ? keyword_argument(argument_nodes, slot) : argument_nodes[slot]
+          argument = argument.value if argument.is_a?(Prism::ImplicitNode)
           argument if argument.is_a?(Prism::LocalVariableReadNode)
         end
       end
 
+      # The value `argument_nodes` pass for the keyword `name` (`poke(acc: a)`), or nil.
+      def keyword_argument(argument_nodes, name)
+        hash = argument_nodes.last
+        return unless hash.is_a?(Prism::KeywordHashNode)
+
+        pair = hash.elements.find do |element|
+          element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode) &&
+            element.key.unescaped.to_sym == name
+        end
+        pair&.value
+      end
+
       NO_ARGUMENT_READS = [].freeze
       private_constant :NO_ARGUMENT_READS
 
@@ -678,7 +754,19 @@ module Rigor
         # stamped by {#seed_instance_ivars}.
         bound = bound.with_published_constant_mark(:ivar, node.name) if
           published_constant_copy?(node.value, rhs_type, post_rhs)
-        [rhs_type, bound]
+        [rhs_type, mark_inferred_param_ivar(bound, node)]
+      end
+
+      # Issue #2189 — the ivar twin of {#bind_local_write}'s ADR-67 WD6b stamp: `@x = param; @x.upcase` reads the
+      # parameter's open-call-site lower bound back, so the ivar carries the `:inferred_param` mark under its
+      # `@`-prefixed name and {Analysis::CheckRules::InferredParamGuard} declines on the read. A write from any
+      # other RHS clears it. Method-local only: the class-ivar census seeding a sibling method types the RHS
+      # without the inference seed, so no lower bound crosses the method boundary to guard.
+      def mark_inferred_param_ivar(bound, node)
+        return bound.with_inferred_param_mark(node.name) if
+          Analysis::CheckRules::InferredParamGuard.rooted?(node.value, scope)
+
+        bound.without_inferred_param_mark(node.name)
       end
 
       def eval_cvar_write(node)
@@ -832,11 +920,24 @@ module Rigor
 
       def compound_eval(node, kind:, op:) # rubocop:disable Naming/MethodParameterName
         current_type = current_type_for(kind, node.name)
-        rhs_type, post_rhs = sub_eval(node.value, scope)
+        rhs_type, post_rhs = sub_eval(node.value, compound_value_scope(kind, node.name, op))
         result_type = compound_result_type(current_type, rhs_type, op)
         [result_type, rebind_variable(post_rhs, kind, node.name, result_type)]
       end
 
+      # Issue #2214 — the scope a compound write's value operand runs in. `x &&= v` runs `v` only when `x` is truthy,
+      # as `x && (x = v)` does, so `v` reads `x` narrowed to its truthy part: `c &&= c + 1` on an `Integer?` `c` reads
+      # `Integer`, not the `nil` that drew `call.possible-nil-receiver`. `x ||= v` and an operator write run `v` from
+      # the scope they start in; a variable the scope does not bind is left alone.
+      def compound_value_scope(kind, name, operator)
+        return scope unless operator == :and
+
+        current = scope.public_send(VAR_KIND_GETTERS.fetch(kind), name)
+        return scope if current.nil?
+
+        scope.public_send(VAR_KIND_BUILDERS.fetch(kind), name, Narrowing.narrow_truthy(current))
+      end
+
       VAR_KIND_GETTERS = {
         local: :local, ivar: :ivar, cvar: :cvar, global: :global
       }.freeze
@@ -906,7 +1007,40 @@ module Rigor
                                         arg_types: index_write_arg_types(node, result_type))
         post = post.with_indexed_narrowing(*address, result_type) if address
 
-        [result_type, forget_rebound_specials(post, node)]
+        # The value the expression yields takes the memoizing reading ({#index_compound_write_value}, #1155) for a
+        # fresh container or construction rvalue, with a container's literal precision erased
+        # ({#memo_bound_value}).
+        [memo_bound_value(node, result_type), forget_rebound_specials(post, node)]
+      end
+
+      # What `x = (tbl[k] ||= v)` binds `x` to. Where {#index_compound_write_value} reads the memoizing idiom, the
+      # slot may hold ANY earlier value of the table, so `x` is the rvalue only as far as its CLASS is known: a
+      # `{}` / `[]` rvalue (a shape or tuple) erases to `Hash[untyped, untyped]` / `Array[untyped]`, because the
+      # stored table is not empty after the first store (`entry[:name].upcase` is no call on nil), and a
+      # construction (`new(...)`, a nominal) is kept. Every other rvalue (a Constant, a union) keeps the stored
+      # `Dynamic | v`, since a literal would read the slot as freshly created at every later read.
+      def memo_bound_value(node, stored)
+        return stored unless node.is_a?(Prism::IndexOrWriteNode)
+
+        value = index_compound_write_value(node)
+        return stored if value == stored
+
+        erased = erase_memo_container(value)
+        erased || stored
+      end
+
+      def erase_memo_container(type)
+        any = Type::Combinator.untyped
+        case type
+        when Type::HashShape then Type::Combinator.nominal_of("Hash", type_args: [any, any])
+        when Type::Tuple then Type::Combinator.nominal_of("Array", type_args: [any])
+        when Type::Nominal
+          case type.class_name
+          when "Hash" then Type::Combinator.nominal_of("Hash", type_args: [any, any])
+          when "Array" then Type::Combinator.nominal_of("Array", type_args: [any])
+          else type
+          end
+        end
       end
 
       # `h[k] &&= v` / `h[k] += v`. Neither had a handler, so both fell to `evaluate`'s default — typed as a pure
@@ -1446,7 +1580,10 @@ module Rigor
           after
         end
         body_entry = reduce_scopes_with_nil_injection(test_exits)
-        return [Narrowing.apply_when_regex_globals(conditions, body_entry), after, true] if rebound
+        if rebound
+          body_entry, after = [body_entry, after].map { |s| forget_called_global_subject(subject, s) }
+          return [Narrowing.apply_when_regex_globals(conditions, body_entry), after, true]
+        end
 
         [Narrowing.case_when_scopes(subject, conditions, body_entry).first,
          Narrowing.case_when_scopes(subject, conditions, after).last, false]
@@ -1493,16 +1630,21 @@ module Rigor
       # reads: its binding moved, the test writes it, or — for an instance variable — a call in the test may write
       # it ({InterveningIvarReset.may_write?}), or — for a global or constant — the test may run code that rebinds
       # one ({GuardRebinding.may_rebind?}).
+      #
+      # A subject that writes a local or instance variable (`case (@x = v)`) is read as that variable, as
+      # {Narrowing.case_when_scopes} narrows it (issue #2211). For such an instance variable the binding test above
+      # answers first (the test's call widens it in {#run_when_test}), so its `may_write?` arm is a guard.
       def when_test_rebinds_subject?(subject, condition, before, after)
+        subject = case_subject_variable(subject)
         name = case_subject_name(subject)
         return false if name.nil?
         return true unless case_subject_binding(subject, before) == case_subject_binding(subject, after)
         return true if OperandEffects.written_variables(condition).include?(name)
 
         case subject
-        when Prism::InstanceVariableReadNode
+        when Prism::InstanceVariableReadNode, Prism::InstanceVariableWriteNode
           InterveningIvarReset.may_write?(condition, name, before, run_lambdas: true)
-        when Prism::LocalVariableReadNode
+        when Prism::LocalVariableReadNode, Prism::LocalVariableWriteNode
           false
         else
           body = when_lambda_body(condition)
@@ -1510,9 +1652,29 @@ module Rigor
         end
       end
 
+      # Issue #2211 — a global subject from a `when` test that may rebind it on ({#when_test_rebinds_subject?}): a
+      # method may assign a global, and the statement walk keeps a global's binding past a call, so the clause
+      # bodies and the later clauses read it as `Dynamic[top]`, as the scope index's walk of a value-position `case`
+      # reads it
+      # (`ScopeIndexer#forget_called_subject`). `$g = nil; case $g when String then 1 when reset! then 2 else $g + 1
+      # end`, with `reset!` assigning `$g`, is `6` in Ruby. An instance variable a test's call may write is widened by
+      # {#run_when_test} instead; any other subject is left as is.
+      def forget_called_global_subject(subject, scope)
+        return scope unless subject.is_a?(Prism::GlobalVariableReadNode)
+
+        scope.with_global(subject.name, Type::Combinator.untyped)
+      end
+
+      # The subject node the rebinding test reads: a parenthesised one unwrapped, and a local or instance variable
+      # write kept as the variable it writes.
+      def case_subject_variable(subject)
+        Narrowing.unwrap_case_subject(subject)
+      end
+
       def case_subject_name(subject)
         case subject
-        when Prism::LocalVariableReadNode, Prism::InstanceVariableReadNode, Prism::GlobalVariableReadNode
+        when Prism::LocalVariableReadNode, Prism::InstanceVariableReadNode, Prism::GlobalVariableReadNode,
+             Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode
           subject.name
         when Prism::ConstantReadNode, Prism::ConstantPathNode
           Narrowing.constant_key(subject)
@@ -1521,8 +1683,8 @@ module Rigor
 
       def case_subject_binding(subject, scope)
         case subject
-        when Prism::LocalVariableReadNode then scope.local(subject.name)
-        when Prism::InstanceVariableReadNode then scope.ivar(subject.name)
+        when Prism::LocalVariableReadNode, Prism::LocalVariableWriteNode then scope.local(subject.name)
+        when Prism::InstanceVariableReadNode, Prism::InstanceVariableWriteNode then scope.ivar(subject.name)
         when Prism::GlobalVariableReadNode then scope.global(subject.name)
         else scope.constant_narrowing(Narrowing.constant_key(subject))
         end
@@ -2222,16 +2384,37 @@ module Rigor
       # ({#loop_body_ivar_writes}).
       def eval_repeating_for(node) = ReflectiveIvarWrite.in_repeating_body { eval_for(node) }
 
+      # A loop's evaluation, with its value recorded for `ExpressionTyper#type_of_loop` ({LoopValueRecord}).
+      # A conditional's evaluation, recorded when it evaluated a loop ({LoopValueRecord.conditional}): the typer
+      # types a conditional that holds a loop again from the scope it was evaluated from, and the loop in its branch
+      # is evaluated from a branch scope no record matches.
+      def eval_recorded_if(node) = record_conditional_value(node) { eval_if(node) }
+
+      def eval_recorded_unless(node) = record_conditional_value(node) { eval_unless(node) }
+
+      # The "evaluated a loop" gate is a memory-only guard: recording every conditional would give the same answers, at
+      # the cost of a retained scope per `if` node, so no behavioural example pins it.
+      def record_conditional_value(node)
+        before = LoopValueRecord.loops_evaluated
+        result = yield
+        LoopValueRecord.conditional(node, scope, result.first) unless LoopValueRecord.loops_evaluated == before
+        result
+      end
+
+      def eval_recorded_loop(node) = record_loop_value(node, eval_loop(node))
+
+      def eval_recorded_for(node) = record_loop_value(node, eval_repeating_for(node))
+
+      def record_loop_value(node, result)
+        LoopValueRecord.record(node, scope, result.first)
+        result
+      end
+
       # `while pred; body; end` / `until pred; body; end`. The body might run zero or more times, so half-bound names
-      # degrade to `T | nil` in the post-loop scope. The loop expression itself types as `Constant[nil]` (Slice 3 phase
-      # 1), reflecting the common case where no `break VALUE` is observed.
+      # degrade to `T | nil` in the post-loop scope. The loop expression is `nil` joined with the value of every `break`
+      # that leaves this loop ({#loop_value}, issue #2031).
       def eval_loop(node)
-        # Issue #1930 — the predicate runs before every iteration but is walked once, so a literal-name
-        # `instance_variable_set` in it joins its value and `Dynamic[top]` ({ReflectiveIvarWrite.in_repeating_body}):
-        # the rebind fixpoint tracks the body's writes only.
-        entry = loop_entry_scope(node)
-        _pred_type, post_pred = ReflectiveIvarWrite.in_repeating_body { sub_eval(node.predicate, entry) }
-        post_pred = widen_predicate_pins(node, post_pred)
+        post_pred = loop_predicate_scope(node)
         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
@@ -2248,7 +2431,7 @@ module Rigor
         # The pass ends with its `next` exits as well as its fall-through ({#loop_iteration}). Its `break` arms are
         # superseded by the fixpoint's converged pass ({#loop_break_arms}) except in a `begin … end while` loop, below.
         jumps = loop_jumps(node.statements)
-        body_scope, first_breaks = single_pass(node, post_pred, jumps)
+        body_scope, first_breaks, first_values = single_pass(node, post_pred, jumps)
         base_scope = join_with_nil_injection(post_pred, body_scope)
 
         names, body_first = loop_rebound_names(node.statements, post_pred)
@@ -2258,17 +2441,50 @@ module Rigor
         # the single-pass join before returning.
         if names.empty?
           fast = loop_content_writeback(node.statements, base_scope, pre_body: post_pred)
-          return [Type::Combinator.constant_of(nil), loop_exit(node, post_pred, fast)]
+          return [loop_value(node, first_values), loop_exit(node, post_pred, fast)]
         end
 
-        post_loop = converged_loop_scope(node, post_pred, base_scope, names, body_first, jumps)
+        post_loop, values = converged_loop_scope(node, post_pred, base_scope, names, body_first, jumps)
         # A `begin … end while` / `until` body runs once before the predicate is first tested, so that iteration's
         # entry lies outside every fixpoint pass's predicate-narrowed one, and a `break` only it can take (`if state ==
         # :idle` under `end while state != :idle`) is dead in every converged pass. The single pass runs from the
         # un-narrowed post-predicate scope, so its arms stand in for that first iteration.
         post_loop = join_break_scopes(post_loop, first_breaks, names) if node.begin_modifier?
         post_loop = loop_exit(node, post_pred, post_loop)
-        [Type::Combinator.constant_of(nil), post_loop]
+        [loop_value(node, first_values + values), post_loop]
+      end
+
+      # The scope a loop's predicate leaves, which the body and the exit edge start from. Issue #1930 — the predicate
+      # runs before every iteration but is walked once, so a literal-name `instance_variable_set` in it joins its value
+      # and `Dynamic[top]` ({ReflectiveIvarWrite.in_repeating_body}): the rebind fixpoint tracks the body's writes only.
+      def loop_predicate_scope(node)
+        entry = loop_entry_scope(node)
+        _pred_type, post_pred = ReflectiveIvarWrite.in_repeating_body { sub_eval(node.predicate, entry) }
+        widen_predicate_pins(node, post_pred)
+      end
+
+      # Issue #2031 — a `while` / `until` expression is `nil` when its predicate ends it and the value of the `break`
+      # that ends it otherwise: `x = while i < k; break @r if i == 4; end` is `"four"` or `nil`. `break_values` holds
+      # what each `break` targeting this loop carried, from the single body pass (the first iteration) and the pass
+      # from the converged bindings ({#loop_break_arms}), which together cover the entry of every iteration. A literal
+      # `while true` / `until false` / `until nil` is never ended by its predicate, so only its `break`s give it a
+      # value; any other predicate is assumed to end it, since its first evaluation says nothing about later ones. A
+      # loop with no reachable `break` keeps its `nil`.
+      def loop_value(node, break_values)
+        nil_type = Type::Combinator.constant_of(nil)
+        return nil_type if break_values.empty?
+        return Type::Combinator.union(*break_values) if endless_loop_predicate?(node)
+
+        Type::Combinator.union(nil_type, *break_values)
+      end
+
+      def endless_loop_predicate?(node)
+        predicate = node.predicate
+        if node.is_a?(Prism::UntilNode)
+          predicate.is_a?(Prism::FalseNode) || predicate.is_a?(Prism::NilNode)
+        else
+          predicate.is_a?(Prism::TrueNode)
+        end
       end
 
       # Issue #1359 — the scope a loop's predicate first runs from: a body that may set `$_` runs again after it ran,
@@ -2330,7 +2546,8 @@ module Rigor
 
       # 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, then the `break`-path bindings the fall-through
-      # dropped (`flag = true; break` -> `flag` is `false | true`, not the stale `false`).
+      # dropped (`flag = true; break` -> `flag` is `false | true`, not the stale `false`). Returns `[scope, values]`,
+      # `values` being what the converged pass's `break`s carry ({#loop_value}).
       def converged_loop_scope(node, post_pred, base_scope, names, body_first, jumps)
         # 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` →
@@ -2338,7 +2555,7 @@ module Rigor
         # 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.
-        break_pass = jumps.breaks && { entry: nil, arms: [] }
+        break_pass = { entry: nil, arms: [], values: [] } if jumps.breaks || later_pass_returns?(node.statements)
         result = loop_rebind_fixpoint(node, post_pred, names, body_first, jumps, break_pass)
         # 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
@@ -2350,8 +2567,8 @@ module Rigor
         # the continuation collection. Pre-state comes from `post_pred` for a name the loop only content-mutates and
         # from `post_loop` for one it also rebinds, so composition still works — see {#loop_content_writeback}.
         post_loop = loop_content_writeback(node.statements, post_loop, pre_body: post_pred, rebound: names)
-        arms = loop_break_arms(node, post_pred, result, body_first, jumps, break_pass)
-        join_break_scopes(post_loop, arms, names)
+        arms, values = loop_break_arms(node, post_pred, result, body_first, jumps, break_pass)
+        [join_break_scopes(post_loop, arms, names), values]
       end
 
       # A loop's continuation: a local its body and predicate only narrowed from `Dynamic[top]` re-joins to it
@@ -2444,8 +2661,11 @@ module Rigor
         [sink, result]
       end
 
-      # One evaluation of a loop body from `entry`. Returns `[exit, breaks]`: the scope the iteration ends with, and the
-      # scopes at the `break`s that target the loop ({LoopJumps}). Every reader of a loop body goes through here — the
+      # One evaluation of a loop body from `entry`. Returns `[exit, breaks, values]`: the scope the iteration ends with,
+      # the scopes at the `break`s that target the loop ({LoopJumps}), and the values those `break`s carry, read from a
+      # `break`-value sink of the loop's own ({#loop_value}); filtering it by the loop's `break`s is defensive, since a
+      # nested loop installs its own sink and a nested block's call evaluates its body under another, so no example
+      # tells the filter apart today. Every reader of a loop body goes through here — the
       # single pass `eval_loop` joins with the pre-loop scope, each pass of its rebind fixpoint, and `eval_for`'s only
       # pass.
       #
@@ -2463,18 +2683,21 @@ module Rigor
         recording = recorded ? {} : UNRECORDED
         evaluate = -> { sub_eval(statements, entry, next_scope_sink: next_sink, **recording).last }
         if jumps.breaks
-          break_sink, fall_through = collect_break_scopes(&evaluate)
+          break_sink, (fall_through, value_sink) = collect_break_scopes do
+            StatementEvaluator.with_break_value_sink(&evaluate)
+          end
           breaks = targeted_scopes(break_sink, jumps.breaks)
+          values = targeted_scopes(value_sink, jumps.breaks)
         else
           fall_through = evaluate.call
-          breaks = NO_BREAK_ARMS
+          breaks = values = NO_BREAK_ARMS
         end
-        return [fall_through, breaks] if next_sink.nil?
+        return [fall_through, breaks, values] if next_sink.nil?
 
         exit_scope = targeted_scopes(next_sink, jumps.nexts).reduce(fall_through) do |acc, next_scope|
           join_with_nil_injection(acc, next_scope)
         end
-        [exit_scope, breaks]
+        [exit_scope, breaks, values]
       end
 
       # The `break` scopes the continuation joins. A `break` leaves the loop, so its binding starts no further iteration
@@ -2494,12 +2717,24 @@ module Rigor
       # The unrecorded pass is otherwise an ordinary evaluation: a `return` it reaches joins the enclosing method's
       # inferred return type, as one any other pass reaches does. That only widens the return, toward values a capped
       # fixpoint's own passes never evaluated.
+      #
+      # Returns `[arms, values]`, `values` being what the same pass's `break`s carry ({#loop_value}).
       def loop_break_arms(node, post_pred, converged, body_first, jumps, break_pass)
-        return NO_BREAK_ARMS if break_pass.nil?
-        return break_pass[:arms] if break_pass[:entry] == converged.except(*body_first)
+        return [NO_BREAK_ARMS, NO_BREAK_ARMS] if break_pass.nil?
+        return break_pass.values_at(:arms, :values) if break_pass[:entry] == converged.except(*body_first)
 
         entry = loop_pass_entry(node, post_pred, converged, body_first, jumps)
-        loop_iteration(node.statements, entry, jumps, recorded: false).last
+        loop_iteration(node.statements, entry, jumps, recorded: false).drop(1)
+      end
+
+      # Issue #2128 — whether a pass from the converged bindings must run for the `return`s in a loop body: a method's
+      # return sink is active and the body holds a `return` that exits the method ({ReturnBarrier.exits_method?}). A
+      # `return` whose condition reads a loop-carried local (`return false if seen > 3` after `seen += 1`) is dead in
+      # every capped fixpoint pass, which runs from a value-pinned assumption (`seen` at most `3`), and only the pass
+      # from the widened binding reaches it ({#loop_break_arms}); without it the method inferred `true` and a
+      # caller's test on it folded always-truthy on correct code.
+      def later_pass_returns?(statements)
+        !Thread.current[RETURN_SINK_KEY].nil? && ReturnBarrier.exits_method?(statements)
       end
 
       # Joins each `break` arm's body-written local bindings into the loop continuation, so a `break`-path binding the
@@ -2674,10 +2909,11 @@ module Rigor
       # it.
       def loop_body_exit_bindings(node, post_pred, bindings, names, body_first, jumps, break_pass = nil)
         entry = loop_pass_entry(node, post_pred, bindings, body_first, jumps)
-        exit_scope, breaks = loop_iteration(node.statements, entry, jumps)
+        exit_scope, breaks, values = loop_iteration(node.statements, entry, jumps)
         if break_pass
           break_pass[:entry] = bindings.except(*body_first)
           break_pass[:arms] = breaks
+          break_pass[:values] = values
         end
         names.to_h { |name| [name, CapturedLocals.bound_type(exit_scope, name)] }
       end
@@ -2736,29 +2972,157 @@ module Rigor
       # index variable AND every local written in the body leak to the surrounding scope. The collection is evaluated
       # once; the body runs zero or more times, so the post-loop scope is the join of the no-iteration scope (just
       # `post_collection`) and the body scope, with half-bound names degraded to `T | nil` via nil-injection. The loop
-      # expression itself types as `Constant[nil]`, the policy `eval_loop` uses for `while` / `until` — a known gap for
-      # `for`, whose value in Ruby is the collection it iterated (issue #1216).
+      # expression is the collection's `each` value joined with every `break` value ({#for_value}, issue #1216).
       def eval_for(node)
         coll_type, post_coll = sub_eval(node.collection, scope)
-        element_type = for_iteration_element_type(coll_type)
-        # Issue #1359 — a body that may set `$_` runs again after it ran, as a `while` body does ({#eval_loop}).
-        body_entry = LastLine.forget_if_set(bind_for_index(node.index, element_type, post_coll), node.statements)
-        body_entry = forget_guard_for_body(node, post_coll, body_entry)
-        body_entry = loop_content_entry(node.statements, post_coll, body_entry)
+        body_entry = for_body_entry(node, for_iteration_element_type(coll_type), post_coll)
 
         if node.statements.nil?
-          return [Type::Combinator.constant_of(nil), join_with_nil_injection(post_coll, body_entry)]
+          return [for_value(node, coll_type, post_coll, NO_BREAK_ARMS),
+                  join_with_nil_injection(post_coll, body_entry)]
         end
 
         # The body pass ends with its `next` exits as well as its fall-through, and its `break` arms are recovered into
         # the continuation (the `for` sibling of `eval_loop`'s break join; `for` has no fixpoint, so the single pass is
         # the only continuation and the only source of `break` arms).
         jumps = loop_jumps(node.statements)
-        body_scope, breaks = loop_iteration(node.statements, body_entry, jumps)
+        body_scope, breaks, values = loop_iteration(node.statements, body_entry, jumps)
+        values += later_for_pass_values(node.statements, body_entry, body_scope, jumps)
         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, breaks, pre_existing + body_first)
-        [Type::Combinator.constant_of(nil), for_exit(node, post_coll, continuation)]
+        continuation = for_exit(node, post_coll, join_break_scopes(continuation, breaks, pre_existing + body_first))
+        continuation = widen_for_elements(node, continuation)
+        [for_value(node, coll_type, continuation, values), continuation]
+      end
+
+      # Issue #2262 — the variables the collection reads, past a body that mutates an element in place: `for x in a;
+      # x << 2; end` leaves `a[0]` holding what the literal's shape did not.
+      def widen_for_elements(node, scope)
+        DeepErasure.widen_element_aliases(
+          node.collection, node.statements, DeepErasure.parameter_names(node.index), scope
+        )
+      end
+
+      # Issue #2128 — a `for` body has no rebind fixpoint, so its only pass enters with every loop-carried local at its
+      # pre-loop binding, and a `return` or `break` whose condition needs a later iteration (`n = 0; for x in xs;
+      # return :f if (n += 1) > 2; end`) was never reached. When the body holds such a jump (a `break`, or a `return`
+      # that exits the method while a return sink is active, {#later_pass_returns?}), one more unrecorded pass runs
+      # with each local and instance variable the body rebinds at its value-pinned widening
+      # (`Type::Combinator.widen_value_pinned`) of its entry binding joined with the first pass's exit, a binding that
+      # covers what any iteration enters with, as the `while` fixpoint's widened binding does. The `return`s it
+      # reaches join the method's return type as any pass's do, and the `break` values it collects are returned for
+      # the loop's value ({#for_value}). The pass records no scope, and the continuation keeps the first pass's
+      # answer.
+      def later_for_pass_values(statements, body_entry, body_scope, jumps)
+        return NO_BREAK_ARMS unless jumps.breaks || later_pass_returns?(statements)
+
+        names, body_first = loop_rebound_names(statements, body_entry)
+        bindings = (names - body_first).filter_map do |name|
+          joined = [body_entry, body_scope].filter_map { |s| CapturedLocals.bound_type(s, name) }
+          [name, Type::Combinator.widen_value_pinned(Type::Combinator.union(*joined))] unless joined.empty?
+        end
+        return NO_BREAK_ARMS if bindings.empty?
+
+        entry = bindings.reduce(body_entry) { |acc, (name, type)| bind_capture(acc, name, type) }
+        loop_iteration(statements, entry, jumps, recorded: false)[2]
+      end
+
+      # The core collections whose `each` with a block answers its receiver.
+      FOR_SELF_EACH_CLASSES = Set["Array", "Hash", "Range"].freeze
+      private_constant :FOR_SELF_EACH_CLASSES
+
+      # The nodes through which a `for` body or index may change the iterated collection's contents: a call (an
+      # in-place mutator on the collection or on an alias of it, or a method that reaches it), `yield` / `super`, an
+      # index store, and an operator write, which calls its operator on the variable's value (`b <<= 9` appends to
+      # the array `b` holds).
+      FOR_MUTATING_NODES = Set[
+        Prism::CallNode, Prism::YieldNode, Prism::SuperNode, Prism::ForwardingSuperNode, Prism::IndexTargetNode,
+        Prism::IndexOperatorWriteNode, Prism::IndexOrWriteNode, Prism::IndexAndWriteNode,
+        Prism::CallOperatorWriteNode, Prism::CallOrWriteNode, Prism::CallAndWriteNode,
+        Prism::LocalVariableOperatorWriteNode, Prism::InstanceVariableOperatorWriteNode,
+        Prism::ClassVariableOperatorWriteNode, Prism::GlobalVariableOperatorWriteNode
+      ].freeze
+      FOR_VARIABLE_READS = Set[Prism::LocalVariableReadNode, Prism::InstanceVariableReadNode].freeze
+      private_constant :FOR_MUTATING_NODES, :FOR_VARIABLE_READS
+
+      # Issue #1216 — `for x in coll` is `coll.each { |x| … }`, so the loop's value is what that `each` answers, or
+      # the value of the `break` that ends it. An Array, a Hash and a Range answer themselves, including when
+      # they are empty and the body never runs, so the value is the collection ({#for_collection_after}). Any other
+      # collection (`Dynamic`, a project class, an `Enumerator`, a union with `nil`) answers `Dynamic[top]`: its
+      # `each` is not known to answer its receiver, and a guessed type would be a claim the analysis cannot back.
+      def for_value(node, coll_type, continuation, break_values)
+        each_value = each_answers_self?(coll_type) ? for_collection_after(node, coll_type, continuation) : Type::Combinator.untyped
+        break_values.empty? ? each_value : Type::Combinator.union(each_value, *break_values)
+      end
+
+      # The collection as the loop leaves it. `each` answers the object it iterated, after the body ran, so a body that
+      # may change its contents ({FOR_MUTATING_NODES}: `a.pop`, `h.delete(k)`, `b << 3` on an alias `b`) leaves
+      # neither its shape nor its size: `a = [1, 2]; for i in a; a.pop; end` is `[1]`. The value is then the
+      # collection's type with every shape and refinement dropped to its nominal ({#shape_erased_collection}), joined,
+      # when the collection is a local or instance variable the loop does not rebind, with that variable's binding
+      # after the loop, which holds the contents the body's own mutator calls add. A body that runs no such code
+      # leaves the collection as it was.
+      def for_collection_after(node, coll_type, continuation)
+        return coll_type unless [node.index, node.statements].any? { |part| for_may_mutate?(part) }
+
+        types = [coll_type]
+        name = for_collection_variable(node)
+        types << CapturedLocals.bound_type(continuation, name) if name
+        deep = DeepErasure.element_mutation?(node.statements, DeepErasure.parameter_names(node.index))
+        Type::Combinator.union(*types.compact.map { |type| shape_erased_collection(type, deep: deep) })
+      end
+
+      def for_may_mutate?(part)
+        return false if part.nil?
+
+        found = false
+        Source::NodeWalker.each(part) { |descendant| found ||= FOR_MUTATING_NODES.include?(descendant.class) }
+        found || FOR_MUTATING_NODES.include?(part.class)
+      end
+
+      # The local or instance variable `for` iterates, when neither its index nor its body rebinds it.
+      def for_collection_variable(node)
+        collection = node.collection
+        return nil unless FOR_VARIABLE_READS.include?(collection.class)
+
+        written = OperandEffects.written_variables(node.index) + OperandEffects.written_variables(node.statements)
+        written.include?(collection.name) ? nil : collection.name
+      end
+
+      # `type` with each `Tuple` / `HashShape` / literal Array or Hash dropped to its nominal, each refinement to its
+      # base. A Range is immutable and keeps its value.
+      def shape_erased_collection(type, deep: false)
+        # A body that mutates an element in place changes the shapes one level down too, which `each` answers
+        # as the elements' own objects ({DeepErasure.widen}).
+        return DeepErasure.widen(type) if deep && !(type.is_a?(Type::Constant) && type.value.is_a?(Range))
+
+        case type
+        when Type::Tuple then MutationWidening.widen_tuple(type)
+        when Type::HashShape then MutationWidening.widen_hash_shape(type)
+        when Type::Constant then type.value.is_a?(Range) ? type : Type::Combinator.widen_value_pinned(type)
+        when Type::Refined, Type::Difference then shape_erased_collection(type.base)
+        when Type::Union then Type::Combinator.union(*type.members.map { |member| shape_erased_collection(member) })
+        else type
+        end
+      end
+
+      def each_answers_self?(type)
+        case type
+        when Type::Tuple, Type::HashShape then true
+        when Type::Nominal then FOR_SELF_EACH_CLASSES.include?(type.class_name)
+        when Type::Constant then type.value.is_a?(Array) || type.value.is_a?(Hash) || type.value.is_a?(Range)
+        when Type::Refined, Type::Difference then each_answers_self?(type.base)
+        when Type::Union then type.members.all? { |member| each_answers_self?(member) }
+        else false
+        end
+      end
+
+      # The scope a `for` body enters with: the index bound to the element. Issue #1359 — a body that may set `$_` runs
+      # again after it ran, as a `while` body does ({#eval_loop}).
+      def for_body_entry(node, element_type, post_coll)
+        body_entry = LastLine.forget_if_set(bind_for_index(node.index, element_type, post_coll), node.statements)
+        body_entry = forget_guard_for_body(node, post_coll, body_entry)
+        loop_content_entry(node.statements, post_coll, body_entry)
       end
 
       # Issue #1429 — a `for` body runs after the collection's `each`, which may be a project method, and after itself.
@@ -4124,13 +4488,163 @@ module Rigor
         end
       end
 
-      # The `{ name => position }` positional parameters whose content the callee mutates, from either channel: those
-      # escape-mutated inside a block (which may run later / repeatedly) AND those mutated directly in the method body
-      # during the call itself (`declaration[:prefix] = v`). Both leave the caller's argument binding stale after the
-      # call, so both floor it. Memoised per def node (the merge is otherwise recomputed at every call site).
+      # The `{ name => slot }` parameters whose content the callee mutates, a slot being a positional index or a
+      # keyword symbol: those it mutates itself ({#own_content_parameters}) and, issue #2104, those it passes on to a
+      # self-call whose callee mutates them, through any number of such hand-offs ({CalleeMutationChain}). Each leaves
+      # the caller's argument binding stale after the call, so each floors it. Memoised per def node (the closure is
+      # otherwise recomputed at every call site), and across evaluators by {#resolved_census}.
       def callee_content_mutated_parameters(def_node)
         cache = (@callee_mutated_param_cache ||= {}.compare_by_identity)
-        cache[def_node] ||= escaped_content_parameters(def_node).merge(direct_content_parameters(def_node))
+        cache[def_node] ||= resolved_census(:close, def_node) do
+          CalleeMutationChain.close(def_node, own: method(:own_content_parameters), edges: method(:forwarding_edges))
+        end
+      end
+
+      # Issue #2104 — the per-thread memo of a census that also resolves self-calls ({#resolve_self_callee_def}), so it
+      # reads, besides `def_node`'s AST, the class self-calls resolve in and the discovery index whose def table they
+      # resolve through. Those two key it: the index by identity, as it is immutable (one slot, as a file's analysis
+      # reads one index; a scope indexed for another file replaces it), the class by name. A run builds hundreds of
+      # thousands of evaluators, and a per-evaluator memo alone recomputed each closure and each def's edges about
+      # thirty times over (#2295's cost on the release gate).
+      #
+      # While a dependency recorder is active the memo is bypassed: a resolution records an ADR-46 read in the file
+      # and in each capture window open at the time, and a hit would leave that read out of them.
+      def resolved_census(kind, def_node)
+        return yield if Analysis::DependencyRecorder.active?
+
+        discovery = scope.discovery
+        slot = Thread.current[RESOLVED_CENSUS_KEY]
+        slot = Thread.current[RESOLVED_CENSUS_KEY] = [discovery, {}] unless slot&.first.equal?(discovery)
+        by_class = (slot.last[kind] ||= {})
+        class_name = enclosing_class_name_for(scope.self_type)
+        by_def = (by_class[class_name] ||= {}.compare_by_identity)
+        by_def.fetch(def_node) { by_def[def_node] = yield }
+      end
+
+      RESOLVED_CENSUS_KEY = :rigor_callee_resolved_census
+      private_constant :RESOLVED_CENSUS_KEY
+
+      # The parameters `def_node` mutates itself, from either channel: those escape-mutated inside a block (which may
+      # run later / repeatedly) AND those mutated directly in the method body during the call itself
+      # (`declaration[:prefix] = v`). A property of the def's AST alone, so it is memoised per def node for the thread
+      # ({#def_census}) rather than per evaluator: a chain reads its callees' census from every evaluator that floors a
+      # call into it.
+      def own_content_parameters(def_node)
+        def_census(:own, def_node) { escaped_content_parameters(def_node).merge(direct_content_parameters(def_node)) }
+      end
+
+      # Issue #2104 — the per-thread memo of a census that reads nothing but `def_node`'s AST, under `kind`.
+      def def_census(kind, def_node)
+        table = (Thread.current[DEF_CENSUS_KEY] ||= ObjectSpace::WeakKeyMap.new)
+        entry = (table[def_node] ||= {})
+        entry.fetch(kind) { entry[kind] = yield }
+      end
+
+      DEF_CENSUS_KEY = :rigor_callee_def_census
+      private_constant :DEF_CENSUS_KEY
+
+      # Issue #2104 — the {CalleeMutationChain::Edge}s along which `def_node` hands one of its parameters, unchanged, to
+      # a self-call resolving to a user def: a positional argument or a keyword value that reads the parameter itself
+      # (not a block-local shadowing it), in the method body or a block in it. The callee resolves in this evaluator's
+      # class, the receiver's class at every hop of a self-call chain. Memoised per def node, and across evaluators by
+      # {#resolved_census}.
+      def forwarding_edges(def_node)
+        cache = (@forwarding_edge_cache ||= {}.compare_by_identity)
+        cache[def_node] ||= resolved_census(:edges, def_node) { compute_forwarding_edges(def_node) }
+      end
+
+      def compute_forwarding_edges(def_node)
+        slots = content_parameter_slots(def_node)
+        edges = []
+        each_forwarding_call(def_node, slots) do |call_node, forwarded|
+          callee = resolve_self_callee_def(call_node)
+          next if callee.nil?
+
+          callee_slots = content_parameter_slots(callee)
+          forwarded.each do |name, callee_slot|
+            names = bound_parameter_names(callee_slots, callee_slot)
+            next if names.empty?
+
+            edges << CalleeMutationChain::Edge.new(name: name, slot: slots[name], callee: callee, callee_names: names)
+          end
+        end
+        edges.empty? ? NO_FORWARDS : edges
+      end
+
+      # Yields each self-call in `def_node`'s body that hands on one of `slots`' parameters, with
+      # {#forwarded_parameters}' answer for it. The calls are an AST property, memoised per def node ({#def_census}).
+      def each_forwarding_call(def_node, slots, &)
+        return if slots.empty?
+
+        def_census(:forwards, def_node) { forwarding_calls(def_node, slots) }.each(&)
+      end
+
+      def forwarding_calls(def_node, slots)
+        calls = []
+        each_node_in_method_scope(def_node.body, 0) do |descendant, depth|
+          next unless self_dispatch_call?(descendant)
+
+          forwarded = forwarded_parameters(descendant, slots, depth)
+          calls << [descendant, forwarded] unless forwarded.empty?
+        end
+        calls.empty? ? NO_FORWARDS : calls
+      end
+
+      NO_FORWARDS = [].freeze
+      private_constant :NO_FORWARDS
+
+      # `[[parameter_name, callee_slot], ...]` for the arguments of `call_node` that read one of `slots`' parameters at
+      # `depth`, the block nesting the call sits at: a read of the method's own parameter there has that depth. An
+      # argument after a splat or `...` has an index that says nothing about the parameter it binds, so it binds
+      # {ANY_SLOT}, any positional parameter of the callee; one before the first splat keeps its index.
+      def forwarded_parameters(call_node, slots, depth)
+        args = call_node.arguments
+        return NO_FORWARDS unless args.is_a?(Prism::ArgumentsNode)
+
+        spread = false
+        forwarded = []
+        args.arguments.each_with_index do |argument, index|
+          if argument.is_a?(Prism::KeywordHashNode)
+            forwarded.concat(forwarded_keywords(argument, slots, depth))
+          elsif argument.is_a?(Prism::SplatNode) || argument.is_a?(Prism::ForwardingArgumentsNode)
+            spread = true
+          elsif (name = parameter_read_name(argument, slots, depth))
+            forwarded << [name, spread ? ANY_SLOT : index]
+          end
+        end
+        forwarded
+      end
+
+      # The `callee_slot` of an argument whose parameter the call does not show (one after a splat).
+      ANY_SLOT = :__any_positional__
+      private_constant :ANY_SLOT
+
+      # The names of the callee's parameters (`callee_slots`, {#content_parameter_slots}) an argument bound to `slot`
+      # may reach: the one at that slot, or every positional one for {ANY_SLOT}.
+      def bound_parameter_names(callee_slots, slot)
+        if slot == ANY_SLOT
+          callee_slots.filter_map { |name, at| name if at.is_a?(Integer) }
+        else
+          callee_slots.filter_map { |name, at| name if at == slot }
+        end
+      end
+
+      def forwarded_keywords(hash_node, slots, depth)
+        hash_node.elements.filter_map do |pair|
+          next unless pair.is_a?(Prism::AssocNode) && pair.key.is_a?(Prism::SymbolNode)
+
+          name = parameter_read_name(pair.value, slots, depth)
+          [name, pair.key.unescaped.to_sym] if name
+        end
+      end
+
+      # The parameter `node` reads when it is a read of one of `slots`' names at `depth` (a keyword shorthand
+      # `poke(acc:)` wraps the read in an `ImplicitNode`), else nil.
+      def parameter_read_name(node, slots, depth)
+        node = node.value if node.is_a?(Prism::ImplicitNode)
+        return unless node.is_a?(Prism::LocalVariableReadNode) && node.depth == depth
+
+        node.name if slots.key?(node.name)
       end
 
       # The user def a self-dispatch `node` resolves to in the enclosing class, or nil. Reuses the discovery index
@@ -4149,7 +4663,7 @@ module Rigor
         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.
+      # The set of `[name, slot]` 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.
@@ -4159,7 +4673,7 @@ module Rigor
       end
 
       def compute_escaped_content_parameters(def_node)
-        positions = positional_parameter_positions(def_node)
+        positions = content_parameter_slots(def_node)
         return {} if positions.empty?
 
         mutated = Set.new
@@ -4174,18 +4688,22 @@ module Rigor
         positions.slice(*mutated)
       end
 
-      # The `{ name => position }` positional parameters whose CONTENT the callee mutates directly in its method body —
-      # a top-level `param[k] = v` / `param << x`, outside a nested block. Memoised per def node. The block-nested case
-      # is `escaped_content_parameters`'s job; walking only outside nested blocks / defs / lambdas here means a matching
+      # The `{ name => slot }` parameters whose CONTENT the callee mutates directly in its method body — a top-level
+      # `param[k] = v` / `param << x`, outside a nested block. Memoised per def node. The block-nested case is
+      # `escaped_content_parameters`'s job; walking only outside nested blocks / defs / lambdas here means a matching
       # parameter-name read is genuinely at method scope (depth 0) rather than a block-local of the same name that
       # merely shadows the parameter — so we never floor a caller argument the callee did not actually mutate.
+      #
+      # A mutation inside a NON-escaping block (`n.times { |i| acc[i] = v }`) is not counted: the bare-collection floor
+      # it would apply turned haml's `AttributeCompiler#compile` (a `temple` array a helper fills in a `times` block,
+      # returned against a declared tuple) into a `def.return-type-mismatch` (af3efef33, and again under #2104).
       def direct_content_parameters(def_node)
         cache = (@direct_param_cache ||= {}.compare_by_identity)
         cache[def_node] ||= compute_direct_content_parameters(def_node)
       end
 
       def compute_direct_content_parameters(def_node)
-        positions = positional_parameter_positions(def_node)
+        positions = content_parameter_slots(def_node)
         return {} if positions.empty?
 
         mutated = Set.new
@@ -4210,6 +4728,43 @@ module Rigor
         end
       end
 
+      # Yields every node reachable from `node` with the number of blocks it sits in: a read of the method's own local
+      # there has that depth. A nested def or lambda is not entered: a def has no access to the method's locals, and a
+      # lambda body is not run by the call. Nor is the block of a {#self_rebinding_block_call?}: a self-call there
+      # either runs on another `self`, or runs later as a method body, so the walk leaves it out.
+      def each_node_in_method_scope(node, depth, &)
+        return if node.nil?
+
+        yield node, depth
+        rebinding = self_rebinding_block_call?(node)
+        node.rigor_each_child do |child|
+          next if child.is_a?(Prism::DefNode) || child.is_a?(Prism::LambdaNode)
+
+          if child.is_a?(Prism::BlockNode)
+            each_node_in_method_scope(child, depth + 1, &) unless rebinding
+          else
+            each_node_in_method_scope(child, depth, &)
+          end
+        end
+      end
+
+      # The calls whose block the hand-off walk leaves out. In an `instance_eval` / `class_exec` / … block, and in a
+      # `Class.new` / `Module.new` / `Struct.new` / `Data.define` block ({AnonymousMetaClass.block_form_receiver}),
+      # `self` is another object, so a self-call there is not a call on the method's receiver. A `define_method` or
+      # `define_singleton_method` block keeps an instance of the class as `self`, but it is a method body that runs
+      # later, if ever, so leaving it out is the conservative reading: a hand-off it holds is not one the call makes.
+      SELF_REBINDING_BLOCK_CALLS = Set[
+        :instance_eval, :instance_exec, :class_eval, :class_exec, :module_eval, :module_exec, :define_method,
+        :define_singleton_method
+      ].freeze
+      private_constant :SELF_REBINDING_BLOCK_CALLS
+
+      def self_rebinding_block_call?(node)
+        return false unless node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode)
+
+        SELF_REBINDING_BLOCK_CALLS.include?(node.name) || !AnonymousMetaClass.block_form_receiver(node).nil?
+      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
@@ -4230,18 +4785,20 @@ module Rigor
         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)
+      # `{ name => slot }` for the parameters a caller's argument binds by name or position: the required / optional
+      # positional ones (slot: their index) and, issue #2104, the keyword ones (slot: the keyword symbol). Rest, post
+      # and block parameters are skipped.
+      def content_parameter_slots(def_node)
         params = def_node.parameters
         return {} if params.nil?
 
         ordered = (params.requireds || []) + (params.optionals || [])
-        positions = {}
+        slots = {}
         ordered.each_with_index do |param, index|
-          positions[param.name] = index if param.respond_to?(:name)
+          slots[param.name] = index if param.respond_to?(:name)
         end
-        positions
+        (params.keywords || []).each { |param| slots[param.name] = param.name }
+        slots
       end
 
       # True when at least one argument of `node` is a bare local-variable read (positional or keyword value) bound in
@@ -4257,9 +4814,10 @@ module Rigor
             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)
+              next false unless pair.is_a?(Prism::AssocNode)
+
+              value = pair.value.is_a?(Prism::ImplicitNode) ? pair.value.value : pair.value
+              value.is_a?(Prism::LocalVariableReadNode) && scope.locals.key?(value.name)
             end
           else
             false
@@ -4417,6 +4975,11 @@ module Rigor
       # The fresh `next`, `break`-value and `break`-scope sinks are defensive: every consumer of those sinks filters by
       # jump-node identity, so no example tells them apart from the outer sinks today. So is the `rescue`: a raise here
       # keeps the arms the earlier passes collected rather than taking out the method.
+      #
+      # Issue #2127 — a block passed to a project method whose body may run it more than once
+      # ({ProjectYielder.may_run_block_repeatedly?}) gets the same pass. No write-back runs for such a call, so its
+      # continuation holds each rebound capture at `Dynamic[top]` ({#drop_captured_narrowing}), and the pass reads it
+      # so: `seen = 0; yielder { return :ret if (seen += 1) > 1 }` reaches the `return`.
       def collect_repeated_block_returns(call_node, post_scope)
         return if Thread.current[RETURN_SINK_KEY].nil?
 
@@ -4440,16 +5003,19 @@ module Rigor
       end
 
       # Whether `block` is an ordinary block (not a return barrier or a class-body block) whose body may `return` from
-      # the method and which `call_node` may run more than once: {#repeating_block_class}'s rule, or `Kernel#loop`,
-      # which that rule leaves out and which runs its block until it breaks or raises. The barrier, refinement and
+      # the method and which `call_node` may run more than once: {#repeating_block_class}'s rule, `Kernel#loop`, which
+      # that rule leaves out and which runs its block until it breaks or raises, or a project method whose body may
+      # run it more than once ({ProjectYielder.may_run_block_repeatedly?}, issue #2127). The barrier, refinement and
       # anonymous-class checks are defensive guards: no such call repeats under that rule today.
       def repeated_block_return_candidate?(call_node, block)
         return false unless block.is_a?(Prism::BlockNode)
         return false unless ReturnBarrier.exits_method?(block.body)
         return false if return_barrier_block?(call_node) || refined_class_context(call_node)
         return false if AnonymousMetaClass.name_for(call_node, scope.source_path)
+        return true if BlockCallTiming.kernel_loop?(call_node) || !repeating_block_class(call_node).nil?
 
-        BlockCallTiming.kernel_loop?(call_node) || !repeating_block_class(call_node).nil?
+        receiver_type = block_call_receiver_type(call_node)
+        !receiver_type.nil? && ProjectYielder.may_run_block_repeatedly?(call_node, receiver_type, scope)
       end
 
       # ADR-56 slice A. For a `:non_escaping` block, fold the continuation binding of every outer local the body can
@@ -5523,12 +6089,7 @@ module Rigor
       # receiver is the one the block-return pass asks about: the explicit receiver, or the implicit `self`
       # (`Object` at the top level).
       def repeating_block_class(call_node)
-        receiver_type =
-          if call_node.receiver
-            explicit_receiver_type(call_node)
-          else
-            operand_scope.self_type || operand_scope.environment.nominal_for_name("Object")
-          end
+        receiver_type = block_call_receiver_type(call_node)
         return nil if receiver_type.nil?
 
         method_name = call_node.name
@@ -5542,6 +6103,13 @@ module Rigor
         nil
       end
 
+      # The receiver a block-carrying call dispatches on: its explicit receiver's type, else `self`, else `Object`.
+      def block_call_receiver_type(call_node)
+        return explicit_receiver_type(call_node) if call_node.receiver
+
+        operand_scope.self_type || operand_scope.environment.nominal_for_name("Object")
+      end
+
       # The binding each outer local or ivar the body rebinds ({CapturedLocals.writes}) from a sentinel seed — `nil` or
       # `false`, alone or as a union of the two — enters a repeating call's body with when the write-back will not run
       # its passes for it ({#write_back_block_captures} reaches only an explicit receiver classified
@@ -6129,7 +6697,7 @@ module Rigor
       # inferred.
       def eval_return(node)
         sink = Thread.current[RETURN_SINK_KEY]
-        sink << jump_value_type(node) if sink
+        sink&.record(node, jump_value_type(node))
         [Type::Combinator.bot, scope]
       end