rigortype 0.3.8 → 0.3.9

data/lib/rigor/environment/rbs_loader.rb

@@ -86,7 +86,17 @@ module Rigor
           env = RBS::Environment.from_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 #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)
+          # Issue #824 — the project's own signatures are already in `env` at this point, so the inline
+          # contribution can be asked the question that keeps the two from colliding: which of its members
+          # does a `.rbs` file already declare? Those stand down per member ({.add_virtual_rbs}).
+          add_virtual_rbs(env, virtual_rbs, sig_member_owners: signature_member_owners(project_files, virtual_rbs))
           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 +129,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)
@@ -383,7 +393,7 @@ module Rigor
         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 +410,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 +827,12 @@ 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 sig_member_owners — issue #824 — `{[class, method, kind] => signature_path}`
+        #   from {.signature_member_owners}. Every member it names is removed from the inline contribution
+        #   before the declaration is added, so `sig/` wins per MEMBER instead of the two colliding and
+        #   costing the whole class its method surface (ADR-32 WD13). The stand-down is reported, never
+        #   silent: {RbsLoader#inline_member_standdowns} re-derives the same set for the run's `:info` row.
+        def add_virtual_rbs(env, virtual_rbs, sig_member_owners: {})
           return if virtual_rbs.nil? || virtual_rbs.empty?
 
           virtual_rbs.each do |filename, content|
@@ -809,6 +843,7 @@ module Rigor
 
             buffer = ::RBS::Buffer.new(name: filename.to_s, content: content.to_s)
             _, directives, decls = ::RBS::Parser.parse_signature(buffer)
+            strip_members_declared_in_signatures!(decls, sig_member_owners) unless sig_member_owners.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 +863,187 @@ module Rigor
           end
         end
 
