rigortype 0.3.7 → 0.3.9

data/lib/rigor/rbs_extended/reporter.rb

@@ -6,47 +6,92 @@ module Rigor
     # cannot surface at the point of failure (the parsers are fail-soft, returning `nil` so call sites fall back
     # to the RBS-declared type).
     #
-    # Owns two event streams:
+    # Owns three event streams:
     #
     # - `#unresolved_payloads` — `rigor:v1:*` directive payloads the resolver could not turn into a
-    #   {Rigor::Type}. Surface as `dynamic.rbs-extended.unresolved` `:info` diagnostics.
+    #   {Rigor::Type}. Surface as `dynamic.rbs-extended.unresolved` `:info` diagnostics, except an
+    #   unresolved `conforms-to` interface, which the aggregator stamps `:warning` (#928).
     # - `#lossy_projections` — shape-projection type functions (`pick_of` / `omit_of` / `partial_of` /
     #   `required_of` / `readonly_of`) applied to a carrier that does not preserve shape information (anything
     #   other than `Type::HashShape` / `Type::Tuple`). Surface as `dynamic.shape.lossy-projection` `:info`
     #   diagnostics.
+    # - `#hkt_directive_errors` — malformed `rigor:v1:hkt_register` / `rigor:v1:hkt_define` directives the
+    #   ADR-20 parser declined. Surface as `dynamic.rbs-extended.hkt-directive-invalid` `:info` diagnostics.
+    # - `#deprecated_forms` — payload spellings the grammar still accepts for one deprecation window but no
+    #   longer displays (ADR-109 WD3: the PHPStan-style `int<a, b>`). Surface as
+    #   `dynamic.rbs-extended.deprecated-form` `:info` diagnostics naming the replacement.
     #
     # Mutable through the run; consumed once by {Rigor::Analysis::Runner} at end-of-run. Each event is
-    # deduplicated by `(payload, source_location)` for unresolved and `(head, source_location)` for
-    # lossy-projection so a single annotation read from many call sites yields one diagnostic.
+    # deduplicated by its whole entry — `(payload, path, line, column)` for unresolved, `(head, path, line,
+    # column)` for lossy-projection, `(message, path, line, column)` for an hkt directive, `(payload,
+    # replacement, path, line, column)` for a deprecated form — so a single annotation read from many call
+    # sites yields one diagnostic.
     #
     # The reporter is intentionally thread-safe via a coarse `Mutex` because the inference engine may read the
     # same method definition from multiple files in parallel; the critical sections are short (Array#include? +
     # Array#<<) so the lock contention is negligible.
     class Reporter
-      UnresolvedEntry = Data.define(:payload, :source_location)
-      LossyProjectionEntry = Data.define(:head, :source_location)
+      # Every entry carries its position as `(path, line, column)` primitives, flattened from the parser's
+      # `RBS::Location` by {.position_of} at record time. Issues #785 (hkt) and #805 (the two older streams).
+      # Two reasons, and either alone decides it. All three streams are drained out of every fork-pool worker
+      # ({Rigor::Analysis::WorkerSession#drain_reporters}), and an `RBS::Location` is a C-extension object with
+      # no `_dump`, so a `Marshal.dump` of the drain payload raises `TypeError` — which kills the worker at
+      # drain time and degrades the run to in-process re-analysis. And an `RBS::Location` compares equal only
+      # against a location over the SAME `RBS::Buffer` object, so two workers that each read the same `.rbs`
+      # would hand the coordinator two entries the dedup cannot collapse — `--workers=N` would then print N
+      # copies of a row `--workers=0` prints once.
+      #
+      # The record methods take the triple rather than the location for the same reason: a door that accepts
+      # an `RBS::Location` is a door a future caller reintroduces the bug through.
+      UnresolvedEntry = Data.define(:payload, :path, :line, :column)
+      LossyProjectionEntry = Data.define(:head, :path, :line, :column)
+      HktDirectiveEntry = Data.define(:message, :path, :line, :column)
+      DeprecatedFormEntry = Data.define(:payload, :replacement, :path, :line, :column)
+
+      # Flattens an `RBS::Location` (or anything answering the same readers) to the `(path, line, column)`
+      # triple every entry carries. `column` is 1-based, since `RBS::Location#start_column` is 0-based and
+      # diagnostics are not. Each component is `nil` when the location cannot supply it, and the diagnostic
+      # then falls back to `.rigor.yml:1:1`.
+      #
+      # Fail-soft by construction, like every parser that calls it: a location that raises while being read
+      # costs the entry its position, never the run.
+      def self.position_of(source_location)
+        return [nil, nil, nil] if source_location.nil?
+
+        buffer = source_location.respond_to?(:buffer) ? source_location.buffer : nil
+        name = buffer.respond_to?(:name) ? buffer.name.to_s : ""
+        line = source_location.respond_to?(:start_line) ? source_location.start_line : nil
+        column = source_location.respond_to?(:start_column) ? source_location.start_column + 1 : nil
+        [name.empty? ? nil : name, line, column]
+      rescue StandardError
+        [nil, nil, nil]
+      end
 
       def initialize
         @unresolved_payloads = []
         @lossy_projections = []
