rigortype 0.4.7 → 0.4.8

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

@@ -9,9 +9,11 @@ require_relative "../external_ancestor_resolution"
 require_relative "../void_origin"
 require_relative "../optimistic_origin"
 require_relative "argument_distribution"
+require_relative "interface_shape"
+require_relative "class_keyed_block_params"
 require_relative "overload_selector"
 require_relative "self_substitute"
-require_relative "../../run_scoped_slots"
+require_relative "../../typing_state"
 
 module Rigor
   module Inference
@@ -51,9 +53,9 @@ module Rigor
       # * Method-level type parameters bind from the block return type (Slice 6 phase C) and from 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]`), plus a `Range[A]` element (#834). A variable reachable only through other
-      #   container positions (`Array[T] arg`), a rest positional (`*T`), or a keyword parameter is still
-      #   unbound and degrades to `Dynamic[Top]`.
+      #   such as `-> Array[T]`), plus a `Range[A]` element (#834) and a `singleton(T)` class object (#2828).
+      #   A variable reachable only through other container positions (`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}).
@@ -72,6 +74,23 @@ module Rigor
         # objects answer to methods their RBS omits (`ActionController::Base`, `Hash`, …).
         ALLOWED_RBS_COMPLETE_ANCESTORS = ["Rigor::Plugin::Base"].freeze
 
+        # #2681 — the owners whose members every class answers to. A name only they declare is not part of an
+        # allow-listed ancestor's contract, so a `def` of it never walks for the declaration it overrides.
+        OBJECT_SURFACE_OWNERS = %w[BasicObject Object Kernel Module Class].freeze
+
+        # Per-thread memo, keyed by environment: the Set of the names an allow-listed ancestor's RBS declarations
+        # declare outside {OBJECT_SURFACE_OWNERS}. It keeps {.def_declaration} off the ancestor walk for any other
+        # `def`.
+        #
+        # ADR-129 WD1 — a run-scoped Memo: the names are a pure function of the environment the entry is keyed on.
+        RBS_COMPLETE_MEMBER_NAMES = TypingState.memo(
+          :rbs_complete_member_names,
+          run_scoped: true, audit: "rbs complete member names",
+          reason: "a WeakKeyMap keyed on the environment; the names are read from its loader " \
+                  "and plugin registry alone"
+        )
+        private_constant :RBS_COMPLETE_MEMBER_NAMES
+
         # 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`
@@ -219,6 +238,17 @@ module Rigor
           )
         end
 
+        # ADR-130 WD5 — interface dispatch switched off. Inside the block a `Rigor::Plugin` interface value keeps its
+        # carrier, but no call on it resolves through the interface's members: the receiver names no class, as
+        # `Dynamic[top]` names none. `rigor sig-gen` analyses here, so it writes no RBS from an interface a plugin
+        # author did not write against, and the behavioural parity gate's `:dispatch_off` mode runs here
+        # (`spec/integration/interface_parity_spec.rb`). The switch is a per-thread `TypingState` frame
+        # ({InterfaceShape.without_dispatch}), so a run under it is sequential: a pooled run raises (`PoolCoordinator`).
+        # No CLI flag or configuration key sets it.
+        def without_interface_dispatch(&) = InterfaceShape.without_dispatch(&)
+
+        def interface_dispatch? = InterfaceShape.dispatch?
+
         # Slice 6 (Phase C sub-phase 1) probe: returns the positional block-parameter types declared by
         # the receiving method's selected RBS overload, translated into `Rigor::Type`. Used by the
         # StatementEvaluator to bind block parameter names before evaluating the block body.
@@ -251,10 +281,89 @@ module Rigor
           )
         end
 
