rigortype 0.1.4 → 0.1.6

data/lib/rigor/inference/method_dispatcher.rb

@@ -4,6 +4,8 @@ require_relative "../reflection"
 require_relative "../type"
 require_relative "../flow_contribution"
 require_relative "../flow_contribution/merger"
+require_relative "../builtins/hkt_builtins"
+require_relative "../builtins/static_return_refinements"
 require_relative "method_dispatcher/constant_folding"
 require_relative "method_dispatcher/literal_string_folding"
 require_relative "method_dispatcher/shape_dispatch"
@@ -62,7 +64,7 @@ module Rigor
       # @param environment [Rigor::Environment, nil] required for
       #   RBS-backed dispatch; when nil only constant folding can fire.
       # @return [Rigor::Type, nil] inferred result type, or `nil` for "no rule".
-      def dispatch(receiver_type:, method_name:, arg_types:,
+      def dispatch(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/MethodLength
                    block_type: nil, environment: nil,
                    call_node: nil, scope: nil)
         return nil if receiver_type.nil?
@@ -88,6 +90,32 @@ module Rigor
         plugin_result = try_plugin_contribution(call_node, scope)
         return plugin_result if plugin_result
 
+        # ADR-20 slice 3 — Rigor-bundled HKT-builtin return-
+        # type tier. Sits ABOVE `RbsDispatch.try_dispatch` so
+        # the handful of stdlib methods whose upstream RBS
+        # signature is `untyped` but whose runtime shape Rigor
+        # models via a Lightweight HKT (`json::value`,
+        # eventually `dry_monads::result`, …) get the reduced
+        # type instead of `Dynamic[Top]`. The table that
+        # populates this tier lives in
+        # `Rigor::Builtins::HktBuiltins::METHOD_RETURN_OVERRIDES`;
+        # plugin-supplied per-method overrides are out of
+        # scope for slice 3 and continue to flow through the
+        # `try_plugin_contribution` tier above.
+        hkt_builtin_result = try_hkt_builtin_return(receiver_type, method_name, arg_types, environment)
+        return hkt_builtin_result if hkt_builtin_result
+
+        # Rigor-bundled static refinement tier. Sits between HKT
+        # and RBS so stdlib methods whose upstream RBS is broader
+        # than the documented behaviour (e.g. `Kernel#__dir__`
+        # declared `() -> String?` when the documented return is
+        # `non-empty-string | nil`) get the tightened type
+        # without modifying the vendored `ruby/rbs` submodule.
+        # The override table lives in
+        # `Rigor::Builtins::StaticReturnRefinements::OVERRIDES`.
+        static_refinement = try_static_refinement(receiver_type, method_name, arg_types)
+        return static_refinement if static_refinement
+
         rbs_result = RbsDispatch.try_dispatch(
           receiver: receiver_type, method_name: method_name, args: arg_types,
           environment: environment, block_type: block_type
@@ -97,6 +125,34 @@ module Rigor
           return rbs_result
         end
 
+        # ADR-16 Tier B / Tier C — synthetic-method tier. Sits
+        # BELOW RBS dispatch (per WD13: user-authored RBS overrides
+        # substrate synthesis) and ABOVE the dependency-source
+        # inference tier so a plugin's declared emit table beats
+        # the generic gem-source fallback for the same class. Slice
+        # 6a-TierB (origin_module dispatch) lands precise return
+        # types for Tier B emissions; Tier C emissions still return
+        # `Dynamic[T]` at this tier (slice 6b is the Tier C
+        # promotion via ADR-13's resolver chain).
+        synthetic_result = try_synthetic_method(
+          receiver_type, method_name, arg_types, block_type, environment
+        )
+        return synthetic_result if synthetic_result
+
+        # ADR-17 slice 2 — project-side patched-method tier.
+        # Sits BELOW the substrate / plugin tiers and ABOVE
+        # dependency-source inference per ADR-17 § "Inference
+        # contract". When the user's `pre_eval:` list named a
+        # file that re-opens a class (e.g.,
+        # `lib/core_ext/string_extensions.rb` declaring
+        # `class String; def to_url; end; end`), the pre-pass
+        # populated `ProjectPatchedMethods` with the `(class,
+        # method, kind)` triple; this tier surfaces it as
+        # `Dynamic[top]` so the patched call resolves
+        # cross-file without `call.undefined-method`.
+        patched_result = try_project_patched_method(receiver_type, method_name, environment)
+        return patched_result if patched_result
+
         # ADR-10 slice 2b-ii — dependency-source inference tier.
         # Sits BELOW RBS dispatch (RBS / RBS::Inline / generated
         # stubs / plugin contracts always win) and ABOVE the
@@ -203,6 +259,80 @@ module Rigor
       # keeps moving — the run-level diagnostic envelope (per
       # ADR-2 § "Plugin Trust and I/O Policy") is owned by
       # `Analysis::Runner#plugin_emitted_diagnostics`.
+      # ADR-20 slice 3 — looks up the receiver / method pair
+      # in {Rigor::Builtins::HktBuiltins::METHOD_RETURN_OVERRIDES}
+      # and returns the reduced HKT type. Only fires when the
+      # receiver is a {Rigor::Type::Singleton} (the
+      # `JSON.parse` shape) and the registry-backed reduction
+      # succeeds; returns `nil` otherwise so the dispatcher
+      # falls through to RBS.
+      def try_hkt_builtin_return(receiver_type, method_name, arg_types, environment)
+        return nil if environment.nil?
+        return nil unless receiver_type.is_a?(Type::Singleton)
+
+        Rigor::Builtins::HktBuiltins.method_return_override(
+          class_name: receiver_type.class_name,
+          method_name: method_name,
+          kind: :singleton,
+          arg_types: arg_types,
+          hkt_registry: environment.hkt_registry
+        )
+      end
+
+      # Consults the Rigor-bundled static refinement table for a
+      # (owner-class, method-name, kind) entry. Kernel methods
+      # are mixed into every non-BasicObject class, so an
+      # implicit-self `__dir__` call (receiver_type =
+      # Nominal[ClassName]) is matched by looking up Kernel as
+      # the owner. Explicit `Kernel.__dir__` (receiver_type =
+      # Singleton[Kernel]) and instance-side calls
+      # (receiver_type = Nominal[Klass]) share the `:both` row.
+      #
+      # The receiver-side ancestor check is intentionally cheap:
+      # any non-BasicObject Nominal / Singleton matches every
+      # Kernel-owned override. BasicObject explicitly excludes
+      # Kernel and is therefore rejected. The narrow risk of a
+      # user-defined `def __dir__` shadowing Kernel's method
+      # would also alter the runtime answer; users with that
+      # configuration opt out via a `signature_paths` overlay
+      # declaring their own return type.
+      def try_static_refinement(receiver_type, method_name, arg_types)
+        candidates = Rigor::Builtins::StaticReturnRefinements.owners_for(method_name)
+        return nil if candidates.empty?
+
+        owner = static_refinement_owner_for(receiver_type, candidates)
+        return nil unless owner
+
+        kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
+        Rigor::Builtins::StaticReturnRefinements.lookup(
+          owner_class_name: owner,
+          method_name: method_name,
+          kind: kind,
+          arg_types: arg_types
+        )
+      end
+
+      # Picks the most specific override owner the receiver
+      # honours. For Kernel-owned overrides the receiver simply
+      # needs to be a real-class Nominal / Singleton (i.e. not
+      # BasicObject and not a Dynamic / Constant / shape carrier
+      # — those carriers go through their own narrower tiers).
+      def static_refinement_owner_for(receiver_type, candidates)
+        receiver_class = static_refinement_class_for(receiver_type)
+        return nil unless receiver_class
+
+        return "Kernel" if candidates.include?("Kernel") && receiver_class != "BasicObject"
+
+        candidates.find { |owner| owner == receiver_class }
+      end
+
+      def static_refinement_class_for(receiver_type)
+        case receiver_type
+        when Type::Singleton, Type::Nominal
+          receiver_type.class_name
+        end
+      end
+
       def try_plugin_contribution(call_node, scope)
         return nil if call_node.nil? || scope.nil?
 
@@ -225,6 +355,125 @@ module Rigor
       # publish as ground-truth `T`). Returns `nil` when the
       # environment carries no index, the index has no entry, or
       # the receiver has no nominal class to look up.
+      # 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):
+      # - Tier B path (slice 6a, `provenance[:origin_module]`
+      #   recorded by the slice-3b scanner): redispatch on
+      #   `Nominal[origin_module]` via `RbsDispatch` so the
+      #   module's authored RBS return type wins. Devise's
+      #   `valid_password?` returns `bool`, not `Dynamic[T]`.
+      # - Tier C path (slice 6b, plain `return_type:` string from
+      #   the manifest's emit table): look up
+      #   `environment.nominal_for_name(return_type)` so
+      #   `attribute :avatar, Types::String` emits a synthetic
+      #   reader returning `Nominal[ActiveStorage::Attached::One]`
+      #   (when the class is in RBS). Unparameterised class names
+      #   only — parameterised forms (`Array[String]`,
+      #   `Hash[K, V]`) and plugin-supplied utility-type names
+      #   (`Pick<T, K>`) require routing through the full ADR-13
+      #   `Plugin::TypeNodeResolver` chain, which slice 6 does
+      #   not yet wire in (the resolver chain is consulted only
+      #   for `%a{rigor:v1:…}` payloads as of ADR-13 slice 3).
+      def try_synthetic_method(receiver_type, method_name, arg_types, block_type, environment)
+        index = environment&.synthetic_method_index
+        return nil if index.nil? || index.empty?
+
+        class_name = synthetic_method_class_name(receiver_type)
+        return nil if class_name.nil?
+
+        matches = case receiver_type
+                  when Type::Singleton then index.lookup_singleton(class_name, method_name)
+                  else index.lookup_instance(class_name, method_name)
+                  end
+        return nil if matches.empty?
+
+        promoted = promote_synthetic_match(matches, method_name, arg_types, block_type, environment)
+        promoted || Type::Combinator.untyped
+      end
+
+      # First non-nil promotion wins. Tier B (origin_module) and
+      # Tier C (return_type nominal lookup) are tried in the
+      # same registration-order pass per WD11 first-wins —
+      # the slice-3b scanner sets `origin_module` for Tier B
+      # entries and leaves it absent for Tier C, so the two
+      # paths self-route per match.
+      def promote_synthetic_match(matches, method_name, arg_types, block_type, environment)
+        return nil if environment.nil?
+
+        matches.each do |synthetic|
+          promoted =
+            promote_via_origin_module(synthetic, method_name, arg_types, block_type, environment) ||
+            promote_via_return_type(synthetic, environment)
+          return promoted if promoted
+        end
+        nil
+      end
+
+      # Slice 6a-TierB. For Tier B emissions (origin_module
+      # recorded in provenance), redispatch the call on the
+      # included module's `Nominal[...]` type via `RbsDispatch`.
+      # Returns nil when the SyntheticMethod is not a Tier B
+      # entry or when the origin_module is not in the RBS env.
+      def promote_via_origin_module(synthetic, method_name, arg_types, block_type, environment)
+        module_name = synthetic.provenance[:origin_module]
+        return nil unless module_name
+
+        module_type = Type::Combinator.nominal_of(module_name)
+        RbsDispatch.try_dispatch(
+          receiver: module_type, method_name: method_name, args: arg_types,
+          environment: environment, block_type: block_type
+        )
+      end
+
+      # Slice 6b-TierC. For Tier C emissions, look up the
+      # manifest-declared `return_type:` string via
+      # `environment.nominal_for_name`. Skips the placeholder
+      # `"untyped"` (Tier B's record-but-do-not-resolve marker
+      # from the slice-3b scanner) and the `"void"` keyword
+      # (RBS-style absent return). Falls back to nil when the
+      # class is not in the env — caller then returns Dynamic[T].
+      TIER_C_PLACEHOLDER_RETURNS = %w[untyped void].freeze
+      private_constant :TIER_C_PLACEHOLDER_RETURNS
+
+      def promote_via_return_type(synthetic, environment)
+        return_type = synthetic.return_type
+        return nil if return_type.nil? || TIER_C_PLACEHOLDER_RETURNS.include?(return_type)
+
+        environment.nominal_for_name(return_type)
+      end
+
+      def synthetic_method_class_name(receiver_type)
+        case receiver_type
+        when Type::Nominal, Type::Singleton then receiver_type.class_name
+        end
+      end
+
+      # ADR-17 slice 2 — project-side patched-method tier.
+      # Slice 3a uses the registry's heuristic-extracted
+      # `return_type` (populated via the same
+      # `Analysis::DependencySourceInference::ReturnTypeHeuristic`
+      # the ADR-10 walker uses): a `def to_url; "hello"; end`
+      # patched onto `String` now resolves `s.to_url` to
+      # `Dynamic[Nominal[String]]` instead of the pre-3a
+      # `Dynamic[Top]`. Falls back to `Dynamic[Top]` when the
+      # heuristic declined (non-literal tail expression).
+      def try_project_patched_method(receiver_type, method_name, environment)
+        registry = environment&.project_patched_methods
+        return nil if registry.nil? || registry.empty?
+
+        class_name = synthetic_method_class_name(receiver_type)
+        return nil if class_name.nil?
+
+        kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
+        entry = registry.lookup(class_name: class_name, method_name: method_name, kind: kind)
+        return nil if entry.nil?
+        return Type::Combinator.untyped if entry.return_type.nil?
+
+        Type::Combinator.dynamic(entry.return_type)
+      end
+
       def try_dependency_source(receiver_type, method_name, environment)
         index = environment&.dependency_source_index
         return nil if index.nil? || index.empty?
@@ -241,8 +490,8 @@ module Rigor
         # inference must not contribute behind their backs.
         return nil if plugin_owns_receiver?(class_name, environment)
 
-        contribution_kind = index.contribution_for(class_name: class_name, method_name: method_name)
-        return Type::Combinator.untyped if contribution_kind
+        contribution = index.contribution_for(class_name: class_name, method_name: method_name)
+        return dependency_source_return_type(contribution) if contribution
 
         # ADR-10 5b — β budget semantics. On a catalog miss,
         # if the receiver class belongs to a budget-exceeded
@@ -294,6 +543,17 @@ module Rigor
         )
       end
 
+      # Maps a {DependencySourceInference::Walker::CatalogEntry}
+      # to the Type the dispatcher returns at the call site.
+      # When the heuristic recovered a static facet, wrap it in
+      # `Dynamic[T]` per ADR-10's gem-boundary contract;
+      # otherwise fall back to the pre-heuristic `Dynamic[top]`.
+      def dependency_source_return_type(contribution)
+        return Type::Combinator.untyped if contribution.return_type.nil?
+
+        Type::Combinator.dynamic(contribution.return_type)
+      end
+
       # Composite preflight for {#record_boundary_cross_if_applicable}.
       # Returns the receiver class name only when every prerequisite
       # for emitting the diagnostic is satisfied (environment carries
@@ -469,9 +729,25 @@ module Rigor
         Type::Combinator.nominal_of(receiver_type.class_name)
       end
 
-      CONSTANT_CONSTRUCTORS = {
-        "Pathname" => ->(arg) { Pathname.new(arg) }
-      }.freeze
+      # ADR-15 Phase 4b.x — `Ractor.make_shareable` on both the
+      # outer Hash and each lambda value. A plain `.freeze` leaves
+      # the Procs unshareable; reading `CONSTANT_CONSTRUCTORS[class]`
+      # from a worker Ractor would raise `Ractor::IsolationError`,
+      # which the `rescue StandardError` in
+      # `constant_constructor_lift` silently swallows — `meta_new`
+      # then falls back to `Nominal[Pathname]` in pool mode while
+      # sequential builds the `Constant<Pathname>` lift. The
+      # divergence surfaces downstream as a spurious
+      # `call.argument-type-mismatch` (sequential's
+      # `argument_type_diagnostic` short-circuits on Constant<Pathname>
+      # because Pathname is not in its CONSTANT_CLASSES table; pool's
+      # Nominal[Pathname] doesn't short-circuit). Surfaced on GitLab
+      # FOSS via `lib/gitlab/mail_room.rb:17`.
+      CONSTANT_CONSTRUCTORS = Ractor.make_shareable({
+                                                      "Pathname" => Ractor.make_shareable(lambda { |arg|
+                                                                                            Pathname.new(arg)
+                                                                                          })
+                                                    })
       private_constant :CONSTANT_CONSTRUCTORS
 
       def constant_constructor_lift(class_name, arg_types)

data/lib/rigor/inference/method_parameter_binder.rb

@@ -211,20 +211,30 @@ module Rigor
       # (`?by:`) while the Ruby `def` lists it as required (or vice
       # versa); the binding is by-name regardless of which side
       # defines it.
-      KEYWORD_PROVIDER = lambda do |fn, slot|
+      KEYWORD_PROVIDER = Ractor.make_shareable(lambda do |fn, slot|
         fn.required_keywords[slot.name]&.type || fn.optional_keywords[slot.name]&.type
-      end
+      end)
       private_constant :KEYWORD_PROVIDER
 
-      RBS_TYPE_PROVIDERS = {
-        required_positional: ->(fn, slot) { fn.required_positionals[slot.index]&.type },
-        optional_positional: ->(fn, slot) { fn.optional_positionals[slot.index]&.type },
-        rest_positional: ->(fn, _slot) { fn.rest_positionals&.type },
-        trailing_positional: ->(fn, slot) { fn.trailing_positionals[slot.index]&.type },
-        required_keyword: KEYWORD_PROVIDER,
-        optional_keyword: KEYWORD_PROVIDER,
-        rest_keyword: ->(fn, _slot) { fn.rest_keywords&.type }
-      }.freeze
+      RBS_TYPE_PROVIDERS = Ractor.make_shareable({
+                                                   required_positional: Ractor.make_shareable(lambda { |fn, slot|
+                                                     fn.required_positionals[slot.index]&.type
+                                                   }),
+                                                   optional_positional: Ractor.make_shareable(lambda { |fn, slot|
+                                                     fn.optional_positionals[slot.index]&.type
+                                                   }),
+                                                   rest_positional: Ractor.make_shareable(lambda { |fn, _slot|
+                                                     fn.rest_positionals&.type
+                                                   }),
+                                                   trailing_positional: Ractor.make_shareable(lambda { |fn, slot|
+                                                     fn.trailing_positionals[slot.index]&.type
+                                                   }),
+                                                   required_keyword: KEYWORD_PROVIDER,
+                                                   optional_keyword: KEYWORD_PROVIDER,
+                                                   rest_keyword: Ractor.make_shareable(lambda { |fn, _slot|
+                                                     fn.rest_keywords&.type
+                                                   })
+                                                 })
       private_constant :RBS_TYPE_PROVIDERS
 
       def rbs_type_for_slot(function, slot)

data/lib/rigor/inference/narrowing.rb

@@ -384,6 +384,14 @@ module Rigor
           analyse_statements(node, scope)
         when Prism::LocalVariableReadNode
           analyse_local_read(node, scope)
+        when Prism::LocalVariableWriteNode
+          analyse_local_write(node, scope)
+        when Prism::InstanceVariableWriteNode
+          analyse_ivar_write(node, scope)
+        when Prism::ClassVariableWriteNode
+          analyse_cvar_write(node, scope)
+        when Prism::GlobalVariableWriteNode
+          analyse_global_write(node, scope)
         when Prism::CallNode
           analyse_call(node, scope)
         when Prism::AndNode
@@ -736,6 +744,59 @@ module Rigor
           ]
         end
 
