rigortype 0.1.5 → 0.1.6

data/lib/rigor/inference/hkt_reducer.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require_relative "hkt_body"
+
+module Rigor
+  module Inference
+    # ADR-20 Slice 2a — reducer that walks a `Definition`'s
+    # `body_tree` against a concrete `Type::App` and returns a
+    # fully-typed `Rigor::Type`.
+    #
+    # Reduction is the operational interpretation of ADR-20
+    # § D4 ("Evaluation rules"):
+    #
+    # 1. **Resolve `F`.** Look up the registered body via
+    #    `registry.definition(uri)`.
+    # 2. **Substitute arguments.** Walk the body tree, replacing
+    #    `{HktBody::Param}` nodes with the matching positional
+    #    arg from the application.
+    # 3. **Build types.** `{HktBody::TypeLeaf}` returns its
+    #    wrapped type as-is; `{HktBody::Union}` and
+    #    `{HktBody::NominalApp}` route their reduced children
+    #    through `Type::Combinator.union` / `.nominal_of` so
+    #    normalization applies.
+    # 4. **Recurse on `{HktBody::AppRef}` nodes.** Reduce the
+    #    args first; if the resulting `(uri, args)` matches an
+    #    App already on the current reduction stack, return the
+    #    in-progress `Type::App` carrier as-is (lazy
+    #    self-reference handling — the standard "tying the
+    #    knot" trick for recursive type aliases like
+    #    `json::value`). Otherwise build a fresh
+    #    `Type::App` and recursively reduce it against the
+    #    same registry, sharing the fuel budget.
+    # 5. **Fuel budget.** Each visited node consumes one unit.
+    #    On exhaustion, reduction unwinds to `app.bound`.
+    #
+    # The reducer is **pure** with respect to its inputs (the
+    # registry + the App) but uses a per-call mutable state
+    # bag for fuel + cycle tracking. Concurrent reductions
+    # MUST allocate fresh reducers (or fresh `_reduce` calls)
+    # — the per-call state is not shared.
+    class HktReducer
+      DEFAULT_FUEL = 64
+
+      class FuelExhausted < StandardError; end
+
+      def initialize(registry)
+        raise ArgumentError, "registry must be an HktRegistry" unless registry.is_a?(HktRegistry)
+
+        @registry = registry
+      end
+
+      # Reduce `app` against the registry.
+      #
+      # @param app [Rigor::Type::App]
+      # @param fuel [Integer] reduction-step budget (default 64
+      #   per ADR-20 WD3). Each visited body node costs one
+      #   unit. On exhaustion the reduction returns `app.bound`.
+      # @return [Rigor::Type] the reduced type, or `app.bound`
+      #   when reduction is impossible (URI not defined, arity
+      #   mismatch, body_tree absent, fuel exhausted).
+      def reduce(app, fuel: DEFAULT_FUEL)
+        raise ArgumentError, "expected a Rigor::Type::App, got #{app.class}" unless app.is_a?(Type::App)
+
+        definition = @registry.definition(app.uri)
+        return app.bound if definition.nil? || definition.body_tree.nil?
+        return app.bound if definition.params.size != app.args.size
+
+        state = State.new(fuel: fuel)
+        begin
+          state.with_in_progress(app.uri, app.args, app) do
+            walk(definition.body_tree, bindings: bindings_for(definition, app.args), state: state) || app.bound
+          end
+        rescue FuelExhausted
+          app.bound
+        end
+      end
+
+      private
+
+      def bindings_for(definition, args)
+        definition.params.zip(args).to_h
+      end
+
+      def walk(node, bindings:, state:)
+        state.consume_fuel!
+
+        case node
+        when HktBody::TypeLeaf
+          node.type
+        when HktBody::Param
+          bindings.fetch(node.name) do
+            raise ArgumentError, "unknown param #{node.name.inspect}; declared: #{bindings.keys}"
+          end
+        when HktBody::Union
+          reduced = node.arms.map { |arm| walk(arm, bindings: bindings, state: state) }
+          Type::Combinator.union(*reduced)
+        when HktBody::NominalApp
+          reduced_args = node.args.map { |arg| walk(arg, bindings: bindings, state: state) }
+          Type::Combinator.nominal_of(node.class_name, type_args: reduced_args)
+        when HktBody::AppRef
+          reduced_args = node.args.map { |arg| walk(arg, bindings: bindings, state: state) }
+          reduce_app_ref(node.uri, reduced_args, state: state)
+        when HktBody::Conditional
+          walk_conditional(node, bindings: bindings, state: state)
+        else
+          raise ArgumentError, "unknown body node: #{node.class}"
+        end
+      end
+
+      # ADR-20 § D3 conditional reduction. Resolves the test
+      # against the current bindings and picks a branch:
+      #
+      # - test = `yes` → return the reduced `then_branch`.
+      # - test = `no`  → return the reduced `else_branch`.
+      # - test = `maybe` → widen to the union of both
+      #   reduced branches (per ADR-20 WD7).
+      def walk_conditional(node, bindings:, state:)
+        verdict = evaluate_test(node.test, bindings: bindings, state: state)
+        case verdict
+        when :yes
+          walk(node.then_branch, bindings: bindings, state: state)
+        when :no
+          walk(node.else_branch, bindings: bindings, state: state)
+        else
+          # `:maybe` — widen to the union of both branches.
+          then_t = walk(node.then_branch, bindings: bindings, state: state)
+          else_t = walk(node.else_branch, bindings: bindings, state: state)
+          Type::Combinator.union(then_t, else_t)
+        end
+      end
+
+      def evaluate_test(test, bindings:, state:)
+        case test
+        when HktBody::TestSubtype
+          left = walk(test.left, bindings: bindings, state: state)
+          right = walk(test.right, bindings: bindings, state: state)
+          subtype_verdict(left, right)
+        when HktBody::TestEquality
+          left = walk(test.left, bindings: bindings, state: state)
+          right = walk(test.right, bindings: bindings, state: state)
+          equality_verdict(left, right)
+        when HktBody::TestMembership
+          left = walk(test.left, bindings: bindings, state: state)
+          options = test.options.map { |o| walk(o, bindings: bindings, state: state) }
+          membership_verdict(left, options)
+        else
+          raise ArgumentError, "unknown test node: #{test.class}"
+        end
+      end
+
+      # `left <: right`. Slice 7a verdict policy: structural
+      # equality is `:yes`; clearly-disjoint nominal /
+      # constant pairs are `:no`; everything else is `:maybe`
+      # (widens to the union per ADR-20 WD7 — robustness
+      # principle keeps us conservative on undecided tests).
+      def subtype_verdict(left, right)
+        return :yes if left == right
+
+        # Both Nominals with different class names AND
+        # neither carries Dynamic — `:no` (statically
+        # disjoint). For any other shape pair, `:maybe`.
+        return :no if disjoint_nominals?(left, right)
+        return :no if disjoint_constants?(left, right)
+
+        :maybe
+      end
+
+      # Structural equality verdict — same shape as
+      # subtype_verdict but symmetric.
+      def equality_verdict(left, right)
+        return :yes if left == right
+        return :no if disjoint_nominals?(left, right)
+        return :no if disjoint_constants?(left, right)
+
+        :maybe
+      end
+
+      def membership_verdict(left, options)
+        verdicts = options.map { |o| equality_verdict(left, o) }
+        return :yes if verdicts.include?(:yes)
+        return :no if verdicts.all? { |v| v == :no }
+
+        :maybe
+      end
+
+      def disjoint_nominals?(left, right)
+        return false unless left.is_a?(Type::Nominal) && right.is_a?(Type::Nominal)
+
+        left.class_name != right.class_name
+      end
+
+      def disjoint_constants?(left, right)
+        return false unless left.is_a?(Type::Constant) && right.is_a?(Type::Constant)
+
+        left.value != right.value
+      end
+
+      def reduce_app_ref(uri, reduced_args, state:)
+        # Cycle detection — when the same `(uri, args)` is
+        # already on the reduction stack, return the
+        # in-progress App carrier as-is so recursive type
+        # aliases (`Array[App[json::value, K]]` inside the
+        # `json::value` body) terminate.
+        existing = state.in_progress_for(uri, reduced_args)
+        return existing if existing
+
+        registration = @registry.registration(uri)
+        bound = registration&.bound || Type::Combinator.untyped
+        new_app = Type::App.new(uri, reduced_args, bound: bound)
+
+        definition = @registry.definition(uri)
+        return new_app if definition.nil? || definition.body_tree.nil?
+        return new_app if definition.params.size != reduced_args.size
+
+        state.with_in_progress(uri, reduced_args, new_app) do
+          walk(definition.body_tree, bindings: bindings_for(definition, reduced_args), state: state) || new_app
+        end
+      end
+
+      # Per-call mutable bag carrying the remaining fuel
+      # budget and the active reduction stack (for cycle
+      # detection). Not shared across `reduce` calls.
+      class State
+        def initialize(fuel:)
+          @fuel = fuel
+          @in_progress = {}
+        end
+
+        def consume_fuel!
+          raise FuelExhausted if @fuel <= 0
+
+          @fuel -= 1
+        end
+
+        def in_progress_for(uri, args)
+          @in_progress[[uri, args]]
+        end
+
+        def with_in_progress(uri, args, app)
+          key = [uri, args]
+          previous = @in_progress[key]
+          @in_progress[key] = app
+          begin
+            yield
+          ensure
+            if previous.nil?
+              @in_progress.delete(key)
+            else
+              @in_progress[key] = previous
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/hkt_registry.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative "hkt_body"
+
+module Rigor
+  module Inference
+    # ADR-20 § "Decision D1 / D2" — registry of Lightweight HKT
+    # tag registrations + type-function bodies parsed off the
+    # `%a{rigor:v1:hkt_register: ...}` /
+    # `%a{rigor:v1:hkt_define: ...}` annotations in shipped
+    # `.rbs` files.
+    #
+    # Slice 1 keeps the registry **opaque**: it stores the
+    # registration metadata (arity, variance, bound) and the
+    # un-evaluated definition body (a raw String — Slice 2
+    # introduces the conditional / indexed-access evaluator that
+    # parses the body and reduces `Type::App` instances against
+    # it). The carrier never needs to read from the registry
+    # because Slice 1's `Type::App` carries its `bound` directly;
+    # the registry exists at this slice solely so the parser
+    # round-trip and downstream slices have a stable target API.
+    #
+    # The registry is immutable after construction. Callers that
+    # need to extend it (e.g. plugin registrations layered on top
+    # of stdlib registrations) MUST build a new registry via
+    # `merge` rather than mutating an existing one. This keeps the
+    # registry shareable across Ractor boundaries per ADR-15.
+    class HktRegistry
+      # Frozen value object recording one tag registration.
+      #
+      # - `uri`: namespaced Symbol per ADR-20 WD1 (must include
+      #   `"::"`).
+      # - `arity`: positive Integer — the number of formal
+      #   parameters the registered constructor takes.
+      # - `variance`: ordered Array of Symbols, one per
+      #   parameter, each `:out` (covariant), `:in`
+      #   (contravariant), or `:inv` (invariant; default).
+      # - `bound`: a `Rigor::Type` to erase to when an `App`
+      #   referring to this URI cannot be reduced. Defaults to
+      #   `Dynamic[Top]` (the parser fills in the default when
+      #   the annotation omits `bound:`).
+      Registration = Data.define(:uri, :arity, :variance, :bound) do
+        def initialize(uri:, arity:, variance:, bound:)
+          raise ArgumentError, "uri must be a Symbol, got #{uri.class}" unless uri.is_a?(Symbol)
+          raise ArgumentError, "uri must be namespaced as `:a::b`, got #{uri.inspect}" unless uri.to_s.include?("::")
+          unless arity.is_a?(Integer) && arity.positive?
+            raise ArgumentError,
+                  "arity must be a positive Integer, got #{arity.inspect}"
+          end
+          raise ArgumentError, "variance must be an Array, got #{variance.class}" unless variance.is_a?(Array)
+          raise ArgumentError, "variance must have #{arity} entries, got #{variance.size}" unless variance.size == arity
+
+          variance.each do |v|
+            unless %i[out in inv].include?(v)
+              raise ArgumentError, "variance entries must be :out, :in, or :inv, got #{v.inspect}"
+            end
+          end
+          raise ArgumentError, "bound must not be nil" if bound.nil?
+
+          super(uri: uri, arity: arity, variance: variance.dup.freeze, bound: bound)
+        end
+      end
+
+      # Frozen value object recording one type-function
+      # definition.
+      #
+      # `body` is the raw String payload from the `%a{...}`
+      # annotation (Slice 1's parser populates it). It stays
+      # opaque until Slice 2b's body-string parser lands.
+      #
+      # `body_tree` is the optional evaluable form: a
+      # `Rigor::Inference::HktBody::*` node tree the Slice 2a
+      # reducer walks against the application's concrete
+      # arguments. Plugin and Rigor-bundled overlay authors
+      # construct it programmatically through
+      # {with_body_tree}; the Slice 2b string parser will set
+      # it from `body` once it ships. The reducer treats a
+      # `nil` `body_tree` as "definition not yet evaluable"
+      # and returns the registered bound.
+      Definition = Data.define(:uri, :params, :body, :body_tree, :source_path, :source_line) do
+        def initialize(uri:, params:, body:, body_tree: nil, source_path: nil, source_line: nil)
+          raise ArgumentError, "uri must be a Symbol, got #{uri.class}" unless uri.is_a?(Symbol)
+          raise ArgumentError, "params must be an Array, got #{params.class}" unless params.is_a?(Array)
+
+          params.each do |p|
+            raise ArgumentError, "params entries must be Symbols, got #{p.inspect}" unless p.is_a?(Symbol)
+          end
+          raise ArgumentError, "body must be a String, got #{body.class}" unless body.is_a?(String)
+
+          super(
+            uri: uri,
+            params: params.dup.freeze,
+            body: body,
+            body_tree: body_tree,
+            source_path: source_path,
+            source_line: source_line
+          )
+        end
+      end
+
+      # Convenience constructor for callers that have a body
+      # tree but no raw String — typically Rigor-bundled HKT
+      # overlays that build the body programmatically. The
+      # raw `body` slot is filled with an empty placeholder
+      # so existing consumers keep their type contract.
+      def self.definition_with_body_tree(uri:, params:, body_tree:, source_path: nil, source_line: nil)
+        Definition.new(
+          uri: uri,
+          params: params,
+          body: "",
+          body_tree: body_tree,
+          source_path: source_path,
+          source_line: source_line
+        )
+      end
+
+      attr_reader :registrations, :definitions
+
+      # @param registrations [Array<Registration>]
+      # @param definitions [Array<Definition>]
+      def initialize(registrations: [], definitions: [])
+        @registrations = registrations.to_h { |r| [r.uri, r] }.freeze
+        @definitions = definitions.to_h { |d| [d.uri, d] }.freeze
+        freeze
+      end
+
+      def registered?(uri)
+        @registrations.key?(uri)
+      end
+
+      def defined?(uri)
+        @definitions.key?(uri)
+      end
+
+      def registration(uri)
+        @registrations[uri]
+      end
+
+      def definition(uri)
+        @definitions[uri]
+      end
+
+      # @return [HktRegistry] a new registry whose entries are
+      #   the union of this registry's and `other`'s. On URI
+      #   collisions `other`'s entries win (last-write-wins; OQ3
+      #   tentative).
+      def merge(other)
+        raise ArgumentError, "merge target must be an HktRegistry, got #{other.class}" unless other.is_a?(HktRegistry)
+
+        self.class.new(
+          registrations: @registrations.merge(other.registrations).values,
+          definitions: @definitions.merge(other.definitions).values
+        )
+      end
+
+      def empty?
+        @registrations.empty? && @definitions.empty?
+      end
+
+      # ADR-20 Slice 2a — reduce an `App` against this
+      # registry. Convenience wrapper around `HktReducer.new(self).reduce`.
+      # Each call allocates a fresh reducer; concurrent
+      # reductions are safe.
+      def reduce(app, fuel: HktReducer::DEFAULT_FUEL)
+        HktReducer.new(self).reduce(app, fuel: fuel)
+      end
+
+      # ADR-20 slice 2e — scan a Rigor RbsLoader for
+      # `rigor:v1:hkt_register` / `rigor:v1:hkt_define`
+      # annotations attached to class- or module-level
+      # declarations in the loaded RBS env, parse them via
+      # {Rigor::RbsExtended::HktDirectives}, and return a new
+      # registry that is the union of `base` and every parsed
+      # entry. Last-write-wins on URI collisions per
+      # {#merge}'s contract. Fail-soft on per-annotation parse
+      # errors (the reporter records an `:info` entry; the
+      # other annotations still apply).
+      #
+      # @param rbs_loader [Rigor::Environment::RbsLoader]
+      # @param base [HktRegistry] starting registry (typically
+      #   the bundled `Rigor::Builtins::HktBuiltins.registry`).
+      # @param name_scope [Rigor::Environment::NameScope, nil]
+      #   threaded through to the bound resolver for class-name
+      #   lookups; safe to omit during scanning since hkt
+      #   bounds are typically `untyped` or stdlib classes.
+      # @param reporter [#record, nil] same fail-soft reporter
+      #   contract the other RBS-extended parsers use.
+      def self.scan_rbs_loader(rbs_loader, base: EMPTY, name_scope: nil, reporter: nil)
+        return base if rbs_loader.nil?
+
+        # Required lazily here to avoid a hard circular
+        # require between hkt_registry / hkt_directives;
+        # HktDirectives requires HktRegistry to construct its
+        # value objects.
+        require_relative "../rbs_extended/hkt_directives"
+
+        registrations = []
+        definitions = []
+
+        rbs_loader.each_class_decl_annotation do |annotation_string, source_location|
+          reg = Rigor::RbsExtended::HktDirectives.parse_register(
+            annotation_string, name_scope: name_scope, reporter: reporter, source_location: source_location
+          )
+          registrations << reg if reg
+
+          defn = Rigor::RbsExtended::HktDirectives.parse_define(
+            annotation_string, reporter: reporter, source_location: source_location
+          )
+          definitions << defn if defn
+        end
+
+        return base if registrations.empty? && definitions.empty?
+
+        overlay = new(registrations: registrations, definitions: definitions)
+        base.merge(overlay)
+      end
+
+      EMPTY = new.freeze
+    end
+  end
+end
+
+require_relative "hkt_reducer"

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