+        # The RBS declaration a `def method_name` on `class_name` (`kind` side) binds its parameters from
+        # (`MethodParameterBinder`): the class's own, or nil.
+        #
+        # #2681 — when `class_name` is a Ruby-source class with no RBS, the declaration the `def` overrides on an
+        # ADR-43 allow-listed ancestor, as an empty RBS declaration of the class would inherit it. Nil whenever the
+        # call bridge would decline for a reason other than `class_name`'s own definition (no scope, no allow-listed
+        # ancestor, a nearer definer between them), and for a declaration one of {OBJECT_SURFACE_OWNERS} makes:
+        # `Kernel#load` is every class's, not that ancestor's contract. `initialize` is never bridged: a constructor
+        # does not override its superclass's contract, and a subclass routinely takes different arguments.
+        def def_declaration(environment, class_name, kind, method_name, scope)
+          direct = lookup_method_on(environment, class_name, kind, method_name)
+          return direct if direct
+          return nil if environment.nil? || scope.nil? || method_name == :initialize
+          return nil unless rbs_complete_member_name?(environment, method_name)
+
+          ancestor = allowed_rbs_complete_ancestor(environment, class_name, kind, method_name, scope,
+                                                   overriding: true)
+          overridden = ancestor && lookup_method_on(environment, ancestor, kind, method_name)
+          overridden unless overridden.nil? || object_surface?(overridden)
+        end
+
+        def object_surface?(method_definition)
+          OBJECT_SURFACE_OWNERS.include?(method_definition.defined_in.to_s.delete_prefix("::"))
+        end
+
+        # A class object carries no type arguments, so a singleton declaration binds none from the receiver.
+        NO_RECEIVER_TYPE_VARS = {}.freeze
+        private_constant :NO_RECEIVER_TYPE_VARS
+
+        # Issue #2884 — the return of a call on `Singleton[class_name]` through `method_definition`, a singleton
+        # declaration {DeclaredConstructor} found on `class_name` or an ancestor, so `instance` and `self` read
+        # `class_name` whichever class wrote it. Nil when the declaration states no return
+        # (`%a{rigor:v1:inferred-return}`).
+        def declared_singleton_return(context, method_definition, class_name)
+          return nil if RbsExtended.inferred_return?(method_definition)
+
+          translate_return_type(
+            method_definition,
+            class_name: class_name, kind: :singleton, method_name: context.method_name, args: context.args || [],
+            type_vars: NO_RECEIVER_TYPE_VARS, block_type: context.block_type, environment: context.environment,
+            scope: context.scope, call_node: context.call_node
+          )
+        end
+
         # rubocop:disable-next Metrics/ClassLength
         class << self
           private
 
+          # Whether some allow-listed ancestor's RBS declarations declare `method_name` outside
+          # {OBJECT_SURFACE_OWNERS}: the one-probe gate that leaves a `def` no ancestor declares, the common case
+          # in a project with no plugin class, on the cost it had before #2681. Read from the declarations, so a
+          # gem signature that fails to build reports nothing more than it did.
+          def rbs_complete_member_name?(environment, method_name)
+            rbs_complete_member_names(environment).include?(method_name)
+          end
+
+          def rbs_complete_member_names(environment)
+            return collect_rbs_complete_member_names(environment) if MemoAudit.enabled? && MemoAudit.suspended?
+
+            table = TypingState.current.weak_key_map(RBS_COMPLETE_MEMBER_NAMES)
+            names = table[environment]
+            if names.nil?
+              return table[environment] = MemoAudit.key_audit("rbs complete member names") do
+                collect_rbs_complete_member_names(environment)
+              end
+            end
+
+            MemoAudit.check("rbs complete member names", names, :environment) do
+              collect_rbs_complete_member_names(environment)
+            end
+          end
+
+          def collect_rbs_complete_member_names(environment)
+            loader = environment.rbs_loader
+            # An RBS-blind environment declares nothing, so no override takes an ancestor's parameters.
+            return Set.new.freeze if loader.nil?
+
+            ancestors = ALLOWED_RBS_COMPLETE_ANCESTORS + (environment.plugin_registry&.rbs_complete_ancestors || [])
+            ancestors.each_with_object(Set.new) do |ancestor, names|
+              names.merge(loader.declared_method_names(ancestor, skip: OBJECT_SURFACE_OWNERS))
+            end.freeze
+          end
+
           def dispatch_for(receiver:, method_name:, args:, environment:, block_type:, self_type_override: nil, # rubocop:disable Metrics/ParameterLists
                            public_only: false, scope: nil, call_node: nil)
             args ||= []
@@ -284,14 +393,17 @@ module Rigor
             # Issue #1794 — a sequence's inherited Enumerable surface reads its Rigor-private element argument, with
             # `self` still the sequence.
             element = ArithmeticSequenceElements.element_receiver(receiver, method_name, environment)
-            self_type_override ||= receiver if element
+            self_type_override = sequence_self(element, receiver, self_type_override)
             receiver = element || receiver
             descriptor = receiver_descriptor(receiver)
             return nil unless descriptor
 
             class_name, kind, receiver_args = descriptor
