rigortype 0.3.9 → 0.4.0

data/lib/rigor/inference/method_dispatcher/rbs_dispatch.rb

@@ -5,9 +5,11 @@ require_relative "../../type"
 require_relative "../../rbs_extended"
 require_relative "../range_constant"
 require_relative "../rbs_type_translator"
+require_relative "../external_ancestor_resolution"
 require_relative "../void_origin"
 require_relative "../optimistic_origin"
 require_relative "overload_selector"
+require_relative "self_substitute"
 
 module Rigor
   module Inference
@@ -42,14 +44,16 @@ module Rigor
       #
       # Remaining limitations:
       #
-      # * `block_type:` is ignored; method types that constrain the block return type are not yet honored.
-      # * Keyword arguments are not threaded through call_arg_types, so overloads with required keywords
-      #   are skipped (they cannot match the empty kwargs we send).
+      # * Keyword arguments reach `args` only as one trailing hash entry and are not matched against keyword
+      #   parameters, so overloads with required keywords are skipped.
       # * Method-level type parameters bind only from two positions: the block return type (Slice 6 phase C)
       #   and a positional parameter whose declared type is EXACTLY a type variable (issue #303 —
       #   `def foo[T]: (T) -> T` binds `T` from the first argument, and carries it into a generic return
       #   such as `-> Array[T]`). A variable reachable only through a container position (`Array[T] arg`),
       #   a rest positional (`*T`), or a keyword parameter is still unbound and degrades to `Dynamic[Top]`.
+      #   A block-return variable that a parameter also names takes the value class the argument and the
+      #   block share once the call passes an argument, or stays unbound when they share none (see
+      #   {compose_block_type_vars}).
       #
       # See docs/adr/4-type-inference-engine.md for the broader plan.
       # rubocop:disable-next Metrics/ModuleLength
@@ -65,6 +69,86 @@ module Rigor
         # objects answer to methods their RBS omits (`ActionController::Base`, `Hash`, …).
         ALLOWED_RBS_COMPLETE_ANCESTORS = ["Rigor::Plugin::Base"].freeze
 
+        # Issue #1094 — the methods through which a value can answer Ruby's implicit `to_ary` conversion.
+        # Multiple assignment and block auto-splat convert through `rb_check_array_type`, which calls
+        # `to_ary` when defined and otherwise asks `respond_to_missing?`, dispatching to `method_missing`
+        # when that answers true — so a `Delegator` destructures its target without defining `to_ary`.
+        ARRAY_CONVERSION_HOOKS = %i[to_ary method_missing respond_to_missing?].freeze
+
+        # The owners whose declarations of those hooks are the defaults rather than an override:
+        # `BasicObject#method_missing` raises and `Kernel#respond_to_missing?` answers false.
+        ARRAY_CONVERSION_DEFAULT_OWNERS = %w[::BasicObject ::Object ::Kernel].freeze
+
+        # Core value classes whose instances never convert — the answer with no RBS environment to hand.
+        ARRAY_CONVERSION_FREE_CORE_CLASSES = %w[
+          Integer Float Symbol String Hash Range Regexp Proc NilClass TrueClass FalseClass
+        ].freeze
+
+        # The classes `Array` itself inherits from. A `Nominal[Object]` is routinely an array at runtime, so
+        # the RBS walk below, which reads the named class's own ancestry, cannot vouch for them.
+        ARRAY_SUPERCLASSES = %w[Object BasicObject].freeze
+
+        # Issue #1094 — whether an instance of `class_name` provably has no implicit array conversion, so
+        # `a, b = value` binds `a` to the value and `b` to `nil` rather than splatting it. Shares ADR-43's
+        # rationale for when an RBS ancestry is closed: the RBS of a class the environment KNOWS is the method
+        # set every other negative rule already trusts (`call.undefined-method` fires on it), while a class the
+        # environment does not know — a Ruby-source class, whatever it inherits — is an open hierarchy and
+        # declines, exactly as ADR-43 keeps it on the Dynamic fallback. Modules and `Array`'s own superclasses
+        # decline because a value of those types is routinely something else. A project `def` of any hook on
+        # the class, its source ancestors, or the default owners declines too: the project's source outranks
+        # the RBS it did not write. Without a `scope` only the core list answers.
+        def array_conversion_free?(class_name, scope)
+          name = class_name.to_s.delete_prefix("::")
+          return false if project_defines_array_conversion?(name, scope)
+          return true if ARRAY_CONVERSION_FREE_CORE_CLASSES.include?(name)
+          return false if scope.nil? || ARRAY_SUPERCLASSES.include?(name)
+
+          rbs_ancestry_array_conversion_free?(name, scope.environment)
+        end
+
+        # ADR-17's boundary for what the project's source can add to a class: a `def` in the analysed file
+        # (`Scope#discovered_method*`, walked through the source ancestry) or in a `pre_eval:` file
+        # (`Environment#project_patched_methods`). Both are asked about the class, its RBS ancestors and the
+        # default owners, because a hook added to any of them reaches the instance.
+        def project_defines_array_conversion?(name, scope)
+          return false if scope.nil?
+
+          owners = [name, *rbs_instance_ancestor_names(name, scope.environment),
+                    *ARRAY_CONVERSION_DEFAULT_OWNERS.map { |owner| owner.delete_prefix("::") }].uniq
+          patched = scope.environment&.project_patched_methods
+          patched = nil if patched && patched.empty?
+          ARRAY_CONVERSION_HOOKS.any? do |hook|
+            scope.discovered_method_through_ancestors?(name, hook, :instance) ||
+              owners.any? do |owner|
+                scope.discovered_method?(owner, hook, :instance) ||
+                  !patched&.lookup(class_name: owner, method_name: hook, kind: :instance).nil?
+              end
+          end
+        end
+
+        def rbs_instance_ancestor_names(name, environment)
+          return [] if environment.nil? || !Rigor::Reflection.rbs_class_known?(name, environment: environment)
+
+          definition = Rigor::Reflection.instance_definition(name, environment: environment)
+          return [] if definition.nil?
+
+          definition.ancestors.ancestors.map { |ancestor| ancestor.name.to_s.delete_prefix("::") }
+        end
+
+        def rbs_ancestry_array_conversion_free?(name, environment)
+          return false if environment.nil?
+          return false unless Rigor::Reflection.rbs_class_known?(name, environment: environment)
+          return false if environment.rbs_module?(name)
+
+          definition = Rigor::Reflection.instance_definition(name, environment: environment)
+          return false if definition.nil?
+
+          ARRAY_CONVERSION_HOOKS.none? do |hook|
+            method = definition.methods[hook]
+            method && !ARRAY_CONVERSION_DEFAULT_OWNERS.include?(method.defined_in.to_s)
+          end
+        end
+
         # Shared empty returns for the argument-position type-variable binding (issue #303). The
         # no-candidate answer is by far the common case — every non-generic overload takes it — so it must
         # not allocate.
@@ -74,6 +158,16 @@ module Rigor
         private_constant :EMPTY_TYPE_PARAM_NAMES
         NO_BINDING = [nil, nil].freeze
         private_constant :NO_BINDING
+        EMPTY_ARGUMENT_NODES = [].freeze
+        private_constant :EMPTY_ARGUMENT_NODES
+
+        # The classes {#shared_value_class} admits. Given an argument of the same class, each one's `+`
+        # answers that class for every receiver, subclass instances included (`String#+` answers a String;
+        # the numeric classes have no instances of a subclass). `class Name < String` is left out, since the
+        # `+` it inherits answers a plain String, and so is any class whose `coerce` may make `+` answer a
+        # third one.
+        CLOSED_VALUE_CLASSES = Set["Integer", "Float", "Rational", "Complex", "String"].freeze
+        private_constant :CLOSED_VALUE_CLASSES
 
         # Both spellings a resolved `RBS::Types::ClassInstance#name` — or a `Nominal#class_name` built
         # from one — may carry for `Range`; core signatures absolutise, but a plugin-contributed one
@@ -148,7 +242,8 @@ module Rigor
             receiver: context.receiver,
             method_name: context.method_name,
             args: context.args,