+        @hkt_directive_errors = []
+        @deprecated_forms = []
         @mutex = Mutex.new
       end
 
-      # @return [Array<UnresolvedEntry>] frozen snapshot of the accumulated unresolved-payload events.
+      # @return frozen snapshot of the accumulated unresolved-payload events.
       def unresolved_payloads
         @mutex.synchronize { @unresolved_payloads.dup.freeze }
       end
 
-      # @return [Array<LossyProjectionEntry>] frozen snapshot of the accumulated lossy-projection events.
+      # @return frozen snapshot of the accumulated lossy-projection events.
       def lossy_projections
         @mutex.synchronize { @lossy_projections.dup.freeze }
       end
 
-      # Records a `dynamic.rbs-extended.unresolved` event. The `source_location` argument is the {RBS::Location}
-      # attached to the source annotation (or `nil` when the caller doesn't have one — the diagnostic falls back
-      # to a generic location in that case).
-      def record_unresolved(payload:, source_location: nil)
-        entry = UnresolvedEntry.new(payload: payload.to_s, source_location: source_location)
+      # Records a `dynamic.rbs-extended.unresolved` event. The position triple is the source annotation's
+      # `.rbs` file / line / 1-based column — {.position_of} flattens the caller's `RBS::Location` into it —
+      # each `nil` when the caller had no location (the diagnostic then falls back to `.rigor.yml:1:1`).
+      def record_unresolved(payload:, path: nil, line: nil, column: nil)
+        entry = UnresolvedEntry.new(
+          payload: frozen_text(payload), path: frozen_text(path), line: line, column: column
+        )
         @mutex.synchronize do
           return if @unresolved_payloads.include?(entry)
 
@@ -56,8 +101,11 @@ module Rigor
 
       # Records a `dynamic.shape.lossy-projection` event for one of the five shape-projection heads. `head` MUST
       # be a String (`"pick_of"`, `"omit_of"`, …); the diagnostic message identifies which projection degraded.
-      def record_lossy_projection(head:, source_location: nil)
-        entry = LossyProjectionEntry.new(head: head.to_s, source_location: source_location)
+      # The position triple is read exactly as {#record_unresolved}'s is.
+      def record_lossy_projection(head:, path: nil, line: nil, column: nil)
+        entry = LossyProjectionEntry.new(
+          head: frozen_text(head), path: frozen_text(path), line: line, column: column
+        )
         @mutex.synchronize do
           return if @lossy_projections.include?(entry)
 
@@ -65,10 +113,68 @@ module Rigor
         end
       end
 
