rigortype 0.3.8 → 0.4.0

data/lib/rigor/inference/block_call_timing.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "../reflection"
+
+module Rigor
+  module Inference
+    # Issue #1095 — the first slice of the block call-timing summary that
+    # `docs/type-specification/control-flow-analysis.md` § "Block call timing" asks for: which callees invoke
+    # their block **immediately, exactly once, and before they return**.
+    #
+    # The fact matters for the value of the call. Since #853 a block-level `break` joins the yielding call's
+    # type, unioned with what the callee returns when the block completes normally. For an arbitrary callee
+    # that normal return must stay — `each` may never yield on an empty receiver. For a callee that always
+    # yields exactly once before returning, a block whose normal completion is unreachable means the normal
+    # return is unreachable too, so the call's value is its `break` arms alone (`bot` when there are none):
+    # `[1, 2].tap { break "s" }` is `"s"`, `[1, 2].tap { raise "x" }` is `bot`.
+    #
+    # ## Catalogue
+    #
+    # Like {ClosureEscapeAnalyzer}'s `OBJECT_NON_ESCAPING` — a weaker "block is not retained" fact that `each`
+    # and `map` also satisfy — this ships as a hardcoded table keyed by `(owner, method)`, where the owner is
+    # the module whose declaration Ruby dispatches to. The sub-phase that replaces the escape catalogue with an
+    # `RBS::Extended` call-timing effect (`rbs-extended.md` reserves the bundle slot) is expected to absorb
+    # this table in the same move, which is why it is keyed by the declaring owner, the way a signature-borne
+    # effect would be, rather than by the receiver's class.
+    #
+    # The owner is `Kernel` for all three, in CRuby (`Object.instance_method(:tap).owner`) and in the bundled
+    # core RBS alike. `Object` is deliberately NOT accepted: every class inherits these methods through
+    # `Object`, so a declaration that resolves to `Object` itself is a project or gem override written on top
+    # of Kernel's, and that override is not known to yield exactly once.
+    #
+    # The summary is a pure query. It never raises on unrecognised input and answers `false` — keep the
+    # `break | normal-return` union — whenever it cannot prove the call reaches the catalogued declaration.
+    module BlockCallTiming
+      EXACTLY_ONCE_IMMEDIATE = {
+        "Kernel" => %i[tap then yield_self].freeze
+      }.freeze
+
+      CANDIDATE_NAMES = EXACTLY_ONCE_IMMEDIATE.values.flatten.uniq.freeze
+      private_constant :CANDIDATE_NAMES
+
+      # The roots a project monkey-patch would redefine the method on for every receiver at once.
+      PATCHABLE_ROOTS = %w[Object Kernel BasicObject].freeze
+      private_constant :PATCHABLE_ROOTS
+
+      # A class object's own metaclass ancestry adds these ahead of `Object`, so a patch on either one
+      # redefines the method for every class-object receiver.
+      SINGLETON_ROOTS = %w[Class Module].freeze
+      private_constant :SINGLETON_ROOTS
+
+      # Receiver-less (or `self.` / `Kernel.`) calls that never return normally: they raise, throw, or end
+      # the process. Anything else — including `loop`, whose RBS return is `bot` although a `StopIteration`
+      # ends it normally ({.loop_may_complete?}) — proves nothing.
+      NON_RETURNING_CALLS = %i[raise fail throw exit exit! abort].freeze
+      private_constant :NON_RETURNING_CALLS
+
+      # Issue #1107 — the nodes a `loop` body may consist of while still provably unable to raise
+      # `StopIteration`: none of them dispatches a method, so nothing in the body can run code that raises.
+      # Everything else — every call (operators and `[]` included), `yield`, `super`, interpolation, a splat,
+      # a constant read (`const_missing`), a `rescue` — may, and declines.
+      STOP_ITERATION_FREE_NODES = [
+        Prism::StatementsNode, Prism::ParenthesesNode, Prism::ArgumentsNode,
+        Prism::BreakNode, Prism::NextNode, Prism::RedoNode, Prism::ReturnNode,
+        Prism::IntegerNode, Prism::FloatNode, Prism::RationalNode, Prism::ImaginaryNode,
+        Prism::StringNode, Prism::SymbolNode, Prism::NilNode, Prism::TrueNode, Prism::FalseNode, Prism::SelfNode,
+        Prism::LocalVariableReadNode, Prism::LocalVariableWriteNode,
+        Prism::InstanceVariableReadNode, Prism::InstanceVariableWriteNode,
+        Prism::IfNode, Prism::UnlessNode, Prism::ElseNode, Prism::AndNode, Prism::OrNode, Prism::ArrayNode
+      ].freeze
+      private_constant :STOP_ITERATION_FREE_NODES
+
+      module_function
+
+      # Issue #1107 — whether a `loop` call can complete normally although its declared return is `bot`.
+      #
+      # `Kernel#loop` is `() { () -> void } -> bot` in core RBS, yet it rescues a `StopIteration` its block
+      # raises and returns that exception's `result` — the enumerator-draining idiom `loop { out << e.next }`
+      # returns `e`'s own `each` value. So the declared `bot` holds only for a body that provably cannot raise
+      # `StopIteration`: one built from {STOP_ITERATION_FREE_NODES} alone (`loop {}`, `loop { break 1 }`), in a
+      # block that declares no parameters. A `&blk` block-pass has no body to prove anything about and completes
+      # too.
+      #
+      # Gated on the spellings that reach the private `Kernel#loop` — receiver-less, `self.`, `Kernel.`,
+      # `::Kernel.` — so `obj.loop { ... }` is some other method, whose declared `bot` is that author's
+      # promise. A project redefinition of `loop` itself is not excluded: widening its `bot` costs precision,
+      # never a false positive.
+      def loop_may_complete?(call_node)
+        return false unless call_node.name == :loop && kernel_spelled_receiver?(call_node.receiver)
+
+        block = call_node.block
+        return false if block.nil?
+        return true unless block.is_a?(Prism::BlockNode)
+        # A parameter default (`|v = e.next|`) is evaluated on every iteration, since `loop` yields no
+        # arguments. Rather than walk the parameter list, any declared parameter widens.
+        return true if block.parameters
+        return false if block.body.nil?
+
+        may_raise_stop_iteration?(block.body)
+      end
+
+      def may_raise_stop_iteration?(node)
+        return true unless STOP_ITERATION_FREE_NODES.any? { |klass| node.is_a?(klass) }
+
+        node.compact_child_nodes.any? { |child| may_raise_stop_iteration?(child) }
+      end
+
+      # Cheap name-only pre-gate, so a call that cannot be catalogued pays nothing further.
+      def candidate_name?(method_name)
+        CANDIDATE_NAMES.include?(method_name)
+      end
+
+      def exactly_once_owner?(owner_name, method_name)
+        methods = EXACTLY_ONCE_IMMEDIATE[owner_name.to_s.delete_prefix("::")]
+        methods ? methods.include?(method_name) : false
+      end
+
+      # Whether a call of `method_name` on `receiver_type` reaches a catalogued exactly-once declaration.
+      #
+      # Gated on the RESOLVED owner, not the name: a class that defines its own `tap` (in source, in a
+      # project `sig/`, or through a project ancestor), a top-level `def tap` (a private `Object` method,
+      # ahead of `Kernel` in every MRO) and an `Object` / `Kernel` monkey-patch all decline. A union receiver
+      # qualifies only when every member does; `Dynamic` and the other carriers that name no class decline.
+      def exactly_once_call?(receiver_type:, method_name:, scope:)
+        return false unless candidate_name?(method_name)
+        return false if scope.nil? || project_redefines_root?(method_name, scope)
+
+        targets = receiver_targets(receiver_type)
+        return false if targets.nil? || targets.empty?
+
+        targets.all? { |class_name, kind| resolves_to_catalogue?(class_name, kind, method_name, scope) }
+      rescue StandardError
+        false
+      end
+
+      # Syntactic proof that a block body cannot complete normally: every path through it ends in a
+      # block-level `break` (which targets the yielding call), `return`, `redo`, or a non-returning Kernel call
+      # ({NON_RETURNING_CALLS}) — or in an expression that must evaluate one of those first. This is ANDed
+      # with the block-return pass's `bot`, never used alone, because a `bot` can also flow out of a callee's
+      # declared return that is not a promise the call never completes (`Kernel#loop` is `-> bot`, yet a
+      # `StopIteration` from `e.next` ends it normally). A shape the walk does not recognise declines.
+      #
+      # Only unconditionally evaluated children are descended: a nested block, lambda, `def` or loop is never
+      # entered (its body may not run, and it retargets `break`), a call's block is not a child the call
+      # promises to run, and `&&` / `||` count only their left operand. A `begin` with `rescue` qualifies only
+      # when its body and every rescue clause must exit; an `ensure` that must exit qualifies on its own.
+      def never_completes_normally?(node, scope)
+        case node
+        when Prism::StatementsNode then node.body.any? { |statement| never_completes_normally?(statement, scope) }
+        when Prism::BreakNode, Prism::ReturnNode, Prism::RedoNode, Prism::RetryNode then true
+        when Prism::ParenthesesNode then never_completes_normally?(node.body, scope)
+        when Prism::CallNode then call_never_returns?(node, scope)
+        when Prism::IfNode, Prism::UnlessNode then conditional_never_completes?(node, scope)
+        when Prism::AndNode, Prism::OrNode then never_completes_normally?(node.left, scope)
+        when Prism::BeginNode then begin_never_completes?(node, scope)
+        when Prism::ArrayNode then node.elements.any? { |element| never_completes_normally?(element, scope) }
+        when Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode
+          never_completes_normally?(node.value, scope)
+        else false
+        end
+      end
+
+      # Deliberately coarse: ANY project definition of the name — top-level, on any class or module, either
+      # side, or a `pre_eval:` patch — declines. Resolving the call-site `self`'s ancestry precisely buys
+      # nothing for names this rare, and the block-return pass is no independent check here: it types a
+      # self-call to an overridden `raise` as Kernel's `bot` too, so a missed override is a wrong `bot`.
+      # {LastLine.reads_line?} declines on it the same way for `gets` and `readline`.
+      def project_defines_anywhere?(method_name, scope)
+        return true if scope.top_level_def_for(method_name)
+        # `discovered_methods` withholds a plain cross-file `def` (the ADR-17 monkey-patch contract); the
+        # def-node tables still carry it, on both sides.
+        return true if [scope.discovered_methods, scope.discovered_def_nodes, scope.discovered_singleton_def_nodes]
+                       .any? { |tables| tables.any? { |_class_name, table| table.key?(method_name) } }
+
+        patched = scope.environment&.project_patched_methods
+        !patched.nil? && patched.by_key.any? { |(_class_name, name, _kind), _entry| name == method_name }
+      end
+
+      class << self
+        private
+
+        def call_never_returns?(node, scope)
+          return true if never_completes_normally?(node.receiver, scope)
+          return true if node.arguments&.arguments&.any? { |argument| never_completes_normally?(argument, scope) }
+          return false unless NON_RETURNING_CALLS.include?(node.name)
+
+          kernel_spelled_receiver?(node.receiver) && !project_defines_anywhere?(node.name, scope)
+        end
+
+        # Implicit self, `self.`, or the `Kernel` module itself (`Kernel.` or the root-anchored `::Kernel.`) —
+        # the spellings that reach Kernel's function.
+        def kernel_spelled_receiver?(receiver)
+          case receiver
+          when nil, Prism::SelfNode then true
+          when Prism::ConstantReadNode then receiver.name == :Kernel
+          when Prism::ConstantPathNode then receiver.parent.nil? && receiver.name == :Kernel
+          else false
+          end
+        end
+
+        def conditional_never_completes?(node, scope)
+          return true if never_completes_normally?(node.predicate, scope)
+
+          alternative = node.is_a?(Prism::IfNode) ? node.subsequent : node.else_clause
+          return false if node.statements.nil? || alternative.nil?
+
+          never_completes_normally?(node.statements, scope) && branch_never_completes?(alternative, scope)
+        end
+
+        def branch_never_completes?(branch, scope)
+          case branch
+          when Prism::ElseNode then never_completes_normally?(branch.statements, scope)
+          else never_completes_normally?(branch, scope)
+          end
+        end
+
+        def begin_never_completes?(node, scope)
+          return true if node.ensure_clause && never_completes_normally?(node.ensure_clause.statements, scope)
+          return false unless never_completes_normally?(node.statements, scope)
+
+          rescue_clause = node.rescue_clause
+          while rescue_clause
+            return false unless never_completes_normally?(rescue_clause.statements, scope)
+
+            rescue_clause = rescue_clause.subsequent
+          end
+          true
+        end
+
+        def project_redefines_root?(method_name, scope)
+          return true if scope.top_level_def_for(method_name)
+
+          patched = scope.environment&.project_patched_methods
+          PATCHABLE_ROOTS.any? do |root|
+            scope.discovered_method?(root, method_name, :instance) ||
+              patched&.lookup(class_name: root, method_name: method_name, kind: :instance)
+          end
+        end
+
+        # `[class_name, :instance | :singleton]` pairs the receiver can dispatch through, or nil when some
+        # part of it names no class. `Tuple` / `HashShape` project to `Array` / `Hash`, `Constant[v]` through
+        # the value's class, the same projection {ClosureEscapeAnalyzer} uses.
+        def receiver_targets(receiver_type)
+          case receiver_type
+          when Type::Union
+            members = receiver_type.members.map { |member| receiver_targets(member) }
+            members.any?(&:nil?) ? nil : members.flatten(1)
+          when Type::Nominal then [[receiver_type.class_name, :instance]]
+          when Type::Singleton then [[receiver_type.class_name, :singleton]]
+          when Type::Tuple then [["Array", :instance]]
+          when Type::HashShape then [["Hash", :instance]]
+          when Type::Constant then [[receiver_type.value.class.name, :instance]]
+          end
+        end
+
+        def resolves_to_catalogue?(class_name, kind, method_name, scope)
+          return false if class_name.nil?
+          return false if scope.discovered_method_through_ancestors?(class_name, method_name, kind)
+
+          if kind == :singleton
+            definition = Rigor::Reflection.singleton_method_definition(class_name, method_name, scope: scope)
+            return false if singleton_ancestor_patched?(class_name, method_name, scope)
+
+            return declared_on_catalogue?(definition, method_name)
+          end
+
+          definition = Rigor::Reflection.instance_method_definition(class_name, method_name, scope: scope)
+          if definition
+            return false if rbs_ancestor_patched?(class_name, method_name, scope)
+
+            return declared_on_catalogue?(definition, method_name)
+          end
+          return false if Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+
+          project_class_resolves_to_catalogue?(class_name, method_name, scope)
+        end
+
+        def declared_on_catalogue?(definition, method_name)
+          return false if definition.nil? || !definition.respond_to?(:defined_in)
+
+          exactly_once_owner?(definition.defined_in, method_name)
+        end
+
+        # A project class the RBS environment does not know: its project ancestry was already cleared by the
+        # discovery walk, so the answer rests on the ancestors it reaches OUTSIDE the project. Each is asked
+        # on its own terms; an ancestor nobody can resolve is uncertainty and declines. No external ancestor
+        # at all is the implicit `< Object`, which reaches `Kernel`.
+        def project_class_resolves_to_catalogue?(class_name, method_name, scope)
+          return false unless scope.known_user_class?(class_name)
+
+          scope.external_ancestor_name_candidates(class_name).all? do |candidates|
+            external_ancestor_resolves_to_catalogue?(candidates, method_name, scope)
+          end
+        end
+
+        def external_ancestor_resolves_to_catalogue?(candidates, method_name, scope)
+          known = candidates.find { |candidate| Rigor::Reflection.rbs_class_known?(candidate, scope: scope) }
+          return false if known.nil?
+
+          definition = Rigor::Reflection.instance_method_definition(known, method_name, scope: scope)
+          # A mixin whose RBS does not mention the method contributes nothing; a CLASS that lacks it is a
+          # `BasicObject` lineage, where the call does not reach `Kernel` at all.
+          return false if rbs_ancestor_patched?(known, method_name, scope)
+          return scope.environment.rbs_module?(known) if definition.nil?
+
+          declared_on_catalogue?(definition, method_name)
+        end
+
+        # The RBS declaration says where the method was DECLARED; a project reopening of a core ancestor
+        # (`module Enumerable; def tap = :x; end`) redefines it without touching RBS, and discovery records
+        # it under the ancestor's own name. So every RBS ancestor — mixins included — is asked.
+        def rbs_ancestor_patched?(class_name, method_name, scope)
+          names_patched?(rbs_ancestor_names(class_name, scope), method_name, :instance, scope)
+        end
+
+        # A class object dispatches through its own and its superclasses' singleton methods, then through
+        # `Class`, `Module`, `Object`, `Kernel` as instance methods.
+        def singleton_ancestor_patched?(class_name, method_name, scope)
+          names_patched?(rbs_ancestor_names(class_name, scope), method_name, :singleton, scope) ||
+            names_patched?(SINGLETON_ROOTS, method_name, :instance, scope)
+        end
+
+        def names_patched?(names, method_name, kind, scope)
+          patched = scope.environment&.project_patched_methods
+          names.any? do |name|
+            scope.discovered_method?(name, method_name, kind) ||
+              patched&.lookup(class_name: name, method_name: method_name, kind: kind)
+          end
+        end
+
+        def rbs_ancestor_names(class_name, scope)
+          loader = scope.environment&.rbs_loader
+          loader ? loader.ancestor_names_for(class_name.to_s) : []
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/block_parameter_binder.rb

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../type"
+require_relative "block_auto_splat"
 require_relative "multi_target_binder"
 
 module Rigor
