rigortype 0.3.8 → 0.4.0

data/lib/rigor/environment/rbs_loader.rb

@@ -4,7 +4,9 @@ require "rbs"
 
 require_relative "../type"
 require_relative "../inference/rbs_type_translator"
+require_relative "../builtins/imported_refinements"
 require_relative "rbs_hierarchy"
+require_relative "member_consistency"
 
 module Rigor
   class Environment
@@ -42,6 +44,19 @@ module Rigor
       # cache HIT. Never a real path, so it must never be reported as one (issue #696).
       CACHED_LOCATION_BUFFER_NAME = "<cached>"
 
+      # Issue #527 — the two directory trees whose `.rbs` files ARE Ruby's own surface: the `rbs` gem's
+      # `core/` and its bundled `stdlib/` repository. {#core_stdlib_classes} tests a declaration's file
+      # against them. Resolved once at load time, on the main Ractor: reading these constants walks a
+      # chain of non-`Ractor.shareable?` module constants and raises `Ractor::IsolationError` inside a
+      # worker (see {#prewarm}). Empty when the rbs version in use does not expose them, which switches
+      # the feature off rather than widening it.
+      CORE_STDLIB_ROOTS = begin
+        [::RBS::EnvironmentLoader::DEFAULT_CORE_ROOT, ::RBS::Repository::DEFAULT_STDLIB_ROOT]
+          .compact.map { |root| "#{root}/".freeze }.freeze
+      rescue StandardError
+        [].freeze
+      end
+
       # Cap on how many quarantined `signature_paths:` files {#warn_about_quarantined_signatures} lists by name
       # before collapsing the tail to "… and N more" — a broken generator can emit many, and a wall of parse
       # errors buries the signal.
@@ -83,10 +98,23 @@ module Rigor
           # mastodon coverage note). Per-file loading quarantines the broken file instead. Vendored / core-overlay
           # sigs are Rigor-shipped and trusted, so they stay on the loader's fast batch path.
           add_bundled_signatures(rbs_loader, loaded_libraries.to_set(&:to_s))
-          env = RBS::Environment.from_loader(rbs_loader)
+          env = unload_upstream_core_shims(RBS::Environment.from_loader(rbs_loader), rbs_loader)
           project_files = project_sig_files(signature_paths)
-          add_project_signatures(env, signature_paths, deferred_signature_paths)
-          add_virtual_rbs(env, virtual_rbs)
+          # Issue #1075 — decided from the inputs before either side enters `env`: the consistency rule may
+          # stand the `.rbs` member down, and that has to happen before its file is added.
+          consistency = member_consistency_for(project_files, virtual_rbs)
+          add_project_signatures(env, signature_paths, deferred_signature_paths,
+                                 standdowns: consistency.signature_standdowns)
+          # Issue #928 — the capability-role catalog goes in AFTER the project's own signatures, per
+          # declaration, so a project that already declares one of these interface names keeps its own
+          # (`add_capability_role_signatures`). The rest of the bundled RBS cannot be ordered that way (it
+          # is what `from_loader` builds the env FROM), which is why a colliding project file is quarantined
+          # instead — and losing a whole `sig/` file to a name as ordinary as `_Closable` is exactly what
+          # shipping a top-level interface catalog would otherwise cost.
+          add_capability_role_signatures(env)
+          # Issues #824 / #1075 — every member a `.rbs` file also declares was ranked above; the inline side of
+          # each pair the `.rbs` won stands down here ({.add_virtual_rbs}), so the two never collide.
+          add_virtual_rbs(env, virtual_rbs, inline_standdowns: consistency.inline_standdowns)
           synthesize_missing_namespaces(env)
           # Issue #777 — resolve-time backstop: also unload colliding PROJECT buffers (class-vs-module /
           # constant redeclarations against bundled RBS). Virtual culprits are preferred when both appear.
@@ -119,8 +147,8 @@ module Rigor
         BIG_MATH_SIG_BASENAME = "big_math.rbs"
         private_constant :BIG_MATH_SIG_BASENAME
 
-        # @param libraries [Array<String>] the resolved library list, `DEFAULT_LIBRARIES` included.
-        # @return [Array<String>] the same list, minus `bigdecimal-math` when `bigdecimal` already brings
+        # @param libraries — the resolved library list, `DEFAULT_LIBRARIES` included.
+        # @return the same list, minus `bigdecimal-math` when `bigdecimal` already brings
         #   `BigMath` in.
         def libraries_without_shadowed_bigdecimal_math(libraries)
           return libraries unless libraries.include?(BIGDECIMAL_LIBRARY) && libraries.include?(BIGDECIMAL_MATH_LIBRARY)
@@ -145,6 +173,55 @@ module Rigor
           false
         end
 
+        # Issue #1109 — the `rbs` gem (a `DEFAULT_LIBRARIES` entry, so in every run) ships the shims its
+        # own Steep check needs under `sig/shims/`, and one of them reopens a core module: `enumerable.rbs`
+        # prepends a `(2) -> Enumerator[[Elem, Elem], void]` overload to `Enumerable#each_slice`. That is
+        # a claim about rbs's own call sites, not about Ruby — `[1, 2, 3].each_slice(2)` yields `[3]` last
+        # — and it leaked into every analysed project: the blockless form typed as a fixed pair (so a
+        # `nil` guard on the second slot folded away) and the block form returned `void` instead of the
+        # receiver. Unloading the file leaves core's `Enumerator[Array[Elem], self]`, which agrees with the
+        # block form's `Array[Elem]`. The other shims (`bundler.rbs`, `rubygems.rbs`) only add missing
+        # declarations and stay. Fails soft to the env as built: a relocated or absent shim, or an rbs API
+        # shape this code does not recognise, keeps the pre-#1109 behaviour rather than failing the build.
+        # Because errors are rescued, the guard spec in `rbs_loader_spec.rb` is what catches a broken unload,
+        # so it must stay green on both lines of the RBS compatibility matrix.
+        RBS_LIBRARY = "rbs"
+        private_constant :RBS_LIBRARY
+        UNSOUND_CORE_SHIMS = %w[shims/enumerable.rbs].freeze
+        private_constant :UNSOUND_CORE_SHIMS
+
+        def unload_upstream_core_shims(env, rbs_loader)
+          return env unless env.respond_to?(:unload)
+
+          shim_names = upstream_core_shim_names(rbs_loader)
+          return env if shim_names.empty?
+
+          buffers = loaded_signature_buffers(env)&.select { |buffer| shim_names.include?(buffer.name.to_s) }
+          buffers.nil? || buffers.empty? ? env : env.unload(buffers)
+        rescue StandardError
+          env
+        end
+
+        # rbs 4.x lists its sources through `each_rbs_source`; rbs 3.x keys `signatures` by `Buffer`, and its
+        # `unload` matches those very objects with `include?`, so the env's own keys are what it must receive.
+        def loaded_signature_buffers(env)
+          if env.respond_to?(:each_rbs_source)
+            env.each_rbs_source.map(&:buffer)
+          elsif env.respond_to?(:signatures)
+            env.signatures.keys
+          end
+        end
+
+        def upstream_core_shim_names(rbs_loader)
+          names = Set.new
+          rbs_loader.each_dir do |source, dir|
+            next unless source.respond_to?(:name) && source.name == RBS_LIBRARY
+
+            UNSOUND_CORE_SHIMS.each { |relative| names << Pathname(dir).join(relative).to_s }
+          end
+          names
+        end
+
         # True when `content` parses as an RBS signature. {#virtual_rbs_collision_quarantined} uses this to
         # tell a collision-dropped virtual entry (parses, but absent from the env) from a parse-failed one
         # (the synthesizer's own WD6 skip, reported separately).
@@ -323,16 +400,21 @@ module Rigor
         # Buffer names are the file's absolute path (matching {.project_sig_files}) so {.project_entry?} — which
         # attributes a `class_decls` entry to the project by buffer name — still recognises these declarations.
         # Sorted for a deterministic add order (the env feeds the cache, ADR-54).