+      # @return frozen snapshot of the accumulated hkt-directive failures.
+      def hkt_directive_errors
+        @mutex.synchronize { @hkt_directive_errors.dup.freeze }
+      end
+
+      # Records a `dynamic.rbs-extended.hkt-directive-invalid` event: one malformed ADR-20 HKT directive the
+      # {Rigor::RbsExtended::HktDirectives} parser declined. `message` names what the parser objected to; the
+      # position triple is the annotation's `.rbs` file / line / 1-based column, each `nil` when the caller had
+      # no location (the diagnostic then falls back to `.rigor.yml:1:1`).
+      #
+      # Every String is frozen individually, not just the enclosing `Data`: the entry crosses the pool drain
+      # channel, whose stated invariant is that its payload is `Ractor.shareable?` as well as Marshal-clean.
+      def record_hkt_error(message:, path: nil, line: nil, column: nil)
+        entry = HktDirectiveEntry.new(
+          message: frozen_text(message), path: frozen_text(path), line: line, column: column
+        )
+        @mutex.synchronize do
+          return if @hkt_directive_errors.include?(entry)
+
+          @hkt_directive_errors << entry
+        end
+      end
+
+      # @return frozen snapshot of the accumulated deprecated-form events.
+      def deprecated_forms
+        @mutex.synchronize { @deprecated_forms.dup.freeze }
+      end
+
+      # Records a `dynamic.rbs-extended.deprecated-form` event (ADR-109 WD3): `payload` is the spelling the
+      # author wrote (`int<5, 10>`), `replacement` the spelling the same type displays as (`Integer[5..10]`),
+      # so the row can say exactly what to write instead. The position triple is read exactly as
+      # {#record_unresolved}'s is, and every String is frozen for the pool drain.
+      def record_deprecated_form(payload:, replacement:, path: nil, line: nil, column: nil)
+        entry = DeprecatedFormEntry.new(
+          payload: frozen_text(payload), replacement: frozen_text(replacement),
+          path: frozen_text(path), line: line, column: column
+        )
+        @mutex.synchronize do
+          return if @deprecated_forms.include?(entry)
+
+          @deprecated_forms << entry
+        end
+      end
+
       # True when no events have accumulated. Used by callers that want to skip the diagnostic-emission pass
       # entirely on the common no-event path.
       def empty?
-        @mutex.synchronize { @unresolved_payloads.empty? && @lossy_projections.empty? }
+        @mutex.synchronize do
+          @unresolved_payloads.empty? && @lossy_projections.empty? && @hkt_directive_errors.empty? &&
+            @deprecated_forms.empty?
+        end
+      end
+
+      private
+
+      # `nil` stays `nil` — the diagnostic falls back to `.rigor.yml:1:1` on a missing path. Anything else
+      # becomes an individually frozen String: the `Data` wrapper is frozen on its own, but the pool drain's
+      # stated invariant is that its payload is `Ractor.shareable?`, which is a DEEP freeze. Coercing here also
+      # means a caller that hands the door an `RBS::Location` by mistake stores its `#to_s`, not the object —
+      # the entry cannot become un-Marshalable from the outside.
+      def frozen_text(value)
+        value.nil? ? nil : value.to_s.dup.freeze
       end
     end
   end

data/lib/rigor/rbs_extended.rb

@@ -92,23 +92,60 @@ module Rigor
       end
     end
 
+    # The shared empty answers of the per-method readers. Dispatch consults the three readers on every RBS
+    # method it resolves (~150k each on the lib self-check) and nearly every method carries no `rigor:v1:`
+    # annotation, so a fresh `[]` / `{}` per decline was pure allocation. Callers never mutate a reader's
+    # result (`read_flow_contribution` selects into fresh arrays; the override map is documented read-only).
+    NO_DIRECTIVES = [].freeze
+    private_constant :NO_DIRECTIVES
+    NO_OVERRIDES = {}.freeze
+    private_constant :NO_OVERRIDES
+
+    # `%a{rigor:v1:inferred-return}` — the declaration states the member's presence and its parameters and
+    # says nothing about what it returns, so the return comes from the body. Normative in
+    # `docs/type-specification/rbs-extended.md`.
+    INFERRED_RETURN_DIRECTIVE = "rigor:v1:inferred-return"
+
     module_function
 
+    # Whether `method_def` declares its return type inferred rather than contracted (issue #823).
+    #
+    # The producer is `rigor-rbs-inline`: inside a file that carries one annotation, upstream rbs-inline
+    # emits a `(untyped, …) -> untyped` skeleton for every unannotated `def` too, and an accepted signature
+    # outranks body inference — so one annotation used to retype every sibling in its file to `untyped`.
+    # The plugin now marks exactly the type slots it DEFAULTED, and {MethodDispatcher::RbsDispatch} declines
+    # a marked member so the call takes the same body-inference tier an undeclared method takes. Nothing
+    # else about the declaration changes: the class keeps its full method surface, `new` keeps its arity,
+    # and cross-file references still resolve.
+    #
+    # Reads `RBS::Definition::Method#annotations`, so it answers for an inherited member too, and a
+    # hand-written `.rbs` may carry the annotation for the same effect.
+    #
+    # @param method_def — an `RBS::Definition::Method`, or anything else answering `#annotations`.
+    def inferred_return?(method_def)
+      return false if method_def.nil?
+
+      annotations = method_def.annotations
+      return false if annotations.nil? || annotations.empty?
+
+      annotations.any? { |annotation| annotation.string.to_s.strip == INFERRED_RETURN_DIRECTIVE }
+    end
+
     # Reads RBS::Extended predicate effects off `RBS::Definition::Method#annotations`. Returns the effects in
     # source order; duplicates and unrecognised `rigor:v1:` directives are dropped. Returns an empty array (NEVER
     # `nil`) for a method with no recognised annotations so callers can iterate unconditionally.
     #