@@ -22,31 +23,56 @@ module Rigor
     # MultiTargetNode parameters (`|(a, b), c|`) are bound by delegating each destructuring slot to
     # {Rigor::Inference::MultiTargetBinder}, so a Tuple-shaped expected element type projects element-wise
     # into the inner locals (Slice 6 phase C sub-phase 2). Numbered parameters (`_1`, `_2`, ...) are bound
-    # from `Prism::NumberedParametersNode` using the same per-position `expected_param_types:` array, so
-    # `[1, 2, 3].each { _1 + _2 }` sees `_1`/`_2` typed identically to their explicit `|x, y|` counterparts.
+    # from `Prism::NumberedParametersNode` as the explicit list of that many required positionals, the
+    # highest `_N` the body references being the arity (CRuby's own reading: `proc { _2 }.parameters` is
+    # `[[:opt, :_1], [:opt, :_2]]`, and `lambda { _2 }.arity` is 2). So `h.each { _1; _2 }` auto-splats like
+    # `|k, v|`, while a body that uses only `_1` reads as `|a|` and does not (issue #1108).
     #
     # The `it` implicit parameter (Ruby 3.4+) is bound from `Prism::ItParametersNode`. It is the
     # single-argument cousin of `_1`: the binder produces `{ it: expected_param_types[0] }` so the body's