-            environment: environment
+            environment: environment,
+            scope: context.scope
           )
         end
 
@@ -186,7 +281,8 @@ module Rigor
             return nil unless descriptor
 
             class_name, kind, receiver_args = descriptor
-            method_definition = lookup_method(environment, class_name, kind, method_name, scope)
+            method_definition = lookup_method(environment, class_name, kind, method_name, scope,
+                                              call_node: call_node)
             return nil unless method_definition
             return nil if public_only && method_private?(method_definition)
             # Issue #823 — a declaration that states the member's presence and parameters but not its
@@ -209,7 +305,8 @@ module Rigor
               type_vars: type_vars,
               block_type: block_type,
               environment: environment,
-              self_type_override: self_type_override,
+              self_type_override: self_type_override ||
+                                  SelfSubstitute.for(receiver, receiver_args, method_name, args, block_type),
               scope: scope,
               call_node: call_node
             )
@@ -325,11 +422,19 @@ module Rigor
             [Type::Combinator.union(*tuple.elements)]
           end
 
+          # An open shape's unseen keys may hold any value (rbs-erasure.md § *Open shapes with extra-value
+          # bounds*), so its projection carries a `Dynamic[top]` arm on both sides. Without it every read the
+          # shape tier does not answer — a `Union` receiver, a non-literal key — took the known values for a
+          # key outside them: `h = { a: 1 }; h.default = 0 if flag; h[:b] == 1` folded always-truthy.
           def hash_shape_type_args(shape)
             return [] if shape.pairs.empty?
 
             key_types = shape.pairs.keys.map { |k| Type::Combinator.constant_of(k) }
             value_types = shape.pairs.values