+        # Assignment-in-condition: `if name = expr` and the more
+        # frequent `if cond && (name = expr)` / `if cond && name =
+        # expr` Redmine-style guard. By the time narrowing runs,
+        # `StatementEvaluator#eval_local_write` has already bound
+        # the assigned local in `scope` to the rvalue type. The
+        # write's own truthiness IS the assigned value's
+        # truthiness, so the truthy edge narrows the local by
+        # `narrow_truthy(current)` and the falsey edge by
+        # `narrow_falsey(current)`. Mirrors `analyse_local_read`
+        # because the only meaningful difference between
+        # "predicate is `var`" and "predicate is `var = expr`" is
+        # which scope holds the just-bound value; the narrowing
+        # contract on the surrounding `if` is the same.
+        def analyse_local_write(node, scope)
+          current = scope.local(node.name)
+          return nil if current.nil?
+
+          [
+            scope.with_local(node.name, narrow_truthy(current)),
+            scope.with_local(node.name, narrow_falsey(current))
+          ]
+        end
+
+        def analyse_ivar_write(node, scope)
+          current = scope.ivar(node.name)
+          return nil if current.nil?
+
+          [
+            scope.with_ivar(node.name, narrow_truthy(current)),
+            scope.with_ivar(node.name, narrow_falsey(current))
+          ]
+        end
+
+        def analyse_cvar_write(node, scope)
+          current = scope.cvar(node.name)
+          return nil if current.nil?
+
+          [
+            scope.with_cvar(node.name, narrow_truthy(current)),
+            scope.with_cvar(node.name, narrow_falsey(current))
+          ]
+        end
+
+        def analyse_global_write(node, scope)
+          current = scope.global(node.name)
+          return nil if current.nil?
+
+          [
+            scope.with_global(node.name, narrow_truthy(current)),
+            scope.with_global(node.name, narrow_falsey(current))
+          ]
+        end
+
         # `if /(?<x>...)/ =~ str` — Prism wraps the `=~` call in a
         # `MatchWriteNode` listing the named-capture targets. The
         # parent `eval_match_write` has already bound each target