-    # @param environment [Rigor::Environment, nil] ADR-13 slice
+    # @param environment — ADR-13 slice
     #   3b. When provided, threads the plugin-supplied
     #   `name_scope:` and the per-run reporter through the
     #   annotation-parse path. `nil` (default) preserves the
     #   pre-slice-3b behaviour — no plugin resolvers consulted
     #   and no diagnostics accumulated.
     def read_predicate_effects(method_def, environment: nil)
-      return [] if method_def.nil?
+      return NO_DIRECTIVES if method_def.nil?
 
       annotations = method_def.annotations
-      return [] if annotations.nil? || annotations.empty?
+      return NO_DIRECTIVES if annotations.nil? || annotations.empty?
 
       name_scope = environment&.name_scope
       reporter = environment&.rbs_extended_reporter
@@ -127,10 +164,11 @@ module Rigor
     end
 
     # The right-hand side accepts either a Capitalised class name (with optional `~` negation, optional `::`
-    # prefix, qualified names) OR a kebab-case refinement payload routed through
-    # `Builtins::ImportedRefinements::Parser` (bare names, `name[T]`, `name<min, max>`). The two arms share the
-    # same overall directive shape; the parser detects which form matched by looking at the `class_name` vs
-    # `refinement` capture groups.
+    # prefix, qualified names) OR a refinement payload routed through
+    # `Builtins::ImportedRefinements::Parser` (bare kebab-case names, `name[T]`, the numeric range form
+    # `Integer[1..10]`, and the deprecated `name<min, max>`). The two arms share the same overall directive
+    # shape; the parser detects which form matched by looking at the `class_name` vs `refinement` capture
+    # groups. A class head followed by a bracketed range literal is a refinement (ADR-109), not a class name.
     PREDICATE_DIRECTIVE_PATTERN = /
       \A
       rigor:v1:(?<directive>predicate-if-(?:true|false))
@@ -141,7 +179,7 @@ module Rigor
       (?:
         (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
         |
-        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?)
+        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?|[A-Z][A-Za-z0-9_]*\[[^\]]*\.\.[^\]]*\])
       )
       \s*
       \z
@@ -183,10 +221,10 @@ module Rigor
     #
     # See {.read_predicate_effects} for the `environment:` keyword contract.
     def read_assert_effects(method_def, environment: nil)
-      return [] if method_def.nil?
+      return NO_DIRECTIVES if method_def.nil?
 
       annotations = method_def.annotations
-      return [] if annotations.nil? || annotations.empty?
+      return NO_DIRECTIVES if annotations.nil? || annotations.empty?
 
       name_scope = environment&.name_scope
       reporter = environment&.rbs_extended_reporter
@@ -214,7 +252,7 @@ module Rigor
       (?:
         (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
         |
-        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?)
+        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?|[A-Z][A-Za-z0-9_]*\[[^\]]*\.\.[^\]]*\])
       )
       \s*
       \z
@@ -352,7 +390,8 @@ module Rigor
 
     # The trailing payload supports the full refinement grammar in `Builtins::ImportedRefinements::Parser` — bare
     # kebab-case names plus parameterised forms like `non-empty-array[Integer]`, `non-empty-hash[Symbol,
-    # Integer]`, and `int<5, 10>`. The directive head is consumed by the regex; the rest is forwarded to the
+    # Integer]`, `Integer[5..10]`, and the deprecated `int<5, 10>`. The directive head is consumed by the regex;
+    # the rest is forwarded to the
     # refinement parser. Anything the parser cannot resolve falls back to nil so the call site keeps the
     # RBS-declared return type.
     RETURN_DIRECTIVE_PATTERN = /
@@ -449,7 +488,7 @@ module Rigor
 
     # Returned for `rigor:v1:param: <name> <refinement>`. The parameter name is a Ruby identifier (Symbol); the
     # type is any `Rigor::Type` the refinement parser resolves (bare kebab-case name, parameterised form, or
