rigortype 0.3.8 → 0.4.0

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

@@ -4,6 +4,8 @@ require "prism"
 
 require_relative "../../type"
 require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
+require_relative "../struct_fold_safety"
 
 module Rigor
   module Inference
@@ -25,6 +27,10 @@ module Rigor
       module StructMaterialization
         module_function
 
+        # Nodes one factory-body scan may visit before it gives up and refuses. A factory is a handful of
+        # nodes; the bound exists so a pathological body cannot turn a per-call-site gate into a walk.
+        FACTORY_BODY_SCAN_BUDGET = 200
+
         # Issue #595 / #525 — the ONE materialisation test. Both places that must answer "was this receiver
         # expression's struct newly built?" go through it: this module's direct member-read gate above, and
         # `ExpressionTyper`'s caller-side `:self`-grant arm. They had forked answers once (the grant arm was
@@ -32,20 +38,95 @@ module Rigor
         # composed `x.dup_self.with(indent: 9).shout` shape survived — a correctly whitelisted `.with` fold
         # firing off a receiver the other gate should never have called fresh.
         #
-        #
-        # @param node [Prism::Node, nil] the receiver EXPRESSION.
-        # @param receiver [Rigor::Type, nil] the carrier the expression produced.
-        # @param scope [Rigor::Scope, nil]
+        # @param node — the receiver EXPRESSION.
+        # @param receiver — the carrier the expression produced.
         def materialization_call?(node, receiver, scope)
           return false unless node.is_a?(Prism::CallNode)
 
           case node.name
           when :new, :[] then struct_class_expression?(node.receiver, scope)
           when :with then !hand_written_with?(receiver, scope)
+          else fresh_factory_call?(node, scope)
+          end
+        end
+
+        # Issue #599 — the FACTORY-METHOD idiom, the one shape #595's whitelist knowingly paid for as a
+        # missed error: `def build = Pair.new("hi", [1, 2])` then `build.items`. The whitelist could not see
+        # through `build`, so the chain declined and a typo on it went unreported.
+        #
+        # It is recovered by asking the callee, under two bounds that keep the answer cheap and fail-closed.
+        #
+        # 1. RESOLUTION is one table read on a shape whose target cannot be an arbitrary object: a
+        #    receiverless send resolved through the confidence-gated top-level def table, or `Const.name`
+        #    resolved through the singleton-side ancestor walk. An INSTANCE-side receiver is refused
+        #    outright — `x.dup_self` is the #595 bug shape, and what `x` holds at the call is exactly what
+        #    this gate has no way to know.
+        # 2. ACCEPTANCE is decided on the callee's RETURN POSITION, not on a self-alias scan of its body.
+        #    "Cannot return `self`" is not the property freshness needs: the factory's `self` is the module
+        #    or `main`, never the struct, while `def get = GLOBAL` over a mutated constant returns a
+        #    long-lived instance with no `self` anywhere in it. What the gate needs is that the returned
+        #    object was built BY THIS CALL, so the body's tail must itself be a materialisation
+        #    ({#fresh_materialization_tail?}) and no `return` may hand back anything else. That subsumes the
+        #    self-alias refusal — a body returning `self` has a `SelfNode` tail, not a `.new` — while
+        #    admitting the idiom the issue is about.
+        def fresh_factory_call?(node, scope)
+          return false if scope.nil?
+
+          body = factory_def_body(node, scope)
+          return false unless body.is_a?(Prism::StatementsNode)
+
+          fresh_materialization_tail?(body.body.last, scope) && !early_return?(body)
+        end
+
+        # The two CHEAPLY RESOLVABLE callee shapes, each a single table read against the frozen discovery
+        # index. `bindable_top_level_def_for` is the confidence-gated accessor — the only one the inference
+        # may bind through — so a call inside a block whose `self` is unmodelled declines here as it does
+        # everywhere else. Anything else, an instance-side receiver above all, resolves to nil.
+        def factory_def_body(node, scope)
+          def_node =
+            case node.receiver
+            when nil then scope.bindable_top_level_def_for(node.name)
+            when Prism::ConstantReadNode, Prism::ConstantPathNode
+              owner = Source::ConstantPath.qualified_name_or_nil(node.receiver)
+              owner && scope.singleton_def_through_ancestors(owner, node.name).first
+            end
+          def_node&.body
+        end
+
+        # A materialisation written in the CALLEE's body, judged syntactically. Deliberately narrower than
+        # {#struct_class_expression?}: that predicate's local-variable arm reads the binding off the scope it
+        # is handed, which is the CALLER's — a local of the same name in the callee body is a different
+        # binding entirely, so the arm is dropped rather than answered from the wrong scope.
+        def fresh_materialization_tail?(node, scope)
+          return false unless node.is_a?(Prism::CallNode)
+          return false unless %i[new []].include?(node.name)
+
+          case node.receiver
+          when Prism::ConstantReadNode, Prism::ConstantPathNode
+            name = Source::ConstantPath.qualified_name_or_nil(node.receiver)
+            !name.nil? && !scope.struct_member_layout(name).nil?
+          when Prism::CallNode then inline_struct_factory?(node.receiver)
           else false
           end
         end
 