-    # `Prism::ItLocalVariableReadNode` lookup sees the same type as the explicit `|x|` form would.
+    # `Prism::ItLocalVariableReadNode` lookup sees the same type as the explicit `|x|` form would, and it
+    # never auto-splats.
+    #
+    # A block whose parameter list CRuby splats spreads the one yielded value across its positionals;
+    # {BlockAutoSplat} owns that rule and its carrier arms, and this binder only applies the table it
+    # answers. Every name the spread binds from an `Array[T]` slot — and every name a nested `|(g, h)|`
+    # destructure binds from one — is reported as optimistic, and {#bind_onto} records those through
+    # `Scope#with_optimistic_local` exactly as the statement-level `a, b = ints` does (issue #1093; the
+    # shared rule lives in {MultiTargetBinder}). A nested `|(g, h)|` destructures the one value the
+    # signature already placed, so it wraps like the statement form.
     #
     # Block-local declarations after `;` (e.g., `|x; y, z|`) are still skipped — they are explicitly
     # block-local, so the outer scope MUST NOT observe them and the binder leaves them unbound.
     #
     # See docs/internal-spec/inference-engine.md for the binding contract.
     class BlockParameterBinder
-      # @param expected_param_types [Array<Rigor::Type>] positional block parameter types in order. Indices
+      # @param expected_param_types — positional block parameter types in order. Indices
       #   the binder cannot fill from this array (because the array is shorter than the parameter list, or
       #   because the slot is a kind we do not pull from the array) default to `Dynamic[Top]`.
       def initialize(expected_param_types: [])