+            if shape.open?
+              key_types += [Type::Combinator.untyped]
+              value_types += [Type::Combinator.untyped]
+            end
             [
               Type::Combinator.union(*key_types),
               Type::Combinator.union(*value_types)
@@ -344,20 +449,43 @@ module Rigor
               method_definition.accessibility == :private
           end
 
-          def lookup_method(environment, class_name, kind, method_name, scope = nil)
+          def lookup_method(environment, class_name, kind, method_name, scope = nil, call_node: nil)
             direct = lookup_method_on(environment, class_name, kind, method_name)
             return direct if direct
 
+            # Issue #1173 — the include-edge sibling of the superclass bridges below: a discovered
+            # class's `include M` where M is RBS-known resolves M's declaration here. It runs BEFORE
+            # them because an include edge precedes the superclass edge in the MRO (`Sub < Hash` with
+            # `include M` chains `Sub → M → Hash`): when both a nearer mixin and a bridged ancestor
+            # declare the name, the mixin is the method that runs. See {#included_module_method}.
+            included = included_module_method(environment, class_name, kind, method_name, scope)
+            return included if included
+
             # ADR-43 — scoped inherited-method resolution. The direct lookup misses when `class_name` is a
             # Ruby-source subclass absent from RBS (so no ancestor walk runs). If its discovered
             # superclass chain reaches an allow-listed RBS-complete ancestor, resolve the method there so
             # inherited contract calls (`self.manifest` on a plugin) resolve and the normal call rules
             # apply. Bounded to the allow-list, so open hierarchies stay on the Dynamic fallback (no false
             # positive on `< ActionController::Base`).
-            ancestor = allowed_rbs_complete_ancestor(environment, class_name, scope)
-            return nil unless ancestor
+            ancestor = allowed_rbs_complete_ancestor(environment, class_name, kind, method_name, scope)
+            return lookup_method_on(environment, ancestor, kind, method_name) if ancestor
+
+            # `extend M` in a class/module body lifts M's INSTANCE surface onto the extending object's
+            # singleton — `class F; extend T::Sig; sig { ... }; end` resolves `sig` through
+            # `T::Sig#sig`. Same contract as the superclass bridge: only allow-listed (manifest
+            # `rbs_complete_extends:`) modules qualify, so open hierarchies stay on Dynamic.
+            if kind == :singleton
+              mod = allowed_rbs_complete_extended_module(environment, class_name, method_name, scope,
+                                                         call_node)
+              return lookup_method_on(environment, mod, :instance, method_name) if mod
+            end
 
-            lookup_method_on(environment, ancestor, kind, method_name)
+            # Issue #527 slice 1 — the same shape, one RBS ancestry wider: a Ruby-source subclass of a
+            # CORE or STDLIB class (`class SubHash < Hash`, `< StandardError`, `< ::StringScanner`)
+            # resolves its inherited calls there. Injected HERE rather than as a new tier because
+            # `dispatch_one` keys `self`, `instance`, the type-variable map and `SelfSubstitute` on the
+            # RECEIVER's class name, so changing only the lookup gets the correct binding for free.
+            core_stdlib_ancestor_method(environment, class_name, kind, method_name, scope)
           end
 
           def lookup_method_on(environment, class_name, kind, method_name)
@@ -374,34 +502,471 @@ module Rigor
           # `class_name` is itself RBS-known (the direct lookup already had authority), or when the
           # discovered chain reaches no allow-listed class. The walk carries a visited set so a malformed
           # cyclic `A < B < A` source cannot loop.
-          def allowed_rbs_complete_ancestor(environment, class_name, scope)
+          #
+          # ADR-43 WD4 — the allow-list's manifest-declared half: a loaded plugin may name its own
+          # contract classes in `rbs_complete_ancestors:` (e.g. rigor-graphql's `GraphQL::Schema::Object`),
+          # extending the engine's hard-coded seed without editing this constant.
+          def allowed_rbs_complete_ancestor(environment, class_name, kind, method_name, scope)
             return nil if scope.nil?
             return nil if Rigor::Reflection.rbs_class_known?(class_name, environment: environment)
 
+            # A project `def` on the receiver class or on a nearer source ancestor shadows the
+            # bridged declaration. RBS dispatch runs before the discovered-method tier, so without
+            # this guard the bridge would resolve e.g. `field` on `GraphQL::Schema::Object` while
+            # the runtime actually calls a user `def self.field` on an intermediate `BaseObject` —
+            # a wrong return type and a false `undefined-method`/arity reading downstream.
+            return nil if scope.discovered_method?(class_name, method_name, kind)
+
+            registry = environment&.plugin_registry
+            each_source_ancestor_candidate(scope, class_name) do |candidate|
+              return nil if scope.discovered_method?(candidate, method_name, kind)
+              return candidate if ALLOWED_RBS_COMPLETE_ANCESTORS.include?(candidate) ||
+                                  registry&.rbs_complete_ancestor?(candidate)
+            end
+            nil
+          end
+
+          # Issue #527 slice 1 — the RBS instance definition a Ruby-source class inherits from a CORE or
+          # STDLIB ancestor, or nil. `Oj::EasyHash < Hash` answering `Dynamic[top]` to `has_key?` while
+          # `{}.has_key?` folds was the largest single opacity family in the 2026-09-01 corpus sweep.
+          #
+          # Why this is not ADR-43's rejected alternative A. That ADR declined blanket inherited
+          # resolution because firing `call.undefined-method` against a PARTIAL gem RBS "would frighten
+          # working code". Two things narrow it here. The ancestry is core / stdlib, whose RBS is the
+          # method set every negative rule already trusts for a direct receiver of it. And the negative
+          # rules do not reach these receivers anyway: `undefined_method_diagnostic` and
+          # `arity_envelope_for` gate on `Reflection.rbs_class_known?` of the RECEIVER, which a
+          # Ruby-source subclass never is. So the risk this arm carries is not a new firing but a
+          # WRONG PRECISE TYPE propagating one hop — which is what the declines below are about.
+          #
+          # The declines, in order of what they protect:
+          #
+          # * `class_name` itself RBS-known — the direct lookup already had authority.
+          # * an ADR-26 plugin-declared open receiver, whose surface is larger than its declarations.
+          # * the subclass or a nearer SOURCE ancestor declares the name (ADR-110): the runtime calls
+          #   the project's `def`, and resolving the inherited declaration would answer about a method
+          #   that never runs. Asked of both discovery tables, because neither sees the whole of what a
+          #   `def` / `attr_*` / `define_method` / `alias` contributes, and both suppress on budget
+          #   exhaustion rather than answering "not declared" from an unfinished walk.
+          # * the walked ancestor, or the class the declaration is actually written on, is not core /
+          #   stdlib. That is what keeps `class MyController < ActionController::Base` on `Dynamic[top]`
+          #   (no RBS at all), and a subclass of an RBS-shipping GEM there too — slice 3's question.
+          # * an ADR-17 `pre_eval:` patch declares the name on the receiver or on any ancestor of the
+          #   owner: the project has replaced the very method whose declaration this would adopt.
+          #
+          # Type variables are NOT inferred: a `Nominal[SubHash]` receiver carries no type arguments, so
+          # `build_type_vars` yields the empty map and `Hash[K, V]`'s free variables degrade to
+          # `Dynamic[top]` per the translator's contract. `SubHash#keys` is `Array[Dynamic[top]]`, which
+          # is exactly what a raw `Hash` receiver already answers — honest rather than a loss.
+          def core_stdlib_ancestor_method(environment, class_name, kind, method_name, scope)
+            return nil if scope.nil? || kind != :instance
+            return nil if environment.nil?
+
+            memo = core_stdlib_memo(environment, scope)
+            key = [class_name.to_s, method_name.to_sym]
+            return memo[key] if memo&.key?(key)
+
+            answer = compute_core_stdlib_ancestor_method(environment, class_name, method_name, scope)
+            memo[key] = answer if memo
+            answer
+          end
+
+          # Issue #1173 — the include-edge sibling of {#core_stdlib_ancestor_method}: a discovered
+          # class's `include M` where M is RBS-known (a project `sig/`, bundled core / stdlib, or a
+          # shipped gem signature) resolves M's declaration here. Ruby inserts an included module into
+          # the ancestor chain outright, so adopting its declaration is the dispatch the runtime
+          # performs — unlike the superclass arm there is no "which classes may be read as complete"
+          # question, only the usual shadow guards: a project `def` on the receiver or a nearer
+          # ancestor, an outside-the-body `include` / `class_eval` mark (#992), or an ADR-17 `pre_eval:`
+          # patch each mean the declaration found is not the method that runs.
+          #
+          # The walk reuses {ExternalAncestorResolution} with `mixins: true` — an include edge precedes
+          # the superclass edge at each BFS node, matching the MRO — and the answer is adopted ONLY
+          # when the resolved owner is an RBS module (`environment.rbs_module?`). A superclass-owned
+          # answer keeps declining: a non-core ancestor class is the gap #527's superclass slice
+          # deferred, and the walk's ordering already gave every include edge its chance first.
+          #
+          # `kind` is `:instance` only: an `include`d module's `def self.x` is not callable on the
+          # includer (the singleton side is a separate #527 item). `self` needs no help here —
+          # `dispatch_one` keys `self` / `instance` on the RECEIVER's class name, so a `-> self`
+          # module method answers the includer, matching CRuby.
+          def included_module_method(environment, class_name, kind, method_name, scope)
+            return nil if scope.nil? || kind != :instance
+            return nil if environment.nil?
+
+            memo = mixin_ancestor_memo(environment, scope)
+            key = [class_name.to_s, method_name.to_sym]
+            return memo[key] if memo&.key?(key)
+
+            answer = compute_included_module_method(environment, class_name, method_name, scope)
+            memo[key] = answer if memo
+            answer
+          end
+
+          # The declines are conjunctive and ordered as {compute_core_stdlib_ancestor_method}'s are:
+          # the two walks that read the project's tables run LAST, only once an RBS declaration is
+          # actually in hand, because they read `Scope#superclass_of` / `#includes_of` and would file a
+          # file-granular ancestry edge for every call site otherwise.
+          def compute_included_module_method(environment, class_name, method_name, scope)
+            return nil if Rigor::Reflection.rbs_class_known?(class_name, environment: environment)
+            return nil if environment.plugin_registry&.open_receiver?(class_name)
+
+            definition, owner = Inference::ExternalAncestorResolution.resolve(
+              class_name, method_name, :instance,
+              scope: scope, environment: environment, record_dependencies: false, mixins: true
+            )
+            return nil if definition.nil?
+            return nil unless environment.rbs_module?(owner)
+            return nil if returns_the_walked_ancestry?(definition, owner, environment)
+            return nil if dynamic_surface_through_ancestors?(scope, class_name)
+            return nil if project_patched_through_ancestors?(environment, scope, class_name, owner, method_name)
+            return nil if source_declares_through_ancestors?(scope, class_name, method_name)
+
+            definition
+          end
+
+          # The same one-slot memo shape as {#core_stdlib_memo}; see there for why it is one slot keyed
+          # on the discovery index's identity, and why a recording run bypasses it.
+          MIXIN_ANCESTOR_MEMO_KEY = :__rigor_mixin_ancestor_dispatch__
+          private_constant :MIXIN_ANCESTOR_MEMO_KEY
+
+          def mixin_ancestor_memo(environment, scope)
+            return nil if Rigor::Analysis::DependencyRecorder.active?
+
+            discovery = scope.discovery
+            slot = Thread.current[MIXIN_ANCESTOR_MEMO_KEY]
+            unless slot && slot[0].equal?(discovery) && slot[1].equal?(environment)
+              slot = [discovery, environment, {}]
+              Thread.current[MIXIN_ANCESTOR_MEMO_KEY] = slot
+            end
+            slot[2]
+          end
+
+          # The declines are conjunctive, so their ORDER is free — and it is chosen so the two that walk
+          # the project's tables run LAST, only once a core / stdlib declaration is actually in hand.
+          # Every unresolved call on a Ruby-source receiver reaches here (`Widget.new.price` on a plain
+          # project class), and those walks read `Scope#superclass_of` / `#includes_of`, which file an
+          # ADR-46 ancestry edge. Running them unconditionally turned every cross-class METHOD call into
+          # a file-granular ancestry dependency — coarser than the symbol edge ADR-46 slice 4 files, and
+          # pinned against by `dependency_recorder_spec`. Reached at all, the edge is genuine: this
+          # answer does depend on the project not declaring the name on that ancestry.
+          def compute_core_stdlib_ancestor_method(environment, class_name, method_name, scope)
+            return nil if Rigor::Reflection.rbs_class_known?(class_name, environment: environment)
+            return nil if environment.plugin_registry&.open_receiver?(class_name)
+
+            definition, owner = Inference::ExternalAncestorResolution.resolve(
+              class_name, method_name, :instance,
+              scope: scope, environment: environment, record_dependencies: false, mixins: false
+            )
+            return nil if definition.nil?
+            return nil unless core_or_stdlib_owned?(environment, owner, definition)
+            return nil if returns_the_walked_ancestry?(definition, owner, environment)
+            return nil if dynamic_surface_through_ancestors?(scope, class_name)
+            return nil if project_patched_through_ancestors?(environment, scope, class_name, owner, method_name)
+            return nil if source_declares_through_ancestors?(scope, class_name, method_name)
+
+            definition
+          end
+
+          # The blocker this slice was first written without. CRuby PRESERVES THE SUBCLASS where core /
+          # stdlib RBS names the base class: `SubHash#merge` returns a `SubHash`, `SubSet#flatten` a
+          # `SubSet`, `SubPathname#basename` a `SubPathname`, `SubDate#+` a `SubDate` — verified against
+          # the interpreter. Adopting the declaration answers `Nominal[Hash]`, and because `Hash` IS
+          # RBS-known the negative rules then read it as a CLOSED surface: `sub.merge({}).own_method`
+          # drew an `error`-severity `call.undefined-method` on working code. That is ADR-5's failure
+          # exactly, one hop downstream — the propagation this slice's own boundary section names.
+          #
+          # RBS cannot distinguish the two families. `String#upcase: () -> String` really does return a
+          # plain `String` for a `String` subclass (Ruby 3.0 changed that), while `Hash#merge: () ->
+          # Hash[K, V]` really does return the subclass, and the two declarations are the same shape.
+          # So the answer is DECLINE, which is master's `Dynamic[top]` and therefore provably cannot
+          # regress a corpus target — rather than substituting the receiver as if the declaration read
+          # `-> self`. That substitution would be right for `merge` and wrong for `upcase`, and its
+          # wrongness is not purely a false negative: a `Nominal[SubStr]` that is really a `String`
+          # narrows `is_a?` guards and can reach `clause.unreachable` on a branch the runtime takes.
+          #
+          # `-> self` and `-> instance` returns are NOT affected and keep their precision: those already
+          # resolve against the receiver (`SubHash#clear` → `SubHash`, `SubStr#force_encoding` →
+          # `SubStr`, `MyError#exception` → `MyError`), which is what CRuby does.
+          #
+          # The test looks for the owner ANYWHERE in the return type, type arguments included. A first
+          # draft unwrapped only the top level, unions and optionals, on the reasoning that a class named
+          # inside `Array[...]` describes the elements rather than the returned object — true, and beside
+          # the point, because the ELEMENTS are subclass instances too. `Pathname#children: () ->
+          # Array[Pathname]` hands back an array of `SubPath`s (likewise `entries`, `each_child`,
+          # `ascend`, `descend`, `find`; only `glob` yields a plain `Pathname`), so
+          # `sub.children.first.own_method` fired the same `call.undefined-method` one level down.
+          # `Date#step`, `Date#upto` and `Set#classify` are the same family and escaped only by the shape
+          # of their declarations.
+          #
+          # The cost of the deeper walk is in the direction WD7 already accepts: `SubStr#chars` →
+          # `Array[String]` now declines although CRuby really does yield plain `String`s. `keys`,
+          # `to_a` and `classify` are unaffected, their arguments being type variables or `self`.
+          #
+          # An `Alias` that expands to the owner is not followed; that is a known gap in the FN direction.
+          def returns_the_walked_ancestry?(definition, owner, environment)
+            names = [owner.to_s.delete_prefix("::"), *rbs_instance_ancestor_names(owner, environment)].to_set
+            method_types = definition.respond_to?(:method_types) ? definition.method_types : nil
+            return false if method_types.nil?
+
+            method_types.any? do |method_type|
+              return_type = method_type.type.respond_to?(:return_type) ? method_type.type.return_type : nil
+              mentions_class?(return_type, names)
+            end
+          rescue StandardError
+            # A signature whose return type cannot be read is a gap, and a gap declines.
+            true
+          end
+
+          # Whether any of `names` appears as a class instance anywhere in `type`, descending through
+          # every child an RBS type exposes — union members, the inside of an optional, and type
+          # ARGUMENTS. See {returns_the_walked_ancestry?}.
+          def mentions_class?(type, names, depth = 0)
+            return false if type.nil? || depth > RETURN_TYPE_UNWRAP_DEPTH
+            return true if own_class_name_matches?(type, names)
+            return false unless type.respond_to?(:each_type)
+
+            type.each_type.any? { |child| mentions_class?(child, names, depth + 1) }
+          end
+
+          def own_class_name_matches?(type, names)
+            type.is_a?(::RBS::Types::ClassInstance) && names.include?(type.name.to_s.delete_prefix("::"))
+          end
+
+          # A guard against a pathological or cyclic signature, not a semantic limit: real return types
+          # nest a level or two (`Array[Pathname]`, `Hash[Symbol, Array[String]]`).
+          RETURN_TYPE_UNWRAP_DEPTH = 8
+          private_constant :RETURN_TYPE_UNWRAP_DEPTH
+
+          # Issue #992's surface mark: a `Klass.include(M)` / `.prepend(M)` / `class_eval` written
+          # OUTSIDE the class body, which `ScopeIndexer` records as `ENVELOPE_DYNAMIC_MARK` because it
+          # can add members the in-body walks never see. `class Extended < Hash; end` followed by
+          # `Extended.include(Ext)` where `Ext#empty?` returns `42` must not adopt `Hash#empty?`. Asked
+          # of the receiver and of every SOURCE ancestor between it and the owner, because a mark on an
+          # intermediate reaches the receiver just as well.
+          def dynamic_surface_through_ancestors?(scope, class_name)
+            return true if dynamic_surface?(scope, class_name)
+
+            each_source_ancestor_candidate(scope, class_name) do |candidate|
+              return true if dynamic_surface?(scope, candidate)
+            end
+            false
+          end
+
+          def dynamic_surface?(scope, class_name)
+            Scope::DiscoveryIndex.rewritten_surface?(scope.parameter_envelopes_of(class_name))
+          end
+
+          # ADR-110's precedence, asked of both tables the project's own members land in. Either one
+          # answering true is a decline; both suppress (answer true) when their shared
+          # `Scope::ANCESTOR_WALK_LIMIT` budget runs out, and record a `BudgetTrace` hit there.
+          def source_declares_through_ancestors?(scope, class_name, method_name)
+            return true if scope.discovered_method_through_ancestors?(class_name, method_name, :instance)
+
+            !scope.user_def_through_ancestors(class_name, method_name).first.nil?
+          end
+
+          # Both ends of the declaration have to be core / stdlib: the ancestor the walk asked (`Hash`,
+          # `StringScanner`) and the class the declaration is written on (`Exception` for
+          # `StandardError#message`, `Comparable` for a `clamp`). Either being a gem's or the project's
+          # own RBS is slice 3's question, not this one's.
+          def core_or_stdlib_owned?(environment, owner, definition)
+            loader = environment.rbs_loader
+            return false if loader.nil? || !loader.respond_to?(:core_or_stdlib_class?)
+            return false unless loader.core_or_stdlib_class?(owner)
+
+            declared_on = definition.respond_to?(:defined_in) ? definition.defined_in : nil
+            return false if declared_on.nil?
+
+            loader.core_or_stdlib_class?(declared_on.to_s)
+          end
+
+          # ADR-17 — a `pre_eval:` file that reopens the receiver, any SOURCE ancestor between it and the
+          # owner, or any RBS ancestor of the owner, and redefines the name. The declaration this arm
+          # would adopt is then not the method that runs. The source chain is the half the first draft
+          # missed: `class Middle < Hash; end; class Leaf < Middle; end` with a `pre_eval:`
+          # `class Middle; def key?(k) = 42; end` answered `bool` for a call that returns `42`.
+          def project_patched_through_ancestors?(environment, scope, class_name, owner, method_name)
+            patched = environment.project_patched_methods
+            return false if patched.nil? || patched.empty?
+
+            owners = [class_name.to_s.delete_prefix("::"), *rbs_instance_ancestor_names(owner, environment)]
+            each_source_ancestor_candidate(scope, class_name) { |candidate| owners << candidate }
+            owners.any? do |name|
+              !patched.lookup(class_name: name, method_name: method_name, kind: :instance).nil?
+            end
+          end
+
+          # Memo for the whole decision. Every call site of a class asks the same `(class, method)`
+          # question, and the answer is a pure function of the frozen discovery index and the
+          # environment, so it is cacheable on their identity. A run that is RECORDING ADR-46
+          # dependency edges bypasses it: the shadow probes above read the project's method tables, and
+          # a memo would swallow that edge for every file after the first.
+          #
+          # ONE slot, replaced rather than accumulated — see {ExternalAncestorResolution}'s twin for
+          # the measurement. A `Scope` hands each analysed file its own discovery index, so an
+          # identity-keyed store would pin every file's index, and every RBS definition resolved
+          # against it, for the length of the run.
+          CORE_STDLIB_ANCESTOR_MEMO_KEY = :__rigor_core_stdlib_ancestor_dispatch__
+          private_constant :CORE_STDLIB_ANCESTOR_MEMO_KEY
+
+          def core_stdlib_memo(environment, scope)
+            return nil if Rigor::Analysis::DependencyRecorder.active?
+
+            discovery = scope.discovery
+            slot = Thread.current[CORE_STDLIB_ANCESTOR_MEMO_KEY]
+            unless slot && slot[0].equal?(discovery) && slot[1].equal?(environment)
+              slot = [discovery, environment, {}]
+              Thread.current[CORE_STDLIB_ANCESTOR_MEMO_KEY] = slot
+            end
+            slot[2]
+          end
+
+          # BFS over the scope's as-written ancestry tables — include edges first, then the
+          # superclass, matching the MRO — yielding every ancestor-name candidate. The tables store
+          # names AS WRITTEN — `"::API::Base"`, bare `"Base"` — so each hop resolves through the
+          # nesting-aware `ancestor_name_candidates` rather than a raw lookup. Deliberately
+          # NOT `external_ancestor_name_candidates`: that walk records `ancestry_sources` edges via
+          # `record_class_dependency`, which would mislabel a dispatch lookup as an ancestry edge.
+          #
+          # Issue #1173 — the walk follows include edges too, because a shadow guard that reads only
+          # the superclass chain misses the nearer half of the ancestry: `class C < Base; include M;
+          # end` chains `C → M → Base`, and a `def`, an outside-the-body mark, or a `pre_eval:` patch
+          # on a source `M` all outrank `Base`'s declaration. A candidate that names a project class /
+          # module continues the walk ({Scope#known_user_class?} — a module that defines nothing and
+          # mixes nothing in still gates what the arm may adopt); an RBS-known or unresolved one is
+          # yielded for the caller's guards but its ancestry is the RBS side's business. The include
+          # table is read RAW (`scope.discovered_includes`), the same reason the superclass table is:
+          # `Scope#includes_of` files `record_class_dependency` on every read — a miss included —
+          # and this walk runs for every unresolved call on a project class (`Widget.new`), so the
+          # reader would turn each one into an ancestry edge ADR-46 slice 4 keeps at symbol
+          # granularity (`dependency_recorder_spec`).
+          def each_source_ancestor_candidate(scope, class_name)
+            supers = scope.discovered_superclasses
+            includes = scope.discovered_includes
+            queue = [class_name.to_s]
+            seen = {}
+            until queue.empty?
+              current = queue.shift
+              next if current.nil? || seen[current]
+
+              seen[current] = true
+              ((includes[current] || []) + [supers[current]].compact).each do |raw|
+                scope.ancestor_name_candidates(current, raw).each do |candidate|
+                  yield candidate
+                  queue << candidate if scope.known_user_class?(candidate)
+                end
+              end
+            end
+          end
+
+          # The extend-edge twin of `allowed_rbs_complete_ancestor` (manifest `rbs_complete_extends:`).
+          # `extend M` lifts M's INSTANCE surface onto the extending class object's singleton, so a
+          # singleton call on a Ruby-source class can resolve through a module the class — or one of
+          # its discovered superclasses — extends. Returns the first resolved candidate name that a
+          # loaded plugin allow-lists, or nil. Same guards as the superclass bridge, minus the
+          # RBS-known receiver exit: the direct lookup has already missed by the time this runs, and
+          # a class that is BOTH source-defined and RBS-known (`class F` in `sig/` plus `extend T::Sig`
+          # in the body) still carries the source edge — the runtime ancestry contains the module
+          # either way, so withholding the bridge would leave a real `sig` opaque. A nearer source
+          # `def self.x` still shadows any bridged module method.
+          def allowed_rbs_complete_extended_module(environment, class_name, method_name, scope,
+                                                   call_node = nil)
+            return nil if scope.nil?
+
+            registry = environment&.plugin_registry
+            return nil if registry.nil?
+
             supers = scope.discovered_superclasses
+            extends = scope.discovered_extends
+            queue = [class_name.to_s]
             seen = {}
-            current = supers[class_name.to_s]
-            until current.nil? || seen[current]
-              return current if ALLOWED_RBS_COMPLETE_ANCESTORS.include?(current)
+            until queue.empty?
+              current = queue.shift
+              next if current.nil? || seen[current]
 
               seen[current] = true
-              current = supers[current]
+              # The class's own `def self.x` sits ahead of every `extend` — once it has run.
+              # `singleton_def_shadows_call?` orders the def against the call site, so a `def self.sig`
+              # written AFTER this `sig {}` does not suppress the bridge.
+              return nil if scope.singleton_def_shadows_call?(current, method_name, call_node)
+
+              resolved = rbs_complete_extended_module_for(current, extends, environment, scope,
+                                                          registry, method_name, call_node)
+              return nil if resolved.equal?(EXTEND_OWNER_STOP)
+              return resolved if resolved
+
+              raw = supers[current]
+              scope.ancestor_name_candidates(current, raw).each { |c| queue << c } if raw
+            end
+            nil
+          end
+
+          # One walk hop of `allowed_rbs_complete_extended_module`. Each `extend` edge binds to the
+          # first resolution candidate that exists at runtime. If that owner DEFINES `method_name`:
+          # an allow-listed RBS module is the answer; a project class or a non-allow-listed RBS name
+          # owns the call, so the hop returns {EXTEND_OWNER_STOP} and the outer walk must not search
+          # later extends or superclasses (a nested `Outer::CustomSig` would otherwise fall through
+          # to `T::Sig` and type the call as `nil`). An owner that does not define the method yields
+          # to the next extended module — Ruby's singleton ancestry searches every extend in turn.
+          def rbs_complete_extended_module_for(current, extends, environment, scope, registry,
+                                               method_name, call_node)
+            each_extended_module_name(current, extends, environment) do |mod_name|
+              owner = scope.ancestor_name_candidates(current, mod_name).find do |candidate|
+                scope.known_user_class?(candidate) ||
+                  Rigor::Reflection.rbs_class_known?(candidate, environment: environment)
+              end
+              next if owner.nil?
+              next unless extend_owner_defines?(owner, method_name, call_node, scope, environment)
+
+              project_owned = scope.known_user_class?(owner)
+              return owner if !project_owned && registry.rbs_complete_extends?(owner)
+
+              return EXTEND_OWNER_STOP
             end
             nil
           end
 
+          def extend_owner_defines?(owner, method_name, call_node, scope, environment)
+            return true if scope.instance_def_shadows_call?(owner, method_name, call_node)
+
+            !lookup_method_on(environment, owner, :instance, method_name).nil?
+          end
+
+          # Sentinel: a nearer `extend` answers `method_name`, so the allow-list must not continue.
+          EXTEND_OWNER_STOP = :__rbs_complete_extends_stop__
+          private_constant :EXTEND_OWNER_STOP
+
+          # The module names `current` extends, source table first (`discovered_extends`, stored in
+          # singleton-ancestor search order — nearest edge first) then the RBS side
+          # (`singleton_extended_modules`, already qualified) — an RBS superclass like `T::Struct`
+          # declares `extend T::Props::ClassMethods` in signature, and a source subclass inherits it.
+          def each_extended_module_name(current, extends, environment, &)
+            (extends[current] || []).each(&)
+            (environment&.singleton_extended_modules(current) || []).each(&)
+          end
+
           # Slice 4 phase 2d substitution map. Zips the class's declared type-parameter names against the
-          # receiver's `type_args`. Returns an empty hash when either side is empty or when arities
-          # disagree -- in both cases free variables in the method's return type degrade to `Dynamic[Top]`
-          # per the translator's contract.
+          # receiver's `type_args`. Returns an empty hash when either side is empty or when the receiver
+          # carries MORE arguments than the class declares -- in every such case free variables in the
+          # method's return type degrade to `Dynamic[Top]` per the translator's contract.
+          #
+          # Issue #1121 -- FEWER arguments than parameters is not a disagreement, it is the partial
+          # application RBS itself licenses for a class whose trailing parameters declare a default:
+          # `Enumerator::Lazy[out E, out R = void]` is spelled `Enumerator::Lazy[Elem]` by the very
+          # signature that hands one back (`Enumerable#lazy: () -> Enumerator::Lazy[Elem]`). Withholding
+          # the whole map there dropped the element binding on every lazy-enumerator receiver, so the
+          # block parameter of `lazy.map { |x| … }` was `Dynamic[top]` and the chain could not recover the
+          # element type. The supplied prefix MUST bind in declaration order and the omitted trailing names
+          # stay unbound (`Dynamic[top]`), exactly as any other free variable does.
           def build_type_vars(environment, class_name, receiver_args)
             return NO_TYPE_VARS if receiver_args.empty?
 
             param_names = Rigor::Reflection.class_type_param_names(class_name, environment: environment)
             return NO_TYPE_VARS if param_names.empty?
-            return NO_TYPE_VARS if param_names.size != receiver_args.size
+            return NO_TYPE_VARS if receiver_args.size > param_names.size
 
-            param_names.zip(receiver_args).to_h
+            param_names.first(receiver_args.size).zip(receiver_args).to_h
           end
 
           # The shared empty substitution map: most receivers carry no type arguments, and the translator
@@ -428,13 +993,16 @@ module Rigor
               end
             # `self_type_override` lets the user-class fallback path preserve the ORIGINAL receiver as the
             # substitute for `Bases::Self` — so `Kernel#dup: () -> self` resolved through the Object
-            # fallback returns the caller's type, not Object.
+            # fallback returns the caller's type, not Object. `dispatch_one` also routes the receiver's
+            # type-argument-bearing projection through it ({SelfSubstitute}, #1092).
             self_type = self_type_override || resolved_self_type
 
             candidates = OverloadSelector.select_candidates(
               method_definition,
               arg_types: args,
-              self_type: self_type,
+              # A `Dynamic` self (#1092) is a return-side answer; overload selection and ReceiverAffinity
+              # read the static facet, as they did before the substitute carried the wrapping.
+              self_type: self_type.is_a?(Type::Dynamic) ? self_type.static_facet : self_type,
               instance_type: instance_type,
               type_vars: type_vars,
               block_required: !block_type.nil?,
@@ -446,6 +1014,7 @@ module Rigor
             record_dispatch_provenance(method_definition, candidates.first, scope, call_node, call_site)
             join_candidate_returns(
               candidates,
+              method_definition: method_definition,
               self_type: self_type, instance_type: instance_type, type_vars: type_vars,
               args: args, block_type: block_type, scope: scope, call_node: call_node, call_site: call_site,
               alias_expander: environment.rbs_loader
@@ -485,17 +1054,20 @@ module Rigor
           # A candidate whose return does not translate leaves the join incomplete — decline (fail-soft
           # to Dynamic downstream) rather than answer a join missing an arm the runtime can take.
           # rubocop:disable-next Metrics/ParameterLists
-          def join_candidate_returns(candidates, self_type:, instance_type:, type_vars:, args:, block_type:,
-                                     scope:, call_node:, call_site:, alias_expander: nil)
+          def join_candidate_returns(candidates, method_definition:, self_type:, instance_type:, type_vars:, args:,
+                                     block_type:, scope:, call_node:, call_site:, alias_expander: nil)
             returns = candidates.map do |method_type|
               full_type_vars = compose_type_vars(method_type, type_vars, args, block_type, scope, call_node, call_site)
-              RbsTypeTranslator.translate(
+              returned = RbsTypeTranslator.translate(
                 method_type.type.return_type,
                 self_type: self_type,
                 instance_type: instance_type,
                 type_vars: full_type_vars,
                 alias_expander: alias_expander
               )
+              next returned unless combining_overload?(method_definition, method_type, call_site)
+
+              class_level_sum(returned, method_type, args)
             end
             return returns.first if returns.size == 1
             return nil if returns.any?(&:nil?)
@@ -507,11 +1079,100 @@ module Rigor
           end
 
           def compose_type_vars(method_type, type_vars, args, block_type, scope, call_node, call_site)
-            vars = compose_block_type_vars(method_type, type_vars, block_type)
+            vars = compose_block_type_vars(method_type, type_vars, block_type, args,
+                                           scope: scope, call_node: call_node, call_site: call_site)
             compose_arg_type_vars(method_type, vars, args, scope: scope, call_node: call_node,
                                                            call_site: call_site)
           end
 
+          # Whether the overload is one `Enumerable` declares for `sum`, whose declared return the tier reads
+          # at class level ({#class_level_sum}). Every overload spells its return as the sides the method adds
+          # together, as a union or as one variable that covers both: `() -> (E | Integer)`,
+          # `[T] () { (E) -> T } -> (Integer | T)`, `[T] (?T) -> (E | T)` and `[U] (?U) { (E) -> U } -> U`.
+          # A value is not closed under that addition, so the value-pinned bindings of `E` (from the
+          # receiver), `T` (from the argument, issue #303) and the block's type do not describe the result:
+          # `[1, 2].each.sum(0.0)` is `3.0`, which `0.0 | 1 | 2` misses. `Array#fetch: [T] (int, T default)
+          # -> (E | T)` is spelled the same way but
+          # returns the default object itself, so the signature alone cannot tell the two apart and the
+          # declaring module does. A class that declares its own `sum` states its own contract and keeps it.
+          def combining_overload?(method_definition, method_type, call_site)
+            return false unless call_site[1] == :sum
+
+            type_def = OptimisticOrigin.matching_type_def(method_definition, method_type)
+            !type_def.nil? && type_def.defined_in.to_s.delete_prefix("::") == "Enumerable"
+          end
+
+          # Apart from the range shortcut ({#range_coerced_seed?}), CRuby's `enum_sum` adds each value to an
+          # accumulator that starts at the seed. Between two of these classes `+` answers the later one
+          # (`1 + 0.5` and `0.5 + 1` are Floats, `1 + 1r` is a Rational), so the accumulator's class only ever
+          # moves up this order.
+          SUM_PROMOTION_RANKS = { "Integer" => 0, "Rational" => 1, "Float" => 2, "Complex" => 3 }.freeze
+          private_constant :SUM_PROMOTION_RANKS
+
+          # CRuby's seed when the call passes none.
+          SUM_DEFAULT_SEED = ["Integer"].freeze
+          private_constant :SUM_DEFAULT_SEED
+
+          # The seeds CRuby's integer-range shortcut adds to with plain `+` ({#range_coerced_seed?}).
+          RANGE_ADDED_SEEDS = Set["Integer", "Float"].freeze
+          private_constant :RANGE_ADDED_SEEDS
+
+          # The class-level reading of a `sum` overload's translated return, or `Dynamic[top]` when a member
+          # widens to none of the value classes {#value_classes} admits. A class, not a value, is what the
+          # addition keeps closed: `sum` over `0.0` and `1 | 2` is `3.0`, a Float, and over `1.5 | 2.5` is
+          # `4.0`.
+          #
+          # The union of the members' classes would still read wider than the runtime, because the seed
+          # promotes every value it absorbs: `ints.each.sum(0.0)` is always a Float, and `Float | Integer`
+          # fires `def.return-type-mismatch` against a declared `-> Float` on correct code. So each class is
+          # taken as the class the accumulator reaches from each seed class ({#promoted_class}), and the seed
+          # itself stays for a receiver that yields nothing: `ints.each.sum(0.0)` reads `Float`, and
+          # `floats.each.sum(0)` reads `Float | Integer`, whose Integer is the empty receiver's `0`.
+          def class_level_sum(type, method_type, args)
+            return nil if type.nil?
+
+            members = value_classes(type)
+            return Type::Combinator.untyped if members.nil?
+
+            seeds = sum_seed_classes(method_type, args)
+            return Type::Combinator.untyped if seeds.nil? || range_coerced_seed?(method_type, seeds)
+
+            reached = seeds.flat_map { |seed| members.map { |member| promoted_class(seed, member) } }
+            Type::Combinator.union(*(seeds | reached).map { |name| Type::Combinator.nominal_of(name) })
+          end
+
+          # Whether CRuby may skip the accumulator and read the seed as a Float. With no block and a seed that
+          # is not a Float, `enum_sum` sums a range with Integer endpoints by Gauss's formula and adds the
+          # result to the seed. An Integer seed takes plain `+`; any other goes through `Integer#coerce`, which
+          # converts it with `Float()`: `(1..3).sum(0r)` is `6.0` and `(1..3).sum("1.5")` is `7.5`. Any object
+          # that answers `begin`, `end` and `exclude_end?` takes the same path, so the receiver's class cannot
+          # rule it out.
+          def range_coerced_seed?(method_type, seeds)
+            method_type.block.nil? && seeds.any? { |seed| !RANGE_ADDED_SEEDS.include?(seed) }
+          end
+
+          # The classes of the value `sum` starts from: the argument when the overload takes one and the call
+          # passes it, and CRuby's `0` otherwise.
+          def sum_seed_classes(method_type, args)
+            fun = method_type.type
+            return SUM_DEFAULT_SEED if args.empty? || !fun.respond_to?(:required_positionals)
+            return SUM_DEFAULT_SEED if fun.required_positionals.empty? && fun.optional_positionals.empty?
+
+            value_classes(args.first)
+          end
+
+          # The class the accumulator reaches when a `member` value is added to a `seed`-class one. `+` does not
+          # add a String and a number (`"" + 1` and `1 + ""` raise), so such a pair keeps the member's class,
+          # which reads wider than the runtime rather than narrower. The range shortcut that does convert a
+          # String seed never reaches here ({#range_coerced_seed?}).
+          def promoted_class(seed, member)
+            seed_rank = SUM_PROMOTION_RANKS[seed]
+            member_rank = SUM_PROMOTION_RANKS[member]
+            return member if seed_rank.nil? || member_rank.nil?
+
+            seed_rank > member_rank ? seed : member
+          end
+
           # Record the `void → top` recovery when the selected overload declares `-> void` and both `scope` and
           # `call_node` are present (the direct-dispatch path). `void_site` is the `[class_name, method_name,
           # kind]` triple the {VoidOrigin} carries.
@@ -558,13 +1219,160 @@ module Rigor
           # block return type at the same call site. Anything outside this exact shape (no block clause,
           # an `untyped` block, a non-variable block return type, a variable not declared in
           # `type_params`) returns the original `type_vars` so fallbacks stay consistent.
-          def compose_block_type_vars(method_type, type_vars, block_type)
+          #
+          # The block alone does not decide a variable that a parameter's type also names once the call
+          # passes an argument. `Enumerable#sum: [U] (?U) { (E) -> U } -> U` adds the block's values to the
+          # argument, `Enumerable#inject: [A] (A initial) { (A, E) -> A } -> A` returns the argument for an
+          # empty receiver, and `Hash#transform_keys: [K2] (hash[_Key, K2]) { (K) -> K2 } -> Hash[K2, V]`
+          # takes a mapping hit's value without yielding. `Dynamic[block_type]` would not do: a `Dynamic`
+          # receiver dispatches through its static facet and answers exactly, so a facet that misses the
+          # runtime value is wrong one call later (`(h.sum(0.0) { |_k, v| v } / h.size).nan?` read
+          # `Integer#nan?`). Nor would joining in the argument as it stands, since
+          # `[1, 2].each.sum(0.0) { |x| x }` is `3.0`, which neither side contains. The variable is bound
+          # to {#shared_value_class} where both sides have one, and to `Dynamic[top]` otherwise. The key
+          # stays in the map either way so {#compose_arg_type_vars} does not bind the variable from the
+          # argument alone.
+          def compose_block_type_vars(method_type, type_vars, block_type, args, scope:, call_node:, call_site:)
             return type_vars if block_type.nil?
 
             block_var_name = method_type_block_return_variable(method_type)
             return type_vars if block_var_name.nil?
+            return type_vars.merge(block_var_name => block_type) unless
+              argument_reaches_variable?(method_type, block_var_name, args)
+
+            shared = shared_value_class(method_type, block_var_name, args, block_type, call_node)
+            bound = shared && arg_binding_permitted?(scope, call_node, call_site) ? shared : Type::Combinator.untyped
+            type_vars.merge(block_var_name => bound)
+          end
 
-            type_vars.merge(block_var_name => block_type)
+          # Whether an argument the call passes may land in a parameter whose type names `name`, anywhere
+          # inside it (`hash[_Key, K2]` names `K2`). The argument count is not matched against the
+          # parameter list: a `*splat` argument stands for any number of arguments, and keyword arguments
+          # arrive as one more entry in `args`, so any argument counts as reaching every parameter.
+          def argument_reaches_variable?(method_type, name, args)
+            return false if args.empty?
+
+            method_type.type.each_param.any? { |param| mentions_variable?(param.type, name) }
+          end
+
+          # The one value class that the arguments landing in `name`'s parameters and the block's type all
+          # share, or nil to leave the variable `Dynamic[top]`. A class, not a value, because a combining
+          # method keeps a class closed and not a value: `[1, 2].each.sum(1) { |x| -x }` is `-2`, which
+          # neither `1` nor `-1 | -2` contains. RBS reads `[U] (?U) { (E) -> U } -> U` the same way, as a
+          # `U` that covers the argument and the block alike. One class and not a union of several, because
+          # `sum` absorbs: over Integers, `sum(0.0)` answers a Float every time, and `Float | Integer` would
+          # fire `def.return-type-mismatch` against a declared `-> Float`.
+          #
+          # The block's type is one typing of its body, so it covers every call only when nothing the block
+          # receives depends on the variable ({#block_receives_variable?}). The argument binding's gate
+          # applies ({#arg_binding_permitted?}), since this reads the argument. The positions must be static
+          # ({#arguments_at_variable}), and every side must widen to a class ({#value_classes}). The block's
+          # type is trusted as far as the engine trusts it, so a hash filled through an alias, which reads
+          # narrower than it is, binds its narrower class here too.
+          def shared_value_class(method_type, name, args, block_type, call_node)
+            return nil if block_receives_variable?(method_type.block, name)
+
+            reaching = arguments_at_variable(method_type, name, args, call_node)
+            return nil if reaching.nil?
+
+            sides = [*reaching, block_type].map { |type| value_classes(type) }
+            return nil unless sides.all?
+
+            classes = sides.flatten(1).uniq
+            classes.size == 1 ? Type::Combinator.nominal_of(classes.first) : nil
+          end
+
+          # Whether the block's parameters or its `self` name the variable, as `inject`'s accumulator
+          # (`{ (A, E) -> A }`) and `produce`'s previous element (`{ (T prev) -> T }`) do. Such a parameter
+          # holds the argument on the first call and the block's own result after it, and the pass that
+          # typed the block typed it once, as whatever reached it: the RBS probe leaves it untyped, but
+          # `IteratorDispatch` hands an Array receiver's `inject` the seed, and a `&:+` block then reads
+          # `0.+`, so `[1.5, 2].inject(0, &:+)`, which is `3.5`, would bind `Integer`.
+          def block_receives_variable?(block, name)
+            return true if block.self_type && mentions_variable?(block.self_type, name)
+
+            block.type.each_param.any? { |param| mentions_variable?(param.type, name) }
+          end
+
+          # The arguments that land in a positional parameter whose whole type is `name`, or nil when the
+          # call's positions or the signature's shape leave that open. The call must pass plain positional
+          # arguments: after a `*splat` that turns out empty, the next argument lands one parameter earlier,
+          # and a forwarded `...` or keyword arguments may land anywhere. The signature must name `name` only
+          # as a whole leading positional parameter's type, and have no trailing positional parameter at
+          # all. One that names the variable takes its argument from the end of the list, which pairing the
+          # leading parameters with the arguments in order would miss; one that does not is declined too,
+          # conservatively.
+          def arguments_at_variable(method_type, name, args, call_node)
+            return nil unless plain_positional_arguments?(call_node, args.size)
+
+            fun = method_type.type
+            return nil unless fun.respond_to?(:trailing_positionals) && fun.trailing_positionals.empty?
+            return nil if named_outside_positionals?(fun, name)
+
+            positionals = fun.required_positionals + fun.optional_positionals
+            positionals.zip(args).each_with_object([]) do |(param, arg), reaching|
+              type = param.type
+              next unless mentions_variable?(type, name)
+              return nil unless type.is_a?(RBS::Types::Variable)
+
+              reaching << arg unless arg.nil?
+            end
+          end
+
+          def plain_positional_arguments?(call_node, count)
+            return false unless call_node.is_a?(Prism::CallNode)
+
+            arguments = call_node.arguments&.arguments || EMPTY_ARGUMENT_NODES
+            arguments.size == count && arguments.none? do |argument|
+              case argument
+              when Prism::SplatNode, Prism::ForwardingArgumentsNode, Prism::KeywordHashNode then true
+              else false
+              end
+            end
+          end
+
+          def named_outside_positionals?(fun, name)
+            others = [fun.rest_positionals, fun.rest_keywords].compact +
+                     fun.required_keywords.values + fun.optional_keywords.values
+            others.any? { |param| mentions_variable?(param.type, name) }
+          end
+
+          # The class names `type`'s union members widen to, or nil when a member widens to none of
+          # {CLOSED_VALUE_CLASSES}.
+          def value_classes(type)
+            members = type.is_a?(Type::Union) ? type.members : [type]
+            classes = members.map { |member| value_class(member) }
+            classes.all? ? classes : nil
+          end
+
+          # A literal widens to its value's class, a bounded number to `Integer` or `Float`, and a refinement
+          # or a difference to its base's class. Everything else declines: a generic class (`[] + [:a]`
+          # concatenates elements rather than keeping either side's), a carrier with no class (a tuple, a
+          # hash shape, `Dynamic`), and `nil` or `NilClass`, whose arm would fire
+          # `call.possible-nil-receiver` where `Array#max` and `#first` bet on a non-empty receiver.
+          def value_class(type)
+            case type
+            when Type::Nominal then closed_value_class(type.class_name)
+            when Type::Constant then closed_value_class(type.value.class.name)
+            when Type::IntegerRange then "Integer"
+            when Type::FloatRange then "Float"
+            when Type::Refined, Type::Difference then value_class(type.base)
+            end
+          end
+
+          def closed_value_class(class_name)
+            name = class_name&.delete_prefix("::")
+            CLOSED_VALUE_CLASSES.include?(name) ? name : nil
+          end
+
+          # A signature nested past {RETURN_TYPE_UNWRAP_DEPTH} counts as naming the variable, which is the
+          # untyped answer.
+          def mentions_variable?(type, name, depth = 0)
+            return true if depth > RETURN_TYPE_UNWRAP_DEPTH
+            return type.name == name if type.is_a?(::RBS::Types::Variable)
+            return false unless type.respond_to?(:each_type)
+
+            type.each_type.any? { |child| mentions_variable?(child, name, depth + 1) }
           end
 
           # Issue #303 — bind method-level type parameters from ARGUMENT positions, layering on top of the
@@ -607,10 +1415,25 @@ module Rigor
               name, bound = param_binding(param, arg, declared, type_vars)
               next if name.nil?
 
+              bound = Type::Combinator.widen_value_pinned(bound) if upper_bounded?(method_type, name)
               bindings[name] = bindings.key?(name) ? Type::Combinator.union(bindings[name], bound) : bound
             end
           end
 
+          # Issue #1347 — a variable that declares an upper bound (`[T < X]`) binds the argument widened off its
+          # value-pinned members. The bound constrains a class, and `Rational#*: [T < Numeric](T) -> T` returns a
+          # value of the argument's class, not the argument, so `r * 0.5` read the literal `0.5`. An unbounded
+          # variable keeps the literal (`Ractor.make_shareable("x")` is `"x"`); a bounded identity return
+          # (`String#setbyte`) gives its literal up. Any bound counts: `upper_bound` answers only a class, singleton
+          # or interface bound, so an alias, union, intersection or optional bound is read through
+          # `upper_bound_type` where the rbs version has it.
+          def upper_bounded?(method_type, name)
+            method_type.type_params.any? do |type_param|
+              type_param.name == name &&
+                (type_param.respond_to?(:upper_bound_type) ? type_param.upper_bound_type : type_param.upper_bound)
+            end
+          end
+
           # The `(variable name, bound type)` a positional parameter contributes, or {NO_BINDING} when it
           # contributes none. The bare-variable shape is tried first because it is the overwhelmingly
           # common one; the `Range[A]` shape is reached only when the parameter is not a bare variable.
@@ -759,11 +1582,11 @@ module Rigor
 
           # ----- block parameter probe (Phase C sub-phase 1) -----
 
-          def probe_block_param_types(receiver:, method_name:, args:, environment:)
+          def probe_block_param_types(receiver:, method_name:, args:, environment:, scope: nil)
             args ||= []
             case receiver
-            when Type::Union then probe_block_param_types_union(receiver, method_name, args, environment)
-            else                  probe_block_param_types_one(receiver, method_name, args, environment)
+            when Type::Union then probe_block_param_types_union(receiver, method_name, args, environment, scope)
+            else                  probe_block_param_types_one(receiver, method_name, args, environment, scope)
             end
           end
 
@@ -771,9 +1594,9 @@ module Rigor
           # member resolves the same arity and types (otherwise the call sites would have to thread
           # per-member binders, which the slice does not support yet). Mismatches degrade to the empty
           # array so the binder defaults all params to Dynamic[Top].
-          def probe_block_param_types_union(receiver, method_name, args, environment)
+          def probe_block_param_types_union(receiver, method_name, args, environment, scope)
             results = receiver.members.map do |member|
-              probe_block_param_types_one(member, method_name, args, environment)
+              probe_block_param_types_one(member, method_name, args, environment, scope)
             end
             return [] if results.empty?
             return [] unless results.all? { |r| r == results.first }
@@ -781,12 +1604,12 @@ module Rigor
             results.first
           end
 
-          def probe_block_param_types_one(receiver, method_name, args, environment)
+          def probe_block_param_types_one(receiver, method_name, args, environment, scope)
             descriptor = receiver_descriptor(receiver)
             return [] unless descriptor
 
             class_name, kind, receiver_args = descriptor
-            method_definition = lookup_method(environment, class_name, kind, method_name)
+            method_definition = lookup_method(environment, class_name, kind, method_name, scope)
             return [] unless method_definition
 
             type_vars = build_type_vars(environment, class_name, receiver_args)
@@ -796,14 +1619,20 @@ module Rigor
               kind: kind,
               args: args,
               type_vars: type_vars,
-              environment: environment
+              environment: environment,
+              receiver: receiver,
+              receiver_args: receiver_args,
+              method_name: method_name
             )
           rescue StandardError
             []
           end
 
+          # rubocop:disable Metrics/ParameterLists
           def extract_block_param_types(method_definition, class_name:, kind:, args:, type_vars:,
-                                        environment: nil)
+                                        environment: nil, receiver: nil, receiver_args: [],
+                                        method_name: nil)
+            # rubocop:enable Metrics/ParameterLists
             instance_type = Type::Combinator.nominal_of(class_name)
             self_type =
               case kind
@@ -811,10 +1640,24 @@ module Rigor
               else                 instance_type
               end
 
+            # Issue #1130 — a block parameter that receives `self` (`Object#tap` yields it) must see the
+            # receiver's type arguments through the SAME {SelfSubstitute} verdict the return path applies
+            # (#1092), so `ints.tap { |a| }` binds `a` to `Array[Integer]` rather than the raw `Array`.
+            # The block path reuses only the keep-vs-degrade verdict, NOT the return path's value-pin
+            # widening: the block parameter is a destructure source, so the receiver's OWN type arguments
+            # (pinned constants included — `[1, 2].tap { |a, b| }` auto-splats the element union
+            # `1 | 2` per slot, the parity an explicit `a, b = [1, 2]` gets) are the substitution the
+            # binder should see. A verdict decline (an element-changing mutator like `map!`) keeps the
+            # raw nominal, so that receiver's block parameter still arrives without its type arguments.
+            substitute = SelfSubstitute.for(receiver, receiver_args, method_name, args, nil)
+            self_type = Type::Combinator.nominal_of(class_name, type_args: receiver_args) if substitute
+
             method_type = OverloadSelector.select(
               method_definition,
               arg_types: args,
-              self_type: self_type,
+              # Overload selection reads a `Dynamic` self's static facet, mirroring the return path;
+              # the substitution verdict here is built from the receiver's type arguments alone.
+              self_type: self_type.is_a?(Type::Dynamic) ? self_type.static_facet : self_type,
               instance_type: instance_type,
               type_vars: type_vars,
               block_required: true,