rigortype 0.3.7 → 0.3.9

data/lib/rigor/environment/rbs_loader.rb

@@ -84,11 +84,24 @@ module Rigor
           # 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)
+          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)
-          env, resolved = resolve_quarantining_virtual_collisions(env, virtual_rbs)
-          stub_missing_referenced_types(env, resolved, project_sig_files(signature_paths))
+          # 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.
+          env, resolved = resolve_quarantining_virtual_collisions(env, virtual_rbs, project_files: project_files)
+          stub_missing_referenced_types(env, resolved, project_files)
         end
 
         # rbs ships `stdlib/bigdecimal/` and `stdlib/bigdecimal-math/` as two libraries, so
@@ -116,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)
@@ -157,32 +170,61 @@ module Rigor
           false
         end
 
-        # Backstop for a virtual-vs-anything `RBS::DuplicatedDeclarationError` that only materialises at
-        # `resolve_type_names` (which rebuilds the env from `sources`). {.add_virtual_rbs}'s transactional
-        # rescue already handles the add-time case — empirically everything on rbs 4.x — but the rbs gemspec
-        # range spans `>= 3.0, < 5.0` (ADR-79) and WHERE duplicate detection fires is an rbs-internal choice
-        # this code must not depend on. Resolution rule is the same as the add-time path: the explicit
-        # signature wins, the colliding VIRTUAL buffer is dropped whole (`RBS::Environment#unload`) and
-        # resolution retries; every pass removes at least one virtual buffer, so the loop is bounded by the
-        # virtual-entry count. A duplicate involving no virtual buffer (sig-vs-sig), or an env without
-        # `#unload` (rbs 3.x), re-raises into the existing one-warning degrade path.
+        # Backstop for a `RBS::DuplicatedDeclarationError` that only materialises at `resolve_type_names`
+        # (which rebuilds the env from `sources`). {.add_virtual_rbs} / {.add_project_parsed_decls}
+        # transactionally handle the add-time case — empirically everything on rbs 4.x — but the rbs
+        # gemspec range spans `>= 3.0, < 5.0` (ADR-79) and WHERE duplicate detection fires is an
+        # rbs-internal choice this code must not depend on. Resolution preference: drop colliding VIRTUAL
+        # buffers first (explicit `.rbs` wins), else drop colliding PROJECT `signature_paths:` buffers
+        # (issue #777 — bundled RBS wins over a kind-colliding project file), then retry. Every pass
+        # removes at least one buffer, so the loop is bounded. A duplicate with neither virtual nor
+        # project culprits (bundled-vs-bundled), or an env without `#unload` (rbs 3.x), re-raises into
+        # the existing one-warning total-failure path.
         #
         # The dropped set is not returned: consumers recover it from the built env via
         # {#virtual_rbs_collision_quarantined}, which also works on a cache HIT where this build never ran.
-        def resolve_quarantining_virtual_collisions(env, virtual_rbs)
+        def resolve_quarantining_virtual_collisions(env, virtual_rbs, project_files: [])
           virtual_names = virtual_rbs.to_set { |name, _content| name.to_s }
-          (virtual_names.size + 1).times do
+          project_names = Array(project_files).to_set(&:to_s)
+          # Bound by virtual + project culprit candidates: each pass removes at least one buffer.
+          (virtual_names.size + project_names.size + 1).times do
             return [env, env.resolve_type_names]
           rescue ::RBS::DuplicatedDeclarationError => e
-            raise unless env.respond_to?(:unload)
+            env = unload_duplicated_declaration_culprits(
+              env, e, virtual_names: virtual_names, project_names: project_names
+            )
+          end
+          [env, env.resolve_type_names]
+        end
+
+        # Prefer dropping colliding VIRTUAL buffers (explicit `.rbs` wins), else PROJECT `signature_paths:`
+        # buffers (issue #777 — bundled RBS wins over a kind-colliding project file). A duplicate with
+        # neither virtual nor project culprits (bundled-vs-bundled), or an env without `#unload`, re-raises.
+        def unload_duplicated_declaration_culprits(env, error, virtual_names:, project_names:)
+          raise unless env.respond_to?(:unload)
+
+          culprits = duplicated_declaration_buffer_names(error)
+          virtual_culprits = culprits.select { |name| virtual_names.include?(name.to_s) }
+          return env.unload(virtual_culprits) unless virtual_culprits.empty?
 
