rigortype 0.4.7 → 0.4.8

data/lib/rigor/inference/string_mutation.rb

@@ -80,6 +80,20 @@ module Rigor
         type.is_a?(Type::Constant) && type.value.is_a?(String)
       end
 
+      # A predicate refinement over String (`decimal-int-string`, `lowercase-string`) under a String mutator → its
+      # `String` base. Any in-place mutation can falsify the predicate (`s.clear` leaves a `decimal-int-string`
+      # empty, `s << "A"` a `lowercase-string` mixed-case), so none keeps it. `nil` for every other input.
+      def widen_refined(refined, method_name)
+        return nil unless refined?(refined)
+        return nil unless MUTATORS.include?(method_name)
+
+        refined.base
+      end
+
+      def refined?(type)
+        type.is_a?(Type::Refined) && type.base.is_a?(Type::Nominal) && type.base.class_name == "String"
+      end
+
       # Whether `method_name`, called with `arg_types` (the call's positional argument types, possibly none), can leave
       # a non-empty receiver empty, and so retract a `non-empty-string` refinement. Every mutator outside
       # {EMPTY_PRESERVING} can, except a {TRANSLATORS} call whose replacement is provably non-empty.

data/lib/rigor/inference/synthetic_method_scanner.rb

@@ -323,21 +323,29 @@ module Rigor
       # - `class_methods do ... end` blocks are NOT yet handled —
       #   singleton-level emission is out of scope per the slice-3
       #   floor framing.
+      #
+      # Issue #3005 — the `included do` blocks of every body of a module some body extends with Concern are read: a
+      # reopening that does not repeat the `extend` runs its block on a module that is already a concern (loaded
+      # first, its `included do` raises, so no running program has the includer without the calls). A module no
+      # body extends with Concern contributes nothing.
       CONCERN_NAME = "ActiveSupport::Concern"
 
       def build_concern_index(asts)
-        index = {}
+        bodies = Hash.new { |hash, name| hash[name] = [] }
         asts.each_value do |ast|
           next if ast.nil?
 
           walk_module_decls(ast, []) do |module_name, body|
-            next if module_name.nil? || body.nil?
-            next unless concern_module_body?(body)
-
-            deferred_calls = collect_included_do_calls(body)
-            index[module_name] = deferred_calls.freeze if deferred_calls.any?
+            bodies[module_name] << body unless module_name.nil? || body.nil?
           end
         end
+        index = {}
+        bodies.each do |module_name, list|
+          next unless list.any? { |body| concern_module_body?(body) }
+
+          deferred_calls = list.flat_map { |body| collect_included_do_calls(body) }
+          index[module_name] = deferred_calls.freeze if deferred_calls.any?
+        end
         index.freeze
       end
 
@@ -359,18 +367,34 @@ module Rigor
       end
 
       # Recognises a module body that begins with (or contains at top level) an `extend ActiveSupport::Concern`
-      # statement.
+      # statement. Issue #3005 — `self.extend` and a receiverless or `self.` `send` / `public_send` /
+      # `__send__(:extend, …)` are the same call.
       def concern_module_body?(body)
         return false unless body.respond_to?(:body)
 
         body.body.any? do |stmt|
-          next false unless stmt.is_a?(Prism::CallNode) && stmt.receiver.nil? && stmt.name == :extend
-
-          args = stmt.arguments&.arguments || []
-          args.any? { |arg| const_name_string(arg) == CONCERN_NAME }
+          args = concern_extend_arguments(stmt)
+          args&.any? { |arg| const_name_string(arg) == CONCERN_NAME }
         end
       end
 