+        # An explicit `return` anywhere in the body hands back an expression the tail check never saw, so the
+        # body is refused rather than scanned arm by arm. Nested `def` / `class` / `module` bodies are a
+        # different method's returns; a block's `return` is this method's, so the walk descends into it. The
+        # visit budget is the fail-closed bound: a body too large to scan is not proven, and unproven is not
+        # fresh.
+        def early_return?(node, budget = [FACTORY_BODY_SCAN_BUDGET])
+          return true if node.is_a?(Prism::ReturnNode)
+          return false if Inference::StructFoldSafety.scope_boundary?(node)
+
+          budget[0] -= 1
+          return true if budget[0].negative?
+
+          found = false
+          node.rigor_each_child { |child| found ||= early_return?(child, budget) }
+          found
+        end
+
         # `.with` copies the receiver into a new instance — unless the struct wrote its own, which is free to
         # return `self` and would reopen the very hole above.
         #

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

@@ -28,7 +28,7 @@ module Rigor
 
         module_function
 
-        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        # @return folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
           method_name = context.method_name

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

@@ -68,8 +68,7 @@ module Rigor
 
         module_function
 
-        # @param context [CallContext]
-        # @return [Rigor::Type, nil] the receiver-independent return type, or nil to decline.
+        # @return the receiver-independent return type, or nil to decline.
         def try_dispatch(context)
           return nil unless context.receiver.is_a?(Type::Dynamic)
 

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

@@ -61,7 +61,7 @@ module Rigor
 
         module_function
 
-        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        # @return folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
           method_name = context.method_name

data/lib/rigor/inference/method_dispatcher.rb

@@ -21,11 +21,15 @@ require_relative "method_dispatcher/iterator_dispatch"
 require_relative "method_dispatcher/reduce_folding"
 require_relative "method_dispatcher/block_folding"
 require_relative "method_dispatcher/array_to_h_folding"
+require_relative "method_dispatcher/hash_transform_keys_folding"
 require_relative "method_dispatcher/file_folding"
 require_relative "method_dispatcher/shellwords_folding"
 require_relative "method_dispatcher/math_folding"
+require_relative "method_dispatcher/random_folding"
 require_relative "method_dispatcher/time_folding"
 require_relative "method_dispatcher/regexp_folding"
+require_relative "method_dispatcher/match_data_folding"
+require_relative "method_dispatcher/process_folding"
 require_relative "method_dispatcher/cgi_folding"
 require_relative "method_dispatcher/uri_folding"
 require_relative "method_dispatcher/set_folding"
@@ -54,19 +58,17 @@ module Rigor
     module MethodDispatcher # rubocop:disable Metrics/ModuleLength
       module_function
 
-      # @param receiver_type [Rigor::Type, nil] type of the receiver expression, or
+      # @param receiver_type — type of the receiver expression, or
       #   `nil` for an implicit-self call.
-      # @param method_name [Symbol]
-      # @param arg_types [Array<Rigor::Type>] positional argument types.
-      # @param block_type [Rigor::Type, nil] inferred return type of the
+      # @param block_type — inferred return type of the
       #   accompanying `do ... end` / `{ ... }` block (Slice 6 phase C
       #   sub-phase 2). When non-nil, the dispatcher prefers an
       #   overload that declares a block, and binds the method's
       #   block-return type variable to `block_type` so a return type
       #   like `Array[U]` resolves to `Array[block_type]`.