-            culprits = e.decls.filter_map { |decl| decl.location&.buffer&.name }
-                        .uniq.select { |name| virtual_names.include?(name) }
-            raise if culprits.empty?
+          # Prefer dropping the project buffer(s): the bundled declaration stays, Greeter/core stay
+          # usable, and only the conflicting file is absent.
+          project_culprits = select_project_collision_culprits(culprits, project_names)
+          raise if project_culprits.empty?
 
-            env = env.unload(culprits)
+          env.unload(project_culprits)
+        end
+
+        def duplicated_declaration_buffer_names(error)
+          error.decls.filter_map { |decl| decl.location&.buffer&.name }.uniq
+        end
+
+        def select_project_collision_culprits(culprits, project_names)
+          culprits.select do |name|
+            project_names.include?(File.expand_path(name.to_s))
+          rescue ArgumentError, TypeError
+            project_names.include?(name.to_s)
           end
-          [env, env.resolve_type_names]
         end
 
         # ADR-5 robustness, second tier. A project `signature_paths:` RBS that *references* a type no loaded
@@ -298,11 +340,26 @@ module Rigor
             next if parsed.nil? # quarantined (unparseable) or unreadable — skip so the env survives
 
             buffer, directives, decls = parsed
-            add_parsed_decls(env, buffer, directives, decls)
+            add_project_parsed_decls(env, buffer, directives, decls)
           end
           add_deferred_signatures(env, deferred)
         end
 
+        # Issue #777 — add one project signature transactionally. `RBS::Environment#add_source` appends to
+        # `sources` BEFORE inserting decls, so a mid-insert `RBS::DuplicatedDeclarationError` (class-vs-module
+        # kind collision against bundled RBS, or a constant redeclared from core) would otherwise leave a
+        # poisoned source that `resolve_type_names` re-raises outside every per-file rescue, collapsing the
+        # WHOLE env to nil. Mirror {.add_virtual_rbs}: drop the poisoned source and continue so Greeter /
+        # core / every non-conflicting project file still load. Without a `sources` table (rbs 3.x) re-raise
+        # into the existing total-failure path — we cannot make the skip transactional there.
+        def add_project_parsed_decls(env, buffer, directives, decls)
+          add_parsed_decls(env, buffer, directives, decls)
+        rescue ::RBS::DuplicatedDeclarationError
+          raise unless env.respond_to?(:sources)
+
+          env.sources.reject! { |source| source.buffer.name == buffer.name }
+        end
+
         # Issue #610 — the DEFERRED half: signature files a bundled plugin contributes through its manifest,
         # added after every other source so each can be asked a question the eager half cannot be asked —
         # "does something already declare this class, at a different generic arity?".
@@ -331,12 +388,12 @@ module Rigor
             buffer, directives, decls = parsed
             next if generic_arity_conflict(env, decls)
 
-            add_parsed_decls(env, buffer, directives, decls)
+            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
@@ -353,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
@@ -436,6 +512,55 @@ module Rigor
           end
         end
 
+        # Issue #777 — project `signature_paths:` files that PARSE but are absent from the built env because
+        # {.add_project_parsed_decls} / {.resolve_quarantining_virtual_collisions} quarantined a duplicated
+        # declaration (typically class-vs-module or a constant already shipped by bundled RBS). Derived from
+        # the env like {#virtual_rbs_collision_quarantined}, so a cache HIT reports the same condition.
+        #
+        # Path membership alone is not enough: the suite's {RbsEnvMemo} reuses a byte-identical env across
+        # `Dir.mktmpdir` roots when `signature_paths:` are relative (`sig/sink.rbs`), leaving buffers named
+        # after the FIRST path. A later example's absolute path is then absent from `present` even though
+        # the declarations loaded — that used to spam `duplicated declaration against bundled RBS` banners
+        # (~60 per CI shard) for fixtures that never collided. Basename + content equality catches that
+        # reuse without hiding a real quarantine (e.g. project `class Base64` vs bundled `module Base64`,
+        # same basename, different bytes).
+        COLLISION_QUARANTINE_NOTE =
+          "duplicated declaration against bundled RBS — quarantined so the rest of the RBS env still loads"
+
+        def collision_quarantined_project_signatures(env, signature_paths)
+          return [] if env.nil?
+
+          present = env.buffers.to_set do |buffer|
+            name = buffer.name
+            next name.to_s unless name
+
+            File.expand_path(name.to_s)
+          rescue ArgumentError, TypeError
+            name.to_s
+          end
+          buffers_by_basename = env.buffers.group_by { |buffer| File.basename(buffer.name.to_s) }
+          project_sig_files(signature_paths).sort.filter_map do |file|
+            next if present.include?(file)
+            next if parse_signature_file(file).nil? # parse / encoding quarantine owns these
+            next if project_signature_loaded_under_other_path?(file, buffers_by_basename)
+
+            [file, "#{file}: #{COLLISION_QUARANTINE_NOTE}"]
+          end
+        end
+
+        # True when `file`'s bytes are already in `env` under a different absolute path (same basename).
+        # See {#collision_quarantined_project_signatures} — keeps memoised env reuse from looking like a
+        # collision quarantine.
+        def project_signature_loaded_under_other_path?(file, buffers_by_basename)
+          peers = buffers_by_basename[File.basename(file)]
+          return false if peers.nil? || peers.empty?
+
+          content = File.read(file, encoding: "UTF-8")
+          peers.any? { |buffer| buffer.content == content }
+        rescue Errno::ENOENT, Errno::EISDIR, Errno::EACCES
+          false
+        end
+
         # The `::`-stripped names of every type a PROJECT signature references that no loaded declaration
         # provides — the input to {.append_stub_declarations}.
         #