+      CONCERN_SEND_CALLS = %i[send public_send __send__].freeze
+      private_constant :CONCERN_SEND_CALLS
+
+      # The modules an `extend` statement on the module's own `self` names, or nil for any other statement.
+      def concern_extend_arguments(stmt)
+        return nil unless stmt.is_a?(Prism::CallNode)
+        return nil unless stmt.receiver.nil? || stmt.receiver.is_a?(Prism::SelfNode)
+
+        args = stmt.arguments&.arguments || []
+        return args if stmt.name == :extend
+        return nil unless CONCERN_SEND_CALLS.include?(stmt.name)
+
+        name = args.first
+        sent = name.unescaped if name.is_a?(Prism::SymbolNode) || name.is_a?(Prism::StringNode)
+        sent == "extend" ? args.drop(1) : nil
+      end
+
       def collect_included_do_calls(body)
         body.body.flat_map do |stmt|
           included_do = stmt.is_a?(Prism::CallNode) && stmt.receiver.nil? && stmt.name == :included

data/lib/rigor/inference/toplevel_def_census.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "../run_scoped_slots"
-require_relative "memo_audit"
+require_relative "../typing_state"
+require_relative "../memo_audit"
 
 module Rigor
   module Inference
@@ -23,8 +23,14 @@ module Rigor
     # is bypassed while one is active, as the callee floor's other memos are.
     module ToplevelDefCensus
       OBJECT_OWNERS = %w[Object Kernel BasicObject].freeze
-      RELIABLE_KEY = RunScopedSlots.register(:rigor_toplevel_def_reliable)
-      private_constant :OBJECT_OWNERS, :RELIABLE_KEY
+      # ADR-129 WD1 — a run-scoped Memo, per discovery index and name: the answer is a function of both, and
+      # `MemoAudit` checks it on a hit.
+      RELIABLE = TypingState.memo(
+        :toplevel_def_reliable,
+        run_scoped: true, audit: "top-level def census",
+        reason: "keyed by discovery index, then name; the environment is the run's; audited by MemoAudit"
+      )
+      private_constant :OBJECT_OWNERS, :RELIABLE
 
       module_function
 
@@ -32,9 +38,11 @@ module Rigor
       def reliable?(scope, name)
         return compute?(scope, name) if Analysis::DependencyRecorder.active? || MemoAudit.suspended?
 
-        table = (Thread.current[RELIABLE_KEY] ||= ObjectSpace::WeakKeyMap.new)
+        table = TypingState.current.weak_key_map(RELIABLE)
         by_name = (table[scope.discovery] ||= {})
-        return by_name[name] = compute?(scope, name) unless by_name.key?(name)
+        unless by_name.key?(name)
+          return by_name[name] = MemoAudit.key_audit("top-level def census") { compute?(scope, name) }
+        end
 
         MemoAudit.check("top-level def census", by_name[name], name) { compute?(scope, name) }
       end

data/lib/rigor/inference/unknown_store_widening.rb

@@ -165,7 +165,7 @@ module Rigor
           arg.members.any? { |member| !member.is_a?(Type::Constant) && !gradual_top?(member) }
       end
 
-      def gradual_top?(member) = member.is_a?(Type::Dynamic) && member.static_facet.is_a?(Type::Top)
+      def gradual_top?(member) = Type::Combinator.untyped?(member)
 
       # `Dynamic[top] | A | B` as `Dynamic[A | B]` for the class members; a literal member (a value-pinned key) and any
       # other element stay as they are.

data/lib/rigor/inference/untyped_rejoin.rb

@@ -57,7 +57,7 @@ module Rigor
       end
 
       def candidate?(entry_type, joined_type)
-        entry_type.is_a?(Type::Dynamic) && entry_type.static_facet.is_a?(Type::Top) &&
+        Type::Combinator.untyped?(entry_type) &&
           joined_type.is_a?(Type::Union) && joined_type.members.any?(Type::Dynamic)
       end
 

data/lib/rigor/inference/void_tail_summary.rb

@@ -5,7 +5,8 @@ require "prism"
 require_relative "void_origin"
 require_relative "../reflection"
 require_relative "../source/node_children"
-require_relative "../run_scoped_slots"
+require_relative "../typing_state"
+require_relative "../memo_audit"
 
 module Rigor
   module Inference