-    # `int<...>` range — the same grammar the `return:` directive accepts).
+    # `Integer[a..b]` range, or the deprecated `int<a, b>` — the same grammar the `return:` directive accepts).
     ParamOverride = Data.define(:param_name, :type)
 
     # Reads every `rigor:v1:param: <name> <refinement>` directive off `RBS::Definition::Method#annotations` and
@@ -469,10 +508,10 @@ module Rigor
     # argument-check purposes; passing a too-wide `Nominal[String]` argument is flagged as an argument-type
     # mismatch at the call site.
     def read_param_type_overrides(method_def, environment: nil)
-      return [] if method_def.nil?
+      return NO_DIRECTIVES if method_def.nil?
 
       annotations = method_def.annotations
-      return [] if annotations.nil? || annotations.empty?
+      return NO_DIRECTIVES if annotations.nil? || annotations.empty?
 
       name_scope = environment&.name_scope
       reporter = environment&.rbs_extended_reporter
@@ -491,9 +530,10 @@ module Rigor
     # frozen Hash<Symbol, Rigor::Type>; missing keys mean "use the RBS-declared type". Callers MUST treat the
     # hash as read-only.
     def param_type_override_map(method_def, environment: nil)
-      read_param_type_overrides(method_def, environment: environment)
-        .to_h { |o| [o.param_name, o.type] }
-        .freeze
+      overrides = read_param_type_overrides(method_def, environment: environment)
+      return NO_OVERRIDES if overrides.empty?
+
+      overrides.to_h { |o| [o.param_name, o.type] }.freeze
     end
 
     # The `is` glue word is optional so authors can write either `param: id is non-empty-string` (consistent with
@@ -708,9 +748,9 @@ module Rigor
     # `RBS::Extended` conflict channel) rather than silently resolved. Returns `nil` when the list
     # carries neither spelling.
     #
-    # @param annotations [Array<#string>] the node's annotations, in source order.
-    # @param owner_key [String] the method key (`Class#m` / `Class.m`) or class name the bound binds.
-    # @param source [Symbol] {Effects::Envelope::SOURCES} member to stamp when the labelled spelling
+    # @param annotations — the node's annotations, in source order.
+    # @param owner_key — the method key (`Class#m` / `Class.m`) or class name the bound binds.
+    # @param source — {Effects::Envelope::SOURCES} member to stamp when the labelled spelling
     #   matched; `%a{pure}` always stamps `:pure_annotation`, and a class-level read overrides both.
     def read_effect_envelope(annotations, owner_key:, source: :effect_annotation, registry: nil, reporter: nil)
       return nil if annotations.nil? || annotations.empty?
@@ -812,10 +852,15 @@ module Rigor
     # ADR-13 slice 3b — guards every reporter call so the in-RbsExtended-module call sites can record events
     # uniformly without nil-checking each time. When the reporter is nil (the v0.1.0 → v0.1.3 default for call
     # sites that do not yet thread `environment:`), the call is a no-op and the parser stays fail-soft.
+    #
+    # Issue #805 — the location is flattened to `(path, line, column)` here, at record time, because the
+    # entry is drained out of every fork-pool worker and an `RBS::Location` neither survives `Marshal.dump`
+    # nor compares equal across two workers' buffers (see {Rigor::RbsExtended::Reporter}).
     def record_unresolved(reporter, payload, source_location)
       return if reporter.nil?
 
-      reporter.record_unresolved(payload: payload, source_location: source_location)
+      path, line, column = Reporter.position_of(source_location)
+      reporter.record_unresolved(payload: payload, path: path, line: line, column: column)
     end
   end
 end