@@ -702,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|
@@ -713,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
@@ -732,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
@@ -758,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
@@ -794,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?
@@ -814,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)
@@ -833,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)
@@ -846,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).
@@ -886,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)
@@ -901,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?
 
@@ -969,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
@@ -1000,8 +1361,10 @@ module Rigor
         # `.freeze`d (per ADR-15 reflection-facade contract) without losing the lazy-memo behaviour. Slot
         # names currently consulted: `:env`, `:env_loaded`, `:env_build_warned`, `:definition_build_warned`,
         # `:definition_build_details`, `:definition_build_reported`, `:definition_build_failures`,
-        # `:internal_demand`, `:builder`, `:reflection`, `:instance_definitions_table`,
-        # `:singleton_definitions_table`.
+        # `:definition_build_deferred_count`, `:definition_build_deferred_first`,
+        # `: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.
         # `@state[:env_loaded]`) to a constant `nil`.
@@ -1029,15 +1392,32 @@ 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] ||= self.class.quarantined_project_signatures(@signature_paths).freeze
+        @state[:quarantined] ||= begin
+          parse_quarantined = self.class.quarantined_project_signatures(@signature_paths)
+          collision_quarantined = self.class.collision_quarantined_project_signatures(
+            @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 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
@@ -1083,14 +1463,15 @@ module Rigor
       end
 
       # 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 by
-      # re-parsing so a cache HIT reports it too — a total failure (typically `RBS::DuplicatedDeclarationError`:
-      # a `signature_paths:` entry redeclaring a constant/class Rigor's bundled RBS already ships) collapses the
-      # WHOLE env to nil. A failed build produces no cached success to hide behind (nothing is 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.
+      # {#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
+      # `RBS::DuplicatedDeclarationError`s are quarantined per-file since #777; this slot remains for
+      # unrecoverable build errors (e.g. bundled-vs-bundled collisions, or hosts without a transactional
+      # `sources`/`unload` API). A failed build produces no cached success to hide behind (nothing is
+      # 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]
@@ -1114,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
@@ -1128,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]
@@ -1143,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
@@ -1306,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).
       #
@@ -1332,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
@@ -1340,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}).
@@ -1351,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.
@@ -1366,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
@@ -1399,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).
@@ -1420,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.
@@ -1444,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
@@ -1486,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
@@ -1501,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
@@ -1736,11 +2176,10 @@ module Rigor
       end
 
       # The RBS environment for this loader. Memoised both on success AND on failure: when the env build
-      # raises (typically `RBS::DuplicatedDeclarationError` because a `signature_paths:` entry redeclares a
-      # constant or class already shipped by stdlib RBS), retrying on every subsequent `env` call would
-      # re-parse and re-resolve the whole sig set per AST node touched during analysis, multiplying per-file
-      # analysis cost by ~100x. Failures short-circuit to `nil` here and are surfaced to the user via
-      # `warn_about_env_build_failure_once` so the broken `signature_paths:` entry is identifiable.
+      # raises an *unrecoverable* `RBS::BaseError` (project-vs-bundled duplicates are quarantined per-file
+      # since #777), retrying on every subsequent `env` call would re-parse and re-resolve the whole sig set
+      # per AST node touched during analysis, multiplying per-file analysis cost by ~100x. Failures
+      # short-circuit to `nil` here and are surfaced to the user via `warn_about_env_build_failure_once`.
       def env
         return @state[:env] if @state[:env_loaded]
 