-        @expected_param_types = expected_param_types
+        @declared_param_types = expected_param_types
+        reset_per_bind_state
+      end
+
+      # The names the last {#bind} bound optimistically nil-free (see the class comment).
+      attr_reader :optimistic
+
+      # Binds the block's parameters into `scope`: {#bind}'s types through `Scope#with_local`, then the
+      # optimistic mark for every name in {#optimistic}.
+      def bind_onto(block_node, scope)
+        types = bind(block_node, scope: scope)
+        MultiTargetBinder::Result.new(types: types, optimistic: @optimistic.dup.freeze).apply_to(scope)
       end
 
-      # @param block_node [Prism::BlockNode]
-      # @return [Hash{Symbol => Rigor::Type}] ordered map from parameter name to bound type. Anonymous
+      # @return ordered map from parameter name to bound type. Anonymous
       #   parameters are skipped; MultiTargetNode destructuring slots delegate to {MultiTargetBinder} and
       #   contribute every named local in declaration order. Numbered-parameter forms (`_1`, `_2`, ...) bind
       #   `:_1`, `:_2`, ... up to the maximum the block body refers to.
-      def bind(block_node)
+      # @param scope — the scope the block is entered from, which answers a nested destructure's `to_ary`
+      #   question ({MultiTargetBinder.bind_marked}).
+      def bind(block_node, scope: nil)
+        reset_per_bind_state
+        @scope = scope
         params_root = block_node.parameters
         return {} if params_root.nil?
 