-        def add_project_signatures(env, signature_paths, deferred_paths = [])
+        #
+        # @param standdowns — issue #1075 — `{signature_path => Set[[class, method, kind]]}`, the members an
+        #   inline declaration displaced because it was the more precise side of a consistent pair
+        #   ({MemberConsistency::Resolution#signature_standdowns}). They are removed before the file is added.
+        def add_project_signatures(env, signature_paths, deferred_paths = [], standdowns: {})
           deferred = project_sig_files(deferred_paths)
           (project_sig_files(signature_paths) - deferred).sort.each do |file|
             parsed = parse_signature_file(file)
             next if parsed.nil? # quarantined (unparseable) or unreadable — skip so the env survives
 
             buffer, directives, decls = parsed
+            strip_members!(decls, standdowns[file]) if standdowns.key?(file)
             add_project_parsed_decls(env, buffer, directives, decls)
           end
-          add_deferred_signatures(env, deferred)
+          add_deferred_signatures(env, deferred, standdowns)
         end
 
         # Issue #777 — add one project signature transactionally. `RBS::Environment#add_source` appends to
@@ -370,7 +452,7 @@ module Rigor
         # (rigor-activerecord's is `relation.rbs`, declaring exactly `Relation`), so dropping the file drops
         # exactly the conflicting declaration. Splitting a plugin file that mixes a colliding class with
         # innocent ones is the change to make if that ever stops being true.
-        def add_deferred_signatures(env, deferred_files)
+        def add_deferred_signatures(env, deferred_files, standdowns = {})
           deferred_files.sort.each do |file|
             parsed = parse_signature_file(file)
             next if parsed.nil?
@@ -378,12 +460,13 @@ module Rigor
             buffer, directives, decls = parsed
             next if generic_arity_conflict(env, decls)
 
+            strip_members!(decls, standdowns[file]) if standdowns.key?(file)
             add_project_parsed_decls(env, buffer, directives, decls)
           end
         end
 
         # Issue #610 — which deferred (plugin-contributed) files stood down, as
-        # `[absolute_path, class_name, existing_arity, incoming_arity]`, sorted. DERIVED from a built env
+        # `[absolute_path, class_name, existing_arity, incoming_arity, existing_file]`, sorted. DERIVED from a built env
         # rather than recorded during the build, for {RbsLoader#quarantined_signatures}' reason: a cache HIT
         # never runs the build, and a condition only the build knew would silently disappear on the second
         # run. Re-asking the same question of the FINAL env gives the same answer — the file's declaration is
@@ -400,21 +483,40 @@ module Rigor
           end
         end
 
-        # The first `[class_name, existing_arity, incoming_arity]` where `decls` would re-declare a class the
-        # env already has with a DIFFERENT number of type parameters, or nil when they agree everywhere.
-        # Equal arity is not a conflict: RBS reopens the class, which is the ordinary and supported case, so
-        # the stand-down must not fire on it.
+        # The first `[class_name, existing_arity, incoming_arity, existing_file]` where `decls` would
+        # re-declare a class the env already has with a DIFFERENT number of type parameters, or nil when
+        # they agree everywhere. Equal arity is not a conflict: RBS reopens the class, which is the ordinary
+        # and supported case, so the stand-down must not fire on it.
+        #
+        # The existing arity is read off the entry's FIRST declaration, never through `entry.type_params`:
+        # rbs 4.x's `ClassEntry#type_params` validates every declaration against the first before answering
+        # and raises `GenericParameterMismatchError` on an entry that already disagrees with itself (rbs
+        # 3.x's does not), so the derived reader ({.deferred_standdowns}) raised on exactly the env it exists
+        # to describe — one a user's own two sources collided, or one the cache served from before the
+        # producer passed the deferred list. The first declaration is also the one rbs compares against.
+        # `existing_file` is that declaration's buffer name — the source that displaced the plugin's — or
+        # nil when it has none or carries only the cached-position sentinel.
         def generic_arity_conflict(env, decls)
           each_declared_class(decls) do |name, arity|
             entry = env.class_decls[::RBS::TypeName.parse(name)]
-            next if entry.nil? || !entry.respond_to?(:type_params)
+            next if entry.nil?
 
-            existing = entry.type_params&.size
-            return [name, existing, arity] if existing && existing != arity
+            first = entry_declarations(entry).first
+            existing = first.respond_to?(:type_params) ? first.type_params&.size : nil
+            return [name, existing, arity, declaration_buffer_name(first)] if existing && existing != arity
           end
           nil
         end
 
+        def declaration_buffer_name(decl)
+          location = decl.respond_to?(:location) ? decl.location : nil
+          buffer = location&.buffer
+          name = buffer.nil? ? nil : buffer.name.to_s
+          return nil if name.nil? || name.empty? || name == CACHED_LOCATION_BUFFER_NAME
+
+          name
+        end
+
         # Yields `[absolute_class_name, type_param_count]` for every class declared anywhere in `decls`,
         # descending through modules and nested classes. Names inside a `module`/`class` body are parsed
         # RELATIVE, so the enclosing path is accumulated here — the env is keyed by absolute name, and
@@ -798,7 +900,13 @@ module Rigor
         # provenance (RBS parse errors cite it) — it is not a real file path. Per WD6 the synthesizer-emit
         # path is responsible for catching its own parse errors and returning `nil` rather than garbage; this
         # method assumes its input is parseable and only rescues `RBS::ParsingError` as a fail-soft.
-        def add_virtual_rbs(env, virtual_rbs)
+        # @param inline_standdowns — issue #1075 — the `[class, method, kind]` keys whose inline member
+        #   stands down because a project `.rbs` declares the same member and ADR-112 WD5's consistency rule
+        #   let the `.rbs` bind ({MemberConsistency::Resolution#inline_standdowns}). Removing them before the
+        #   declaration is added keeps the two from colliding and costing the whole class its method surface.
+        #   The outcome is reported, never silent: {RbsLoader#member_consistency} re-derives the same records
+        #   for the run's rows.
+        def add_virtual_rbs(env, virtual_rbs, inline_standdowns: Set.new)
           return if virtual_rbs.nil? || virtual_rbs.empty?
 
           virtual_rbs.each do |filename, content|
@@ -809,6 +917,7 @@ module Rigor
 
             buffer = ::RBS::Buffer.new(name: filename.to_s, content: content.to_s)
             _, directives, decls = ::RBS::Parser.parse_signature(buffer)
+            strip_members!(decls, inline_standdowns) unless inline_standdowns.empty?
             add_parsed_decls(env, buffer, directives, decls)
           rescue ::RBS::BaseError
             # WD6 fail-soft: a single broken virtual RBS contribution does not pull the whole env down — for
@@ -828,6 +937,204 @@ module Rigor
           end
         end
 