@@ -1778,10 +2217,11 @@ module Rigor
         lines = listed.map { |_path, first_line| "    - #{first_line}" }
         lines << "    … and #{more} more" if more.positive?
         warn(
-          "rigor: skipped #{quarantined.size} unparseable RBS file(s) under `signature_paths:`.\n  " \
-          "They were QUARANTINED so the rest of your RBS env still loads, but the types they\n  " \
-          "declare are absent — calls into them read `Dynamic[top]`, so coverage and diagnostics\n  " \
-          "are reduced. Fix the parse error(s) to restore that coverage:\n" \
+          "rigor: skipped #{quarantined.size} RBS file(s) under `signature_paths:` (unparseable or\n  " \
+          "duplicated against bundled RBS). They were QUARANTINED so the rest of your RBS env\n  " \
+          "still loads, but the types they declare are absent — calls into them read\n  " \
+          "`Dynamic[top]`, so coverage and diagnostics are reduced. Fix the parse error(s) or\n  " \
+          "remove the conflicting declaration(s) to restore that coverage:\n" \
           "#{lines.join("\n")}"
         )
       end
@@ -1870,8 +2310,8 @@ module Rigor
       #
       # {#during_internal_demand} (issue #696) — these two walk EVERY known class, so a failure they hit is a
       # failure of the sig set, not of anything the run asked about, and it must not reach
-      # {#definition_build_failures}. The stderr banner is deliberately left armed here, byte-for-byte as
-      # before.
+      # {#definition_build_failures}. The stderr fallback stays armed, but {#during_internal_demand} folds
+      # every failure found by one outermost walk into one bounded summary (issue #718).
       def instance_definitions_table
         @state[:instance_definitions_table] ||= during_internal_demand do
           build_definitions_table { |name| build_instance_definition(name) }
@@ -2005,7 +2445,9 @@ module Rigor
       # review, second pass).
       #
       # Save-and-restore rather than a bare flag: `#prewarm` wraps a body whose members wrap themselves, and
-      # a nested demand must not un-mark its caller on the way out.
+      # a nested demand must not un-mark its caller on the way out. A successful outermost exit flushes the
+      # deferred stderr summary; an outermost exit that raises keeps the detailed fallback banner armed even
+      # when an earlier internal-demand episode already emitted the loader-instance summary.
       #
       # Per LOADER, not per thread. Nesting and a raise mid-demand are both handled, and the fork pool forks
       # after `#prewarm` returns, so no CLI path shares a loader across concurrent analyses. An in-process
@@ -2013,10 +2455,29 @@ module Rigor
       # silence another's reporting; not reachable today, and not worth a thread-local until it is.
       def during_internal_demand
         previous = @state[:internal_demand]
+        outermost = !previous
+        if outermost
+          @state[:definition_build_deferred_count] = 0
+          @state[:definition_build_deferred_first] = nil
+        end
         @state[:internal_demand] = true
-        yield
-      ensure
-        @state[:internal_demand] = previous
+        # `rescue`/`else` keeps the normal block result precise for the analyzer; the pending marker covers
+        # non-local exits (e.g. `throw`) that unwind through `ensure` without entering either branch.
+        @state[:internal_demand_status] = :pending if outermost
+        begin
+          result = yield
+          @state[:internal_demand_status] = :completed if outermost
+        rescue StandardError, ScriptError => e
+          @state[:internal_demand_status] = :aborted if outermost
+          warn_about_aborted_definition_build_failures if outermost
+          raise e
+        else
+          warn_about_deferred_definition_build_failures if outermost
+          result
+        ensure
+          @state[:internal_demand] = previous
+          warn_about_aborted_definition_build_failures if outermost && @state[:internal_demand_status] == :pending
+        end
       end
 
       # The third twin of {#warn_about_quarantined_signatures} / {#warn_about_virtual_rbs_collisions}: name,
@@ -2029,21 +2490,33 @@ module Rigor
       # {#env}, because the whole env is built eagerly and every quarantine/collision is already known by
       # then. Definition builds are LAZY (ADR-54 WD1 — built on demand per class the FIRST time a caller asks,
       # long after {#env} has already run), so there is no later central checkpoint to fire from before the