-      # @param environment [Rigor::Environment, nil] required for
+      # @param environment — required for
       #   RBS-backed dispatch; when nil only constant folding can fire.
-      # @return [Rigor::Type, nil] inferred result type, or `nil` for "no rule".
+      # @return inferred result type, or `nil` for "no rule".
       def dispatch(receiver_type:, method_name:, arg_types:,
                    block_type: nil, environment: nil,
                    call_node: nil, scope: nil)
@@ -94,9 +96,12 @@ module Rigor
         result
       end
 
-      def resolve(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # `plugin_typed_sink` is internal bookkeeping for the composite-receiver tier below: when it is an
+      # Array, an answering plugin tier PUSHES the call node instead of recording it on the scope, and
+      # the tier commits the buffer only if it goes on to answer. See {#try_composite_receiver}.
+      def resolve(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
                   block_type: nil, environment: nil,
-                  call_node: nil, scope: nil)
+                  call_node: nil, scope: nil, plugin_typed_sink: nil)
         return nil if receiver_type.nil?
 
         # Build the call context once and thread it — unchanged — through every tier
@@ -126,7 +131,22 @@ module Rigor
           # RBS's, and `call.undefined-method` reads that record instead of re-deciding from the receiver's
           # (possibly partial) signature. Recorded for EVERY plugin answer, dynamic or precise: the
           # incoherence the record closes is about which subsystem typed the call, not about the type.
-          scope&.record_plugin_typed_call(call_node)
+          #
+          # Under a composite-receiver projection the record is BUFFERED instead (#1101). It is the one
+          # recording in this method that is set-only — `Scope#plugin_typed_calls` has no removal, and
+          # `CheckRules#call_site_exempt?` / `#source_arity_envelope` read it as an exemption — so a
+          # member a plugin answers beside a member that declines would exempt a call this dispatcher
+          # never typed, silencing `call.undefined-method` and `call.wrong-arity` on a firing that stands.
+          # `call_site_exempt?` runs ahead of the receiver-shape branch, so the union rule is covered by
+          # it too and the suppression is reachable end to end — the arms are measured in
+          # `spec/integration/composite_receiver_plugin_typed_suppression_spec.rb`. The
+          # `record_dynamic_origin` writes below and in the tiers that follow need no such care: that
+          # table is last-wins and the caller's fail-soft widening overwrites it.
+          if plugin_typed_sink
+            plugin_typed_sink << call_node
+          else
+            scope&.record_plugin_typed_call(call_node)
+          end
           if plugin_result.is_a?(Type::Dynamic)
             scope&.record_dynamic_origin(call_node, DynamicOrigin::FRAMEWORK_DSL_BOUNDARY)
           end
@@ -255,7 +275,13 @@ module Rigor
         if fallback_result.is_a?(Type::Dynamic)
           scope&.record_dynamic_origin(call_node, DynamicOrigin::INFERRED_RETURN_UNTYPED)
         end
-        fallback_result
+        return fallback_result if fallback_result
+
+        # Issue #1101 — composite-receiver projection, the last tier. Every tier above needs a
+        # receiver it can name; a `Union` or a `Difference` is not one, so a composite receiver whose
+        # members WOULD each resolve still lands `Dynamic[top]`. Retry per projected member through
+        # this same chain. See {#try_composite_receiver} for the projection rule and why it sits here.
+        try_composite_receiver(context)
       end
 
       # ADR-100 WD4 — records the transitive `-> void` provenance when the called method is a
@@ -335,10 +361,14 @@ module Rigor
           [receiver_type.class_name, :instance]
         when Type::Singleton, Type::StructClass, Type::DataClass
           [receiver_type.class_name, :singleton]
-        else [nil, nil]
+        else NO_DISCOVERED_LOOKUP
         end
       end
 
+      # The shared "no discovered-method key" pair; callers destructure it (#775).
+      NO_DISCOVERED_LOOKUP = [nil, nil].freeze
+      private_constant :NO_DISCOVERED_LOOKUP
+
       # ADR-5 robustness — returns `Dynamic[Top]` when the receiver is an instance or singleton
       # of a type Rigor synthesized (a missing-namespace module or a referenced-type stub). The
       # stub has no methods, so the call would otherwise reach the user-class fallback and