+        # Issue #1075 / ADR-112 WD5 — the member-level half of inline-vs-`sig/` consistency, which replaced
+        # #824's "`sig/` wins per member" (ADR-32 WD13).
+        #
+        # A method declared BOTH by a project `.rbs` and by an inline annotation in its own `.rb` lands twice
+        # in one `RBS::Environment`: rbs merges the two sources into a single `ClassEntry` and ranks neither,
+        # so `RBS::DefinitionBuilder::MethodBuilder::Methods#validate!` raises
+        # `RBS::DuplicatedMethodDefinitionError` and the WHOLE class loses its method surface — every call on
+        # it, real methods and typos alike, reads `Dynamic[top]`. Measured on Rigor's own tree while
+        # [#779](https://github.com/rigortype/rigor/pull/779) was evaluated: 17 of 234 annotated files
+        # overlapped `sig/`, and the collision took 44 classes down. Steep 2.1 / rbs 4.1 have no precedence
+        # rule to follow here (ADR-32 WD13), so exactly one of the two members has to go before the
+        # environment is built. {MemberConsistency} decides which: the more precise of two consistent
+        # declarations binds, and on a contradiction or an undecidable pair the `.rbs` does.
+        #
+        # @return a {MemberConsistency::Resolution}. {MemberConsistency::EMPTY} — and free — for a project
+        #   that contributes no inline RBS, which is every project without a `source_rbs_synthesizer:` plugin.
+        #
+        # Derived from the loader's INPUTS — the synthesized sources and the project's signature files —
+        # never from a built environment, for {RbsLoader#quarantined_signatures}' reason turned inside out: a
+        # cache HIT never runs the build, and a stripped member leaves no trace in the environment to read
+        # back. The build and {RbsLoader#member_consistency} call this same function on the same two inputs,
+        # so the members they strip and the rows they report agree warm and cold.
+        def member_consistency_for(project_files, virtual_rbs, proof: nil)
+          return MemberConsistency::EMPTY if virtual_rbs.nil? || virtual_rbs.empty?
+
+          signature_members, shadowable = signature_member_index(project_files, virtual_rbs)
+          inline_members = inline_member_entries(virtual_rbs, all: !signature_members.empty?)
+          MemberConsistency.resolve(signature_members, inline_members, shadowable: shadowable, proof: proof)
+        end
+
+        # `[owners, shadowable]`. `owners` is `{[class_name, method_name, kind] => [signature_path, member,
+        # visibility]}` for every method-shaped member the project's own `signature_paths:` files declare and
+        # the inline sources also name; the first file in sorted order owns a key two `.rbs` files declare
+        # (that pair fails the definition build anyway). `shadowable` is every `::` segment of every class /
+        # module name the inline sources and the signature files declare — the names a relative reference
+        # might resolve to inside an enclosing namespace ({MemberConsistency::Comparator#faithful?}).
+        #
+        # The parse is scoped by a substring pre-filter over each file's text: a declaration has to spell its
+        # own name, so a signature file mentioning none of the names the inline sources declare cannot
+        # collide with them. The filter over-approximates (it matches a name in a comment or a type position
+        # too), so it can only cost an unnecessary parse, never miss a collision.
+        def signature_member_index(project_files, virtual_rbs)
+          names = inline_declared_name_segments(virtual_rbs)
+          return [{}, names] if project_files.nil? || project_files.empty? || names.empty?
+
+          shadowable = names.dup
+          owners = project_files.to_a.sort.each_with_object({}) do |file, index|
+            content = read_signature_text(file)
+            next if content.nil?
+
+            merge_declared_segments(content, shadowable)
+            next if names.none? { |name| content.include?(name) }
+
+            index_signature_members(index, file, parse_signature_source(file, content))
+          end
+          [owners, shadowable]
+        end
+
+        def index_signature_members(index, file, decls)
+          return if decls.nil?
+
+          each_declared_member(decls) do |class_name, member, visibility|
+            member_method_keys(member).each do |method_name, kind|
+              index[[class_name, method_name, kind]] ||= [file, member, visibility].freeze
+            end
+          end
+        end
+
+        # The directive heads a refinement {MemberConsistency.refinement_conflicts} checks, used to skip
+        # parsing an inline source that carries none when no `.rbs` overlaps it. Narrower than `rigor:v1:` on
+        # purpose: rbs-inline's output marks every skeleton `%a{rigor:v1:inferred-return}`, so that prefix is
+        # in nearly every synthesized source.
+        REFINEMENT_DIRECTIVE_MARKS = ["rigor:v1:return:", "rigor:v1:param:"].freeze
+        private_constant :REFINEMENT_DIRECTIVE_MARKS
+
+        # `[[virtual_name, class_name, member], ...]` for the inline members {MemberConsistency.resolve}
+        # reads: every member when a `.rbs` file may overlap them (`all:`), otherwise only the members of a
+        # source that carries a `rigor:v1:return:` / `rigor:v1:param:` refinement, which is checked against
+        # its own declared type. Entries {.add_virtual_rbs} would skip are skipped here too.
+        def inline_member_entries(virtual_rbs, all:)
+          virtual_rbs.each_with_object([]) do |(name, content), entries|
+            content = content.to_s
+            next if content.empty? || invalid_encoding?(content)
+            next unless all || REFINEMENT_DIRECTIVE_MARKS.any? { |mark| content.include?(mark) }
+
+            decls = parse_signature_source(name, content)
+            next if decls.nil?
+
+            each_declared_member(decls) do |class_name, member, visibility|
+              entries << [name.to_s, class_name, member, visibility]
+            end
+          end
+        end
+
+        # Removes, in place, every member contributing a key in `keys` (a Set of `[class, method, kind]`).
+        # Nested declarations are descended into after the rejection, and a declaration member contributes no
+        # method key, so nesting is never itself removed.
+        def strip_members!(decls, keys, prefix = [])
+          Array(decls).each do |decl|
+            next unless declaration_with_members?(decl)
+
+            inner = prefix + [decl.name.to_s.delete_prefix("::")]
+            class_name = inner.join("::")
+            decl.members.reject! do |member|
+              member_method_keys(member).any? { |method_name, kind| keys.include?([class_name, method_name, kind]) }
+            end
+            strip_members!(decl.members, keys, inner)
+          end
+        end
+
+        # Yields `[class_name, member, visibility]` for every member of every class / module declaration in
+        # `decls`, descending through nesting. The enclosing path is accumulated and the name rendered
+        # `::`-stripped, so a `module Foo; class Bar` and a `class Foo::Bar` elsewhere key the same — which is
+        # what makes a `sig/` declaration and an inline one comparable at all. `visibility` is the member's
+        # own (`private def x`) or else the one the enclosing `private` / `public` section sets; a singleton
+        # method takes no section, as in Ruby.
+        def each_declared_member(decls, prefix = [], &block)
+          Array(decls).each do |decl|
+            next unless declaration_with_members?(decl)
+
+            inner = prefix + [decl.name.to_s.delete_prefix("::")]
+            class_name = inner.join("::")
+            section = :public
+            decl.members.each do |member|
+              case member
+              when ::RBS::AST::Members::Private then section = :private
+              when ::RBS::AST::Members::Public then section = :public
+              else block.call(class_name, member, member_visibility(member, section))
+              end
+            end
+            each_declared_member(decl.members, inner, &block)
+          end
+        end
+
+        def member_visibility(member, section)
+          own = member.respond_to?(:visibility) ? member.visibility : nil
+          return own if own
+
+          member.respond_to?(:kind) && member.kind == :singleton ? :public : section
+        end
+
+        def declaration_with_members?(decl)
+          (decl.is_a?(::RBS::AST::Declarations::Module) || decl.is_a?(::RBS::AST::Declarations::Class)) &&
+            decl.respond_to?(:members)
+        end
+
+        # {MemberConsistency.member_method_keys} — the `[method_name, kind]` pairs a member contributes to a
+        # definition build, which is what decides whether two members collide.
+        def member_method_keys(member)
+          MemberConsistency.member_method_keys(member)
+        end
+
+        # A class / module declaration header, as the pre-filter in {.signature_member_index} reads it out of
+        # synthesized RBS text.
+        INLINE_DECLARATION_NAME = /^[ \t]*(?:class|module)[ \t]+([A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)/
+        private_constant :INLINE_DECLARATION_NAME
+
+        # Every `::`-separated segment of every class / module name the inline sources declare, read off the
+        # synthesized TEXT rather than a parse: the set only has to be a SUPERSET (it feeds the pre-filter),
+        # and a regexp over the handful of annotated files is far cheaper than parsing them a second time.
+        # Entries {.add_virtual_rbs} would skip are skipped here too — an empty or invalid-UTF-8 contribution
+        # declares nothing, and `String#scan` raises `ArgumentError` on invalid bytes rather than returning
+        # no match.
+        def inline_declared_name_segments(virtual_rbs)
+          virtual_rbs.each_with_object(Set.new) do |(_name, content), acc|
+            content = content.to_s
+            next if content.empty? || invalid_encoding?(content)
+
+            merge_declared_segments(content, acc)
+          end
+        end
+
+        # Adds every `::` segment of every class / module header in `content` to `segments`. The pattern has
+        # one capture group, which every match fills.
+        def merge_declared_segments(content, segments)
+          content.scan(INLINE_DECLARATION_NAME) { segments.merge(Regexp.last_match(1).to_s.split("::")) }
+        end
+
+        # One project signature file's text, or nil when it is unreadable or not valid UTF-8.
+        def read_signature_text(file)
+          content = File.read(file, encoding: "UTF-8")
+          invalid_encoding?(content) ? nil : content
+        rescue Errno::ENOENT, Errno::EISDIR, Errno::EACCES
+          nil
+        end
+
+        # The declarations of already-read RBS text, or nil when it does not parse. The twin of
+        # {.parse_signature_file} for content the caller already holds (a synthesized virtual source, or a
+        # signature file the pre-filter has just read).
+        def parse_signature_source(name, content)
+          _buffer, _directives, decls = ::RBS::Parser.parse_signature(
+            ::RBS::Buffer.new(name: name.to_s, content: content)
+          )
+          decls
+        rescue ::RBS::BaseError
+          nil
+        end
+
         # Per-gem `data/vendored_gem_sigs/<gem>/` directories that ship with Rigor. Each subdirectory is one
         # gem's RBS surface (the `<gem>.rbs` file is the typical content; `LICENSE.upstream` records
         # provenance). Coverage is deliberately scoped to the native-extension and "everywhere in Rails" gems
@@ -840,9 +1147,10 @@ module Rigor
         private_constant :VENDORED_GEM_SIGS_ROOT
 
         # Rigor-owned core-overlay RBS (`data/core_overlay/`). Reopens Ruby core classes to add methods
-        # upstream `ruby/rbs` omits but which every concrete value answers at runtime — loaded last so
-        # upstream always wins on conflict. Public so the cache descriptor can digest these files into the
-        # env-blob key.
+        # upstream `ruby/rbs` omits but which every concrete value answers at runtime. A direct `def` that
+        # another source also declares is a `DuplicatedMethodDefinitionError`, not a precedence question, so a
+        # method a project `sig/` or a later rbs is likely to declare goes on a module the class extends
+        # (`process.rbs`). Public so the cache descriptor can digest these files into the env-blob key.
         CORE_OVERLAY_SIGS_ROOT = File.expand_path(
           "../../../data/core_overlay",
           __dir__
@@ -854,6 +1162,51 @@ module Rigor
           [Pathname(CORE_OVERLAY_SIGS_ROOT)]
         end
 
+        # Rigor's capability-role catalog (`data/capability_roles/`) — the structural interfaces ADR-1 and
+        # `docs/type-specification/structural-interfaces-and-object-shapes.md` name as shipped, so a
+        # `%a{rigor:v1:conforms-to _ClosableStream}` written by following the specification resolves in a
+        # default run instead of failing soft to an unresolved-interface row. Public for the same reason
+        # {.core_overlay_sig_paths} is: the cache descriptor digests these files into the env-blob key.
+        CAPABILITY_ROLES_SIGS_ROOT = File.expand_path(
+          "../../../data/capability_roles",
+          __dir__
+        ).freeze
+
+        def capability_role_sig_paths
+          return [] unless File.directory?(CAPABILITY_ROLES_SIGS_ROOT)
+
+          [Pathname(CAPABILITY_ROLES_SIGS_ROOT)]
+        end
+
+        # Adds the catalog to an env that already holds the project's own signatures, one INTERFACE at a
+        # time, skipping any name the env already declares. Granularity is the declaration rather than the
+        # file (the #610 stand-down's unit) because this one file carries five unrelated roles: a project
+        # declaring `_Closable` must not also lose `_ClosableStream`.
+        def add_capability_role_signatures(env)
+          declared = declared_interface_names(env)
+          capability_role_sig_paths.each do |dir|
+            dir.children.sort.each do |file|
+              next unless file.file? && file.extname == ".rbs"
+
+              parsed = parse_signature_file(file.to_s)
+              next if parsed.nil?
+
+              buffer, directives, decls = parsed
+              standing = decls.reject { |decl| declared.include?(decl.name.absolute!) }
+              next if standing.empty?
+
+              add_parsed_decls(env, buffer, directives, standing)
+            end
+          end
+        end
+
+        # @param env — the environment the project's signatures are already in.
+        def declared_interface_names(env)
+          return Set.new unless env.respond_to?(:interface_decls)
+
+          env.interface_decls.keys.to_set
+        end
+
         # Bundled signature sources that SUPPLEMENT a stdlib library's own declarations rather than stand
         # alone: each re-opens a class the named `RBS::EnvironmentLoader` library declares with a mixin
         # (`CGI::QueryExtension`), a superclass (`Prism::Result`), or an `| ...` overload continuation
@@ -867,6 +1220,10 @@ module Rigor
         # `core_overlay/pathname.rbs` also carries an `| ...` continuation but is deliberately NOT listed:
         # its base (`Pathname#expand_path`) lives in rbs's `core/pathname.rbs` on every supported rbs
         # release (3.10 / 4.0 / 4.1), so the continuation is safe — and applicable — with no library loaded.
+        # `core_overlay/string_io.rbs` re-opens a class the `stringio` library declares yet is NOT listed
+        # either: `RBS::EnvironmentLoader#load` adds that library itself whenever it loads core (rbs 3.7+),
+        # and earlier releases declare `StringIO` in core, so gating would only drop its `Enumerable` mixin
+        # where `StringIO` is present anyway.
         #
         # Keyed by `data/vendored_gem_sigs/` directory basename.
         LIBRARY_SUPPLEMENT_VENDORED_DIRS = {
@@ -883,14 +1240,25 @@ module Rigor
         }.freeze
         private_constant :LIBRARY_SUPPLEMENT_CORE_OVERLAYS
 
+        # `data/core_overlay/` files that fill a hole only one `rbs` release line has, keyed by file basename
+        # to the `rbs` version requirement they load under. Each carries an `| ...` continuation of overloads a
+        # later line declares upstream, so loading it there would add a second copy of them. The env-cache key
+        # already carries `RBS::VERSION` ({Cache::RbsDescriptor.rbs_gem_entry}), so switching lines re-keys.
+        # The requirement is a String, not a `Gem::Requirement`, so the constant stays `Ractor.shareable?`.
+        RBS_LINE_CORE_OVERLAYS = {
+          "hash_rbs3.rbs" => "< 4.0"
+        }.freeze
+        private_constant :RBS_LINE_CORE_OVERLAYS
+
         # Adds the Rigor-shipped signature sources to `rbs_loader`: every `data/vendored_gem_sigs/<gem>/`
-        # directory, then the `data/core_overlay/` files — the overlay LAST so an upstream declaration
-        # always wins on conflict (these reopenings only fill genuine holes, e.g. `Numeric#to_f`/`to_i`/
-        # `to_r`, which upstream RBS declares on the concrete subclasses but not on the abstract `Numeric`
-        # that Rigor's arithmetic-chain widening produces). The overlay is added per-file, not
-        # per-directory, because the `LIBRARY_SUPPLEMENT_CORE_OVERLAYS` files must be gated individually.
+        # directory, then the `data/core_overlay/` files, which fill genuine holes only (e.g. `Numeric#to_f`/
+        # `to_i`/`to_r`, which upstream RBS declares on the concrete subclasses but not on the abstract `Numeric`
+        # that Rigor's arithmetic-chain widening produces). Load order does not settle a conflict: a method
+        # both sides declare directly raises `DuplicatedMethodDefinitionError` for the whole class. The
+        # overlay is added per-file, not per-directory, because the `LIBRARY_SUPPLEMENT_CORE_OVERLAYS` and
+        # `RBS_LINE_CORE_OVERLAYS` files must be gated individually.
         #
-        # @param loaded_library_names [Set<String>] libraries that actually resolved on this loader.
+        # @param loaded_library_names — libraries that actually resolved on this loader.
         def add_bundled_signatures(rbs_loader, loaded_library_names)
           vendored_gem_sig_paths.each do |path|
             next unless path.directory?
@@ -904,21 +1272,29 @@ module Rigor
             dir.children.sort.each do |file|
               next unless file.file? && file.extname == ".rbs"
               next unless supplement_dependency_loaded?(LIBRARY_SUPPLEMENT_CORE_OVERLAYS, file, loaded_library_names)
+              next unless rbs_line_matches?(file)
 
               rbs_loader.add(path: file)
             end
           end
         end
 
-        # @param supplements [Hash{String => String}] basename → gating library map.
-        # @param path [Pathname] the vendored directory or overlay file to test.
-        # @param loaded_library_names [Set<String>] libraries that actually resolved on this loader.
-        # @return [Boolean] true when `path` carries no library dependency, or its library loaded.
+        # @param supplements — basename → gating library map.
+        # @param path — the vendored directory or overlay file to test.
+        # @param loaded_library_names — libraries that actually resolved on this loader.
+        # @return true when `path` carries no library dependency, or its library loaded.
         def supplement_dependency_loaded?(supplements, path, loaded_library_names)
           library = supplements[path.basename.to_s]
           library.nil? || loaded_library_names.include?(library)
         end
 
+        # @param path — a `data/core_overlay/` file.
+        # @return true when `path` is not tied to an `rbs` release line, or the running `rbs` is on its line.
+        def rbs_line_matches?(path)
+          requirement = RBS_LINE_CORE_OVERLAYS[path.basename.to_s]
+          requirement.nil? || Gem::Requirement.new(requirement).satisfied_by?(Gem::Version.new(::RBS::VERSION))
+        end
+
         # Rigor-owned per-gem RBS overlays (`data/gem_overlay/<gem>/`), ADR-72. Unlike the unconditional
         # `core_overlay`, each gem's overlay is loaded ONLY when that gem is locked in the project's
         # Gemfile.lock but ships no RBS of its own — {Environment.for_project} decides eligibility and passes
@@ -929,9 +1305,9 @@ module Rigor
           __dir__
         ).freeze
 
-        # @param gem_names [Enumerable<String>] overlay-eligible Gemfile.lock gem names (the caller filters
+        # @param gem_names — overlay-eligible Gemfile.lock gem names (the caller filters
         #   to the `:missing`-coverage, no-conflicting-plugin set).
-        # @return [Array<Pathname>] the bundled overlay directory for each gem that ships one; empty when
+        # @return the bundled overlay directory for each gem that ships one; empty when
         #   none match or the overlay root is absent.
         def gem_overlay_sig_paths(gem_names)
           return [] unless File.directory?(GEM_OVERLAY_SIGS_ROOT)
@@ -942,9 +1318,9 @@ module Rigor
           end
         end
 
-        # @param path [String, Pathname] typically an entry from an {RbsLoader} instance's
+        # @param path — typically an entry from an {RbsLoader} instance's
         #   {#signature_paths}.
-        # @return [Boolean] whether `path` sits under the bundled gem-overlay root — what
+        # @return whether `path` sits under the bundled gem-overlay root — what
         #   `CheckRules::GEM_OVERLAY_OPEN_RECEIVERS`'s gate consults so that a class name's membership in
         #   that list alone never grants the open-receiver exemption; the overlay directory that made the
         #   entry true must have actually loaded THIS run too (issue #632, tracked further by #660).
@@ -982,7 +1358,7 @@ module Rigor
         # answer to the very same question, on the class that already owns the overlay's layout
         # ({GEM_OVERLAY_SIGS_ROOT}, {.gem_overlay_sig_paths}).
         #
-        # @param signature_paths [Array<String, Pathname>] typically an {RbsLoader} instance's
+        # @param signature_paths — typically an {RbsLoader} instance's
         #   {#signature_paths}. Takes the whole list rather than one entry so the twin's file set resolves
         #   once per question — `CheckRules` asks it per `ActiveSupport::Duration` receiver.
         def gem_overlay_twin_signatures_loaded?(signature_paths)
@@ -997,7 +1373,7 @@ module Rigor
         # id mapping and passes the id; this resolves the id to the engine's own bundled `sig/` and answers
         # the filesystem question.
         #
-        # @param plugin_id [String] a manifest id, e.g. `"activesupport-core-ext"`.
+        # @param plugin_id — a manifest id, e.g. `"activesupport-core-ext"`.
         def bundled_overlay_twin_signatures_loaded?(plugin_id, signature_paths)
           return false if signature_paths.nil? || signature_paths.empty?
 
@@ -1065,23 +1441,27 @@ module Rigor
         end
       end
 
-      attr_reader :libraries, :signature_paths, :cache_store, :virtual_rbs
+      attr_reader :libraries, :signature_paths, :cache_store, :virtual_rbs, :deferred_signature_paths
 
-      # @param libraries [Array<String, Symbol>] stdlib library names to load on top of core (e.g.,
+      # @param libraries — stdlib library names to load on top of core (e.g.,
       #   `["pathname", "json"]`). Empty by default. Each entry MUST correspond to a directory under the
       #   `rbs` gem's `stdlib/` tree; unknown names are silently dropped on environment build (the underlying
       #   `RBS::EnvironmentLoader` raises and we fail-soft).
-      # @param signature_paths [Array<String, Pathname>] additional directories of `.rbs` files to load
+      # @param signature_paths — additional directories of `.rbs` files to load
       #   (typically the project's `sig/` tree). Non-existent or non-directory paths are filtered out at
       #   build time so the loader stays robust to fixtures and bare repositories.
-      # @param cache_store [Rigor::Cache::Store, nil] the persistent cache the loader threads through to
+      # @param cache_store — the persistent cache the loader threads through to
       #   `RbsEnvironment`, `RbsKnownClassNames`, `RbsConstantTable`, `RbsClassAncestorTable`, and
       #   `RbsClassTypeParamNames` producers. Pass `nil` (the default) to skip caching; the runner threads
       #   its own Store through here when enabled.
-      # @param virtual_rbs [Array<[String, String]>] ADR-32 WD4 — `[virtual_filename, rbs_source]` pairs
+      # @param virtual_rbs — >] ADR-32 WD4 — `[virtual_filename, rbs_source]` pairs
       #   synthesised from project source by a plugin's `Manifest#source_rbs_synthesizer`. Merged into the
       #   env after `signature_paths:` and the vendored stubs. Pass `[]` (the default) when no
       #   synthesizer-emitting plugin is loaded.
+      # @param deferred_signature_paths — the subset of `signature_paths:` a bundled plugin
+      #   contributed (issue #610): loaded last and allowed to stand down against a colliding generic
+      #   arity. Read back by the env-cache producer, which rebuilds the env from the loader's readers on
+      #   a miss — a list it cannot read is a stand-down that runs only on a `--no-cache` build.
       def initialize(libraries: [], signature_paths: [], cache_store: nil, virtual_rbs: [],
                      deferred_signature_paths: [])
         @libraries = libraries.map(&:to_s).freeze
@@ -1097,8 +1477,8 @@ module Rigor
         # names currently consulted: `:env`, `:env_loaded`, `:env_build_warned`, `:definition_build_warned`,
         # `:definition_build_details`, `:definition_build_reported`, `:definition_build_failures`,
         # `:definition_build_deferred_count`, `:definition_build_deferred_first`,
-        # `:definition_build_summary_warned`, `:internal_demand`, `:internal_demand_status`, `:builder`,
-        # `:reflection`,
+        # `:definition_build_summary_warned`, `:member_consistency`, `:member_consistency_proven`, `:internal_demand`,
+        # `:internal_demand_status`, `:builder`, `:reflection`,
         # `:instance_definitions_table`, `:singleton_definitions_table`.
         # Constructed via `Hash.new` (NOT a `{ ... }` literal) so Rigor's `HashShape` narrowing doesn't
         # infer a fixed key set from the initial state and fold post-initial slot reads (e.g.
@@ -1127,7 +1507,7 @@ module Rigor
       # the stderr banner) reads it, and a cache HIT reaches it too — the env was built with the file already
       # quarantined, so the condition is invisible in the cached env itself.
       #
-      # @return [Array<Array(String, String)>] empty when every `signature_paths:` file parses.
+      # @return empty when every `signature_paths:` file parses.
       def quarantined_signatures
         @state[:quarantined] ||= begin
           parse_quarantined = self.class.quarantined_project_signatures(@signature_paths)
@@ -1135,17 +1515,24 @@ module Rigor
             @state[:env], @signature_paths
           )
           parse_paths = parse_quarantined.to_set { |path, _note| path }