-            method_definition = lookup_method(environment, class_name, kind, method_name, scope,
-                                              call_node: call_node)
+            if kind == :interface
+              return dispatch_interface(receiver, class_name, receiver_args, method_name, args, environment, block_type,
+                                        scope: scope, call_node: call_node)
+            end
+            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
@@ -307,17 +419,11 @@ module Rigor
             type_vars = build_type_vars(environment, class_name, receiver_args)
             translate_return_type(
               method_definition,
-              class_name: class_name,
-              kind: kind,
-              method_name: method_name,
-              args: args,
-              type_vars: type_vars,
-              block_type: block_type,
-              environment: environment,
+              class_name: class_name, kind: kind, method_name: method_name, args: args, type_vars: type_vars,
+              block_type: block_type, environment: environment,
               self_type_override: self_type_override ||
                                   SelfSubstitute.for(receiver, receiver_args, method_name, args, block_type),
-              scope: scope,
-              call_node: call_node
+              scope: scope, call_node: call_node
             )
           rescue StandardError
             # Defensive: if RBS' definition builder raises on a broken hierarchy (e.g., partially loaded
@@ -325,6 +431,55 @@ module Rigor
             nil
           end
 
+          # The `self` a call on a sequence's element keeps: the sequence (#1794), unless the caller already set one.
+          # A method rather than a two-value return, which would allocate an Array on every dispatch.
+          def sequence_self(element, receiver, self_type_override)
+            element ? (self_type_override || receiver) : self_type_override
+          end
+
+          # ADR-130 WD3 — a call on a `Rigor::Plugin` interface value (`Dynamic[Interface]`). A member the interface
+          # does not declare declines, so the call falls through the later tiers as one on `Dynamic[top]` does:
+          # the value's class is wider than the interface, and reporting such a call is #2686's opt-in rule. A
+          # declared member answers through the overloads that take the call's shape ({InterfaceShape}), with
+          # `self` the receiver and `instance` untyped. A block-pass that may be nil may run the call block-less, so
+          # it answers only when both shapes are taken and their returns agree.
+          # rubocop:disable-next Metrics/ParameterLists
+          def dispatch_interface(receiver, name, receiver_args, method_name, args, environment, block_type, scope:,
+                                 call_node:)
+            definition = interface_method(environment, name, method_name)
+            return nil if definition.nil?
+
+            type_vars = interface_type_vars(environment, name, receiver_args)
+            shape = lambda do |shape_block|
+              accepted = InterfaceShape.accepting(definition, args, block: !shape_block.nil?, call_node: call_node)
+              accepted && translate_return_type(
+                accepted, class_name: name, kind: :interface, method_name: method_name, args: args,
+                          type_vars: type_vars, block_type: shape_block, environment: environment,
+                          self_type_override: receiver, scope: scope, call_node: call_node
+              )
+            end
+            return shape.call(block_type) unless InterfaceShape.nilable_block_pass?(call_node, scope)
+
+            block_less = shape.call(nil)
+            block_less if block_less && block_less == shape.call(block_type || Type::Combinator.untyped)
+          end
+
+          # The interface's declaration of `method_name`, or nil when it declares none.
+          def interface_method(environment, name, method_name)
+            environment.rbs_loader.interface_definition(name)&.methods&.[](method_name.to_sym)
+          end
+
+          # The interface's own type parameters bound to the value's type arguments, as {#build_type_vars} binds a
+          # class's: a parameter left unbound (a defaulted one) reads `Dynamic[top]`.
+          def interface_type_vars(environment, name, receiver_args)
+            return NO_TYPE_VARS if receiver_args.empty?
+
+            param_names = environment.rbs_loader.interface_definition(name)&.type_params || []
+            return NO_TYPE_VARS if param_names.empty? || receiver_args.size > param_names.size
+
+            param_names.first(receiver_args.size).zip(receiver_args).to_h
+          end
+
           # Issue #661 — `Kernel#<=>: (untyped other) -> 0?` is the IDENTITY comparison: `0` when the two
           # are the same object, `nil` otherwise, and correct as written for a bare `Object`. Reached by
           # inheritance it stops being a statement about the call. `1.day <=> 2.days` typed as `0?`, and a
@@ -408,10 +563,18 @@ module Rigor
               # (ConstantFolding, ShapeDispatch#dispatch_integer_range) do not own.
               ["Integer", :instance, []]
             when Type::Dynamic
-              receiver_descriptor(receiver.static_facet)
+              facet_descriptor(receiver.static_facet)
             end
           end
 