+        # Issue #824 / ADR-32 WD13 — the member-level half of inline-vs-`sig/` precedence.
+        #
+        # 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 (Steep reports the same collision as a signature diagnostic and the class still
+        # fails to build), so the spec's "SHOULD follow Steep 2.0" pointer resolves to nothing and the choice
+        # is Rigor's: the reviewed, `sig-gen`-managed `.rbs` wins, per member.
+        #
+        # @return `{[class_name, method_name, kind] => signature_path}` for every
+        #   method-shaped member the project's own `signature_paths:` files declare and the inline sources
+        #   also name. Empty — and free — for a project that contributes no inline RBS, which is every
+        #   project without a `source_rbs_synthesizer:` plugin.
+        #
+        # 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_owners(project_files, virtual_rbs)
+          return {} if project_files.nil? || virtual_rbs.nil? || virtual_rbs.empty?
+
+          names = inline_declared_name_segments(virtual_rbs)
+          return {} if names.empty?
+
+          project_files.to_a.sort.each_with_object({}) do |file, owners|
+            decls = parse_signature_file_if_mentions(file, names)
+            next if decls.nil?
+
+            each_declared_member(decls) do |class_name, member|
+              member_method_keys(member).each do |method_name, kind|
+                owners[[class_name, method_name, kind]] ||= file
+              end
+            end
+          end
+        end
+
+        # The `[class, method, kind, signature_path, virtual_buffer_name]` record for every inline member
+        # {.add_virtual_rbs} stands down, sorted and deduplicated.
+        #
+        # Derived from the loader's own INPUTS — the synthesized sources and the project's signature files —
+        # never from the built environment, for {RbsLoader#quarantined_signatures}' reason turned inside out:
+        # a cache HIT never runs the build, and the stripped member leaves no trace in the environment to
+        # read back. The same two inputs answer identically warm and cold, which is what makes the reported
+        # set independent of cache state.
+        def inline_member_standdowns_for(signature_paths:, virtual_rbs:)
+          owners = signature_member_owners(project_sig_files(signature_paths), virtual_rbs)
+          return [].freeze if owners.empty?
+
+          records = virtual_rbs.flat_map do |name, content|
+            next [] if content.nil? || content.empty? || invalid_encoding?(content.to_s)
+
+            decls = parse_signature_source(name, content.to_s)
+            decls.nil? ? [] : member_standdowns_in(name, decls, owners)
+          end
+          records.uniq.sort_by { |record| [record[0], record[1].to_s, record[2].to_s] }.freeze
+        end
+
+        def member_standdowns_in(virtual_name, decls, owners)
+          records = []
+          each_declared_member(decls) do |class_name, member|
+            member_method_keys(member).each do |method_name, kind|
+              signature_path = owners[[class_name, method_name, kind]]
+              next if signature_path.nil?
+
+              records << [class_name, method_name, kind, signature_path, virtual_name.to_s].freeze
+            end
+          end
+          records
+        end
+
+        # Removes, in place, every member `owners` says a project signature already declares. 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_declared_in_signatures!(decls, owners, 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| owners.key?([class_name, method_name, kind]) }
+            end
+            strip_members_declared_in_signatures!(decl.members, owners, inner)
+          end
+        end
+
+        # Yields `[class_name, member]` 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.
+        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("::")
+            decl.members.each { |member| block.call(class_name, member) }
+            each_declared_member(decl.members, inner, &block)
+          end
+        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
+
+        # The `[method_name, kind]` pairs one RBS member contributes to a definition build, mirroring
+        # `RBS::DefinitionBuilder::MethodBuilder#build_instance` / `#build_singleton` — which is what decides
+        # whether two members collide. An attribute contributes its reader and / or writer name (`foo`,
+        # `foo=`), an alias its new name, and `def self?.x` both sides. An `overloading?` member (`def x: ...
+        # | ...`) contributes NOTHING: rbs files those under `overloads` rather than `originals`, so they are
+        # designed to compose with an existing declaration and must not stand down against it.
+        def member_method_keys(member)
+          case member
+          when ::RBS::AST::Members::MethodDefinition then method_definition_keys(member)
+          when ::RBS::AST::Members::AttrReader then [[member.name, member.kind]]
+          when ::RBS::AST::Members::AttrWriter then [[:"#{member.name}=", member.kind]]
+          when ::RBS::AST::Members::AttrAccessor then [[member.name, member.kind], [:"#{member.name}=", member.kind]]
+          when ::RBS::AST::Members::Alias then [[member.new_name, member.kind]]
+          else []
+          end
+        end
+
+        def method_definition_keys(member)
+          return [] if member.respond_to?(:overloading?) && member.overloading?
+
+          case member.kind
+          when :instance then [[member.name, :instance]]
+          when :singleton then [[member.name, :singleton]]
+          else [[member.name, :instance], [member.name, :singleton]] # `def self?.x` defines both sides
+          end
+        end
+
+        # A class / module declaration header, as the pre-filter in {.signature_member_owners} 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)
+
+            content.scan(INLINE_DECLARATION_NAME) { |(declared)| acc.merge(declared.split("::")) }
+          end
+        end
+
+        # Parses one project signature file, or nil when it is unreadable, not valid UTF-8, unparseable, or
+        # mentions none of `names` (so nothing in it can collide with the inline sources).
+        def parse_signature_file_if_mentions(file, names)
+          content = File.read(file, encoding: "UTF-8")
+          return nil if invalid_encoding?(content)
+          return nil if names.none? { |name| content.include?(name) }
+
+          parse_signature_source(file, 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
@@ -854,6 +1070,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
@@ -890,7 +1151,7 @@ module Rigor
         # 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.
         #
-        # @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?
@@ -910,10 +1171,10 @@ module Rigor
           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)
@@ -929,9 +1190,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 +1203,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 +1243,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 +1258,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 +1326,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 +1362,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`, `:inline_member_standdowns`, `: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 +1392,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 +1400,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
@@ -1199,7 +1471,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,7 +1495,7 @@ 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,
+      # @return `[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.
       def definition_build_failures
@@ -1237,7 +1509,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 +1524,25 @@ module Rigor
         end
       end
 
+      # Issue #824 / ADR-32 WD13 — the inline (rbs-inline) members that stood down because the project's own
+      # `signature_paths:` already declare the same `(class, method, kind)`. The `.rbs` wins per member; the
+      # rest of the file's annotations still bind, 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 `[class_name, method_name, kind, signature_path,
+      #   virtual_buffer_name]` records, sorted. Empty (and free) whenever the project contributes no inline
+      #   RBS or none of it overlaps a signature file.
+      def inline_member_standdowns
+        @state[:inline_member_standdowns] ||=
+          self.class.inline_member_standdowns_for(signature_paths: @signature_paths, virtual_rbs: @virtual_rbs)
+      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 +1706,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 +1732,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 +1739,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 +1750,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 +1765,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 +1798,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 +1819,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 +1873,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 +1926,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 +1941,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
@@ -2276,8 +2607,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)