+          # Issue #610 — a deferred file that STOOD DOWN is absent from the env by design, which is exactly
+          # what the collision derivation reads as "quarantined". Derived from the same env, so a cache HIT
+          # excludes it too; {#signature_standdowns} is where it is reported instead.
+          stood_down = self.class.deferred_standdowns(@state[:env], @deferred_signature_paths).to_set(&:first)
           (
             parse_quarantined +
-            collision_quarantined.reject { |entry| parse_paths.include?(entry[0]) }
+            collision_quarantined.reject do |entry|
+              parse_paths.include?(entry[0]) || stood_down.include?(entry[0])
+            end
           ).freeze
         end
       end
 
       # Issue #610 — plugin-contributed signature files that stood down against a colliding generic arity,
-      # as `[absolute_path, class_name, existing_arity, incoming_arity]`. Empty whenever no plugin sig
-      # collides, which is every project that has not run `rbs collection install` for a gem a bundled
-      # plugin also declares.
+      # as `[absolute_path, class_name, existing_arity, incoming_arity, existing_file]`. Empty whenever no
+      # plugin sig collides, which is every project that has not run `rbs collection install` for a gem a
+      # bundled plugin also declares. Reported as `rbs.coverage.plugin-signature-stood-down` (`:info`); the
+      # same file MUST NOT also appear in {#quarantined_signatures}.
       def signature_standdowns
         @state[:signature_standdowns] ||= self.class.deferred_standdowns(env, @deferred_signature_paths).freeze
       end