+          # A `Dynamic`'s facet names what the facet names, and a `Rigor::Plugin` interface facet names the interface
+          # (ADR-130 WD3), unless dispatch is switched off, where it names nothing, as `top` does.
+          def facet_descriptor(facet)
+            return receiver_descriptor(facet) unless facet.is_a?(Type::Interface)
+
+            [facet.name, :interface, facet.type_args] if interface_dispatch?
+          end
+
           # ADR-48 — project a `Data`/`Struct` member carrier to its tagging class (or the `Data`/`Struct`
           # supertype) so non-member calls (`inspect`, `==`, `frozen?`, ...) resolve through RBS rather
           # than mis-firing undefined-method. Precise member reads were already folded by DataFolding /
@@ -515,7 +678,10 @@ module Rigor
           # 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)
+          #
+          # #2681 — `overriding: true` asks for the declaration a `def` on `class_name` overrides (its parameter
+          # binding), so `class_name`'s own definition of the name is set aside; every nearer ancestor still shadows.
+          def allowed_rbs_complete_ancestor(environment, class_name, kind, method_name, scope, overriding: false)
             return nil if scope.nil?
             return nil if Rigor::Reflection.rbs_class_known?(class_name, environment: environment)
 
@@ -524,15 +690,22 @@ module Rigor
             # 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)
+            return nil if !overriding && 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)
-              next unless ALLOWED_RBS_COMPLETE_ANCESTORS.include?(candidate) ||
-                          registry&.rbs_complete_ancestor?(candidate)
-
-              return shadowed_in_ruby_order?(scope, class_name, kind, method_name, candidate) ? nil : candidate
+              # #2681 — the engine seed's own source (`lib/rigor/plugin/base.rb`, which this repository's plugin
+              # check discovers) is the implementation its RBS describes, not a nearer definer. A project `def` on
+              # a manifest-declared ancestor is a reopen (`class Grape::API; def self.desc`), which Ruby calls
+              # instead of the declaration, so it still shadows.
+              seed = ALLOWED_RBS_COMPLETE_ANCESTORS.include?(candidate)
+              return nil if !seed && scope.discovered_method?(candidate, method_name, kind)
+              next unless seed || registry&.rbs_complete_ancestor?(candidate)
+
+              return nil if shadowed_in_ruby_order?(scope, class_name, kind, method_name, candidate,
+                                                    overriding: overriding)
+
+              return candidate
             end
             nil
           end
@@ -546,7 +719,8 @@ module Rigor
           # passed over, as the breadth-first walk always did. An unsettled chain withholds too: a mixin edge the
           # tables cannot place (a receiver-form `Demo.include(M)` after the body, an edge in a conditional, a block or
           # a hook) may put a definer ahead of the ancestor.
-          def shadowed_in_ruby_order?(scope, class_name, kind, method_name, ancestor)
+          # With `overriding`, `class_name`'s own entry is the overriding `def` itself and does not shadow.
+          def shadowed_in_ruby_order?(scope, class_name, kind, method_name, ancestor, overriding: false)
             chain = Scope::ResolutionChain.for(scope, class_name.to_s, kind, :methods)
             return true if chain.unsettled?
 
@@ -557,6 +731,8 @@ module Rigor
             return true if stop.nil?
 
             entries.first(stop).any? do |entry|
+              next false if overriding && !entry.external? && entry.name == class_name.to_s
+
               if entry.external?
                 rbs_declares_ahead?(scope, entry, method_name)
               else
@@ -619,12 +795,22 @@ module Rigor
             return nil if scope.nil? || kind != :instance
             return nil if environment.nil?
 
+            if MemoAudit.enabled? && MemoAudit.suspended?
+              return compute_core_stdlib_ancestor_method(environment, class_name, method_name, scope)
+            end
+
             memo = core_stdlib_memo(environment, scope)
             key = [class_name.to_s, method_name.to_sym]
-            return memo[key] if memo.key?(key)
+            if memo.key?(key)
+              return MemoAudit.check("core stdlib ancestor dispatch", memo[key], key[0], key[1]) do
+                compute_core_stdlib_ancestor_method(environment, class_name, method_name, scope)
+              end
+            end
 
             store_unless_recorded(memo, key) do
-              compute_core_stdlib_ancestor_method(environment, class_name, method_name, scope)
+              MemoAudit.key_audit("core stdlib ancestor dispatch") do
+                compute_core_stdlib_ancestor_method(environment, class_name, method_name, scope)
+              end
             end
           end
 