data/lib/rigor/reflection/constant_path.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Rigor
+  # {Reflection}'s second constant-resolution phase, split out for the reader rather than for the
+  # loader: `reflection.rb` asks what a whole spelling names under a series of prefixes, and this file
+  # asks what a PATH names segment by segment. Reopening the module rather than nesting under it keeps
+  # the walk inside the facade its callers already read, and lets it use the same private candidate
+  # lookups (`constant_type_at`, `enclosing_class_path`, `ancestor_constant_scopes`) the ladder uses.
+  module Reflection
+    module_function
+
+    # Issue #656 — Ruby's lookup for an as-written, unrooted constant PATH (`A::B`, `A::B::C`), which is
+    # a different question from "what does this whole string name under some prefix". Ruby resolves the
+    # FIRST segment through the ladder a bare name gets — `Module.nesting`, then the enclosing class's
+    # ancestors, then the top level — and then resolves each LATER segment inside the constant the
+    # previous segment produced, searching THAT constant's own ancestors in turn. So `A::B` written in
+    # `P::Guard` with `P::A < P::Base` names `P::Base::B`, while every whole-path candidate
+    # (`P::Guard::A::B`, `P::A::B`, `A::B`) either misses or names a real but different class.
+    #
+    # `known` decides the FINAL segment only, so the constant typer (any constant, values included) and
+    # `Inference::Narrowing`'s class-guard resolver (classes only) share one walk without sharing an
+    # acceptance test — the two cannot answer different names for the same spelling. Every earlier
+    # segment must name a namespace, because only a namespace can own the next one.
+    #
+    # Returns nil for a single-segment name — the callers' own ladders already own that case — and the
+    # moment any segment declines. Declining hands the caller back its unchanged fallback instead of a
+    # guess: a walk that finds the WRONG constant is worse than the wrong constant answered today
+    # (AGENTS.md § "Implementation Guidelines").
+    #
+    # Checked against MRI 4.0.5 rather than recollection: a later segment does NOT reach the top level
+    # for either a Class or a Module owner (`P::Mod::B` raises `NameError` where a top-level `B`
+    # exists), which is why {.constant_in_namespace} consults the owner's ancestors and stops. Rigor
+    # still lets its callers fall through to their own top-level rung there — that read raises at
+    # runtime and Rigor reports nothing about it either way, so retracting the resolution would trade a
+    # silent wrong answer for a silent absent one at no gain (the same reasoning as
+    # {.toplevel_first_constant_type}'s caller-derived rungs).
+    def resolve_constant_path_name(name, scope, &known)
+      segments = name.to_s.split("::")
+      return nil unless segments.size > 1
+
+      owner = path_head_owner(segments.first, scope)
+      last = segments.size - 1
+      segments.each_with_index do |segment, index|
+        next if index.zero?
+        return nil if owner.nil?
+
+        owner = constant_in_namespace(owner, segment, scope) do |candidate|
+          index == last ? known.call(candidate) : namespace_known?(candidate, scope)
+        end
+      end
+      owner
+    end
+
+    # Step 2.5's rung as a type: the segment-wise name, then that name looked up like any other
+    # candidate so the answer comes from the same source-precedence order as every other rung.
+    def constant_path_type(name, scope)
+      qualified = resolve_constant_path_name(name, scope) { |candidate| constant_type_at(candidate, scope) }
+      qualified && constant_type_at(qualified, scope)
+    end
+    private_class_method :constant_path_type
+
+    # The namespace a path's FIRST segment names — the bare-name ladder, restricted to answers that can
+    # OWN the segments that follow. A value constant is not one of them, so it declines here rather
+    # than producing a namespace prefix no source knows.
+    def path_head_owner(head, scope)
+      hit = first_namespace_hit(lexical_nesting_chain(scope), head, scope)
+      return hit if hit
+
+      prefix = enclosing_class_path(scope)
+      unless prefix.nil? || prefix.empty?
+        hit = first_namespace_hit(bounded_ancestor_scopes(prefix, scope), head, scope)
+        return hit if hit
+      end
+
+      head if namespace_known?(head, scope)
+    end
+    private_class_method :path_head_owner
+
+    # {.first_constant_hit}'s namespace twin: the first `<entry>::<name>` that can own further segments.
+    def first_namespace_hit(entries, name, scope)
+      entries.each do |entry|
+        candidate = "#{entry}::#{name}"
+        return candidate if namespace_known?(candidate, scope)
+      end
+      nil
+    end
+    private_class_method :first_namespace_hit
+
+    # `segment` looked up inside `owner` and then through `owner`'s own ancestors — Ruby's lookup for
+    # every segment after the first. `Object` is deliberately absent: MRI raises rather than reaching a
+    # top-level constant through an explicit `::` receiver.
+    def constant_in_namespace(owner, segment, scope)
+      candidate = "#{owner}::#{segment}"
+      return candidate if yield(candidate)
+
+      bounded_ancestor_scopes(owner, scope).each do |ancestor|
+        inherited = "#{ancestor}::#{segment}"
+        return inherited if yield(inherited)
+      end
+      nil
+    end
+    private_class_method :constant_in_namespace
+
+    # How many of {.ancestor_constant_scopes}' entries one segment may consult, under
+    # `Scope::ANCESTOR_WALK_LIMIT` — the budget `Scope`'s method lookup already spends on this same
+    # graph, reused rather than re-chosen so one pathological ancestry costs one bound. The list
+    # itself is the memoised one step 2 builds, so this bounds the per-segment consultation the walk
+    # adds and not the graph. Reported through the shared counter, so a truncated walk is visible in a
+    # budget trace instead of looking like a plain miss.
+    def bounded_ancestor_scopes(class_name, scope)
+      scopes = ancestor_constant_scopes(class_name, scope)
+      return scopes if scopes.size <= Scope::ANCESTOR_WALK_LIMIT
+
+      Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
+      scopes.first(Scope::ANCESTOR_WALK_LIMIT)
+    end
+    private_class_method :bounded_ancestor_scopes
+
+    # Whether `name` can OWN a constant. `class_known?` covers the RBS and registry classes and modules;
+    # the project tables cover a namespace the project declares with no RBS for it.
+    def namespace_known?(name, scope)
+      scope.environment.class_known?(name) || known_project_namespace?(name, scope)
+    end
+    private_class_method :namespace_known?
+  end
+end