@@ -1185,11 +1572,94 @@ module Rigor
       end
       private :build_project_declared_classes
 
+      # Issue #527 — the class / module names whose PRIMARY declaration lives in the `rbs` gem's own
+      # `core/` or `stdlib/` tree, top-level prefix stripped.
+      #
+      # The distinction it draws is narrower than {#project_declared_classes}'s: not "who wrote this
+      # signature" but "is this Ruby's own documented surface". A core / stdlib signature is the method
+      # set every negative check rule already trusts for a direct receiver of the class, which is what
+      # lets a Ruby-source SUBCLASS of one resolve its inherited calls there (`RbsDispatch`'s
+      # `core_stdlib_ancestor_method`). A GEM's RBS is a different claim — routinely partial, which is
+      # ADR-43's whole reason for declining blanket inherited resolution — so it is deliberately outside
+      # this set even when the gem ships signatures and even when it is one of {DEFAULT_LIBRARIES}
+      # (`prism`, `rbs` are gems whose signatures ship with the gem, not entries of rbs's `stdlib/`).
+      #
+      # Attribution is by buffer NAME, the same mechanism and the same limits as
+      # {#project_declared_classes}: it survives the ADR-54 environment cache, and an old blob's
+      # `<cached>` sentinel lands every class OUTSIDE the set — the feature switches off rather than
+      # widening, which is the direction ADR-5 wants. Memoised per loader; one pass over `class_decls`.
+      def core_stdlib_classes
+        @state[:core_stdlib_classes] ||= build_core_stdlib_classes
+      end
+
+      def build_core_stdlib_classes
+        environment = env
+        return Set.new.freeze if environment.nil? || CORE_STDLIB_ROOTS.empty?
+
+        names = environment.class_decls.each_with_object(Set.new) do |(rbs_name, entry), acc|
+          decl = self.class.primary_decl_for(entry)
+          next if decl.nil?
+
+          path = self.class.declaration_buffer_name(decl)
+          next if path.nil?
+
+          acc << rbs_name.to_s.delete_prefix("::") if CORE_STDLIB_ROOTS.any? { |root| path.start_with?(root) }
+        end
+        names.freeze
+      rescue ::RBS::BaseError
+        Set.new.freeze
+      end
+      private :build_core_stdlib_classes
+
+      # True when `class_name` is declared by Ruby core or a stdlib library (see {#core_stdlib_classes}).
+      def core_or_stdlib_class?(class_name)
+        core_stdlib_classes.include?(class_name.to_s.delete_prefix("::"))
+      end
+
       # True when `class_name`'s RBS declaration is one the project wrote (see {#project_declared_classes}).
       def project_declared_class?(class_name)
         project_declared_classes.include?(class_name.to_s.delete_prefix("::"))
       end
 