@@ -651,12 +837,23 @@ module Rigor
             return nil if scope.nil? || kind != :instance
             return nil if environment.nil?
 
+            if MemoAudit.enabled? && MemoAudit.suspended?
+              return compute_included_module_method(environment, class_name, method_name,
+                                                    scope)
+            end
+
             memo = mixin_ancestor_memo(environment, scope)
             key = [class_name.to_s, method_name.to_sym]
-            return memo[key] if memo.key?(key)
+            if memo.key?(key)
+              return MemoAudit.check("mixin ancestor dispatch", memo[key], key[0], key[1]) do
+                compute_included_module_method(environment, class_name, method_name, scope)
+              end
+            end
 
             store_unless_recorded(memo, key) do
-              compute_included_module_method(environment, class_name, method_name, scope)
+              MemoAudit.key_audit("mixin ancestor dispatch") do
+                compute_included_module_method(environment, class_name, method_name, scope)
+              end
             end
           end
 
@@ -684,11 +881,18 @@ module Rigor
 
           # 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 what a recording run may store in it.
-          MIXIN_ANCESTOR_MEMO_KEY = RunScopedSlots.register(:__rigor_mixin_ancestor_dispatch__)
-          private_constant :MIXIN_ANCESTOR_MEMO_KEY
+          #
+          # ADR-129 WD1 — a run-scoped Memo, keyed as {#ancestor_memo_slot} says.
+          MIXIN_ANCESTOR_MEMO = TypingState.memo(
+            :mixin_ancestor_dispatch,
+            run_scoped: true, audit: "mixin ancestor dispatch",
+            reason: "one slot keyed on the identities of the discovery index and environment, and " \
+                    "on whether the thread is recording; the answers read nothing else"
+          )
+          private_constant :MIXIN_ANCESTOR_MEMO
 
           def mixin_ancestor_memo(environment, scope)
-            ancestor_memo_slot(MIXIN_ANCESTOR_MEMO_KEY, environment, scope)
+            ancestor_memo_slot(MIXIN_ANCESTOR_MEMO, environment, scope)
           end
 
           # The declines are conjunctive, so their ORDER is free — and it is chosen so the two that walk
@@ -858,23 +1062,31 @@ module Rigor
           # 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 = RunScopedSlots.register(:__rigor_core_stdlib_ancestor_dispatch__)
-          private_constant :CORE_STDLIB_ANCESTOR_MEMO_KEY
+          #
+          # ADR-129 WD1 — a run-scoped Memo, keyed as {#ancestor_memo_slot} says.
+          CORE_STDLIB_ANCESTOR_MEMO = TypingState.memo(
+            :core_stdlib_ancestor_dispatch,
+            run_scoped: true, audit: "core stdlib ancestor dispatch",
+            reason: "one slot keyed on the identities of the discovery index and environment, and " \
+                    "on whether the thread is recording; the answers read nothing else"
+          )
+          private_constant :CORE_STDLIB_ANCESTOR_MEMO
 
           def core_stdlib_memo(environment, scope)
-            ancestor_memo_slot(CORE_STDLIB_ANCESTOR_MEMO_KEY, environment, scope)
+            ancestor_memo_slot(CORE_STDLIB_ANCESTOR_MEMO, environment, scope)
           end
 
           # The slot behind both memos. Whether this thread is recording is part of its key, so a slot
           # filled with every answer is never read by a recording caller, which may only reuse the
           # answers {#store_unless_recorded} lets through.
-          def ancestor_memo_slot(memo_key, environment, scope)
+          def ancestor_memo_slot(memo_slot, environment, scope)
             discovery = scope.discovery
             recording = Rigor::Analysis::DependencyRecorder.recording?
-            slot = Thread.current[memo_key]
+            state = TypingState.current
+            slot = state[memo_slot]
             unless slot && slot[0].equal?(discovery) && slot[1].equal?(environment) && slot[2] == recording
               slot = [discovery, environment, recording, {}]
-              Thread.current[memo_key] = slot
+              state[memo_slot] = slot
             end
             slot[3]
           end
@@ -1684,7 +1896,8 @@ module Rigor
           #
           # * only a positional parameter (required or optional) whose declared type is EXACTLY
           #   `RBS::Types::Variable`, plus the one container shape issue #834 admits (see