@@ -64,14 +90,29 @@ module Rigor
 
       private
 
+      # {#apply_auto_splat} rewrites the positional table for the block it is binding, so every {#bind} starts
+      # from the declared types again; a binder reused across blocks must not see the previous block's splat.
+      def reset_per_bind_state
+        @expected_param_types = @declared_param_types
+        @splat_rest_type = nil
+        @optimistic_positions = []
+        @optimistic = []
+        @scope = nil
+      end
+
       # `|_1, _2|` numbered-parameter form. Prism exposes the implicit count through
       # `NumberedParametersNode#maximum` (the highest `_N` referenced in the body); we materialise bindings
-      # for `:_1` through `:_maximum` so the block body's `LocalVariableReadNode` lookups see the same types
-      # as the equivalent explicit `|x, y|` form would.
+      # for `:_1` through `:_maximum`, auto-splatting exactly as the explicit list of that many required
+      # positionals would, so the body's `LocalVariableReadNode` lookups see the same types and marks.
       def bind_numbered_parameters(numbered_node)
+        arity = numbered_node.maximum
+        apply_auto_splat(BlockAutoSplat::ParameterShape.of_arity(arity))
+
         bindings = {}
-        numbered_node.maximum.times do |i|
-          bindings[:"_#{i + 1}"] = positional_type_at(i)
+        arity.times do |i|
+          name = :"_#{i + 1}"
+          bindings[name] = positional_type_at(i)
+          @optimistic << name if @optimistic_positions.include?(i)
         end
         bindings
       end