+      # Issue #1362 — the translated type of the RBS declaration of the global variable `name` (`:$stdout`, declared
+      # `IO` by the core signatures), or nil when no loaded signature declares it. Translated without an alias
+      # expander, as {#constant_type} translates a constant, so `$DEBUG: boolish` reads `Dynamic[top]` rather than
+      # `top`.
+      def global_type(name)
+        global_declarations[name.to_sym]&.first
+      end
+
+      # True when `name`'s RBS declaration lives in the `rbs` gem's own `core/` or `stdlib/` tree: a global the
+      # interpreter or a default library sets. Attributed by buffer name, as {#core_or_stdlib_class?} is, with the
+      # same limit: an environment blob without buffer names answers false for every global.
+      def core_or_stdlib_global?(name)
+        global_declarations[name.to_sym]&.last || false
+      end
+
+      # `name => [type, core_or_stdlib]` for every global the environment declares; a declaration whose type
+      # translates to `bot` is left out. Memoised per loader: the core signatures declare about fifty.
+      def global_declarations
+        @state[:global_declarations] ||= build_global_declarations
+      end
+      private :global_declarations
+
+      def build_global_declarations
+        environment = env
+        return {}.freeze if environment.nil?
+
+        table = environment.global_decls.each_with_object({}) do |(name, entry), acc|
+          type = Inference::RbsTypeTranslator.translate(entry.decl.type)
+          next if type.is_a?(Type::Bot)
+
+          path = self.class.declaration_buffer_name(entry.decl)
+          acc[name.to_sym] = [type, !path.nil? && CORE_STDLIB_ROOTS.any? { |root| path.start_with?(root) }].freeze
+        end
+        table.freeze
+      rescue ::RBS::BaseError
+        {}.freeze
+      end
+      private :build_global_declarations
+
       # The total RBS-environment build failure captured this run, or nil when the env built. Unlike
       # {#quarantined_signatures} — which the env survives, one file lighter, and which is re-derived so a
       # cache HIT reports it too — a total failure collapses the WHOLE env to nil. Project-vs-bundled
@@ -1199,7 +1669,7 @@ module Rigor
       # persisted, so every run re-attempts and re-raises), so this is captured directly in {#env}'s rescue
       # rather than re-derived. Forcing `env` (any query does) populates it.
       #
-      # @return [Array(String, String, Array<String>), nil] `[error_class_name, first_error_line,
+      # @return `[error_class_name, first_error_line,
       #   conflicting_buffer_names]`, or nil when the environment built successfully.
       def env_build_failure
         env unless @state[:env_loaded]
@@ -1223,9 +1693,10 @@ module Rigor
       # definition-build failure leaves no trace in the env at all — the env is fine; it is the BUILD over it
       # that raised — so the rescue is the only place that ever knows.
       #
-      # @return [Array<Array(String, String, String, Array<String>)>] `[class_name, error_class_name,
-      #   first_error_line, conflicting_buffer_names]`, one per class, in first-failure order. Empty for a
-      #   healthy sig set, which is the common case.
+      # @return `[class_name, error_class_name, member, conflicting_buffer_names,
+      #   unresolved_type_name_detail]`, one per class, in first-failure order (issue #997 added the fifth
+      #   slot; see {#unresolved_type_name_detail} — `nil` there for every failure kind but an unresolvable
+      #   type name). Empty for a healthy sig set, which is the common case.
       def definition_build_failures
         (@state[:definition_build_failures] || []).dup.freeze
       end