-          #   {#range_element_binding}) — no general container walk, so `(Array[T]) -> T` still degrades;
+          #   {#range_element_binding}) and the class-object shape issue #2828 admits ({#singleton_param_binding}) —
+          #   no general container walk, so `(Array[T]) -> T` still degrades;
           # * only names the SELECTED overload declares in its own `type_params` (a class-level variable
           #   keeps its receiver-derived binding);
           # * an existing key wins, so the receiver and the block return type both outrank an argument;
@@ -1693,7 +1906,7 @@ module Rigor
           #
           # See {#arg_binding_permitted?} for why the contribution is gated on the call site.
           def compose_arg_type_vars(method_type, type_vars, args, scope:, call_node:, call_site:)
-            bindings = arg_type_var_bindings(method_type, type_vars, args)
+            bindings = arg_type_var_bindings(method_type, type_vars, args, scope&.environment, call_node)
             return type_vars if bindings.empty?
             return type_vars unless arg_binding_permitted?(scope, call_node, call_site)
 
@@ -1702,7 +1915,7 @@ module Rigor
 
           # The candidate bindings, computed before the guard so a non-generic overload (the overwhelming
           # majority) never pays for the `scope` probes.
-          def arg_type_var_bindings(method_type, type_vars, args)
+          def arg_type_var_bindings(method_type, type_vars, args, environment = nil, call_node = nil)
             declared = declared_type_param_names(method_type)
             return EMPTY_TYPE_VARS if declared.empty? || args.empty?
 
@@ -1714,6 +1927,11 @@ module Rigor
               next if arg.nil?
 
               name, bound = param_binding(param, arg, declared, type_vars)
+              if name.nil?
+                name, bound = singleton_param_binding(method_type, param, arg, declared, type_vars,
+                                                      environment)
+                next if name && class_factory_argument?(call_node)
+              end
               next if name.nil?
 
               bound = Type::Combinator.widen_value_pinned(bound) if upper_bounded?(method_type, name)
@@ -1749,6 +1967,80 @@ module Rigor
             range_element_binding(param, arg, declared, type_vars)
           end
 
+          # Issue #2828 — a positional parameter spelled `singleton(T)` for a method-level variable `T` binds `T`
+          # to the instance type of the class object the call passes: `Resolv::DNS#getresources: [T < Resource]
+          # (dns_name, singleton(T)) -> Array[T]` answers `Array[Resolv::DNS::Resource::IN::MX]` for an
+          # `IN::MX` argument. A union of class objects binds the union of their instances, as a bare `T` binds
+          # its argument union. Every other argument — `Dynamic`, an instance, a union with a non-class member —
+          # binds nothing, and neither does a class the declared upper bound does not provably admit: an
+          # interface, alias or other non-class bound, or a class the environment cannot order below the bound.
+          def singleton_param_binding(method_type, param, arg, declared, type_vars, environment)
+            name = singleton_variable_name(param, declared, type_vars)
+            return NO_BINDING if name.nil?
+
+            members = arg.is_a?(Type::Union) ? arg.members : [arg]
+            return NO_BINDING unless members.all?(Type::Singleton)
+
+            within = members.all? { |member| within_upper_bound?(method_type, name, member, environment) }
+            return NO_BINDING unless within
+
+            instances = members.map { |member| Type::Combinator.nominal_of(member.class_name) }
+            [name, instances.size == 1 ? instances.first : Type::Combinator.union(*instances)]
+          end
+
+          # RBS parses `singleton(T)` as a class singleton whose type name is the bare, unqualified `T`; the
+          # parameter names a variable when that name is one the overload declares and has not yet bound.
+          def singleton_variable_name(param, declared, type_vars)
+            declared_type = param.type
+            return nil unless declared_type.is_a?(RBS::Types::ClassSingleton)
+
+            type_name = declared_type.name
+            return nil unless type_name.namespace.empty?
+
+            name = type_name.name
+            return nil unless declared.include?(name)
+            return nil if type_vars.key?(name)
+
+            name
+          end
+
+          # Whether the call passes, as any positional argument, a class built by `Class.new`, `Struct.new` or
+          # `Data.define` with a block. The engine types `Class.new(Widget) { def extra = 1 }` as `singleton(Widget)`,
+          # so binding `T` from it would read the instance as a plain `Widget` and report `extra` as undefined. The
+          # argument node is visible here; a local the class was assigned to is not, and still binds.
+          def class_factory_argument?(call_node)
+            arguments = call_node.respond_to?(:arguments) ? call_node.arguments&.arguments : nil
+            return false if arguments.nil?
+
+            arguments.any? { |argument| class_factory_call?(argument) }
+          end
+
+          CLASS_FACTORIES = { new: %w[Class Struct].freeze, define: %w[Data].freeze }.freeze
+          private_constant :CLASS_FACTORIES
+
+          def class_factory_call?(node)
+            return false unless node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode)
+
+            receivers = CLASS_FACTORIES[node.name]
+            return false if receivers.nil?
+
+            receiver = node.receiver
+            name = case receiver
+                   when Prism::ConstantReadNode then receiver.name.to_s
+                   when Prism::ConstantPathNode then receiver.parent.nil? ? receiver.name.to_s : nil
+                   end
+            receivers.include?(name)
+          end
+
+          def within_upper_bound?(method_type, name, singleton, environment)
+            type_param = method_type.type_params.find { |tp| tp.name == name }
+            bound = type_param.respond_to?(:upper_bound_type) ? type_param.upper_bound_type : type_param.upper_bound
+            return true if bound.nil?
+            return false unless bound.is_a?(RBS::Types::ClassInstance) && environment
+
+            %i[equal subclass].include?(environment.class_ordering(singleton.class_name, bound.name.to_s))
+          end
+
           def declared_type_param_names(method_type)
             params = method_type.respond_to?(:type_params) ? method_type.type_params : nil
             return EMPTY_TYPE_PARAM_NAMES if params.nil? || params.empty?