@@ -3,6 +3,7 @@
 require_relative "../../type"
 require_relative "../acceptance"
 require_relative "../rbs_type_translator"
+require_relative "receiver_affinity"
 
 module Rigor
   module Inference
@@ -44,6 +45,33 @@ module Rigor
       module OverloadSelector
         module_function
 
+        # Canonical RBS-core aliases shipped by `core/builtin.rbs`
+        # whose body is `<Nominal> | _DuckType`. Matching an
+        # overload against an Integer literal should pick the
+        # `(int) -> Array[Elem]` body over the `(string) -> String`
+        # body because Integer satisfies `int`'s strict arm and
+        # not `string`'s. The translator collapses both aliases
+        # to `Dynamic[Top]` (interfaces are not structurally
+        # matched yet), so a dedicated pass 1.5 between strict
+        # and gradual consults this map to pick the alias whose
+        # strict arm matches.
+        #
+        # Symbol keys are the alias names as they appear under
+        # `RBS::Types::Alias#name.to_s` (the `name` is a
+        # `TypeName` whose `to_s` includes the `::` prefix).
+        # Values are an Array of class names whose Nominal[..]
+        # form is the alias's strict-arm matcher.
+        ALIAS_STRICT_NOMINALS = {
+          "::int" => ["Integer"],
+          "::string" => ["String"],
+          "::interned" => %w[Symbol String],
+          "::io" => ["IO"],
+          "::encoding" => %w[Encoding String],
+          "::path" => ["String"],
+          "::boolean" => %w[TrueClass FalseClass]
+        }.freeze
+        private_constant :ALIAS_STRICT_NOMINALS
+
         # @param method_definition [RBS::Definition::Method]
         # @param arg_types [Array<Rigor::Type>] caller-provided types in
         #   positional order. Empty when there are no arguments.