@@ -86,7 +127,7 @@ module Rigor
         params_node = params_root.parameters
         return {} if params_node.nil?
 
-        apply_auto_splat(params_node)
+        apply_auto_splat(BlockAutoSplat::ParameterShape.of(params_node))
 
         bindings = {}
         bind_positionals(params_node, bindings, 0)
@@ -97,8 +138,8 @@ module Rigor
         bindings
       end
 
-      # Ruby blocks (NOT lambdas) auto-splat a single yielded Tuple-shaped value when the block declares more
-      # than one required positional parameter:
+      # Ruby blocks (NOT lambdas) auto-splat a single yielded array-ish value when the parameter list is
+      # one CRuby splats:
       #
       #   { a: 1 }.each { |k, v| ... }
       #
@@ -107,21 +148,21 @@ module Rigor
       # the binder would assign `k = Tuple[K, V]` and `v = Dynamic[Top]`, and any call on
       # `k.<method-not-on-Tuple>` would false-fire.
       #
-      # The rule fires only when (a) the receiver yields exactly one value (`expected_param_types.size ==
-      # 1`), (b) the block declares more than one positional slot, and (c) that single expected element is a
-      # Tuple. Multi-arg yields (e.g. `each_with_index`'s `(element, index)` pair) are NOT auto-splatted —
-      # matching Ruby semantics where a multi-arg yield to a `|a, b, c|` block fills the extra slot with nil
-      # rather than splatting any element.
-      def apply_auto_splat(params_node)
+      # The rule fires only when the receiver yields exactly one value (`expected_param_types.size == 1`)
+      # and {BlockAutoSplat} answers a table for that value and `shape`. A multi-arg yield (e.g.
+      # `each_with_index`'s `(element, index)` pair) is NOT auto-splatted — matching Ruby semantics where a
+      # multi-arg yield to a `|a, b, c|` block fills the extra slot with nil rather than splatting any
+      # element.
+      def apply_auto_splat(shape)
         return unless @expected_param_types.size == 1
+        return unless shape.splats?
 
-        pos_count = params_node.requireds.size + params_node.optionals.size + params_node.posts.size
-        return unless pos_count > 1
-
-        first = @expected_param_types[0]
-        return unless first.is_a?(Type::Tuple)
+        table = BlockAutoSplat.for(shape, @expected_param_types[0])
+        return if table.nil?
 
-        @expected_param_types = first.elements
+        @expected_param_types = table.types
+        @optimistic_positions = table.optimistic_positions
+        @splat_rest_type = table.rest_type
       end
 
       def bind_positionals(params_node, bindings, cursor)
@@ -161,7 +202,8 @@ module Rigor
         rest = params_node.rest
         return unless rest.respond_to?(:name) && rest&.name
 
-        bindings[rest.name] = Type::Combinator.nominal_of("Array", type_args: [Type::Combinator.untyped])
+        bindings[rest.name] =
+          @splat_rest_type || Type::Combinator.nominal_of("Array", type_args: [Type::Combinator.untyped])
       end
 
       def bind_keywords(params_node, bindings)