@@ -916,12 +977,12 @@ module Rigor
         # zero-arg predicates on `Numeric`. We model them as
         # comparisons against the literal 0 so the existing range
         # narrowing handles them uniformly.
-        ZERO_CLASS_PREDICATE_RULES = {
-          positive?: { truthy: [:>, 0],  falsey: [:<=, 0] },
-          negative?: { truthy: [:<, 0],  falsey: [:>=, 0] },
-          zero?: { truthy: [:eq, 0], falsey: [:ne, 0] },
-          nonzero?: { truthy: [:ne, 0], falsey: [:eq, 0] }
-        }.freeze
+        ZERO_CLASS_PREDICATE_RULES = Ractor.make_shareable({
+                                                             positive?: { truthy: [:>, 0], falsey: [:<=, 0] },
+                                                             negative?: { truthy: [:<, 0], falsey: [:>=, 0] },
+                                                             zero?: { truthy: [:eq, 0], falsey: [:ne, 0] },
+                                                             nonzero?: { truthy: [:ne, 0], falsey: [:eq, 0] }
+                                                           })
         private_constant :ZERO_CLASS_PREDICATE_RULES
 
         def analyse_zero_class_predicate(node, scope, predicate:)
@@ -1202,15 +1263,73 @@ module Rigor
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
 