@@ -1824,7 +2116,7 @@ module Rigor
           # dress up an absence of evidence as an inference. The variable stays unbound and degrades as it
           # did before, which is the same value anyway.
           def no_static_evidence?(arg)
-            arg.is_a?(Type::Dynamic) && arg.static_facet.is_a?(Type::Top)
+            Type::Combinator.untyped?(arg)
           end
 
           # Issue #303 — the FP guard on the argument-position binding.
@@ -1949,13 +2241,11 @@ module Rigor
 
           def probe_block_param_types(receiver:, method_name:, args:, environment:, scope: nil, call_node: nil)
             args ||= []
-            keywords_last = ArgumentNodes.keyword_hash_last?(call_node, args)
-            splat = splat_indices(call_node, args)
             case receiver
             when Type::Union
-              probe_block_param_types_union(receiver, method_name, args, environment, scope, keywords_last, splat)
+              probe_block_param_types_union(receiver, method_name, args, environment, scope, call_node)
             else
-              probe_block_param_types_one(receiver, method_name, args, environment, scope, keywords_last, splat)
+              probe_block_param_types_one(receiver, method_name, args, environment, scope, call_node)
             end
           end
 
@@ -1963,9 +2253,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, scope, keywords_last, splat)
+          def probe_block_param_types_union(receiver, method_name, args, environment, scope, call_node)
             results = receiver.members.map do |member|
-              probe_block_param_types_one(member, method_name, args, environment, scope, keywords_last, splat)
+              probe_block_param_types_one(member, method_name, args, environment, scope, call_node)
             end
             return [] if results.empty?
             return [] unless results.all? { |r| r == results.first }
@@ -1973,44 +2263,52 @@ module Rigor
             results.first
           end
 
-          def probe_block_param_types_one(receiver, method_name, args, environment, scope, keywords_last, splat)
+          def probe_block_param_types_one(receiver, method_name, args, environment, scope, call_node)
             receiver = ArithmeticSequenceElements.element_receiver(receiver, method_name, environment, block: true) ||
                        receiver
             descriptor = receiver_descriptor(receiver)
             return [] unless descriptor
 
             class_name, kind, receiver_args = descriptor
-            method_definition = lookup_method(environment, class_name, kind, method_name, scope)
+            method_definition = probe_definition(environment, class_name, kind, method_name, args, scope, call_node)
             return [] unless method_definition
 