@@ -54,8 +55,8 @@ module Rigor
     # cycle (nil). Memoising is therefore always sound, and the cycle guard only ever rejects a node that
     # is still mid-computation on the current chain (never yet memoised).
     class VoidTailSummary
-      # Run-scoped memo, the ADR-84 `return_memo_bucket` house pattern: a single retained slot on
-      # `Thread.current` keyed by the run-generation token's identity, so a re-run in one process (LSP,
+      # Run-scoped memo, the ADR-84 `return_memo_bucket` house pattern: a single retained slot in
+      # the thread's {TypingState} keyed by the run-generation token's identity, so a re-run in one process (LSP,
       # ADR-62 warm loop) lands in a fresh bucket and can neither serve stale entries nor accumulate
       # them. Thread-local ⇒ each fork-pool worker (a separate process) and each Ractor-pool worker (its
       # own Ractor-local `Thread.current`) builds its own bucket; the bucket hash is created and mutated
@@ -63,8 +64,15 @@ module Rigor
       # graceful-degradation branch is needed. `def_node` identity is stable per run (the ADR-85
       # {DefNodeResolver} yields one node object per `(path, node_id)`), the same identity the ADR-84
       # return memo relies on.
-      MEMO_KEY = RunScopedSlots.register(:__rigor_void_tail_summary_memo__)
-      private_constant :MEMO_KEY
+      #
+      # ADR-129 WD1 — a run-scoped Memo keyed on the token's identity: the bucket holds summaries that are pure
+      # functions of the def node they key on within one run.
+      MEMO = TypingState.memo(
+        :void_tail_summary,
+        run_scoped: true, audit: ["void tail origin", "void tail walk"],
+        reason: "a bucket of per-def-node summaries, keyed on the run-generation token's identity"
+      )
+      private_constant :MEMO
 
       def initialize(scope)
         @scope = scope
@@ -82,7 +90,11 @@ module Rigor
         return nil if def_node.nil?
 
         memo = memo_bucket
-        return memo[def_node] if memo.key?(def_node)
+        if memo.key?(def_node)
+          return MemoAudit.check("void tail origin", memo[def_node], def_node) do
+            walk(def_node, owner, kind, {}.compare_by_identity)
+          end
+        end
 
         walk(def_node, owner, kind, {}.compare_by_identity)
       end
@@ -98,10 +110,14 @@ module Rigor
         return nil if visited.key?(def_node)
 
         memo = memo_bucket
-        return memo[def_node] if memo.key?(def_node)
+        if memo.key?(def_node)
+          return MemoAudit.check("void tail walk", memo[def_node], def_node) do
+            walk(def_node, owner, kind, {}.compare_by_identity)
+          end
+        end
 
         visited[def_node] = true
-        memo[def_node] = compute(def_node, owner, kind, visited)
+        memo[def_node] = MemoAudit.key_audit("void tail walk") { compute(def_node, owner, kind, visited) }
       end
 
       def compute(def_node, owner, kind, visited)
@@ -206,11 +222,14 @@ module Rigor
       end
 
       def memo_bucket
+        return {}.compare_by_identity if MemoAudit.enabled? && MemoAudit.suspended?
+
         generation = scope.run_generation || scope.discovered_def_nodes
-        slot = Thread.current[MEMO_KEY]
+        state = TypingState.current
+        slot = state[MEMO]
         unless slot && slot[0].equal?(generation)
           slot = [generation, {}.compare_by_identity]
-          Thread.current[MEMO_KEY] = slot
+          state[MEMO] = slot
         end
         slot[1]
       end