@@ -447,6 +477,52 @@ module Rigor
         FlowContribution::Merger.merge(contributions).return_type
       end
 
+      # Issue #963 item 2 — the MEMBERSHIP half of the two plugin tiers, for #618's own-method veto.
+      #
+      # `ExpressionTyper#try_local_def_dispatch` has to decide whether the call's own `self` answers the
+      # name before a same-named top-level `def` may bind, and a plugin-supplied member is an answer Ruby
+      # really dispatches to: a model's column reader, an association, a scope, a macro-synthesised
+      # reader. The veto asked neither tier, so a top-level `def name` bound ahead of the member and
+      # typed the read as the def's `nil` — #618's false positive at a source the veto could not see.
+      #
+      # The question is asked HERE, of the same two tiers `resolve` consults and in the same order, rather
+      # than reconstructed in the veto: a name this reports as answered is a name the dispatch really would
+      # resolve, and no plugin knowledge moves into the engine's veto. The tiers are the gated
+      # `dynamic_return` walk and the ADR-16 synthetic-method index (Tier C `heredoc_templates` emissions
+      # today; the Tier B `Plugin::Macro::TraitRegistry` explosions share that table but cannot populate it
+      # until #476 threads a real environment into the pre-pass that builds it, so no trait member reaches
+      # this predicate in production yet — it will when #476 lands, with no change here).
+      #
+      # It is a predicate, not a type: the veto's job is to stop the top-level bind, after which the call
+      # falls through to the ordinary dispatch chain and the tier that answered here answers there too. The
+      # walk is not on the hot path — it runs only once `Scope#bindable_top_level_def_for` has already
+      # produced a candidate, which needs a project top-level `def` of the same name.
+      def plugin_member_answers?(call_node:, scope:, receiver_type:, method_name:)
+        return false if receiver_type.nil?
+        return true unless try_plugin_contribution(call_node, scope, receiver_type).nil?
+
+        synthetic_method_member?(receiver_type, method_name, scope&.environment)
+      end
+
+      # The synthetic-method half of {#plugin_member_answers?} — the same `(class_name, method_name, kind)`
+      # probe {#try_synthetic_method} makes, without the return-type promotion the veto has no use for.
+      def synthetic_method_member?(receiver_type, method_name, environment)
+        index = environment&.synthetic_method_index
+        return false if index.nil? || index.empty?
+
+        class_name = synthetic_method_class_name(receiver_type)
+        return false if class_name.nil?
+
+        matches = if receiver_type.is_a?(Type::Singleton)
+                    index.lookup_singleton(class_name, method_name)
+                  else
+                    index.lookup_instance(class_name, method_name)
+                  end
+        !matches.empty?
+      rescue StandardError
+        false
+      end
+
       # ADR-16 synthetic-method tier. Slice 2b shipped the floor — a match short-circuits at the
       # right precedence (above dep-source / discovered / user-class-fallback; below RBS) and
       # returns `Dynamic[T]`. Slice 6 (precision promotion):
@@ -759,8 +835,10 @@ module Rigor
         "File" => FileFolding,
         "Shellwords" => ShellwordsFolding,
         "Math" => MathFolding,
+        "Random" => RandomFolding,
         "Time" => TimeFolding,
         "Regexp" => RegexpFolding,
+        "Process" => ProcessFolding,
         "CGI" => CGIFolding,
         "URI" => URIFolding,
         "Set" => SetFolding,
@@ -769,7 +847,7 @@ module Rigor
       private_constant :STDLIB_SINGLETON_FOLDERS
 
       PRECISE_TIERS_TAIL = Ractor.make_shareable([
-        MethodFolding, ReduceFolding, ArrayToHFolding, BlockFolding
+        MethodFolding, ReduceFolding, ArrayToHFolding, HashTransformKeysFolding, BlockFolding
       ].freeze)
       private_constant :PRECISE_TIERS_TAIL
 
@@ -797,11 +875,8 @@ module Rigor
           return result if result
         end
 
