rigortype 0.1.17 → 0.1.18

data/lib/rigor/configuration.rb

@@ -70,12 +70,15 @@ module Rigor
       "fold_platform_specific_paths" => false,
       "cache" => {
         "path" => ".rigor/cache",
-        # LRU eviction cap in bytes. nil (the default) disables eviction;
-        # the cache grows until the user runs `rigor check --clear-cache`.
-        # Set to a positive integer (e.g. 536870912 for 512 MB) to keep the
-        # cache bounded — the least-recently-used entries are removed at the
-        # end of each run when the total exceeds this limit.
-        "max_bytes" => nil
+        # LRU eviction cap in bytes (ADR-54 WD3). The least-recently-used
+        # entries are removed at the end of a run when the total exceeds
+        # this limit. The 256 MB default exists to reap orphans — entries
+        # whose content key nothing references any more (an rbs gem bump,
+        # a signature change) and that no run would otherwise ever delete;
+        # a full active per-project set is ~2 MB, so the cap never touches
+        # live entries. Set explicitly to `null` to disable eviction
+        # (pre-WD3 behaviour: the cache grows until `--clear-cache`).
+        "max_bytes" => 268_435_456
       },
       "plugins_io" => {
         "network" => "disabled",

data/lib/rigor/environment/rbs_loader.rb

@@ -559,29 +559,17 @@ module Rigor
       #   definition cannot be built (RBS may raise on broken hierarchies;
       #   we fail-soft and return nil so the caller can fall back).
       #
-      # When `cache_store` is set, the loader fetches the per-class
-      # definition through {Cache::RbsInstanceDefinitions.fetch} so
-      # subsequent runs (and other loaders sharing the same Store)
-      # skip the `RBS::DefinitionBuilder.build_instance` step.
-      # In-memory `@instance_definition_cache` keeps the per-process
-      # short-circuit on top.
+      # Built on demand from the (possibly cache-loaded) env; the
+      # in-memory `@instance_definition_cache` keeps the per-process
+      # short-circuit. ADR-54 WD1 retired the definitions disk blob:
+      # given a cached env, `Marshal.load`-ing every definition was
+      # measurably slower (and allocation-heavier) than rebuilding
+      # the ones a run actually touches.
       def instance_definition(class_name)
         key = class_name.to_s
         return @instance_definition_cache[key] if @instance_definition_cache.key?(key)
 
-        @instance_definition_cache[key] = if cache_store
-                                            cached_instance_definition(class_name)
-                                          else
-                                            build_instance_definition(class_name)
-                                          end
-      end
-
-      # Public uncached accessor used by the cache producer
-      # ({Rigor::Cache::RbsInstanceDefinitions}). Avoids the
-      # `private_method_called` round-trip a `loader.send(...)`
-      # callsite would require.
-      def uncached_instance_definition(class_name)
-        build_instance_definition(class_name)
+        @instance_definition_cache[key] = build_instance_definition(class_name)
       end
 
       # @return [RBS::Definition::Method, nil]
@@ -636,24 +624,14 @@ module Rigor
       #   those inherited from `Class` and `Module` for class types.
       #   Returns nil for unknown names and on RBS build errors (fail-soft).
       #
-      # When `cache_store` is set, the loader fetches the per-class
-      # singleton definition through
-      # {Cache::RbsSingletonDefinitions.fetch}; the same caching
-      # discipline as {#instance_definition}.
+      # Built on demand from the env with a per-process memo; the
+      # same on-demand discipline as {#instance_definition} (ADR-54
+      # WD1).
       def singleton_definition(class_name)
         key = class_name.to_s
         return @singleton_definition_cache[key] if @singleton_definition_cache.key?(key)
 
-        @singleton_definition_cache[key] = if cache_store
-                                             cached_singleton_definition(class_name)
-                                           else
-                                             build_singleton_definition(class_name)
-                                           end
-      end
-
-      # Public uncached accessor used by the cache producer.
-      def uncached_singleton_definition(class_name)
-        build_singleton_definition(class_name)
+        @singleton_definition_cache[key] = build_singleton_definition(class_name)
       end
 
       # @return [RBS::Definition::Method, nil] the class method on
@@ -762,18 +740,20 @@ module Rigor
       end
 
       # ADR-15 Phase 4b.x — eagerly drives every cached
-      # producer so a subsequent worker Ractor can serve all
-      # of its RBS queries from the Marshal blob on disk
-      # without ever calling `RBS::EnvironmentLoader.new`.
+      # producer (plus the eager definitions tables, computed
+      # from the cached env since ADR-54 WD1) so a subsequent
+      # worker Ractor can serve all of its RBS queries without
+      # ever calling `RBS::EnvironmentLoader.new`.
       # The loader path that calls `EnvironmentLoader.new`
       # transitively reads a chain of non-`Ractor.shareable?`
       # module constants
       # (`RBS::EnvironmentLoader::DEFAULT_CORE_ROOT`,
       # `RBS::Repository::DEFAULT_STDLIB_ROOT`,
       # `Gem::Requirement::DefaultRequirement`, …) and trips
-      # `Ractor::IsolationError`. Pre-warming the cache on
-      # the main Ractor and letting workers consult ONLY the
-      # Marshal-loaded blob sidesteps the whole chain.
+      # `Ractor::IsolationError`. Pre-warming on the main
+      # Ractor — env blob loaded, derived tables built — keeps
+      # workers off that chain (`RBS::DefinitionBuilder` over
+      # an already-built env does not touch it).
       #
       # No-op when `cache_store` is nil — without a Store the
       # worker has no choice but to build env via the loader,
@@ -793,6 +773,20 @@ module Rigor
         self
       end
 
+      # ADR-54 WD4 — the shared cache descriptor for every RBS-derived
+      # producer consulting this loader. Building it digests every
+      # `.rbs` file under `signature_paths` + the vendored gem sigs,
+      # and the result is identical across producers, so one build is
+      # memoised per loader (on `@state`, alongside `:env` — the env
+      # itself is loader-lifetime-memoised, so this adds no new
+      # staleness class).
+      def rbs_cache_descriptor
+        @state[:rbs_cache_descriptor] ||= begin
+          require_relative "../cache/rbs_descriptor"
+          Cache::RbsDescriptor.build(self)
+        end
+      end
+
       # ADR-15 Phase 2b — return the loader's read-only
       # query surface as a frozen, `Ractor.shareable?`
       # {Reflection} value object. Built lazily on first
@@ -969,43 +963,34 @@ module Rigor
         Cache::RbsEnvironment.fetch(loader: self, store: cache_store)
       end
 
-      # Per-process Hash<String, RBS::Definition> for the instance
-      # side. Loaded once on first miss through the
-      # {Cache::RbsInstanceDefinitions} producer (single Marshal
-      # blob); subsequent calls are pure Hash lookups. Cold runs
-      # build every known class once and persist; warm runs (and
-      # other loaders sharing the same Store) skip the
-      # `RBS::DefinitionBuilder.build_instance` work entirely.
-      def cached_instance_definition(class_name)
-        instance_definitions_table[normalise_class_key(class_name)]
-      end
-
+      # Full `Hash<String, RBS::Definition>` tables for the
+      # {#prewarm} / {#reflection} consumers (ADR-15 Phase 2b/4b.x),
+      # which need every definition materialised up front. Built
+      # from the (cached) env via `RBS::DefinitionBuilder` — ADR-54
+      # WD1 retired the disk blobs these used to `Marshal.load`
+      # (building all definitions from a cached env is faster), so
+      # the eager-table cost is now a compute, not a load. Keys stay
+      # in `RBS::TypeName#to_s` form (top-level prefixed `"::Hash"`)
+      # — the shape {Environment::Reflection} documents.
       def instance_definitions_table
-        @state[:instance_definitions_table] ||= begin
-          require_relative "../cache/rbs_instance_definitions"
-          fetch_or_compute_producer(Cache::RbsInstanceDefinitions)
+        @state[:instance_definitions_table] ||= build_definitions_table do |name|
+          build_instance_definition(name)
         end
       end
 
-      def cached_singleton_definition(class_name)
-        singleton_definitions_table[normalise_class_key(class_name)]
-      end
-
       def singleton_definitions_table
-        @state[:singleton_definitions_table] ||= begin
-          require_relative "../cache/rbs_instance_definitions"
-          fetch_or_compute_producer(Cache::RbsSingletonDefinitions)
+        @state[:singleton_definitions_table] ||= build_definitions_table do |name|
+          build_singleton_definition(name)
         end
       end
 
-      # The cache producers persist class names in
-      # `RBS::TypeName#to_s` form (top-level prefixed
-      # `"::Hash"`); plain-name lookups (`"Hash"`) normalise
-      # before the Hash query so callers stay agnostic to the
-      # prefix.
-      def normalise_class_key(class_name)
-        s = class_name.to_s
-        s.start_with?("::") ? s : "::#{s}"
+      def build_definitions_table
+        table = {}
+        each_known_class_name do |name|
+          definition = yield(name)
+          table[name] = definition if definition
+        end
+        table
       end
 
       def builder

data/lib/rigor/environment.rb

@@ -77,7 +77,7 @@ module Rigor
     # @param plugin_registry [Rigor::Plugin::Registry, nil] v0.1.1
     #   Track 2 slice 7. The per-run plugin registry the
     #   inference engine consults at call sites for plugin
-    #   `#flow_contribution_for` overrides. When nil (the
+    #   `dynamic_return` rules. When nil (the
     #   default), no plugin-level return-type contribution
     #   participates — useful for tests, the `Environment.default`
     #   facade, and analyses that don't load plugins.

data/lib/rigor/inference/acceptance.rb

@@ -243,6 +243,12 @@ module Rigor
           when Type::HashShape
             accepts(self_type, project_hash_shape_to_nominal(other_type), mode: mode)
               .with_reason("projected HashShape to Nominal[Hash]")
+          when Type::DataInstance
+            # ADR-48: a class-tagged member instance is exactly one value of
+            # its tagging class, so it projects to that class's nominal (the
+            # anonymous local-bound form projects to `Data` itself).
+            accepts(self_type, project_data_instance_to_nominal(other_type), mode: mode)
+              .with_reason("projected DataInstance to Nominal[#{other_type.class_name || 'Data'}]")
           when Type::Difference, Type::Refined
             # A refinement carrier's value set is a subset of its
             # base. So if `self` (Nominal) accepts the base, it
@@ -376,6 +382,10 @@ module Rigor
           end
         end
 
+        def project_data_instance_to_nominal(instance)
+          Type::Combinator.nominal_of(instance.class_name || "Data")
+        end
+
         def project_hash_shape_to_nominal(shape)
           return Type::Combinator.nominal_of(Hash) if shape.pairs.empty?
 

data/lib/rigor/inference/expression_typer.rb

@@ -8,6 +8,7 @@ require_relative "../analysis/self_call_resolution_recorder"
 require_relative "block_parameter_binder"
 require_relative "budget_trace"
 require_relative "fallback"
+require_relative "flow_tracer"
 require_relative "indexed_narrowing"
 require_relative "macro_block_self_type"
 require_relative "method_dispatcher"
@@ -219,6 +220,15 @@ module Rigor
       end
 
       def type_of(node)
+        return untraced_type_of(node) unless FlowTracer.active?
+
+        # `rigor trace` — bracket the recursion with enter/result events.
+        # The tracer is observational only: the inferred type flows
+        # through unchanged (see FlowTracer's contract).
+        FlowTracer.trace_node(node) { untraced_type_of(node) }
+      end
+
+      def untraced_type_of(node)
         # Slice A-declarations. ScopeIndexer pre-fills
         # `scope.declared_types` for declaration-position nodes
         # (`module Foo` / `class Bar` headers) with the qualified
@@ -668,26 +678,17 @@ module Rigor
       end
 
       # Returns `:truthy`, `:falsey`, or `nil` for an arbitrary
-      # predicate expression under three-valued logic. Uses the
-      # same {Narrowing} probe as `StatementEvaluator#eval_if`:
-      # the predicate is truthy when its falsey fragment is `Bot`,
-      # falsey when its truthy fragment is `Bot`. So
-      # `Nominal[Integer]` (always truthy in Ruby), `Constant[nil]`,
-      # and `Constant[false]` fold one branch; `Union[true, false]`,
-      # `Dynamic[T]`, and `Top` keep both branches live.
+      # predicate expression under three-valued logic.
+      # {Narrowing.predicate_certainty} owns the judgment (the same
+      # one `StatementEvaluator#live_branch_for_if` reads on the
+      # scope side): `Nominal[Integer]` (always truthy in Ruby),
+      # `Constant[nil]`, and `Constant[false]` fold one branch;
+      # `Union[true, false]`, `Dynamic[T]`, and `Top` keep both
+      # branches live.
       def constant_predicate_polarity(predicate)
         return nil if predicate.nil?
 
-        type = type_of(predicate)
-        return nil if type.nil? || type.is_a?(Type::Bot)
-
-        truthy_bot = Narrowing.narrow_truthy(type).is_a?(Type::Bot)
-        falsey_bot = Narrowing.narrow_falsey(type).is_a?(Type::Bot)
-
-        return :falsey if truthy_bot && !falsey_bot
-        return :truthy if !truthy_bot && falsey_bot
-
-        nil
+        Narrowing.predicate_certainty(type_of(predicate))
       end
 
       def type_of_else(node)
@@ -818,29 +819,14 @@ module Rigor
       # `:maybe` — the existing union fallback handles them.
       def case_when_pattern_certainty(subject_type, pattern_node)
         class_name = build_constant_path_name(pattern_node)
-        return class_pattern_certainty(subject_type, class_name) if class_name
+        return Narrowing.class_pattern_certainty(subject_type, class_name, environment: scope.environment) if class_name
 
         literal = literal_pattern_value(pattern_node)
-        return literal_pattern_certainty(subject_type, literal[:value]) if literal
+        return Narrowing.value_pattern_certainty(subject_type, literal[:value]) if literal
 
         :maybe
       end
 
-      def class_pattern_certainty(subject_type, class_name)
-        env = scope.environment
-        truthy_bot = Narrowing.narrow_class(subject_type, class_name, environment: env).is_a?(Type::Bot)
-        falsey_bot = Narrowing.narrow_not_class(subject_type, class_name, environment: env).is_a?(Type::Bot)
-
-        return :no if truthy_bot && !falsey_bot
-        return :yes if !truthy_bot && falsey_bot
-
-        :maybe
-      end
-
-      VALUE_EQUALITY_CLASSES = [Integer, Float, Rational, Complex, String, Symbol,
-                                TrueClass, FalseClass, NilClass].freeze
-      private_constant :VALUE_EQUALITY_CLASSES
-
       # Returns `{ value: v }` when `pattern_node` types to a
       # `Constant[v]` of a value-equality-safe class (so `===`
       # reduces to `==`), else nil. Wrapped in a hash so a literal
@@ -849,18 +835,11 @@ module Rigor
       def literal_pattern_value(pattern_node)
         type = type_of(pattern_node)
         return nil unless type.is_a?(Type::Constant)
-        return nil unless VALUE_EQUALITY_CLASSES.any? { |klass| type.value.is_a?(klass) }
+        return nil unless Narrowing::VALUE_EQUALITY_CLASSES.any? { |klass| type.value.is_a?(klass) }
 
         { value: type.value }
       end
 
-      def literal_pattern_certainty(subject_type, pattern_value)
-        return :maybe unless subject_type.is_a?(Type::Constant)
-        return :maybe unless VALUE_EQUALITY_CLASSES.any? { |klass| subject_type.value.is_a?(klass) }
-
-        pattern_value == subject_type.value ? :yes : :no
-      end
-
       # `when` clauses for `case` and `in` clauses for `case ... in` have
       # the same body shape; we reuse one handler for both Prism node
       # classes.
@@ -1565,7 +1544,7 @@ module Rigor
       # nil when the parameter shape is too complex for the
       # first-iteration binder (rest args, keyword args,
       # block params, etc.).
-      def build_user_method_body_scope(def_node, receiver, arg_types) # rubocop:disable Metrics/AbcSize
+      def build_user_method_body_scope(def_node, receiver, arg_types)
         params = def_node.parameters
         required = params&.requireds || []
         return nil unless params.nil? || user_method_param_shape_simple?(params)
@@ -1578,30 +1557,17 @@ module Rigor
         locals = {}
         required.each_with_index { |param, index| locals[param.name.to_sym] = arg_types[index] }
 
-        # Construct the body scope in a SINGLE allocation. The previous
+        # Construct the body scope in a SINGLE allocation — the previous
         # `Scope.empty.with_*.with_*…` chain allocated a fresh frozen Scope
-        # per field — ~12 throwaway Scopes to build one body scope, run per
-        # user-method-call inference, which made these `with_*` the dominant
-        # `Scope#rebuild` source. Each field here is a plain inherited
-        # reference (the project-wide indexes + self_type); every unset
-        # field defaults to the same empty binding the old chain left it at,
-        # so the result is identical (ADR-44).
+        # per field, run per user-method-call inference (ADR-44). The
+        # discovery index is inherited whole by reference (ADR-53 Track A);
+        # the hand-copied per-field list this replaces had silently dropped
+        # `data_member_layouts` and `discovered_method_visibilities`.
         Scope.new(
           environment: scope.environment,
           locals: locals.freeze,
           self_type: receiver,
-          declared_types: scope.declared_types,
-          discovered_classes: scope.discovered_classes,
-          in_source_constants: scope.in_source_constants,
-          class_ivars: scope.class_ivars,
-          class_cvars: scope.class_cvars,
-          program_globals: scope.program_globals,
-          discovered_methods: scope.discovered_methods,
-          discovered_def_nodes: scope.discovered_def_nodes,
-          discovered_def_sources: scope.discovered_def_sources,
-          discovered_superclasses: scope.discovered_superclasses,
-          discovered_includes: scope.discovered_includes,
-          discovered_class_sources: scope.discovered_class_sources
+          discovery: scope.discovery
         )
       end
 

data/lib/rigor/inference/flow_tracer.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # Thread-local event recorder behind `rigor trace`: while a block runs
+    # under {record}, the inference engine emits a flat, ordered event
+    # stream describing HOW it typed the program — expression enter/result
+    # pairs, scope binds, union formation, and method-dispatch outcomes.
+    # The CLI replays that stream as a terminal animation (or dumps it as
+    # JSON); the engine itself never reads the events back, so recording
+    # is purely observational and MUST NOT change any inferred type.
+    #
+    # Modelled on {Analysis::DependencyRecorder}: thread-local state, a
+    # module-level activation count so the disabled fast path ({active?})
+    # is a plain integer read, and a frozen snapshot for consumers. The
+    # instrumented hot paths (`ExpressionTyper#type_of`,
+    # `Scope#with_local`, `Type::Combinator.union`,
+    # `MethodDispatcher.dispatch`) each guard their emit behind {active?},
+    # so a normal (non-tracing) run pays one integer comparison.
+    module FlowTracer
+      KEY = :__rigor_flow_tracer__
+      private_constant :KEY
+
+      # One animation-relevant moment.
+      #
+      # kind     :enter | :result | :bind | :union | :dispatch
+      # depth    expression-recursion depth at emit time (0 = statement level)
+      # location frozen Hash with :start_line/:start_column/:end_line/
+      #          :end_column/:start_offset/:end_offset, or nil. Events
+      #          without a node of their own (:bind, :union) inherit the
+      #          innermost in-flight expression node's location so the
+      #          replayer can still highlight the source being evaluated.
+      # stack    frozen Array of short node-class names, outermost first
+      # data     frozen kind-specific Hash (types pre-rendered as Strings
+      #          via `describe(:short)` so events serialise to JSON as-is)
+      Event = Data.define(:kind, :depth, :location, :stack, :data)
+
+      # Mutable per-thread accumulator; only ever touched by the thread
+      # that activated it, so no locking is needed on the emit path.
+      class Recorder
+        attr_reader :events
+
+        def initialize
+          @events = []
+          @stack = []
+        end
+
+        # Brackets one `ExpressionTyper#type_of` recursion: emits :enter,
+        # runs the real inference, emits :result with the inferred type,
+        # and returns the type unchanged.
+        def node(node)
+          location = location_of(node)
+          name = short_name(node.class)
+          emit(:enter, location: location, data: { node: name })
+          @stack.push(node)
+          result = nil
+          begin
+            result = yield
+          ensure
+            @stack.pop
+          end
+          emit(:result, location: location, data: { node: name, type: FlowTracer.describe(result) })
+          result
+        end
+
+        def emit(kind, location: nil, data: {})
+          @events << Event.new(
+            kind: kind,
+            depth: @stack.size,
+            location: (location || current_location)&.freeze,
+            stack: @stack.map { |n| short_name(n.class) }.freeze,
+            data: data.freeze
+          )
+        end
+
+        private
+
+        def current_location
+          location_of(@stack.last)
+        end
+
+        def location_of(node)
+          return nil unless node.respond_to?(:location) && node.location
+
+          loc = node.location
+          {
+            start_line: loc.start_line, start_column: loc.start_column,
+            end_line: loc.end_line, end_column: loc.end_column,
+            start_offset: loc.start_offset, end_offset: loc.end_offset
+          }
+        end
+
+        def short_name(klass)
+          klass.name.to_s.split("::").last
+        end
+      end
+
+      @active_count = 0
+      @mutex = Mutex.new
+
+      module_function
+
+      # Activates recording on the current thread for the duration of the
+      # block and returns the frozen event list. Nests safely; restores
+      # the previous recorder on exit.
+      def record
+        previous = Thread.current[KEY]
+        recorder = Recorder.new
+        Thread.current[KEY] = recorder
+        @mutex.synchronize { @active_count += 1 }
+        yield
+        recorder.events.freeze
+      ensure
+        Thread.current[KEY] = previous
+        @mutex.synchronize { @active_count -= 1 }
+      end
+
+      # Plain integer read (GVL-atomic) — the disabled fast path.
+      def active?
+        @active_count.positive?
+      end
+
+      # Brackets one expression-typing recursion. Falls through to the
+      # bare block when the current thread is not recording (another
+      # thread may have flipped {active?}).
+      def trace_node(node, &)
+        recorder = Thread.current[KEY]
+        return yield unless recorder
+
+        recorder.node(node, &)
+      end
+
+      # `Scope#with_local` — the moment a local enters the scope.
+      def bind(name, type)
+        Thread.current[KEY]&.emit(:bind, data: { name: name.to_s, type: describe(type) })
+      end
+
+      # `Type::Combinator.union` — the moment branch types merge
+      # (including degenerate collapses like `1 | 1 → 1`).
+      def union(members, result)
+        Thread.current[KEY]&.emit(
+          :union,
+          data: { members: members.map { |m| describe(m) }.freeze, type: describe(result) }
+        )
+      end
+
+      # `MethodDispatcher.dispatch` — resolution or the fail-soft `nil`
+      # ("no rule matched"; the caller will widen to `Dynamic[Top]`).
+      def dispatch(receiver:, method_name:, args:, result:, location: nil)
+        recorder = Thread.current[KEY]
+        return unless recorder
+
+        recorder.emit(
+          :dispatch,
+          location: location && location_hash(location),
+          data: {
+            receiver: describe(receiver), method: method_name.to_s,
+            args: args.map { |a| describe(a) }.freeze,
+            type: result && describe(result), resolved: !result.nil?
+          }
+        )
+      end
+
+      def describe(type)
+        return "nil" if type.nil?
+        return type.describe(:short) if type.respond_to?(:describe)
+
+        type.inspect
+      end
+
+      def location_hash(loc)
+        {
+          start_line: loc.start_line, start_column: loc.start_column,
+          end_line: loc.end_line, end_column: loc.end_column,
+          start_offset: loc.start_offset, end_offset: loc.end_offset
+        }
+      end
+    end
+  end
+end

data/lib/rigor/inference/macro_block_self_type.rb

@@ -51,11 +51,16 @@ module Rigor
         receiver_class_name = singleton_receiver_class_name(receiver_type)
         return nil if receiver_class_name.nil?
 
-        verb = call_node.name
-        registry.plugins.each do |plugin|
-          plugin.manifest.block_as_methods.each do |entry| # rigor:disable undefined-method
-            return instance_type_for(receiver_class_name, environment) if matches?(entry, verb, receiver_class_name,
-                                                                                   environment)
+        # ADR-52 WD1 — the verb-keyed table compiled at registry build
+        # replaces the per-call plugins × block_as_methods linear scan.
+        # Entries arrive in (plugin registration, declaration) order, so
+        # the first ancestry match below is the same entry the previous
+        # walk returned; the verb membership the old `matches?` checked
+        # is guaranteed by the table key.
+        entries = registry.contribution_index.block_entries_for(call_node.name)
+        entries.each do |entry|
+          if receiver_class_inherits_from?(receiver_class_name, entry.receiver_constraint, environment)
+            return instance_type_for(receiver_class_name, environment)
           end
         end
         nil
@@ -73,12 +78,6 @@ module Rigor
         receiver_type.class_name
       end
 
-      def matches?(entry, verb, receiver_class_name, environment)
-        return false unless entry.verbs.include?(verb)
-
-        receiver_class_inherits_from?(receiver_class_name, entry.receiver_constraint, environment)
-      end
-
       def receiver_class_inherits_from?(class_name, constraint, environment)
         return true if class_name == constraint
 

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

@@ -32,7 +32,16 @@ module Rigor
       #    matches, accept the first arity-and-gradual-accept match
       #    (the v0.1.1 behaviour). Alias / Interface / Intersection
       #    params still reach this pass, so call sites whose only
-      #    candidate IS an alias-typed overload keep working.
+      #    candidate IS an alias-typed overload keep working. One
+      #    exclusion: an `untyped` argument does NOT gradually match
+      #    a value-pinning param (`nil` / literal types — carriers
+      #    that admit only specific values). Those overloads carry
+      #    value-precise returns (`Kernel#Array: (nil) -> []`,
+      #    `Regexp#=~: (nil) -> nil`) that would otherwise win purely
+      #    by list position and inject false constants into the flow;
+      #    they remain selectable when the argument PROVES the value
+      #    (strict pass) or when no other overload matches (step 4's
+      #    fallback picks the first overload regardless).
       # 4. If no overload matches at all, fall back to
       #    `method_types.first` so existing call sites keep their
       #    phase 1 / 2b behavior. This preserves the fail-soft
@@ -393,9 +402,32 @@ module Rigor
               instance_type: instance_type,
               type_vars: type_vars
             )
+            # An `untyped` arg gradually accepts against every param,
+            # so a value-pinning param would be "matched" with zero
+            # evidence and its value-precise return (`(nil) -> []`)
+            # would beat broader overloads purely by list position.
+            # Decline the pair; only the strict pass (where the arg
+            # proves the value) or the final first-overload fallback
+            # may select such an overload. (Pass 1 already skips
+            # untyped args entirely, so this only engages pass 2.)
+            return false if untyped_arg?(arg) && value_pinning?(param_type)
+
             result = param_type.accepts(arg, mode: :gradual)
             result.yes? || result.maybe?
           end
+
+          # A type that admits only specific VALUES rather than a
+          # class of values: a `Constant` carrier (RBS `nil` and
+          # literal types both translate to one) or a union made up
+          # entirely of them (`true | false`, `1 | 2`, `nil?`-style
+          # optionals of literals).
+          def value_pinning?(type)
+            case type
+            when Type::Constant then true
+            when Type::Union then type.members.all? { |member| value_pinning?(member) }
+            else false
+            end
+          end
         end
       end
     end