@@ -1237,7 +1708,7 @@ module Rigor
       # the {#quarantined_signatures} trick — so a cache HIT, which never runs the build, reports the same
       # condition: the marshalled env simply lacks the dropped buffers.
       #
-      # @return [Array<String>] virtual buffer names (source-file paths) whose contribution was dropped.
+      # @return virtual buffer names (source-file paths) whose contribution was dropped.
       def virtual_rbs_collision_quarantined
         @state[:virtual_rbs_collisions] ||= begin
           built = @state[:env]
@@ -1252,6 +1723,29 @@ module Rigor
         end
       end
 
+      # Issue #1075 / ADR-112 WD5 — one {MemberConsistency::Record} per `(class, method, kind)` the project's
+      # own `signature_paths:` and an inline (rbs-inline) source both declare, saying which side bound and
+      # why, plus one per `rigor:v1:return:` / `rigor:v1:param:` refinement that exceeds its member's own
+      # declared type. The rest of the file's annotations still bind either way, and the class keeps its
+      # method surface instead of failing its definition build.
+      #
+      # The sibling of {#virtual_rbs_collision_quarantined} one granularity finer: that one names a whole
+      # inline FILE dropped for a class-level duplicate, this one names a single member. Both are derived
+      # rather than recorded, so a cache HIT — where no build ran — reports the same condition; here the
+      # derivation reads the loader's inputs rather than the built env, because a stripped member leaves no
+      # trace in the env at all.
+      #
+      # @return the records, sorted. Empty (and free) whenever the project contributes no inline RBS.
+      #
+      # @param proof — a {MemberConsistency::RbsProof} over this loader, without which no pair is reported
+      #   as a contradiction (only the severity of a row depends on it, never which declaration binds).
+      def member_consistency(proof: nil)
+        key = proof ? :member_consistency_proven : :member_consistency
+        @state[key] ||= self.class.member_consistency_for(
+          self.class.project_sig_files(@signature_paths), @virtual_rbs, proof: proof
+        ).records
+      end
+
       # The referenced-but-undeclared types {.stub_missing_referenced_types} stubbed so the project classes
       # that mention them could build (e.g. an unavailable `DRb::DRbServer`, or a stale
       # `Textbringer::EditorError`). Recovered off the built env like {#synthesized_namespaces}, so it
@@ -1415,7 +1909,7 @@ module Rigor
         {}.freeze
       end
 
-      # @return [RBS::Definition, nil] the resolved instance definition for `class_name`, or nil when the
+      # @return the resolved instance definition for `class_name`, or nil when the
       #   class is unknown or its definition cannot be built (RBS may raise on broken hierarchies; we
       #   fail-soft and return nil so the caller can fall back).
       #
@@ -1441,7 +1935,6 @@ module Rigor
         definition
       end
 
-      # @return [RBS::Definition::Method, nil]
       def instance_method(class_name:, method_name:)
         definition = instance_definition(class_name)
         return nil unless definition
@@ -1449,7 +1942,7 @@ module Rigor
         definition.methods[method_name.to_sym]
       end
 
-      # @return [Array<Symbol>, nil] every instance-method name on `class_name` — own, inherited, and
+      # @return every instance-method name on `class_name` — own, inherited, and
       #   included — as resolved by `RBS::DefinitionBuilder`. Returns `nil` (NOT `[]`) when the class
       #   definition cannot be built so callers can tell "no methods" apart from "unknown class". Used by the
       #   `rigor:v1:conforms-to` presence check ({Rigor::RbsExtended::ConformanceChecker}).
@@ -1460,7 +1953,7 @@ module Rigor
         definition.methods.keys
       end
 
-      # @return [RBS::Definition, nil] the built definition for the RBS interface `interface_name`
+      # @return the built definition for the RBS interface `interface_name`
       #   (`_RewindableStream`), whose `.methods` are the required members (including interface-ancestor
       #   members). Returns `nil` when the name does not resolve to a loaded interface (a typo, or the
       #   defining library / sig set is not on the load path). Fail-soft on RBS build errors.
@@ -1475,15 +1968,15 @@ module Rigor
         nil
       end
 
-      # @return [Array<Symbol>, nil] every method name required by the RBS interface `interface_name`, or nil
+      # @return every method name required by the RBS interface `interface_name`, or nil
       #   when it does not resolve. Thin accessor over {#interface_definition} for the presence check.
       def interface_method_names(interface_name)
         interface_definition(interface_name)&.methods&.keys
       end
 
-      # @param rbs_alias [RBS::Types::Alias] a type-alias reference (`string`, `int`, `range[int?]`, …)
+      # @param rbs_alias — a type-alias reference (`string`, `int`, `range[int?]`, …)
       #   appearing in a method signature.
-      # @return [RBS::Types::t, nil] the alias's aliased type one level out, with type arguments substituted
+      # @return the alias's aliased type one level out, with type arguments substituted
       #   for a generic alias (`string` → `::String | ::_ToStr`; `range[int?]` → `::Range[int?] |
       #   ::_Range[int?]`), or nil for an unresolved name. Lets a caller see through the alias that
       #   {Inference::RbsTypeTranslator} otherwise degrades to `untyped`, which is why an interface/alias
@@ -1508,7 +2001,7 @@ module Rigor
         nil
       end
 
-      # @return [RBS::Definition, nil] the resolved singleton (class object) definition for `class_name`. The
+      # @return the resolved singleton (class object) definition for `class_name`. The
       #   methods on this definition are the *class methods* of `class_name`, including those inherited from
       #   `Class` and `Module` for class types. Returns nil for unknown names and on RBS build errors
       #   (fail-soft).
@@ -1529,7 +2022,37 @@ module Rigor
         definition
       end
 
-      # @return [RBS::Definition::Method, nil] the class method on `class_name`. For example,
+      # Issue #915 — the MODULE names in `class_name`'s singleton ancestry, as RBS declares it. A
+      # `class C; extend M; end` written in a project's own `sig/` puts `M` there and nothing else in the
+      # environment surface exposes it: {#ancestor_names_for} answers the instance side only.
+      #
+      # Modules only, deliberately. `RBS::DefinitionBuilder#build_singleton` mixes the extended modules in
+      # with the singleton's class chain (`Class`, `Module`, `Object`, `BasicObject`), and the classes there
+      # are already what the `Class` approximation in `Inference::Narrowing` reasons through. The modules
+      # that survive the filter — the declared `extend` targets, plus `Kernel` through `Object` — are each a
+      # true answer to `C.is_a?(M)`.
+      #
+      # Marked as an internal demand for the same reason {#ancestor_names_for} is (issue #696): asking
+      # whether a module sits in an ancestry is not asking whether the class's method surface resolves, and
+      # letting it report would make the reported class list depend on the cache state.
+      #
+      # @return `::`-stripped module names, or `[]` for an unknown class and on any RBS build error.
+      def singleton_extended_module_names(class_name)
+        key = class_name.to_s.delete_prefix("::")
+        during_internal_demand do
+          definition = singleton_definition(key)
+          next [].freeze if definition.nil?
+
+          definition.ancestors.ancestors.filter_map do |ancestor|
+            name = ancestor.name.to_s.delete_prefix("::")
+            name if ancestor.is_a?(::RBS::Definition::Ancestor::Instance) && rbs_module?(name)
+          end.uniq.freeze
+        end
+      rescue ::RBS::BaseError, StandardError
+        [].freeze
+      end
+
+      # @return the class method on `class_name`. For example,
       #   `singleton_method(class_name: "Integer", method_name: :sqrt)` returns the definition for
       #   `Integer.sqrt`, while `singleton_method(class_name: "Foo", method_name: :new)` returns Class#new
       #   for any class type.
@@ -1553,18 +2076,29 @@ module Rigor
       # process) through {Cache::RbsClassTypeParamNames.fetch} and answers point lookups from it. Cold runs
       # build the table once and persist it; warm runs (and a separate loader sharing the same Store) skip
       # the env walk entirely.