-        receiver = context.receiver
-        if receiver.is_a?(Type::Singleton) && (folder = STDLIB_SINGLETON_FOLDERS[receiver.class_name])
-          result = folder.try_dispatch(context)
-          return result if result
-        end
+        folder_result = dispatch_receiver_keyed_folder(context)
+        return folder_result if folder_result
 
         kernel_result = dispatch_kernel_intrinsic(context)
         return kernel_result if kernel_result
@@ -813,6 +888,19 @@ module Rigor
         nil
       end
 
+      # The folders the receiver's class selects, at most one per call: a stdlib singleton folder, or for a
+      # `MatchData` receiver the slice fold of the proven `$~` (issue #1381). Every other receiver skips them without
+      # a trial.
+      def dispatch_receiver_keyed_folder(context)
+        receiver = context.receiver
+        folder =
+          case receiver
+          when Type::Singleton then STDLIB_SINGLETON_FOLDERS[receiver.class_name]
+          when Type::Nominal then MatchDataFolding if receiver.class_name == "MatchData"
+          end
+        folder&.try_dispatch(context)
+      end
+
       # ADR-91 WD1 — the single dispatcher-held ownership gate for the Kernel module-function surface
       # (gate-by-held-key, the same move STDLIB_SINGLETON_FOLDERS made above). The tier runs only when
       # the method name is in the compiled `INTRINSIC_NAMES` table AND the call is attributable to
@@ -890,6 +978,123 @@ module Rigor
         end
       end
 
