rigortype 0.3.9 → 0.4.0

data/lib/rigor/inference/captured_locals.rb

@@ -4,6 +4,12 @@ require "prism"
 
 require_relative "../source/node_walker"
 require_relative "block_parameter_binder"
+require_relative "element_read_widening"
+require_relative "index_write_widening"
+require_relative "mutation_widening"
+require_relative "optimistic_origin"
+require_relative "receiver_alias"
+require_relative "unknown_store_widening"
 
 module Rigor
   module Inference
@@ -16,11 +22,21 @@ module Rigor
     # A write counts across every local-write form — plain `=` (`LocalVariableWriteNode`), the operator /
     # `||=` / `&&=` compound forms, and a multi-assign target (`x, y = …` → `LocalVariableTargetNode` under
     # a `MultiWriteNode`) — at ANY depth: a block is a closure, so a write inside a nested block binds the
-    # same outer variable. Block-introduced names (parameters, numbered parameters, `;`-locals) and names
-    # not bound in the outer scope are excluded; a write to either is not a captured rebind of an outer
-    # variable.
-    module CapturedLocals
-      LOCAL_WRITE_NODES = [
+    # same outer variable. Block-introduced names (parameters, numbered parameters, `;`-locals), names
+    # not bound in the outer scope, a write a nested block's own parameter or block-local shadows, and a
+    # write inside a nested `def` or class body ({.outer_local?}) are excluded; a write to any of them is
+    # not a captured rebind of an outer variable.
+    #
+    # All three also ask for the instance variables the body rebinds (`ivars: true`). The per-element fold asks
+    # for every other binding that outlives an iteration as well (`non_locals: true`): the class variables and
+    # globals the body rebinds, and the instance variable behind an attribute setter it calls on `self`. Names
+    # keep their sigil, so a map over every kind never collides, and {.bound_type} / {.bind} reach each name
+    # through its own kind of binding.
+    #
+    # {.content_mutations} is the sibling set on the same terms: the captured outer locals the body mutates
+    # IN PLACE rather than rebinds, which the rebind set cannot see and the per-element fold needs as well.
+    module CapturedLocals # rubocop:disable Metrics/ModuleLength
+      LOCAL_WRITE_NODES = Set[
         Prism::LocalVariableWriteNode,
         Prism::LocalVariableOperatorWriteNode,
         Prism::LocalVariableOrWriteNode,
@@ -28,24 +44,380 @@ module Rigor
         Prism::LocalVariableTargetNode
       ].freeze
 
+      # The write forms of the bindings other than locals that outlive an iteration: instance variables, class
+      # variables and globals.
+      NON_LOCAL_WRITE_NODES = Set[
+        Prism::InstanceVariableWriteNode,
+        Prism::InstanceVariableOperatorWriteNode,
+        Prism::InstanceVariableOrWriteNode,
+        Prism::InstanceVariableAndWriteNode,
+        Prism::InstanceVariableTargetNode,
+        Prism::ClassVariableWriteNode,
+        Prism::ClassVariableOperatorWriteNode,
+        Prism::ClassVariableOrWriteNode,
+        Prism::ClassVariableAndWriteNode,
+        Prism::ClassVariableTargetNode,
+        Prism::GlobalVariableWriteNode,
+        Prism::GlobalVariableOperatorWriteNode,
+        Prism::GlobalVariableOrWriteNode,
+        Prism::GlobalVariableAndWriteNode,
+        Prism::GlobalVariableTargetNode
+      ].freeze
+
+      # The call forms that invoke an attribute setter: `self.w = v`, the compound `self.w += v` / `||=` / `&&=`,
+      # and a multi-assign target `self.w, x = …`.
+      SETTER_CALL_NODES = Set[
+        Prism::CallNode, Prism::CallOperatorWriteNode, Prism::CallOrWriteNode, Prism::CallAndWriteNode,
+        Prism::CallTargetNode
+      ].freeze
+      private_constant :SETTER_CALL_NODES
+
+      # An attribute writer's name: an identifier followed by `=`. `==`, `!=`, `<=`, `>=`, `===` and `[]=` are
+      # not setters.
+      SETTER_NAME = /\A[A-Za-z_]\w*=\z/
+      private_constant :SETTER_NAME
+
+      # The binding the per-element fold lays under a block's parameters: each name's type across iterations, and
+      # the optimistic nil-freeness mark an iteration's own rebind gave it, which {.bind} adds to the one the
+      # call site already holds — as `Scope#join` unions the marks of the scopes it joins. `repeated` is the
+      # `RepeatedOrWrites::Marks` of the index `||=` sites whose slot an earlier run may have filled, marked on the
+      # same scope: those of the per-element fold's `position`, or every site when no position is given.
+      Bindings = Data.define(:types, :marks, :repeated) do
+        def names = types.keys
+
+        def lay(scope, position: nil)
+          bound = types.reduce(scope) do |acc, (name, type)|
+            CapturedLocals.bind(acc, name, type, optimistic: marks[name])
+          end
+          bound.with_repeated_or_writes(repeated.at(position))
+        end
+      end
+
+      # The empty answers, shared: every block-bearing call's return pass asks both questions, and nearly every
+      # body answers nothing to either.
+      NO_NAMES = [].freeze
+      NO_SITES = {}.freeze
+      private_constant :NO_NAMES, :NO_SITES
+
       module_function
 
       # @param base_scope — the call-site scope the block closes over.
+      # @param ivars — also collect the instance variables the body rebinds. An ivar is not captured — the
+      #   block shares the caller's `self` — but it outlives an iteration, and the call, exactly as a captured
+      #   local does. It counts on the same terms as a local (every write form, any depth, bound in
+      #   `base_scope`), except that one still on its class-wide binding does not: ADR-58's declaration seed is
+      #   the union of every write in the class, this body's included, so nothing the body stores can move it,
+      #   and rebinding it would only drop the declaration mark that keeps its nil from being diagnostic fuel.
+      #   A nested block that rebinds `self` (`o.instance_eval`) writes another object's ivar, and a nested
+      #   `def` runs only when called; both still count, because an `instance_eval` without a receiver, or a
+      #   call to that `def` inside the body, does write this one.
+      # @param non_locals — the per-element fold's superset of `ivars`: the class variables and globals the body
+      #   rebinds count too, on the same terms, and so does an attribute setter called on `self` (`self.w = v`)
+      #   as a rebind of the instance variable it is named after, `@w`: the `attr_writer` / `attr_accessor`
+      #   convention stores there, and no write node shows it. A hand-written setter storing elsewhere is not
+      #   seen.
       # @return the captured names the body writes, each once, in first-write order.
-      def writes(block_node, base_scope)
+      def writes(block_node, base_scope, ivars: false, non_locals: false)
+        body = block_node.body
+        return NO_NAMES if body.nil?
+
+        introduced = nil
+        names = nil
+        outliving = non_locals || ivars
+        Source::NodeWalker.each_with_ancestors(body) do |descendant, ancestors|
+          name =
+            if LOCAL_WRITE_NODES.include?(descendant.class)
+              captured_local_write(descendant, ancestors, base_scope) { introduced ||= introduced_locals(block_node) }
+            elsif outliving
+              rebindable_outliving_write(descendant, base_scope, non_locals)
+            end
+          (names ||= []) << name if name
+        end
+        names ? names.uniq : NO_NAMES
+      end
+
+      def rebindable_outliving_write(node, base_scope, non_locals)
+        name = outliving_write_name(node, non_locals)
+        name if name && rebindable_non_local?(base_scope, name)
+      end
+
+      # The outer local a local-write node rebinds, or nil when the call site does not bind it, the write resolves
+      # inside a nested block or `def` ({.outer_local?}), or the block introduces it (the block yields the
+      # introduced set, computed only when needed).
+      def captured_local_write(node, ancestors, base_scope)
+        name = node.name
+        return nil unless base_scope.locals.key?(name) && outer_local?(node, ancestors)
+
+        yield.include?(name) ? nil : name
+      end
+
+      # The non-local `node` rebinds under `non_locals:` — or, without it, the instance variable only.
+      def outliving_write_name(node, non_locals)
+        name = non_local_write_name(node)
+        non_locals || (name && ivar_name?(name) && NON_LOCAL_WRITE_NODES.include?(node.class)) ? name : nil
+      end
+
+      # The instance, class or global variable `node` rebinds, or nil when it rebinds none of them.
+      def non_local_write_name(node)
+        return node.name if NON_LOCAL_WRITE_NODES.include?(node.class)
+
+        setter_ivar_name(node)
+      end
+
+      # `@w` for an attribute setter called on `self` (`self.w = …` and its compound and target forms), else nil.
+      def setter_ivar_name(node)
+        return nil unless SETTER_CALL_NODES.include?(node.class) && node.receiver.is_a?(Prism::SelfNode)
+
+        setter = node.respond_to?(:write_name) ? node.write_name : node.name
+        return nil unless SETTER_NAME.match?(setter)
+
+        :"@#{setter.to_s.delete_suffix('=')}"
+      end
+
+      def rebindable_non_local?(scope, name)
+        variable_kind(name) == :ivar ? rebindable_ivar?(scope, name) : !bound_type(scope, name).nil?
+      end
+
+      def rebindable_ivar?(scope, name)
+        !scope.ivar(name).nil? && !scope.declaration_sourced?(:ivar, name)
+      end
+
+      # The binding `scope` holds for a name from {.writes}.
+      def bound_type(scope, name)
+        case variable_kind(name)
+        when :ivar then scope.ivar(name)
+        when :cvar then scope.cvar(name)
+        when :global then scope.global(name)
+        else scope.local(name)
+        end
+      end
+
+      # `scope` with a name from {.writes} bound to `type`, keeping the name's optimistic nil-freeness mark
+      # (issue #286). `Scope#with_local` / `#with_ivar` drop it as a fresh write should, but here `type`
+      # stands for the binding across iterations, and a value that was nil-free only optimistically still is:
+      # without the mark `x.nil?` folds to `false` where the runtime answers `true`. `optimistic` is a mark the
+      # binding carries besides the one `scope` already holds — one an iteration's own rebind made. Class
+      # variables and globals carry no mark. {OptimisticOrigin.carry_local_mark} owns the re-marking, and with
+      # it the miss answer the mark records (issue #1302).
+      def bind(scope, name, type, optimistic: nil)
+        case variable_kind(name)
+        when :ivar then OptimisticOrigin.carry_ivar_mark(scope, scope.with_ivar(name, type), name, optimistic)
+        when :cvar then scope.with_cvar(name, type)
+        when :global then scope.with_global(name, type)
+        else OptimisticOrigin.carry_local_mark(scope, scope.with_local(name, type), name, optimistic)
+        end
+      end
+
+      # The optimistic nil-freeness mark `scope` holds for a name from {.writes}, or nil.
+      def optimistic_mark(scope, name)
+        case variable_kind(name)
+        when :ivar then scope.optimistic_ivar(name)
+        when :local then scope.optimistic_local(name)
+        end
+      end
+
+      def ivar_name?(name) = variable_kind(name) == :ivar
+
+      # Ruby spells a global with a leading `$`, a class variable with `@@`, an instance variable with a single
+      # `@`, and a local with none of them.
+      def variable_kind(name)
+        if name.start_with?("$") then :global
+        elsif name.start_with?("@@") then :cvar
+        elsif name.start_with?("@") then :ivar
+        else :local
+        end
+      end
+
+      # The nodes that change a receiver's CONTENT without rebinding it: a call to a name the straight-line
+      # widening responds to ({MutationWidening::SHAPE_MUTATORS}), and the index writes that store through
+      # `[]=` without being a `[]=` call ({IndexWriteWidening::CONTENT_WRITE_NODE_CLASSES}, the one list the
+      # block-return threading gate and the captured-local write-back read too).
+      INDEX_STORE_NODES = IndexWriteWidening::CONTENT_WRITE_NODE_CLASSES
+      private_constant :INDEX_STORE_NODES
+
+      # The captured outer locals the body mutates in place, each mapped to its mutation sites (the nodes
+      # above) in source order. A site counts through every variable its receiver can evaluate to
+      # ({ReceiverAlias.candidates}), at any nesting depth as long as a local's read does not resolve inside a nested
+      # block ({.outer_local?}), and a local is excluded on exactly the terms {.writes} excludes it.
+      #
+      # Under `non_locals: true` the instance variables, class variables and globals the body mutates in place
+      # count too, on the terms {.writes} takes a rebound one ({.rebindable_non_local?}). Since the block-return
+      # threading gate threads an index write, `@cache[:first] ||= e; @cache[:first] == 2` would otherwise type
+      # every position from the empty entry hash, store THAT position's `e`, and fold `find` to `2` where Ruby,
+      # keeping the first iteration's `1`, answers `nil`; `$seen << x; n == 1` after `n = $seen.size` folded
+      # `find` to `nil` the same way. A class variable or global counts only as the receiver itself (parentheses
+      # aside), not through a branch that selects it.
+      #
+      # A local also counts through the two routes straight-line code widens it by without reading it as the
+      # receiver. A mutator on an element read rooted at it (`a[0] << e`, the local {ElementReadWidening}
+      # widens) is a site of that local. A self-call whose callee content-mutates the parameter a local is passed
+      # to (`add_to(a, e)`, the local `StatementEvaluator#content_mutated_arguments` reports) is a
+      # {UnknownStoreWidening::CalleeStore} site of it. Both were invisible here, so every position of the fold
+      # read the local at its entry contents: `a = [[1]]; [1, 2].map { |e| v = a[0].size; a[0] << e; v }`
+      # folded to `[1, 1]` where Ruby answers `[1, 2]`.
+      #
+      # @param base_scope — the call-site scope the block closes over.
+      # @param non_locals — also collect the instance variables, class variables and globals the body mutates
+      #   in place.
+      # @return `{ name => [site, ...] }`, empty for the overwhelmingly common body that mutates nothing
+      #   captured.
+      def content_mutations(block_node, base_scope, non_locals: false)
         body = block_node.body
-        return [] if body.nil?
+        return NO_SITES if body.nil?
+
+        introduced = nil
+        body_mutation_sites(body, base_scope, non_locals) { introduced ||= introduced_locals(block_node) }
+      end
+
+      # Issue #1412 — false when `node` certainly holds nothing {.writes} (with `ivars: true`) or
+      # {.content_mutations} could collect against `base_scope`: no write to a local it binds, no instance, class or
+      # global variable write, no mutator or index store, and no self-call passing a local. It over-approximates
+      # (a write a block parameter shadows still answers true) and allocates nothing, so a caller can skip both
+      # scans, and whatever it would compute only to use their answers, for the common body that touches no capture.
+      def may_touch_capture?(node, base_scope)
+        return true if capture_touch?(node, base_scope)
+
+        node.rigor_each_child { |child| return true if may_touch_capture?(child, base_scope) }
+        false
+      end
+
+      def capture_touch?(node, base_scope)
+        klass = node.class
+        return base_scope.locals.key?(node.name) if LOCAL_WRITE_NODES.include?(klass)
+        return true if NON_LOCAL_WRITE_NODES.include?(klass) || INDEX_STORE_NODES.include?(klass)
+        return false unless klass == Prism::CallNode
+
+        receiver = node.receiver
+        return true if receiver && MutationWidening::SHAPE_MUTATORS.include?(node.name)
+
+        callee_call?(node)
+      end
+
+      # Issue #1412 — {.content_mutations} for a `while` / `until` / `for` body: the locals bound in `base_scope`
+      # (the scope the loop body first enters from) that the body mutates in place. A loop body opens no scope and
+      # introduces no name, so every such local counts on the same depth terms a block's capture does — a read
+      # that resolves inside a nested block or lambda, or inside a nested `def` or class body, is not the loop's.
+      #
+      # @return `{ name => [site, ...] }`, empty for the common body that mutates nothing.
+      def loop_content_mutations(statements, base_scope)
+        return NO_SITES if statements.nil?
+
+        body_mutation_sites(statements, base_scope, false) { NO_INTRODUCED }
+      end
+
+      NO_INTRODUCED = Set.new.freeze
+      private_constant :NO_INTRODUCED
+
+      # The mutation sites under `body` whose reads name a variable {.captured_target?} accepts, keyed by name.
+      # The block yields the names the enclosing construct introduces, asked only when a local site is found.
+      def body_mutation_sites(body, base_scope, non_locals, &)
+        sites = nil
+        evaluator = nil
+        Source::NodeWalker.each_with_ancestors(body) do |descendant, ancestors|
+          # A callee is resolved in the call-site scope, as the straight-line callee floor resolves it.
+          site = mutation_site(descendant) { evaluator ||= StatementEvaluator.new(scope: base_scope) }
+          next if site.nil?
+
+          site_reads(site).each do |read|
+            next unless captured_target?(read, ancestors, base_scope, non_locals, &)
+
+            ((sites ||= {})[read.name] ||= []) << site
+          end
+        end
+        sites || NO_SITES
+      end
+
+      # The mutation site `node` is — the node itself, or a {UnknownStoreWidening::CalleeStore} for a self-call
+      # whose callee content-mutates a local it is passed — or nil. A self-call is resolved by the
+      # `StatementEvaluator` the block yields, which the caller builds only when one is needed. A mutator name
+      # called on `self` (`self.store(h, k)`, `self.push(a, x)`) names no variable as its receiver, so it is asked
+      # as a self-call, as the straight-line callee floor asks it.
+      def mutation_site(node)
+        receiver = mutated_receiver(node)
+        return node if receiver && !receiver.is_a?(Prism::SelfNode)
+        return nil unless callee_call?(node)
+
+        arguments = yield.content_mutated_arguments(node)
+        arguments.empty? ? nil : UnknownStoreWidening::CalleeStore.new(node, arguments)
+      end
+
+      # The variable reads a mutation site reaches: a callee store's arguments, the local an element read is
+      # rooted at, or else {ReceiverAlias.mutated_reads} of the receiver.
+      def site_reads(site)
+        return site.arguments if site.is_a?(UnknownStoreWidening::CalleeStore)
+
+        receiver = mutated_receiver(site)
+        path = ElementReadWidening.element_read_path(receiver)
+        path ? [path.first] : ReceiverAlias.mutated_reads(receiver)
+      end
+
+      # A call to a method on `self` (implicit or explicit) that passes a local as an argument — the only kind
+      # the callee floor can report a site for, so the only kind worth resolving.
+      def callee_call?(node)
+        return false unless node.is_a?(Prism::CallNode)
+        return false unless node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
+
+        arguments = node.arguments&.arguments
+        !arguments.nil? && arguments.any?(Prism::LocalVariableReadNode)
+      end
+
+      # True when `read` names a variable {.content_mutations} collects: a {.content_target?} which, when it is a
+      # local, does not resolve inside a nested block and is not one the block introduces (the block yields that set,
+      # computed only when needed). An `it` read is never one: it is the parameter of the innermost block around
+      # it, so the body's own `it` is introduced and a nested block's `it` is that block's.
+      def captured_target?(read, ancestors, base_scope, non_locals)
+        return false if read.is_a?(Prism::ItLocalVariableReadNode)
+        return false unless content_target?(read, base_scope, non_locals)
+        return true unless read.is_a?(Prism::LocalVariableReadNode)
+
+        outer_local?(read, ancestors) && !yield.include?(read.name)
+      end
+
+      # A local bound at the call site (the block's own names are excluded by the caller), or — under
+      # `non_locals:` — an instance variable, class variable or global {.rebindable_non_local?} accepts.
+      def content_target?(read, base_scope, non_locals)
+        return base_scope.locals.key?(read.name) if read.is_a?(Prism::LocalVariableReadNode)
+
+        non_locals && rebindable_non_local?(base_scope, read.name)
+      end
+
+      # False when a local read or write resolves inside a scope nested between the body and `node`. Prism resolves a
+      # name in a nested block's own scope first, so `[[9]].each { |a| a << x }` mutates, and `[[9]].each { |a| a =
+      # x }` rebinds, that block's parameter, not the outer local that happens to share its name: its `depth` stops
+      # short of the body's own scope. A `def`, `class`, `module` or `class << self` body opens a scope of its own
+      # that sees no outer local at all, so `def helper; z = 5; end` writes the method's `z` — but only its body,
+      # and a `def`'s parameters, are that scope: a `def (o = x).m` receiver, a `class Foo < (s = x)` superclass or
+      # a `class << (t = x)` target runs in the enclosing one and is left to the depth test. {.writes} and
+      # {.content_mutations} both ask it, so the two sets cannot disagree about which `a` a site names. A name
+      # resolving in the body's own scope is left to the block-introduced exclusion: Prism puts an outer local there
+      # only when the parse never saw it declared, which a synthetic call-site scope can still bind.
+      def outer_local?(node, ancestors)
+        nesting = 0
+        ancestors.each_with_index do |ancestor, index|
+          return false if hard_scope_entered?(ancestor, ancestors[index + 1] || node)
+
+          nesting += 1 if NESTED_SCOPE_NODES.include?(ancestor.class)
+        end
+        node.depth >= nesting
+      end
+
+      # True when `child`, the next node on the path, is inside the scope `ancestor` opens.
+      def hard_scope_entered?(ancestor, child)
+        case ancestor
+        when Prism::DefNode then child.equal?(ancestor.body) || child.equal?(ancestor.parameters)
+        when Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode then child.equal?(ancestor.body)
+        else false
+        end
+      end
 
-        introduced = introduced_locals(block_node)
-        outer_writes = []
-        Source::NodeWalker.each(body) do |descendant|
-          next unless LOCAL_WRITE_NODES.any? { |klass| descendant.is_a?(klass) }
-          next if introduced.include?(descendant.name)
-          next unless base_scope.locals.key?(descendant.name)
+      NESTED_SCOPE_NODES = Set[Prism::BlockNode, Prism::LambdaNode].freeze
+      private_constant :NESTED_SCOPE_NODES
 
-          outer_writes << descendant.name
+      def mutated_receiver(node)
+        case node
+        when Prism::CallNode then node.receiver if MutationWidening::SHAPE_MUTATORS.include?(node.name)
+        when *INDEX_STORE_NODES then node.receiver
         end
-        outer_writes.uniq
       end
 
       # Names the block itself introduces: parameters (numbered parameters included, via

data/lib/rigor/inference/closure_escape_analyzer.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "../type"
+require_relative "../reflection"
+require_relative "external_ancestor_resolution"
+require_relative "project_method_ownership"
 
 module Rigor
   module Inference
@@ -30,14 +33,19 @@ module Rigor
     # therefore covers ONLY the core-and-stdlib surface where immediate invocation is part of the documented
     # contract:
     #
-    # - `Array`, `Hash`, `Range`, `Integer`, `Enumerator::Lazy` iteration methods (`each`, `map`, `select`,
-    #   `reject`, `flat_map`, `find`/`detect`, `any?`, `all?`, `none?`, `one?`, `count`, `inject`/`reduce`,
-    #   `each_with_index`, `each_with_object`, `min_by`, `max_by`, `sort_by`, `partition`, `group_by`,
-    #   `tally`, `sum`, `take_while`, `drop_while`, `chunk_while`, `slice_when`, `zip`, `collect`,
+    # - `Array`, `Hash`, `Range`, `Set`, `Enumerator`, `Enumerator::Lazy` iteration methods (`each`, `map`,
+    #   `select`, `reject`, `flat_map`, `find`/`detect`, `any?`, `all?`, `none?`, `one?`, `count`,
+    #   `inject`/`reduce`, `each_with_index`, `each_with_object`, `min_by`, `max_by`, `sort_by`, `partition`,
+    #   `group_by`, `tally`, `sum`, `take_while`, `drop_while`, `chunk_while`, `slice_when`, `zip`, `collect`,
     #   `collect_concat`, `filter`, `filter_map`).
     # - `Hash`-only iteration: `each_pair`, `each_key`, `each_value`, `transform_keys`, `transform_values`.
     # - `Integer#times`, `Integer#upto`, `Integer#downto`, `Range#each`, `Range#step`.
-    # - `Object#tap`, `Object#then`, `Object#yield_self`.
+    # - `IO` / `File` / `StringIO` line iteration (`each`, `each_line`, `each_byte`, `each_char`,
+    #   `each_codepoint`, the singleton `foreach`) and the same Enumerable methods minus
+    #   {DEFERRED_ENUMERATOR_METHODS}.
+    # - `Object#tap`, `Object#then`, `Object#yield_self`. The stronger "yields exactly once, before returning"
+    #   fact for these three lives in {BlockCallTiming}; that table is expected to move to the same
+    #   `RBS::Extended` call-timing effect as this one.
     # - Tuple/HashShape carriers map to Array/Hash for catalogue lookup so a literal `[1, 2, 3].each { ... }`
     #   is recognised.
     #
@@ -46,6 +54,14 @@ module Rigor
     # retained. False positives in this catalogue would silently weaken the soundness of fact retention in
     # later sub-phases.
     #
+    # Issue #1234 — a project class is outside the catalogue by name, yet `class Shelf; include Enumerable`
+    # answers `find` with `Enumerable#find` all the same. Given the `scope:` whose discovery tables know the
+    # project, a `Nominal` receiver of a project class classifies through its ancestry
+    # ({.ancestry_non_escaping?}): the method must be one the project does not define anywhere in that
+    # ancestry, and the first ancestor outside the project that declares it must be a catalogued class or
+    # `Enumerable` ({MIXIN_NON_ESCAPING}). An ancestor the RBS environment does not know could declare
+    # anything, so meeting one first declines.
+    #
     # The analyzer is a pure query. It MUST NOT mutate the receiver type or scope, MUST NOT raise on
     # unrecognised inputs, and MUST be deterministic for a given input.
     module ClosureEscapeAnalyzer
@@ -53,23 +69,65 @@ module Rigor
 
       # @param environment — reserved for the future sub-phase that consults
       #   `RBS::Extended` call-timing effects; sub-phase 3a ignores it.
+      # @param scope — the project's discovery tables, for the ancestry step; without it a project class
+      #   stays `:unknown`.
       # @return one of `:non_escaping`, `:escaping`, `:unknown`.
-      def classify(receiver_type:, method_name:, environment: nil) # rubocop:disable Lint/UnusedMethodArgument
+      def classify(receiver_type:, method_name:, environment: nil, scope: nil) # rubocop:disable Lint/UnusedMethodArgument
         return :unknown if receiver_type.nil?
 
+        method_sym = method_name.to_sym
         class_name = receiver_class_name(receiver_type)
-        return :unknown if class_name.nil?
+        if class_name
+          return :non_escaping if non_escaping?(class_name, method_sym)
+          return :escaping if escaping?(class_name, method_sym)
+        end
+
+        instance_class = instance_carrier_class_name(receiver_type)
+        return :unknown if instance_class.nil?
+
+        ancestry_non_escaping?(instance_class, method_sym, scope) ? :non_escaping : :unknown
+      end
+
+      # Issue #1234 — whether some catalogue entry lists `method_name` as an iteration method: a name that runs
+      # its block once per element wherever the catalogue knows the receiver. `tap` / `then` / `yield_self` are
+      # left out, as they run the block exactly once. This is a fact about the NAME, for the one consumer that
+      # asks it of an `:unknown` receiver ({BlockRepetition.may_repeat?}); it proves nothing about escape.
+      def iterator_name?(method_name)
+        ITERATOR_NAMES.include?(method_name)
+      end
 
+      # Issue #1234 — whether the NAME of a catalogued iterator is the only thing Rigor knows about the method
+      # `receiver_type` answers `method_name` with, so a pass may read it as repetition
+      # ({BlockRepetition.may_repeat?}, for an `:unknown` receiver). It holds for a receiver Rigor cannot
+      # see at all (`Dynamic`, `Top`), and for a class it can see whose method the project does not define.
+      #
+      # A method the project defines under a catalogued name is the project's, not the iterator, so the name
+      # says nothing about how often it yields: `class Vault; def select(key) = yield(key.to_s); end` runs its
+      # block once. "Defines" is a `def`, `define_method` or `attr_*` anywhere in a project class's ancestry
+      # (instance side, or singleton side for a class-object receiver), or a signature whose declaring owner
+      # is a project class or module. A carrier this does not recognise, or one whose class it cannot name
+      # (an anonymous `Struct.new` value), answers false: when Rigor cannot tell whether the project owns the
+      # method, it does not assume repetition. {ProjectMethodOwnership.targets} carries the carrier audit.
+      def repeats_by_name?(receiver_type:, method_name:, scope:)
         method_sym = method_name.to_sym
-        return :non_escaping if non_escaping?(class_name, method_sym)
-        return :escaping if escaping?(class_name, method_sym)
+        return false unless ITERATOR_NAMES.include?(method_sym)
 
-        :unknown
+        targets = ProjectMethodOwnership.targets(receiver_type)
+        return false if targets.nil?
+
+        targets.none? { |class_name, kind| ProjectMethodOwnership.defines?(class_name, method_sym, kind, scope) }
       end
 
       class << self
         private
 
+        # The instance-side class a `Nominal` or an ADR-48 member carrier names, for the ancestry step.
+        def instance_carrier_class_name(receiver_type)
+          case receiver_type
+          when Type::Nominal, Type::StructInstance, Type::DataInstance then receiver_type.class_name&.to_s
+          end
+        end
+
         # Resolve a single concrete class name for catalogue lookup. Returns `nil` when the receiver carrier
         # does not name a single class (e.g. `Top`, `Dynamic[Top]`, `Union[...]`, `Bot`). `Tuple` projects to
         # `Array`; `HashShape` to `Hash`; `Singleton[C]` to `C` (so `Integer.times` would resolve as a
@@ -115,6 +173,64 @@ module Rigor
           methods = ESCAPING[class_name]
           methods ? methods.include?(method_sym) : false
         end
+
+        # Issue #1234 — a project class answers `method_sym` through the catalogued ancestor Ruby dispatches it
+        # to. The cheap gates come first: the name must be a catalogued iteration method, and the receiver a
+        # class the project declares. A definition anywhere in the project ancestry — the class's own `def
+        # find`, a project module's, a reopened `Enumerable`'s — is not the catalogued method and declines.
+        # A class the project's `sig/` declares asks its RBS definition where the method comes from; one
+        # without RBS walks the ancestors outside the project in method-resolution order.
+        def ancestry_non_escaping?(class_name, method_sym, scope)
+          return false if scope.nil? || !ITERATOR_NAMES.include?(method_sym)
+          return false unless scope.known_user_class?(class_name)
+
+          by_method = (ProjectMethodOwnership.memo(scope)[:ancestry][class_name] ||= {})
+          return by_method[method_sym] if by_method.key?(method_sym)
+
+          by_method[method_sym] = compute_ancestry_non_escaping?(class_name, method_sym, scope)
+        end
+
+        def compute_ancestry_non_escaping?(class_name, method_sym, scope)
+          return false if ProjectMethodOwnership.defines?(class_name, method_sym, :instance, scope)
+
+          if Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+            return catalogued_declaration?(method_definition(class_name, method_sym, :instance, scope), method_sym)
+          end
+
+          external_ancestry_non_escaping?(class_name, method_sym, scope)
+        end
+
+        # The RBS definition, or nil — a malformed signature is a gap, and
+        # {ExternalAncestorResolution.method_definition} is the one place that rescues it.
+        def method_definition(class_name, method_sym, kind, scope)
+          ExternalAncestorResolution.method_definition(class_name, method_sym, kind, scope: scope)
+        end
+
+        # The first external ancestor that declares the method decides. One the environment does not know may
+        # declare it, so it declines rather than being skipped; one that does not declare it is skipped.
+        def external_ancestry_non_escaping?(class_name, method_sym, scope)
+          scope.external_ancestor_name_candidates(class_name).each do |candidates|
+            known = candidates.find { |candidate| Rigor::Reflection.rbs_class_known?(candidate, scope: scope) }
+            return false if known.nil?
+            return true if catalogued_owner?(known, method_sym)
+
+            definition = method_definition(known, method_sym, :instance, scope)
+            return catalogued_declaration?(definition, method_sym) if definition
+          end
+          false
+        end
+
+        def catalogued_declaration?(definition, method_sym)
+          return false if definition.nil? || !definition.respond_to?(:defined_in)
+
+          owner = definition.defined_in
+          !owner.nil? && catalogued_owner?(owner.to_s.delete_prefix("::"), method_sym)
+        end
+
+        def catalogued_owner?(name, method_sym)
+          methods = NON_ESCAPING[name] || MIXIN_NON_ESCAPING[name]
+          methods ? methods.include?(method_sym) : false
+        end
       end
 
       OBJECT_NON_ESCAPING = %i[tap then yield_self].freeze
@@ -149,9 +265,24 @@ module Rigor
       # `File.foreach(path) { case … when … then flag = true when … then return true if flag end }` classifies
       # `:unknown` and misses the loop-body re-narrowing, so a local written in one `when` arm reads its
       # pre-loop value in a sibling arm and a guarding condition folds to a spurious constant.
+      #
+      # The three are also `Enumerable[String]` over lines (rbs core declares it for `IO`;
+      # `data/core_overlay/string_io.rbs` for `StringIO`). An eager Enumerable method runs its block from inside
+      # the call, through `each`, so `io.each_with_index { … }` / `io.detect { … }` carry the same contract and
+      # take `ENUMERABLE_NON_ESCAPING` — minus {DEFERRED_ENUMERATOR_METHODS}, whose block outlives the call. On
+      # the `singleton(File)` / `singleton(IO)` side those names only ever meet `IO.select`, which takes no
+      # block and so never retains one. The key is the exact class name: a subclass (`Tempfile`, a user
+      # `StringIO` subclass) stays `:unknown`.
       IO_ITERATION = %i[each_line each each_byte each_char each_codepoint].freeze
       IO_SINGLETON_ITERATION = %i[foreach].freeze
 
+      # Enumerable methods that return an Enumerator holding the block and run it only when that Enumerator is
+      # consumed, so the block may run after locals it reads or writes have changed. They are NOT
+      # non-escaping. `ENUMERABLE_NON_ESCAPING` still lists them for the collection entries — a defect tracked
+      # as #1311; the stream entries below leave them out rather than inherit it.
+      DEFERRED_ENUMERATOR_METHODS = %i[chunk chunk_while slice_when slice_before slice_after].freeze
+      STREAM_ENUMERABLE_NON_ESCAPING = (ENUMERABLE_NON_ESCAPING - DEFERRED_ENUMERATOR_METHODS).freeze
+
       NON_ESCAPING = {
         "Array" => (ENUMERABLE_NON_ESCAPING + ARRAY_EXTRA).freeze,
         "Hash" => (ENUMERABLE_NON_ESCAPING + HASH_EXTRA).freeze,
@@ -160,11 +291,24 @@ module Rigor
         "Integer" => INTEGER_EXTRA,
         "Enumerator" => ENUMERABLE_NON_ESCAPING,
         "Enumerator::Lazy" => ENUMERABLE_NON_ESCAPING,
-        "IO" => (IO_ITERATION + IO_SINGLETON_ITERATION).freeze,
-        "File" => (IO_ITERATION + IO_SINGLETON_ITERATION).freeze,
-        "StringIO" => IO_ITERATION
+        "IO" => (STREAM_ENUMERABLE_NON_ESCAPING | IO_ITERATION | IO_SINGLETON_ITERATION).freeze,
+        "File" => (STREAM_ENUMERABLE_NON_ESCAPING | IO_ITERATION | IO_SINGLETON_ITERATION).freeze,
+        "StringIO" => (STREAM_ENUMERABLE_NON_ESCAPING | IO_ITERATION).freeze
+      }.freeze
+
+      # Issue #1234 — the catalogued modules a project class reaches only through its ancestry, read only by
+      # {.ancestry_non_escaping?} after the project has been ruled out as the method's owner. `Enumerable`'s
+      # methods run the block from inside the call, through the includer's `each` — minus
+      # {DEFERRED_ENUMERATOR_METHODS}, whose Enumerator outlives it, and minus `each` itself, which
+      # `Enumerable` does not declare: the includer supplies it, so nothing here speaks for it. For that
+      # reason a receiver typed as the bare module is not a key of {NON_ESCAPING} either.
+      MIXIN_NON_ESCAPING = {
+        "Enumerable" => (STREAM_ENUMERABLE_NON_ESCAPING - %i[each]).freeze
       }.freeze
 
+      # Every name a {NON_ESCAPING} entry lists as iteration, for {.iterator_name?} and the ancestry gate.
+      ITERATOR_NAMES = (NON_ESCAPING.values.flatten.to_set - OBJECT_NON_ESCAPING).freeze
+
       # Methods that are documented to **retain** the block past the call. The block is stored or scheduled,
       # so outer narrowing facts on writeable captured locals cannot survive.
       ESCAPING = {