data/lib/rigor/lens/claims/comparison.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../../environment/member_consistency"
+
+module Rigor
+  module Lens
+    class Claims
+      # The deliberately small proof fragment of lens-claims.md. Unknown is not a failed subtype check.
+      class Comparison
+        def initialize(loader, relative_conflict:)
+          @loader = loader
+          @proof = Environment::MemberConsistency::RbsProof.new(loader)
+          @relative_conflict = relative_conflict
+        end
+
+        def call(sub, sup)
+          included = sub.map do |arm|
+            match = sup.filter_map do |other|
+              (rule = inclusion(arm, other)) && evidence(rule, arm, other.display)
+            end.first
+            match
+          end
+          return ["compatible", "proven_inclusion", included] if included.none?(nil)
+
+          sub.each do |arm|
+            rules = sup.map { |other| disjoint(arm, other) }
+            next if rules.any?(nil)
+
+            return ["conflict", "proven_disjoint_arm", [evidence(rules.first, arm, sup.map(&:display).join(" | "))]]
+          end
+          ["unknown", "unproven", []]
+        end
+
+        private
+
+        def evidence(rule, arm, against)
+          { "rule" => rule, "arm" => arm.display, "against" => against }
+        end
+
+        def inclusion(sub, sup)
+          return "equal" if sub.identity == sup.identity
+          return nil unless sup.kind == :class && sup.arguments.empty?
+          return nil unless @loader.class_type_param_names(sup.value).empty?
+
+          name = sub.kind == :literal ? sub.value.class.name : sub.value
+          unreliable = Environment::MemberConsistency::RbsProof::UNRELIABLE_ANCESTRY
+          return nil if unreliable.include?(name) || unreliable.include?(sup.value)
+          return nil unless @loader.ancestor_names_for(name).include?(sup.value)
+
+          sub.kind == :literal ? "literal_class_ancestor" : "class_ancestor"
+        end
+
+        def disjoint(left, right)
+          return nil if !@relative_conflict && (left.relative || right.relative)
+          return "distinct_literals" if left.kind == :literal && right.kind == :literal && !left.value.eql?(right.value)
+
+          disjoint_classes(left, right)
+        end
+
+        def disjoint_classes(left, right)
+          left_name = left.kind == :literal ? left.value.class.name : left.value
+          right_name = right.kind == :literal ? right.value.class.name : right.value
+          left_ancestors = @proof.class_ancestors(left_name)
+          right_ancestors = @proof.class_ancestors(right_name)
+          return nil if left_ancestors.nil? || right_ancestors.nil?
+
+          if left.kind == :literal
+            "literal_outside_class" unless left_ancestors.include?(right_name)
+          elsif right.kind == :literal
+            "literal_outside_class" unless right_ancestors.include?(left_name)
+          elsif !left_ancestors.include?(right_name) && !right_ancestors.include?(left_name)
+            "unrelated_classes"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/lens/claims/request.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  module Lens
+    class Claims
+      class IntegrityError < StandardError; end
+
+      # Validates transport and source identity before the incremental session is started.
+      class Request
+        attr_reader :claims, :digest, :paths
+
+        def self.read(path, root:, arguments:)
+          bytes = File.binread(path).force_encoding(Encoding::UTF_8)
+          raise IntegrityError, "claims request is not UTF-8" unless bytes.valid_encoding?
+
+          new(JSON.parse(bytes), digest: Lens.digest(bytes), root: root, arguments: arguments)
+        rescue SystemCallError, JSON::ParserError => e
+          raise IntegrityError, "cannot read claims request: #{e.message}"
+        end
+
+        def initialize(data, digest:, root:, arguments:)
+          @digest = digest
+          @root = root
+          @arguments = arguments.map { |argument| File.expand_path(argument, root) }
+          validate_header(data)
+          @claims = data.fetch("claims")
+          @files = data.fetch("files")
+          @paths = {}
+          @readable_paths = Set.new
+          @preflight = true
+          @files.each { |file| validate_file(file) }
+          ids = []
+          @claims.each do |claim|
+            validate_claim(claim)
+            ids << claim.fetch("id")
+          end
+          require_value(ids.uniq.size == ids.size, "duplicate claim id")
+          verify_sources!
+          @preflight = false
+        end
+
+        def verify_sources!(targets = [])
+          @files.each do |file|
+            absolute = @paths.fetch(file.fetch("path"))
+            bytes = readable(absolute)
+            target = targets.find { |entry| entry.absolute == absolute }
+            require_value(bytes || (!@readable_paths.include?(absolute) && !target&.reader),
+                          "source became unreadable during analysis: #{file['path']}")
+            @readable_paths << absolute if @preflight && bytes
+            next unless bytes
+
+            require_value(Lens.digest(bytes) == file.fetch("digest"), "stale claims digest: #{file['path']}")
+            if target&.reader
+              require_value(target.reader.digest == file.fetch("digest"),
+                            "source changed during analysis: #{file['path']}")
+            end
+            verify_spans(file, bytes.bytesize)
+          end
+        end
+
+        private
+
+        def verify_spans(file, size)
+          @claims.select { |claim| claim.fetch("file") == file.fetch("path") }.each do |claim|
+            %w[declaration tag].each do |field|
+              require_value(claim.fetch(field).fetch("span").fetch("end_offset") <= size,
+                            "#{field} span outside #{file['path']}")
+            end
+          end
+        end
+
+        def validate_header(data)
+          require_value(data.is_a?(Hash), "claims request must be an object")
+          require_value(data["schema"] == "lens-claims-request/v0", "unsupported claims schema")
+          require_value(data["revision"].is_a?(Integer) && data["revision"] == 1, "unsupported claims revision")
+          require_value(data["grammar"] == "rbs", "unsupported claims grammar")
+          %w[files claims].each { |field| require_value(data[field].is_a?(Array), "#{field} must be an array") }
+        end
+
+        def validate_file(file)
+          strings(file, %w[path digest])
+          path = file.fetch("path")
+          absolute = File.expand_path(path, @root)
+          relative = Pathname(absolute).relative_path_from(Pathname(@root)).to_s
+          require_value(path == relative, "file path must be root-relative: #{path}")
+          require_value(@arguments.include?(absolute), "claims file is not a target: #{path}")
+          require_value(!@paths.key?(path), "duplicate claims file: #{path}")
+          require_value(file.fetch("digest").match?(/\Axxh3-64:[0-9a-f]{16}\z/), "invalid claims file digest")
+          @paths[path] = absolute
+        end
+
+        def validate_claim(claim)
+          strings(claim, %w[id file claim])
+          require_value(@paths.key?(claim.fetch("file")), "claim file is missing from files")
+          declaration = claim["declaration"]
+          strings(declaration, %w[kind owner scope name])
+          tag = claim["tag"]
+          strings(tag, %w[name])
+          require_value(tag.key?("subject") && (tag["subject"].nil? || tag["subject"].is_a?(String)),
+                        "tag subject must be a string or null")
+          [declaration, tag].each { |entry| validate_span(entry["span"]) }
+        end
+
+        def validate_span(span)
+          require_value(span.is_a?(Hash), "span must be an object")
+          start = span["start_offset"]
+          finish = span["end_offset"]
+          require_value(start.is_a?(Integer) && finish.is_a?(Integer) && start >= 0 && finish >= start,
+                        "invalid byte span")
+        end
+
+        def strings(object, fields)
+          require_value(object.is_a?(Hash), "claims entry must be an object")
+          fields.each { |field| require_value(object[field].is_a?(String), "#{field} must be a string") }
+        end
+
+        def require_value(condition, message)
+          raise IntegrityError, message unless condition
+        end
+
+        def readable(path)
+          File.binread(path) if File.file?(path)
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rigor/lens/claims/type_reader.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "rbs"
+require_relative "../../rbs_extended"
+require_relative "../../scope/resolution_chain"
+
+module Rigor
+  module Lens
+    class Claims
+      # Normalizes RBS ASTs without erasing unsupported forms or using display text as identity.
+      class TypeReader
+        Atom = Data.define(:kind, :value, :arguments, :relative) do
+          def identity
+            [kind, value, arguments.map { |arms| arms.to_set(&:identity) }]
+          end
+
+          def display
+            return value.inspect if kind == :literal
+
+            suffix = arguments.empty? ? "" : "[#{arguments.map { |arms| arms.map(&:display).join(' | ') }.join(', ')}]"
+            "::#{value}#{suffix}"
+          end
+        end
+
+        attr_reader :reasons
+
+        def self.parse(text)
+          # An empty, blank or comment-only text parses to nil rather than raising.
+          type = ::RBS::Parser.parse_type(text, require_eof: true)
+          type ? [type, nil] : [nil, "syntax_error"]
+        rescue ::RBS::ParsingError
+          extended = RbsExtended.parse_return_type_override("rigor:v1:return: #{text}")
+          [nil, extended ? "unsupported_grammar_feature" : "syntax_error"]
+        end
+
+        # `owner` is the member's owner; an RBS declaration of the member sits in its namespace, which a builder
+        # block's lexical nesting does not name.
+        def initialize(scope:, nesting:, singleton_nesting: false, owner: nil)
+          @scope = scope
+          @loader = scope.environment.rbs_loader
+          @resolver = @loader.type_name_resolver
+          @nesting = nesting
+          @singleton_nesting = singleton_nesting
+          @context = rbs_context(Array(nesting))
+          @owner_context = owner && owner != "Object" ? rbs_context(owner_namespaces(owner)) : nil
+          @reasons = Set.new
+        end
+
+        def read(type, claim: false, aliases: Set.new)
+          case type
+          when ::RBS::Types::Bases::Any
+            @reasons << "dynamic_type"
+            []
+          when ::RBS::Types::Bases::Bool then [literal(true), literal(false)]
+          when ::RBS::Types::Bases::Nil then [literal(nil)]
+          when ::RBS::Types::Literal then [literal(type.literal)]
+          when ::RBS::Types::Union then type.types.flat_map { |part| read(part, claim: claim, aliases: aliases) }
+          when ::RBS::Types::Optional then read(type.type, claim: claim, aliases: aliases) + [literal(nil)]
+          when ::RBS::Types::Alias then read_alias(type, claim, aliases)
+          when ::RBS::Types::ClassInstance then read_class(type, claim, aliases)
+          else
+            @reasons << "unsupported_type"
+            type.each_type { |part| read(part, claim: claim, aliases: aliases) }
+            []
+          end
+        end
+
+        private
+
+        def rbs_context(names)
+          names.reduce(nil) do |outer, name|
+            type_name = ::RBS::TypeName.parse("::#{name}")
+            @loader.class_known?(name) ? [outer, type_name] : outer
+          end
+        end
+
+        def owner_namespaces(owner)
+          segments = owner.split("::")
+          segments.each_index.map { |index| segments[0..index].join("::") }
+        end
+
+        def literal(value, relative: false)
+          Atom.new(kind: :literal, value: value, arguments: [], relative: relative)
+        end
+
+        def resolve(name, claim)
+          resolved = @resolver&.resolve(name, context: claim ? @context : nil)
+          if resolved.nil?
+            @reasons << "unresolved_name"
+          elsif claim && !name.absolute? && name.class?
+            compare_ruby_name(name, resolved)
+          end
+          resolved
+        end
+
+        def compare_ruby_name(name, resolved)
+          # An unlocated alias body has no known cref. A singleton class's anonymous cref is not a
+          # named namespace either; its constant table and ancestry cannot be read as the owner's.
+          if @nesting.nil? || @singleton_nesting
+            @reasons << "ambiguous_name"
+            return
+          end
+
+          ruby = ruby_name(name.to_s)
+          @reasons << "ambiguous_name" if ruby && ruby != resolved.to_s.delete_prefix("::")
+        end
+
+        def read_class(type, claim, aliases)
+          name = resolve(type.name, claim)
+          arguments = type.args.map { |arg| read(arg, claim: claim, aliases: aliases) }
+          return [] unless name
+
+          key = name.to_s.delete_prefix("::")
+          if !@loader.class_known?(key) || arguments.size != @loader.class_type_param_names(key).size
+            @reasons << "unsupported_type"
+          end
+          singles = { "TrueClass" => true, "FalseClass" => false, "NilClass" => nil }
+          if arguments.empty? && singles.key?(key)
+            return [literal(singles.fetch(key), relative: claim && !type.name.absolute?)]
+          end
+
+          [Atom.new(kind: :class, value: key, arguments: arguments, relative: claim && !type.name.absolute?)]
+        end
+
+        def read_alias(type, claim, aliases)
+          name = resolve(type.name, claim)
+          type.args.each { |arg| read(arg, claim: claim, aliases: aliases) }
+          return [] unless name
+
+          relative = claim && !type.name.absolute?
+          return [] if relative && !alias_name_settled?(type.name, name)
+
+          entry = @loader.type_alias_declaration(name)
+          if entry.nil? || !entry.type_params.empty? || !type.args.empty? || aliases.include?(name)
+            @reasons << "unsupported_type"
+            return []
+          end
+          # The resolved declaration binds names in the alias's namespace, not the claim's lexical scope. Arms
+          # reached through a relatively written name stay relative, so the conflict guard still applies.
+          arms = read(entry.type, aliases: aliases | [name])
+          relative ? arms.map { |arm| arm.with(relative: true) } : arms
+        end
+
+        # A type alias has no Ruby meaning, so the only reading to cross-check is the RBS one: the claim's lexical
+        # context and the member's RBS namespace must resolve a relative alias name alike. An unlocated body or a
+        # singleton-class body has no context to read it in.
+        def alias_name_settled?(written, resolved)
+          if @nesting.nil? || @singleton_nesting
+            @reasons << "ambiguous_name"
+            return false
+          end
+          return true if @owner_context.nil? || @owner_context == @context
+
+          declared = @resolver&.resolve(written, context: @owner_context)
+          return true if declared == resolved
+
+          @reasons << "ambiguous_name"
+          false
+        end
+
+        # Project constants only: a missing entry falls back to RBS, which also knows libraries and gems.
+        # Resolve the first segment before the rest, so a Ruby-only namespace cannot fall through to core.
+        def ruby_name(written)
+          head, *tail = written.split("::")
+          found = project_constant_in(@nesting.reverse, head)
+          found ||= ancestor_constant(head)
+          found = head if found.nil? && (@nesting.empty? || @loader.rbs_module?(@nesting.last)) && project_name?(head)
+          found && ([found] + tail).join("::")
+        end
+
+        def project_constant_in(bases, name)
+          bases.each do |base|
+            candidate = base == "Object" ? name : "#{base}::#{name}"
+            return candidate if project_name?(candidate)
+          end
+          nil
+        end
+
+        def project_name?(name)
+          @scope.declared_class?(name) || @scope.bound_constant_names(name).include?(name)
+        end
+
+        def ancestor_constant(name)
+          chain = Scope::ResolutionChain.for(@scope, @nesting.last || "Object", :instance, :constants)
+          found = chain_constant(chain, name)
+          settled = chain.settle(@scope, found) { |retro| chain_constant(retro, name) }
+          if chain.truncated? || chain.wildcard_mixin? || settled != :chain || opaque_ancestry?(chain)
+            @reasons << "ambiguous_name"
+            return nil
+          end
+          found
+        end
+
+        # A superclass the tables cannot name (`Class.new(Base)`, `< pick`, a builder class's `Struct`/`Data`) or an
+        # external ancestor no RBS declares (`< SomeAlias`): the constants it holds are not on the chain.
+        def opaque_ancestry?(chain)
+          return true if chain.opaque_tail?(@scope)
+
+          chain.entries.any? { |entry| entry.external? && entry.candidates.none? { |name| @loader.class_known?(name) } }
+        end
+
+        def chain_constant(chain, name)
+          chain.search(@scope) do |entry|
+            bases = entry.external? ? external_ancestors(entry) : [entry.name]
+            project_constant_in(bases, name)
+          end
+        end
+
+        def external_ancestors(entry)
+          name = entry.candidates.find { |candidate| @loader.class_known?(candidate) }
+          name ? @loader.ancestor_names_for(name) : []
+        end
+      end
+    end
+  end
+end