+      # Issue #1101 — the composite-receiver projection tier, the LAST thing `resolve` tries.
+      #
+      # Every tier above needs a receiver it can *name*: `receiver_descriptor`, the discovered-method
+      # lookup, the dependency-source and synthesized-stub tiers and the user-class fallback all switch
+      # on `Nominal` / `Singleton` / a member carrier. A `Union` or a `Difference` is none of those, so a
+      # composite receiver whose members would each resolve perfectly well still fell through the whole
+      # chain and landed `Dynamic[top]`.
+      #
+      # `RbsDispatch` already distributes over a `Union` (and erases a `Difference` to its base, #533),
+      # but it does so INSIDE one tier, so a member that needs a LOWER tier — a user class with no RBS,
+      # a discovered `def`, an opt-in gem — makes the whole union decline. That is the corpus shape:
+      # rigor-actionpack types `params[:k]` as `ActionController::Parameters | nil`, the `Parameters` arm
+      # resolves only through the user-class fallback, and so `params[:k].present?` / `#==` / `#blank?` /
+      # `#to_s` read opaque on every Rails app. Measured by toggling this file alone: the named-pair
+      # census drains 137 sites on redmine and 56 on mastodon, and `rigor check` reports the same
+      # diagnostics on both arms across eight survey targets.
+      #
+      # **Why the bottom and not next to `RbsDispatch`.** Sitting here, the tier can only ever replace a
+      # `Dynamic[top]` the typer was about to produce — the same ADR-5 argument {UniversalObjectDispatch}
+      # makes. Hoisting the projection above `RbsDispatch` would change answers that resolve today, which
+      # is a different change with a different measurement.
+      #
+      # **The projection rule** (`receiver_projection` below; the normative statement lives in
+      # [`inference-engine.md`](docs/internal-spec/inference-engine.md) § "Composite receivers"):
+      #
+      # - `Union[A, B, …]` projects to its members. Each is dispatched through this same chain and the
+      #   results are unioned; if ANY member declines, the whole tier declines. Never a partial answer —
+      #   a union whose members disagree about whether the method exists is exactly the case where an
+      #   answer would be a guess.
+      # - `Difference[base, nil]` projects to `base` with its nil-valued members removed. Removing `nil`
+      #   from a receiver cannot change method resolution at all: `NilClass` is nobody's ancestor, so
+      #   every remaining inhabitant looks a method up exactly as a plain `base` inhabitant does, and the
+      #   carrier is value-set-equal to the projection. This is `T.must(x)` (rigor-sorbet's
+      #   `strip_nil`), which builds `Difference[inferred(x), Constant[nil]]` — over a `T?` local that
+      #   base IS a union, which is why the two arms compose rather than being separate features.
+      # - Any other `Difference` DECLINES. `A − B` for a real `B` is a claim about which inhabitants
+      #   survive, and the projection has nowhere to put it: dispatching on `A` re-admits exactly the
+      #   overrides `B` contributed, and over a union base (`(String | Integer) − Integer` is Strings
+      #   only) it re-admits a member the difference eliminated and unions in its answer — a WIDER type
+      #   than today's decline, on a shape no corpus target produces. Subtracting a class from a union
+      #   needs an algebra the `Difference` carrier does not have (it removes a value set, not a member),
+      #   so the honest answer is to keep declining until something demands it. `RbsDispatch`'s #533
+      #   erasure is untouched and still answers these for an RBS-known base.
+      #
+      # `self` binds to the PROJECTED receiver, not to the composite: the projection is the exact set of
+      # inhabitants that can reach the method, so a `-> self` method (`dup`, `itself`, `tap`) answers per
+      # member and the union reassembles them — `(String | Symbol)#itself` is `String | Symbol`. Nothing is
+      # lost on the `Difference` arm because the projection is value-set-equal to the carrier there. This
+      # falls out of re-entering `resolve` rather than needing a `self_type_override`.
+      def try_composite_receiver(context)
+        members = receiver_projection(context.receiver)
+        return nil if members.nil? || members.size > COMPOSITE_PROJECTION_MEMBERS
+
+        plugin_typed = []
+        results = members.map do |member|
+          resolve(
+            receiver_type: member, method_name: context.method_name, arg_types: context.args,
+            block_type: context.block_type, environment: context.environment,
+            call_node: context.call_node, scope: context.scope, plugin_typed_sink: plugin_typed
+          )
+        end
+        return nil if results.any?(&:nil?)
+
+        plugin_typed.uniq.each { |node| context.scope&.record_plugin_typed_call(node) }
+        Type::Combinator.union(*results)
+      end
+
+      # An upper bound on the fan-out, because this tier re-runs the FULL dispatch chain per member.
+      # Real unions are two or three members wide; a receiver wider than this is a join the engine has
+      # already lost precision on, and paying N chain walks to union N answers is not worth it.
+      COMPOSITE_PROJECTION_MEMBERS = 8
+      private_constant :COMPOSITE_PROJECTION_MEMBERS
+
+      # The receivers each member of a composite carrier is dispatched as, or nil when the carrier is not
+      # projectable. Every member returned MUST itself be non-composite: that is what bounds the re-entry
+      # into `resolve` at one level, by construction rather than by a counter — the nested call reaches
+      # this tier with a receiver it declines immediately. A normalized `Union` never holds a `Union`, so
+      # the shapes the guard turns away are a `Difference` over a `Difference` (`T.must(T.must(x))`) and a
+      # `Union` holding one (`c ? T.must(y) : Bar.new`, which normalizes to `(A - nil) | Bar`). Both
+      # decline exactly as they did before this tier existed; neither appears in the survey corpus.
+      def receiver_projection(receiver)
+        members =
+          case receiver
+          when Type::Union then receiver.members
+          when Type::Difference then difference_projection(receiver)
+          end
+        return nil if members.nil? || members.empty?
+        return nil if members.any? { |member| member.is_a?(Type::Union) || member.is_a?(Type::Difference) }
+
+        members
+      end
+
+      # `Difference[base, nil]` projects to `base` minus its nil-valued members; every other difference
+      # declines. The nil filter runs over a scalar base as well as a union one, so the rule stays total:
+      # `Combinator.difference` does not normalize `NilClass - nil` (or `nil - nil`) to `Bot`, and this
+      # tier must not project `[NilClass]` and answer a NilClass method for a carrier with no inhabitant.
+      # Nothing observable turns on it today — `RbsDispatch`'s #533 erasure sits above this tier and
+      # already answers a nil-only base from the base's own descriptor — which is why the guard is here
+      # rather than in `Combinator`, where it would be a normalization change with its own blast radius.
+      def difference_projection(difference)
+        return nil unless nil_valued_type?(difference.removed)
+
+        base = difference.base
+        members = base.is_a?(Type::Union) ? base.members : [base]
+        retained = members.reject { |member| nil_valued_type?(member) }
+        return nil if retained.empty?
+
+        retained
+      end
+
+      # `nil` as either carrier spells it: the value-pinned `Constant[nil]` the engine normally produces,
+      # and the `Nominal[NilClass]` a widened or RBS-sourced position carries.
+      def nil_valued_type?(type)
+        (type.is_a?(Type::Constant) && type.value.nil?) ||
+          (type.is_a?(Type::Nominal) && type.class_name == "NilClass")
+      end
+
       # Slice 7 phase 8 — meta-introspection shortcuts. The default `Object#class` RBS return
       # type is `Class`, but for a receiver of known nominal identity we can do better:
       # `instance_of(Foo).class` is `Singleton[Foo]` (the class object itself), which downstream