@@ -200,9 +242,12 @@ module Rigor
         case param
         when Prism::RequiredParameterNode
           bindings[param.name] = positional_type_at(cursor)
+          @optimistic << param.name if @optimistic_positions.include?(cursor)
         when Prism::MultiTargetNode
-          nested = MultiTargetBinder.bind(param, positional_type_at(cursor))
-          bindings.merge!(nested)
+          nested = MultiTargetBinder.bind_marked(param, positional_type_at(cursor),
+                                                 optimistic: @optimistic_positions.include?(cursor), scope: @scope)
+          bindings.merge!(nested.types)
+          @optimistic.concat(nested.optimistic)
         end
       end
 

data/lib/rigor/inference/block_repetition.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "block_call_timing"
+require_relative "closure_escape_analyzer"
+
+module Rigor
+  module Inference
+    # Whether a block-accepting call may run its block more than once, so a later run reads a captured binding an
+    # earlier run moved. Two passes ask it and share this one rule: the block-return pass
+    # (`ExpressionTyper#block_may_repeat?`), which lays the #587 (b) captured binding under such a block, and the
+    # statement pass (`StatementEvaluator#repeating_block_entry`, issue #1412), which lays the ADR-56 WD2.13
+    # content-mutation widening on its entry.
+    #
+    # The core iteration methods {ClosureEscapeAnalyzer} catalogues as non-escaping prove it — for a project class
+    # too, through its ancestry (`include Enumerable`); `tap` / `then` / `yield_self` are catalogued there too but
+    # run their block exactly once ({BlockCallTiming}).
+    #
+    # Issue #1234 — a receiver the analyzer cannot classify at all (`Dynamic`, a union, a project class whose
+    # ancestry it cannot follow) repeats when the method NAME is a catalogued iterator the project does not define
+    # on it ({ClosureEscapeAnalyzer.repeats_by_name?}): `items.all? { seen += 1; seen == 1 }` on an untyped `items`
+    # kept the first run's `seen == 1`, the predicate folded to `true`, and the condition on the result was
+    # reported as constant. This is a reading of `:unknown` for these two passes alone; escape analysis still
+    # treats it as unproven. Any other name, and a receiver classified `:escaping`, answers false, which keeps the
+    # entry scope: it is exact for a block run once (`m.synchronize { out = buf; buf = nil; out }` is `buf`'s value,
+    # and a cross-iteration binding would add the `nil` a second run never reads).
+    #
+    # A receiver that provably holds at most one element runs the block at most once however it iterates, so it
+    # answers false too: `done = false; [:only].each { break if done; done = true }` is `[:only]`, and the
+    # cross-iteration `done` would have typed it `Array[Symbol]?`.
+    module BlockRepetition
+      module_function
+
+      # `classification` is the receiver's {ClosureEscapeAnalyzer.classify} answer when the caller already holds it.
+      def may_repeat?(method_name:, receiver_type:, scope:, classification: nil)
+        return false if BlockCallTiming.candidate_name?(method_name)
+        return false if at_most_one_run?(method_name, receiver_type)
+
+        classification ||= ClosureEscapeAnalyzer.classify(
+          receiver_type: receiver_type, method_name: method_name, scope: scope
+        )
+        case classification
+        when :non_escaping then true
+        when :unknown
+          ClosureEscapeAnalyzer.repeats_by_name?(receiver_type: receiver_type, method_name: method_name, scope: scope)
+        else false
+        end
+      end
+
+      def at_most_one_run?(method_name, receiver_type)
+        case receiver_type
+        when Type::Tuple then receiver_type.elements.size <= 1
+        when Type::HashShape then receiver_type.closed? && receiver_type.pairs.size <= 1
+        when Type::Constant then constant_at_most_one_run?(method_name, receiver_type.value)
+        else false
+        end
+      end
+
+      # `1.times` and a one-element integer range iterate once.
+      def constant_at_most_one_run?(method_name, value)
+        case value
+        when Integer then method_name == :times && value <= 1
+        when Range
+          value.begin.is_a?(Integer) && value.end.is_a?(Integer) &&
+            value.end - value.begin + (value.exclude_end? ? 0 : 1) <= 1
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/body_fixpoint.rb