data/lib/rigor/reflection.rb

@@ -51,9 +51,6 @@ module Rigor
 
     module_function
 
-    # @param class_name [String, Symbol]
-    # @param scope [Rigor::Scope]
-    # @return [Boolean]
     def class_known?(class_name, scope: Scope.empty)
       return true if scope.discovered_classes.key?(class_name.to_s)
 
@@ -92,7 +89,7 @@ module Rigor
       loader.project_declared_class?(class_name)
     end
 
-    # @return [Symbol] one of `:equal`, `:subclass`, `:superclass`,
+    # @return one of `:equal`, `:subclass`, `:superclass`,
     #   `:disjoint`, `:unknown`.
     def class_ordering(lhs, rhs, scope: Scope.empty)
       scope.environment.class_ordering(lhs, rhs)
@@ -171,9 +168,16 @@ module Rigor
       # § "Implementation Guidelines"). Only project ancestors are walked; an RBS-known superclass
       # contributes no name here (see {.ancestor_constant_scopes}).
       #
+      # Step 2.5 (#656) — the path read SEGMENT BY SEGMENT, which is the only rung that can answer a
+      # path whose head and tail have different owners. See {.resolve_constant_path_name}. It sits
+      # BELOW the whole-path rungs so no read that resolves today moves, and ABOVE step 3 because
+      # beating the top-level whole-string answer is the point: `A::B` inside `P::Guard` with
+      # `P::A < P::Base` is `P::Base::B`, and step 3's `A::B` is a real but different class.
+      #
       # Step 3 — the bare name (top level).
       first_constant_hit(lexical_nesting_chain(scope), name, scope) ||
         ancestor_constant_type(name, scope, enclosing_class_path(scope)) ||
+        constant_path_type(name, scope) ||
         constant_type_at(name, scope)
     end
 
@@ -215,8 +219,12 @@ module Rigor
     # dependabot-core — `docs/notes/20260905-toplevel-def-cref-movable-sites.md`). Rigor reports nothing
     # about them either way, so retracting them would trade a silent wrong answer for a silent absent one at
     # no gain. Making them FIRE is a separate question with its own false-positive budget.
+    #
+    # Issue #656's rung goes LAST here rather than second: for a top-level body Ruby's own first answer
+    # for `A::B` is the top level, and a whole-string hit there already means "`A` owns `B`". The
+    # segment-wise walk only has something to add once that misses.
     def toplevel_first_constant_type(name, scope)
-      constant_type_at(name, scope) || caller_derived_constant_type(name, scope)
+      constant_type_at(name, scope) || caller_derived_constant_type(name, scope) || constant_path_type(name, scope)
     end
     private_class_method :toplevel_first_constant_type
 
@@ -242,11 +250,16 @@ module Rigor
       singleton = env.singleton_for_name(candidate)
       return singleton if singleton
 