@@ -1350,18 +1555,13 @@ module Rigor
       # method definition, or selected overload does not provide statically declared block
       # parameter types. Callers MUST treat the empty array as "no information"; the binder
       # falls back to `Dynamic[Top]` for every parameter slot in that case.
-      #
-      # @param receiver_type [Rigor::Type, nil]
-      # @param method_name [Symbol]
-      # @param arg_types [Array<Rigor::Type>]
-      # @param environment [Rigor::Environment, nil]
-      # @return [Array<Rigor::Type>]
-      def expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil)
+      def expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil,
+                                     scope: nil)
         return [] if receiver_type.nil?
 
         context = CallContext.build(
           receiver: receiver_type, method_name: method_name,
-          args: arg_types, environment: environment
+          args: arg_types, environment: environment, scope: scope
         )
         iterator_result = IteratorDispatch.block_param_types(context)
         return iterator_result if iterator_result

data/lib/rigor/inference/method_parameter_binder.rb

@@ -55,14 +55,13 @@ module Rigor
     end
 
     class MethodParameterBinder
-      # @param environment [Rigor::Environment]
-      # @param class_path [String, nil] the qualified name of the class the method is defined in
+      # @param class_path — the qualified name of the class the method is defined in
       #   (e.g., `"Foo::Bar"`), or `nil` for a top-level `def` outside any class. When `nil` (or
       #   when the class is unknown to RBS), every parameter falls back to `Dynamic[Top]`.
-      # @param singleton [Boolean] `true` when the def is a singleton method (either `def
+      # @param singleton — `true` when the def is a singleton method (either `def
       #   self.foo` or a `def foo` inside `class << self`); routes the lookup through
       #   `RbsLoader#singleton_method`.
-      # @param source_path [String, nil] the project-relative path of the file the method is
+      # @param source_path — the project-relative path of the file the method is
       #   defined in. Used to match ADR-28 path-scoped protocol contracts; `nil` (the default
       #   for synthetic / probe scopes) disables the contract tier.
       def initialize(environment:, class_path:, singleton:, source_path: nil)
@@ -72,8 +71,7 @@ module Rigor
         @source_path = source_path
       end
 
-      # @param def_node [Prism::DefNode]
-      # @return [Hash{Symbol => Rigor::Type}] ordered map from parameter name to bound type.
+      # @return ordered map from parameter name to bound type.
       #   Anonymous parameters (`*` and `**` without a name) are skipped.
       def bind(def_node)
         slots = collect_slots(def_node.parameters)
@@ -200,7 +198,14 @@ module Rigor
       # both `()` and `(int)` overloads — only the second matches a `def first(n)` redefinition)
       # are silently skipped, so the binder defaults to the most informative type the RBS
       # signature provides without having to know which overload the runtime will pick.
+      #
+      # An overload declared `(?)` (`RBS::Types::UntypedFunction`, issue #1430) has no parameter lists and
+      # accepts any argument in every slot, so no slot can be narrowed below `Dynamic[Top]`: binding a typed
+      # sibling overload's parameter type would read a value that overload legitimately passes as a
+      # contradiction inside the body. Every slot keeps its default; the declared return type still applies.
       def apply_rbs_overloads(types, slots, method_types)
+        return unless method_types.all? { |mt| mt.type.respond_to?(:required_positionals) }
+
         slots.each do |slot|
           next if slot.name.nil?
 
@@ -260,9 +265,7 @@ module Rigor
         return nil if contracts.empty?
 
         singleton = def_node.receiver.is_a?(Prism::SelfNode) || @singleton
-        contracts.find do |contract|
-          contract.method_name == def_node.name && contract.singleton == singleton
-        end
+        contracts.find { |contract| contract.method_name == def_node.name && contract.singleton == singleton }
       end
 
       def positional_slot_at(slots, index)