@@ -77,36 +105,19 @@ module Rigor
           # compatibility.
           param_overrides = RbsExtended.param_type_override_map(method_definition, environment: environment)
 
-          # Pass 1: prefer overloads whose param types stay strict —
-          # no translator-induced `Dynamic[Top]` from Alias /
-          # Interface / Intersection. The pass is skipped
-          # entirely when any arg is `Dynamic[Top]` (literally
-          # `untyped`), because gradual acceptance against an
-          # untyped arg accepts every param indiscriminately and
-          # would let pass 1 lock in an arbitrary strict overload
-          # (e.g. `Regexp#=~(nil) -> nil` over the
-          # `(::interned?) -> Integer?` overload). Pass 2 falls
-          # back to the original gradual matcher so overloads
-          # that legitimately rely on duck-typed params still
-          # resolve when nothing stricter applies.
-          match = find_matching_overload(
-            overloads,
-            arg_types: arg_types,
-            self_type: self_type,
-            instance_type: instance_type,
-            type_vars: type_vars,
-            block_required: block_required,
-            param_overrides: param_overrides,
-            strict: true
-          ) || find_matching_overload(
-            overloads,
-            arg_types: arg_types,
-            self_type: self_type,
-            instance_type: instance_type,
-            type_vars: type_vars,
-            block_required: block_required,
-            param_overrides: param_overrides,
-            strict: false
+          # Pre-sort: demote overloads whose param class is a
+          # disjoint sibling of the receiver class (e.g.
+          # `Integer#+(BigDecimal) -> BigDecimal` from the
+          # `bigdecimal` RBS reopen). Honors the coerce
+          # convention so `5 + ?` for unknown `?` resolves to
+          # the receiver-class-preserving arm rather than an
+          # arbitrary sibling-class arm that only wins by
+          # overload-list position.
+          overloads = ReceiverAffinity.reorder(overloads, self_type: self_type, environment: environment)
+
+          match = run_selection_passes(
+            overloads, arg_types: arg_types, self_type: self_type, instance_type: instance_type,
+                       type_vars: type_vars, block_required: block_required, param_overrides: param_overrides
           )
           return match if match
           return overloads.find { |mt| overload_has_block?(mt) } if block_required
@@ -121,6 +132,30 @@ module Rigor
         class << self
           private
 
+          # Three-pass overload search:
+          # - Pass 1 (strict): skipped when any arg is
+          #   `Dynamic[Top]`, because gradual acceptance against
+          #   an untyped arg accepts every param indiscriminately
+          #   and would let pass 1 lock in an arbitrary strict
+          #   overload (e.g. `Regexp#=~(nil) -> nil` over the
+          #   `(::interned?) -> Integer?` overload).
+          # - Pass 1.5 (alias-resolved): consults each `RBS::Types::Alias`'s
+          #   strict arm so e.g. `Array#*(int)` wins over the
+          #   `Array#*(string) -> String` overload for Integer args.
+          # - Pass 2 (gradual): the original gradual matcher so
+          #   overloads that legitimately rely on duck-typed
+          #   params still resolve when nothing stricter applies.
+          def run_selection_passes(overloads, arg_types:, self_type:, instance_type:, type_vars:, block_required:,
+                                   param_overrides:)
+            shared = {
+              arg_types: arg_types, self_type: self_type, instance_type: instance_type,
+              type_vars: type_vars, block_required: block_required, param_overrides: param_overrides
+            }
+            find_matching_overload(overloads, **shared, strict: true) ||
+              find_matching_overload_via_aliases(overloads, arg_types: arg_types, block_required: block_required) ||
+              find_matching_overload(overloads, **shared, strict: false)
+          end
+
           # rubocop:disable Metrics/ParameterLists
           def find_matching_overload(overloads, arg_types:, self_type:, instance_type:, type_vars:, block_required:,
                                      param_overrides:, strict:)
@@ -150,6 +185,66 @@ module Rigor
             type.is_a?(Type::Dynamic) && type.static_facet.is_a?(Type::Top)
           end
 
+          # Pass 1.5: for arity-compatible overloads whose every
+          # positional param is either a strict nominal OR a
+          # well-known core alias (`int` / `string` / `interned`
+          # / etc.), check the arg against the alias's STRICT
+          # arm. An Integer literal arg matches `int` here but
+          # not `string`, so `Array#*(int)` wins over the
+          # `Array#*(string) -> String` overload — even though
+          # both translate to `Dynamic[Top]` at the param level.
+          # Only fires when EVERY positional param has a known
+          # alias-or-strict shape; otherwise gradual matching
+          # takes over.
+          def find_matching_overload_via_aliases(overloads, arg_types:, block_required:)
+            overloads.find do |method_type|
+              next false if block_required && !OverloadSelector.overload_has_block?(method_type)
+
+              fun = method_type.type
+              next false unless arity_compatible?(fun, arg_types.size)
+
+              params = positional_params_for(fun, arg_types.size)
+              next false unless params.size == arg_types.size
+
+              params.zip(arg_types).all? { |param, arg| alias_param_accepts?(param.type, arg) }
+            end
+          end
+
+          # Checks the param's RBS type against an arg using
+          # alias-strict-arm matching. Optional / Union wrappers
+          # are flattened; alias resolution is one level deep
+          # (the canonical core aliases all have non-alias
+          # strict arms).
+          def alias_param_accepts?(rbs_type, arg)
+            nominal_names = strict_nominal_names_for(rbs_type)
+            return false if nominal_names.nil? || nominal_names.empty?
+
+            nominal_names.any? do |class_name|
+              result = Type::Combinator.nominal_of(class_name).accepts(arg, mode: :gradual)
+              result.yes? || result.maybe?
+            end
+          end
+
+          # Returns the candidate class names a param's RBS type
+          # accepts under alias-resolved strict matching, or nil
+          # when the shape cannot be reduced to a closed set of
+          # nominals (e.g. an Interface or an unrecognised alias).
+          def strict_nominal_names_for(rbs_type)
+            case rbs_type
+            when RBS::Types::ClassInstance
+              [rbs_type.name.to_s.delete_prefix("::")]
+            when RBS::Types::Alias
+              ALIAS_STRICT_NOMINALS[rbs_type.name.to_s]
+            when RBS::Types::Optional
+              strict_nominal_names_for(rbs_type.type)
+            when RBS::Types::Union
+              parts = rbs_type.types.map { |t| strict_nominal_names_for(t) }
+              return nil if parts.any?(&:nil?)
+
+              parts.flatten
+            end
+          end
+
           # Returns true when every positional param the call
           # site engages translates to a non-`Dynamic[Top]`
           # carrier. Alias / Interface / Intersection RBS types