@@ -19,19 +19,20 @@ module Rigor
     # The mechanism is parameterized over an `evaluate_body` callable so slice B can reuse it: given the
     # current per-name bindings it returns the per-name exit bindings produced by one body evaluation from
     # those bindings (names the body leaves unwritten in a given pass simply do not appear in the returned
-    # hash).
+    # hash). Slice C's content join reuses it too, with each "name" one evidence slot of a collection
+    # (`StatementEvaluator#join_content_to_fixpoint`) and a `bot` seed standing for "nothing stored yet".
     module BodyFixpoint
       # One body evaluation per iteration; ADR-55's shape (cap 3).
       CAP = 3
 
       module_function
 
-      # @param names [Array<Symbol>] the outer locals the body can rebind.
-      # @param seed_bindings [Hash{Symbol=>Type}] pre-state binding per name.
-      # @param widen [#call] value-pinned widener (Constant -> Nominal).
-      # @param evaluate_body [#call] `bindings -> exit_bindings` — evaluates the body once from `bindings`
+      # @param names — the outer locals the body can rebind.
+      # @param seed_bindings — pre-state binding per name.
+      # @param widen — value-pinned widener (Constant -> Nominal).
+      # @param evaluate_body — `bindings -> exit_bindings` — evaluates the body once from `bindings`
       #   (the per-name current assumption) and returns the per-name exit binding it produced.
-      # @return [Hash{Symbol=>Type}] the continuation binding per name.
+      # @return the continuation binding per name.
       def converge(names:, seed_bindings:, widen:, evaluate_body:)
         return {} if names.empty?
 

data/lib/rigor/inference/budget_trace.rb

@@ -49,7 +49,8 @@ module Rigor
       RECURSION_FIXPOINT_CAP = :recursion_fixpoint_cap
       # `BodyFixpoint#converge` (ADR-56 slice A — non-escaping block captured-local write-back) ran its
       # 3-evaluation cap without the written local's join converging and collapsed that local to
-      # `Dynamic[top]` (the escaping-block floor). Shared by slice B's loop-body fixpoint.
+      # `Dynamic[top]` (the escaping-block floor). Shared by slice B's loop-body fixpoint and by slice C's
+      # content-evidence fixpoint, where the collapsed name is one element / key / value slot of a collection join.
       BLOCK_WRITEBACK_CAP = :block_writeback_cap
 
       # ADR-57 return-memo profile counters (not cutoffs — see the module doc). All bumped by
@@ -65,8 +66,6 @@ module Rigor
       #   plain `(receiver, method)` signature was already on the recursion guard stack.
       # - {MEMO_REFUSE_UNROLL} — pre-ADR-84 blanket refusal (constant-arg unroll in flight). Kept in the table
       #   as the ADR-84 WD3 gate pin: structurally unreachable, must read ~0.
-      # - {MEMO_REFUSE_CONSULT_TAINTED} — a candidate frame computed a result but an ADR-55 fixpoint summary
-      #   was *consulted* during the compute, so the result is a transient Kleene iterate and was NOT stored.
       # - {MEMO_REFUSE_TRANSIENT} — ADR-84 WD3: a candidate frame's compute bracket saw a
       #   transient-machinery event (recursion-guard hit / unroll-fuel exhaustion / ADR-55 WD1 clamp /
       #   fixpoint-cap collapse — `ExpressionTyper#note_transient_fallback`) that referenced a stack frame
@@ -79,15 +78,13 @@ module Rigor
       MEMO_BODY_EVALS = :memo_body_evals
       MEMO_REFUSE_ON_STACK = :memo_refuse_on_stack
       MEMO_REFUSE_UNROLL = :memo_refuse_unroll
-      MEMO_REFUSE_CONSULT_TAINTED = :memo_refuse_consult_tainted
       MEMO_REFUSE_TRANSIENT = :memo_refuse_transient
 
       CATEGORIES = [
         RECURSION_GUARD, ANCESTOR_WALK_LIMIT, HKT_FUEL_EXHAUSTED, RECURSION_UNROLL_FUEL,
         RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP,
         MEMO_ENTRIES, MEMO_HITS, MEMO_MISSES, MEMO_BODY_EVALS,
-        MEMO_REFUSE_ON_STACK, MEMO_REFUSE_UNROLL, MEMO_REFUSE_CONSULT_TAINTED,
-        MEMO_REFUSE_TRANSIENT
+        MEMO_REFUSE_ON_STACK, MEMO_REFUSE_UNROLL, MEMO_REFUSE_TRANSIENT
       ].freeze
 
       # Distribution (histogram) categories — read-only observations of a value's size at a site, used to