+      # Issue #639 — the class-EXISTENCE edge. Without it a reference-only consumer (`Foo` with no call on
+      # it) recorded nothing, so deleting the declaring file left the warm `--incremental` run serving
+      # `singleton(Foo)` where `--no-cache` answers the honest unresolved type. Recorded ahead of the lookup
+      # rather than on the hit: every rung of the ladder spells the same last segment, which is the whole of
+      # the key, so one call covers the candidates instead of a branch around each.
+      scope.record_class_existence(candidate) if Analysis::DependencyRecorder.active?
       in_source_class = scope.discovered_classes[candidate]
       return in_source_class if in_source_class
 
-      in_source_value = scope.in_source_constants[candidate]
-      if in_source_value
+      if (in_source_value = scope.in_source_constants[candidate])
         scope.record_constant_dependency(candidate) if Analysis::DependencyRecorder.active?
         return in_source_value
       end
@@ -465,15 +478,14 @@ module Rigor
     end
     private_class_method :rbs_loader_for
 
-    # @return [Boolean] true when the analyzed source contains a class / module declaration
+    # @return true when the analyzed source contains a class / module declaration
     #   for the given name. Does NOT consult the RBS loader (use {.class_known?} for the
     #   union).
     def discovered_class?(class_name, scope: Scope.empty)
       scope.discovered_classes.key?(class_name.to_s)
     end
 
-    # @param kind [:instance, :singleton]
-    # @return [Boolean] true when the ScopeIndexer recorded a `def` for the given method on
+    # @return true when the ScopeIndexer recorded a `def` for the given method on
     #   the given class with the matching kind.
     #
     # ADR-46 — a MISS records a negative cross-file dependency, so a consumer whose analysis
@@ -497,3 +509,7 @@ module Rigor
     end
   end
 end
+
+# Loaded last: the segment-wise path walk reopens the module above and reads its private candidate
+# lookups, so the facade has to exist first.
+require_relative "reflection/constant_path"

data/lib/rigor/runtime/jit.rb

@@ -70,7 +70,7 @@ module Rigor
       # call is what enabled YJIT (so the `?`-suffix predicate convention does
       # not apply; hence the Naming/PredicateMethod exemption).
       #
-      # @return [Boolean] true if this call enabled YJIT; false if it was a
+      # @return true if this call enabled YJIT; false if it was a
       #   no-op (unavailable / opted out / already enabled).
       def enable_now # rubocop:disable Naming/PredicateMethod
         return false unless available?
@@ -90,8 +90,8 @@ module Rigor
       # up front (unavailable / opted out / already enabled), so callers never
       # pay for a thread that could only no-op.
       #
-      # @param seconds [Numeric] the amortization deadline.
-      # @return [Thread, nil] the deadline thread, or nil when no-op up front.
+      # @param seconds — the amortization deadline.
+      # @return the deadline thread, or nil when no-op up front.
       def enable_after(seconds)
         return nil unless available?
         return nil if disabled?
@@ -143,7 +143,7 @@ module Rigor
       # Re-arming goes through {enable_after}, so the child records the same
       # absolute deadline it inherited and a grandchild fork carries it too.
       #
-      # @return [Thread, nil] the child's deadline thread; nil when YJIT was
+      # @return the child's deadline thread; nil when YJIT was
       #   enabled immediately, and nil when the call is a no-op up front
       #   (unavailable / opted out / already enabled — a child forked after the
       #   parent enabled inherits the enabled state and has nothing to do).
@@ -166,8 +166,6 @@ module Rigor
 
       # The resolved {enable_after} deadline: {DEADLINE_ENV} when it parses to a
       # non-negative float, else {DEFAULT_DEADLINE_SECONDS}.
-      #
-      # @return [Numeric]
       def deadline_seconds
         raw = ENV.fetch(DEADLINE_ENV, nil)
         return DEFAULT_DEADLINE_SECONDS if raw.nil? || raw.empty?
@@ -176,12 +174,12 @@ module Rigor
         value && value >= 0 ? value : DEFAULT_DEADLINE_SECONDS
       end
 
-      # @return [Boolean] whether this Ruby exposes `RubyVM::YJIT.enable`.
+      # @return whether this Ruby exposes `RubyVM::YJIT.enable`.
       def available?
         defined?(RubyVM::YJIT.enable) ? true : false
       end
 
-      # @return [Boolean] whether the opt-out env switch is set.
+      # @return whether the opt-out env switch is set.
       def disabled?
         ENV[DISABLE_ENV] == "1"
       end