-      # affected classes even exist. This warns inline at the rescue site instead, gated on
-      # `@state[:definition_build_warned]` (keyed by class name) so the instance and singleton sides — and
-      # any re-entry once the per-process `@instance_definition_cache` / `@singleton_definition_cache`
-      # memoize the failure — warn at most once per class name, cache-hit runs included (a definition build
-      # is per-process regardless of the RBS-env cache tier). `@state` is per-LOADER-INSTANCE, not
-      # process-global, so under the fork-based analysis pool each worker holds its own loader and its own
-      # `@state`: a class whose definition fails can print its warning once per worker that happens to touch
-      # it, i.e. more than once in a single `rigor check` run. Deduplicating that across processes is out of
-      # scope here — see [#295](https://github.com/rigortype/rigor/issues/295).
+      # affected classes even exist. An ordinary demand therefore warns inline at the rescue site; Rigor's
+      # own internal demand defers until its outermost boundary and collapses the whole walk to one summary
+      # (issue #718). Both routes share `@state[:definition_build_warned]` (keyed by normalized class name),
+      # so the instance and singleton sides — and any re-entry once the per-loader-instance definition caches memoize
+      # the failure — count or warn at most once per class name, cache-hit runs included.
+      #
+      # `@state` is per LOADER INSTANCE, not process-global. A fork-pool prewarm finishes before the fork, so
+      # that loader instance emits its summary once in the parent and its dedupe state is inherited by the
+      # workers. A separate loader instance (for example, a parameter-inference pre-pass) has its own summary
+      # budget. A failure first reached by an ordinary demand can still warn once in each worker that reaches
+      # it; deduplicating that across processes is out of scope here — see [#295](https://github.com/rigortype/rigor/issues/295).
       def warn_about_definition_build_failure(class_name, error)
         warned = (@state[:definition_build_warned] ||= {})
-        key = class_name.to_s
+        key = class_name.to_s.delete_prefix("::")
         return if warned[key]
 
         warned[key] = true
+        if @state[:internal_demand]
+          @state[:definition_build_deferred_count] = @state.fetch(:definition_build_deferred_count, 0) + 1
+          @state[:definition_build_deferred_first] ||= [class_name.to_s, error]
+          return
+        end
+
+        warn(definition_build_failure_warning(class_name, error))
+      end
+
+      def definition_build_failure_warning(class_name, error)
         first_line = error.message.to_s.lines.first.to_s.strip
         buffers = definition_build_conflict_buffers(error)
         collisions =
@@ -2056,13 +2529,42 @@ module Rigor
             lines << "    … and #{more} more" if more.positive?
             "\n  Colliding declaration(s):\n#{lines.join("\n")}"
           end
-        warn(
-          "rigor: RBS definition build failed for `#{class_name}`: #{error.class}: #{first_line}\n  " \
+        "rigor: RBS definition build failed for `#{class_name}`: #{error.class}: #{first_line}\n  " \
           "Rigor still treats the class as known, so calls into it now silently degrade to\n  " \
           "`Dynamic[top]` — real methods and typos alike — instead of resolving normally.#{collisions}"
+      end
+
+      def warn_about_deferred_definition_build_failures
+        return if @state[:definition_build_summary_warned]
+
+        count = @state[:definition_build_deferred_count]
+        return if count.nil? || count.zero?
+
+        @state[:definition_build_summary_warned] = true
+        first_class, first_error = @state[:definition_build_deferred_first]
+        affected = if count == 1
+                     "1 class affected"
+                   else
+                     more = count - 1
+                     noun = more == 1 ? "class" : "classes"
+                     "… and #{more} more #{noun} affected (#{count} total)"
+                   end
+        warn(
+          "#{definition_build_failure_warning(first_class, first_error)}\n  " \
+          "Internal whole-universe demand found #{affected}; the " \
+          "`rbs.coverage.definition-build-failed` diagnostic reports the classes the analysis demanded and " \
+          "the culprit member and signature files."
         )
       end
 
+      def warn_about_aborted_definition_build_failures
+        count = @state[:definition_build_deferred_count]
+        return if count.nil? || count.zero?
+
+        first_class, first_error = @state[:definition_build_deferred_first]
+        warn(definition_build_failure_warning(first_class, first_error))
+      end
+
       # The definition-build twin of {#env_build_conflict_buffers}: the declaration source file(s) named by a
       # `RBS::DefinitionBuilder` failure, so {#warn_about_definition_build_failure} can name the colliding
       # declarations rather than only the exception's class and message. The payload shape varies by error
@@ -2105,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)