-          class_name = static_class_name(node.arguments.arguments.first)
-          return nil if class_name.nil?
+          bare_name = static_class_name(node.arguments.arguments.first)
+          return nil if bare_name.nil?
 
           current = scope.local(node.receiver.name)
           return nil if current.nil?
 
+          # Resolve `bare_name` through the lexical-scope chain
+          # so a name shadowed by the current class / enclosing
+          # module wins over the top-level constant. Mirrors
+          # Ruby's `Module.nesting`-driven constant lookup. The
+          # canonical motivating case: inside
+          # `Rigor::Type::Singleton#==`, `is_a?(Singleton)`
+          # should resolve to `Rigor::Type::Singleton`, not the
+          # top-level stdlib `Singleton` mixin (which would
+          # surface as a spurious `undefined-method` on
+          # subsequent `other.class_name` calls).
+          class_name = resolve_class_name_lexically(bare_name, scope)
           class_predicate_scopes(scope, node.receiver.name, current, class_name, exact: exact)
         end
 
+        # Walks the lexical-nesting chain derived from
+        # `scope.self_type` and returns the first
+        # `<prefix>::<bare_name>` (or bare `<bare_name>` at the
+        # top level) that the environment recognises. Falls back
+        # to `bare_name` itself when nothing in the chain
+        # resolves; the downstream `narrow_class` then yields
+        # the conservative answer for unknown receivers.
+        def resolve_class_name_lexically(bare_name, scope)
+          return bare_name if bare_name.include?("::") # Already qualified.
+
+          chain = lexical_nesting_for(scope)
+          chain.each do |prefix|
+            candidate = "#{prefix}::#{bare_name}"
+            return candidate if class_known_to_scope?(scope, candidate)
+          end
+          bare_name
+        end
+
+        # Combines the environment's RBS-known set with the
+        # scope's in-source `discovered_classes` table so a
+        # lexical-nesting candidate matches a class the project
+        # declares but has no RBS for.
+        def class_known_to_scope?(scope, candidate)
+          return true if scope.environment.class_known?(candidate)
+
+          scope.discovered_classes.key?(candidate)
+        end
+
+        # Approximates `Module.nesting` from the inferable
+        # `self_type`. Today's implementation handles the common
+        # case: when the surrounding method is a regular
+        # instance method (`self_type = Nominal[T]`) or a
+        # class-body / singleton (`self_type = Singleton[T]`),
+        # the chain is `T`'s namespace path — `Foo::Bar::Baz`
+        # → `["Foo::Bar::Baz", "Foo::Bar", "Foo"]`. Returns an
+        # empty array when `self_type` is unknown.
+        def lexical_nesting_for(scope)
+          self_type = scope.self_type
+          base = case self_type
+                 when Type::Nominal, Type::Singleton then self_type.class_name
+                 end
+          return [] if base.nil? || base.empty?
+
+          parts = base.split("::")
+          parts.each_index.map { |i| parts[0..-(i + 1)].join("::") }
+        end
+
         def class_predicate_scopes(scope, name, current, class_name, exact:)
           [
             scope.with_local(

data/lib/rigor/inference/project_patched_methods.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-17 § "Inference contract" — project-wide patched-method
+    # registry populated by the pre-eval pre-pass (slice 2) from
+    # the user's `.rigor.yml` `pre_eval:` list.
+    #
+    # Each entry records one `def` declaration the pre-pass
+    # observed inside a class / module body. The dispatcher's
+    # `try_project_patched_method` tier consults this registry
+    # between the plugin tier and the dependency-source tier so
+    # project-side `lib/core_ext/string_extensions.rb` patches
+    # are visible to cross-file dispatch.
+    #
+    # Slice 2 ships the registry at the **floor**: the dispatcher
+    # answers `Type::Combinator.untyped` (Dynamic[Top]) on a hit;
+    # return-type inference for patched methods stays deferred
+    # (a separate slice when concrete demand surfaces — most
+    # real-world `core_ext` patches return shapes the analyzer
+    # could heuristically extract via the same machinery the
+    # ADR-10 walker uses, but slice 2 keeps the surface narrow).
+    class ProjectPatchedMethods
+      # Frozen value-object recording one `def` observed by the
+      # pre-pass. `class_name` is the qualified prefix
+      # (`"String"`, `"Foo::Bar"`); `method_name` is the
+      # declared name; `kind` is `:instance` or `:singleton`;
+      # `source_path` / `source_line` carry attribution for
+      # diagnostics; `return_type` is the
+      # {Analysis::DependencySourceInference::ReturnTypeHeuristic}-
+      # extracted static facet (a `Rigor::Type::*`) or `nil`
+      # when the heuristic declined. The dispatcher wraps a
+      # non-nil `return_type` in `Dynamic[T]`; a `nil`
+      # `return_type` falls back to `Dynamic[top]`.
+      Entry = Data.define(:class_name, :method_name, :kind, :source_path, :source_line, :return_type) do
+        def initialize(class_name:, method_name:, kind:, source_path:, source_line:, return_type: nil)
+          super
+        end
+      end
+
+      attr_reader :by_key
+
+      # @param entries [Array<Entry>] flat list of declarations
+      #   observed during the pre-pass. First-write-wins on
+      #   `(class_name, method_name, kind)` duplicates so the
+      #   `pre-eval.duplicate-declaration` diagnostic emission
+      #   stays decoupled from registry behaviour.
+      def initialize(entries: [])
+        @by_key = entries.each_with_object({}) do |entry, acc|
+          key = [entry.class_name, entry.method_name, entry.kind]
+          acc[key] ||= entry
+        end.freeze
+        freeze
+      end
+
+      # @return [Entry, nil] the recorded entry for the given
+      #   `(class_name, method_name, kind)` triple, or `nil`
+      #   when no pre-eval file declared it.
+      def lookup(class_name:, method_name:, kind:)
+        @by_key[[class_name, method_name, kind]]
+      end
+
+      def empty?
+        @by_key.empty?
+      end
+
+      EMPTY = new.freeze
+    end
+  end
+end