+      #
+      # #775 — memoised per class name and answered as a frozen list. `RBS::Definition#type_params` is not
+      # an accessor: it re-derives the names through the entry's type-param declarations (a substitution
+      # per call), and generic dispatch asks for the receiver class's names on every call (~110k times on
+      # the lib self-check, the largest remaining rbs-side allocation). The env is immutable for the
+      # loader's lifetime, so the answer never changes; every consumer only reads it.
       def class_type_param_names(class_name)
-        if cache_store
-          key = class_name.to_s.delete_prefix("::")
-          return type_param_names_table.fetch(key, []).dup
-        end
-
-        definition = instance_definition(class_name)
-        return [] unless definition
+        memo = (@state[:type_param_names] ||= {})
+        key = class_name.to_s
+        return memo[key] if memo.key?(key)
 
-        definition.type_params.dup
+        memo[key] =
+          if cache_store
+            type_param_names_table.fetch(key.delete_prefix("::"), NO_TYPE_PARAMS).freeze
+          else
+            definition = instance_definition(class_name)
+            definition ? definition.type_params.freeze : NO_TYPE_PARAMS
+          end
       end
 
+      NO_TYPE_PARAMS = [].freeze
+      private_constant :NO_TYPE_PARAMS
+
       def class_ordering(lhs, rhs)
         @hierarchy.class_ordering(lhs, rhs)
       end
@@ -1595,7 +2129,7 @@ module Rigor
       # way, and both yield `[]` for an unknown or unbuildable class. Pinned by spec across all three cache
       # states.
       #
-      # @return [Array<String>] `::`-stripped ancestor names, or `[]` for an unknown or unbuildable class.
+      # @return `::`-stripped ancestor names, or `[]` for an unknown or unbuildable class.
       def ancestor_names_for(class_name)
         key = class_name.to_s.delete_prefix("::")
         during_internal_demand do
@@ -1610,7 +2144,7 @@ module Rigor
         [].freeze
       end
 
-      # @return [Array<String>] every RBS-declared constant name (top-level prefixed, e.g., `"::Math::PI"`)
+      # @return every RBS-declared constant name (top-level prefixed, e.g., `"::Math::PI"`)
       #   currently loaded into the environment. Used by the cache producer that materialises the
       #   constant-type table; ordinary callers should keep using {#constant_type} for point lookups.
       def constant_names
@@ -1694,11 +2228,21 @@ module Rigor
       # Building it digests every `.rbs` file under `signature_paths` + the vendored gem sigs, and the
       # result is identical across producers, so one build is memoised per loader (on `@state`, alongside
       # `:env` — the env itself is loader-lifetime-memoised, so this adds no new staleness class).
+      #
+      # Issue #1014 — nil when the engine's source cannot be digested ({Cache::EngineSource::Unavailable});
+      # {Cache::RbsCacheProducer.fetch} then computes uncached. Memoised through `key?` rather than `||=` so
+      # that answer is reached once: rebuilding it would re-digest the whole signature tree per producer to
+      # arrive at the same nil.
       def rbs_cache_descriptor
-        @state[:rbs_cache_descriptor] ||= begin
-          require_relative "../cache/rbs_descriptor"
-          Cache::RbsDescriptor.build(self)
-        end
+        return @state[:rbs_cache_descriptor] if @state.key?(:rbs_cache_descriptor)
+
+        require_relative "../cache/rbs_descriptor"
+        @state[:rbs_cache_descriptor] =
+          begin
+            Cache::RbsDescriptor.build(self)
+          rescue Cache::EngineSource::Unavailable
+            nil
+          end
       end
 
       # ADR-15 Phase 2b — return the loader's read-only query surface as a frozen, `Ractor.shareable?`
@@ -2066,7 +2610,60 @@ module Rigor
         return if details.key?(key)
 
         details[key] = [key, error.class.name.to_s, definition_build_member(error),
-                        definition_build_conflict_buffers(error)].freeze
+                        definition_build_conflict_buffers(error), unresolved_type_name_detail(error)].freeze
+      end
+
+      # Issue #997 — the `RBS::NoTypeFoundError` twin of {#definition_build_member}: `nil` for every other
+      # error class, so the cached tuple gains a populated fifth slot only for the failure kind it
+      # distinguishes — "one declaration names a type that does not exist" from "two declarations collide"
+      # ({DiagnosticAggregator#definition_build_advice}, which folds this in).
+      #
+      # Computed once, at RAISE time, and frozen into the cached detail rather than re-derived when a warm
+      # run replays the tuple from {IncrementalSnapshot} — there is no live `RBS::NoTypeFoundError` to
+      # re-inspect on that path, only the plain strings this method already reduced it to.
+      #
+      # `[token, location, refinement_hint]`:
+      # - `token` is the unresolved name exactly as `RBS::NoTypeFoundError#type_name` carries it — the ONLY
+      #   name that ever reaches RBS. A hyphenated payload (`finite-float`) is truncated to its first
+      #   segment by rbs-inline's own tolerant type parse (`RBS::Parser.parse_type(..., require_eof: false)`
+      #   stops at the first complete type and silently discards the rest), so `-float` never becomes a
+      #   token RBS itself can name or complain about.
+      # - `location` is `error.location.to_s` verbatim (`"virtual:rbs-inline:<path>:line:col...line:col"`)
+      #   — the position the error already carries, per issue #997, named rather than re-derived. It is a
+      #   position in the SYNTHESIZED buffer for an inline annotation, not necessarily the `.rb` line the
+      #   author wrote: {Effects::InlineAnchor} maps a known `%a{...}` spelling back by ordinal, which does
+      #   not apply to an arbitrary broken type token, so no such mapping is attempted here.
+      # - `refinement_hint` is the full compound name (`"finite-float"`) when the SAME synthesized buffer —
+      #   rbs-inline re-emits the author's original `# @rbs name: TYPE` comment verbatim above the member it
+      #   generates — carries `token` immediately followed by a hyphenated continuation that is ITSELF a
+      #   registered {Builtins::ImportedRefinements} name; `nil` otherwise. Exact-match only: a near-miss
+      #   compound name says nothing, so a coincidental `token-suffix` that is not a real refinement can
+      #   never manufacture a misleading "did you mean" (false positives outrank worst-case reading).
+      def unresolved_type_name_detail(error)
+        return nil unless error.is_a?(::RBS::NoTypeFoundError)
+
+        token = error.type_name.to_s.delete_prefix("::")
+        [token, error.location&.to_s, refinement_hint_for(token, error)].freeze
+      rescue ::RBS::BaseError, StandardError
+        nil
+      end
+
+      # The buffer rbs-inline synthesized still carries the author's own comment line verbatim (the
+      # "annotation echo" {Effects::InlineAnchor} documents), so a hyphenated refinement name truncated out
+      # of the parsed type ({#unresolved_type_name_detail}) is still readable a few characters further along
+      # the SAME text the error's own location already points into.
+      def refinement_hint_for(token, error)
+        return nil if token.empty?
+
+        content = error.location&.buffer&.content
+        return nil if content.nil?
+
+        candidate = content[/\b#{Regexp.escape(token)}-[A-Za-z0-9][\w-]*/]
+        return nil if candidate.nil?
+
+        Builtins::ImportedRefinements.known?(candidate) ? candidate : nil
+      rescue ::RBS::BaseError, StandardError
+        nil
       end
 
       # Issue #696 — the REPORTING half: promote a remembered detail into {#definition_build_failures}
@@ -2276,8 +2873,6 @@ module Rigor
       # `#method_name`; `UnknownMethodAliasError` and `NoSuperclassFoundError` have `#type_name`;
       # `SuperclassMismatchError` has `#name`. `RecursiveAncestorError` has none of them and yields nil, and
       # the diagnostic then omits the clause rather than inventing one.
-      #
-      # @return [String, nil]
       def definition_build_member(error)
         return error.qualified_method_name.to_s if error.respond_to?(:qualified_method_name)