-            type_vars = build_type_vars(environment, class_name, receiver_args)
-            extract_block_param_types(
+            type_vars =
+              if kind == :interface
+                interface_type_vars(environment, class_name, receiver_args)
+              else
+                build_type_vars(environment, class_name, receiver_args)
+              end
+            params = extract_block_param_types(
               method_definition,
-              class_name: class_name,
-              kind: kind,
-              args: args,
-              type_vars: type_vars,
-              environment: environment,
-              receiver: receiver,
-              receiver_args: receiver_args,
-              method_name: method_name,
-              keywords_last: keywords_last, positional_splat: splat
+              class_name: class_name, kind: kind, args: args, type_vars: type_vars, environment: environment,
+              receiver: receiver, receiver_args: receiver_args, method_name: method_name,
+              keywords_last: ArgumentNodes.keyword_hash_last?(call_node, args),
+              positional_splat: splat_indices(call_node, args), scope: scope, call_node: call_node
             )
+            ClassKeyedBlockParams.rebind(method_definition, method_name, args, params)
           rescue StandardError
             []
           end
 
+          # The declaration the block-parameter probe reads. On an interface value a block literal binds its parameters
+          # through the overloads that take the call's shape, as the call's return does (ADR-130 WD3,
+          # {#dispatch_interface}).
+          def probe_definition(environment, class_name, kind, method_name, args, scope, call_node)
+            return lookup_method(environment, class_name, kind, method_name, scope) unless kind == :interface
+
+            declared = interface_method(environment, class_name, method_name)
+            declared && InterfaceShape.accepting(declared, args, block: true, call_node: call_node)
+          end
+
           # rubocop:disable Metrics/ParameterLists
           def extract_block_param_types(method_definition, class_name:, kind:, args:, type_vars:,
                                         environment: nil, receiver: nil, receiver_args: [],
-                                        method_name: nil, keywords_last: false, positional_splat: nil)
+                                        method_name: nil, keywords_last: false, positional_splat: nil,
+                                        scope: nil, call_node: nil)
             # rubocop:enable Metrics/ParameterLists
             instance_type = Type::Combinator.nominal_of(class_name)
-            self_type =
-              case kind
-              when :singleton then Type::Combinator.singleton_of(class_name)
-              else                 instance_type
-              end
+            self_type = block_self_type(kind, class_name, instance_type, receiver)
 
             # 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
@@ -2052,9 +2350,53 @@ module Rigor
             )
             return [] unless method_type
 
+            type_vars = compose_singleton_arg_type_vars(method_type, type_vars, args, environment,
+                                                        scope: scope, call_node: call_node,
+                                                        call_site: [class_name, method_name, kind])
             block_params_of(method_type, self_type, instance_type, type_vars, environment) || []
           end
 
+          # Issue #2828 — the block-parameter twin of {#compose_arg_type_vars}, for the `singleton(T)` shape alone
+          # ({#singleton_param_binding}): `Resolv::DNS#each_resource: [T < Resource] (dns_name, singleton(T))
+          # { (T) -> void } -> void` yields the typeclass's instances. A bare `T` parameter stays out of the block
+          # path: it binds the argument's own (possibly value-pinned) type, and `each_with_object([])`'s memo
+          # would read as the empty tuple the block then appends to.
+          def compose_singleton_arg_type_vars(method_type, type_vars, args, environment, scope:, call_node:, call_site:)
+            declared = declared_type_param_names(method_type)
+            return type_vars if declared.empty? || args.empty?
+
+            fun = method_type.type
+            return type_vars unless fun.respond_to?(:required_positionals)
+
+            bindings = singleton_bindings(method_type, fun, args, declared, type_vars, environment)
+            return type_vars if bindings.empty? || class_factory_argument?(call_node)
+            return type_vars unless arg_binding_permitted?(scope, call_node, call_site)
+
+            type_vars.merge(bindings)
+          end
+
+          def singleton_bindings(method_type, fun, args, declared, type_vars, environment)
+            positionals = fun.required_positionals + fun.optional_positionals
+            positionals.zip(args).each_with_object({}) do |(param, arg), bindings|
+              next if arg.nil?
+
+              name, bound = singleton_param_binding(method_type, param, arg, declared, type_vars, environment)
+              next if name.nil?
+
+              bindings[name] = bindings.key?(name) ? Type::Combinator.union(bindings[name], bound) : bound
+            end
+          end
+
+          # What RBS `self` reads in a block parameter of the member: the class's instance or singleton, and inside an
+          # interface member the receiver (ADR-130 WD1).
+          def block_self_type(kind, class_name, instance_type, receiver)
+            case kind
+            when :singleton then Type::Combinator.singleton_of(class_name)
+            when :interface then receiver
+            else instance_type
+            end
+          end
+
           # The block parameters every overload in `matches` declares alike, or no information (`[]`).
           def agreed_block_params(matches, self_type, instance_type, type_vars, environment)
             answers = matches.uniq.map do |method_type|