rigortype 0.3.6 → 0.3.8

data/lib/rigor/environment/rbs_loader.rb

@@ -23,7 +23,7 @@ module Rigor
     # API stays purely functional.
     #
     # See docs/internal-spec/inference-engine.md for the binding contract.
-    # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
     class RbsLoader
       # Buffer name stamped on the `module` declarations synthesized by {.synthesize_missing_namespaces}.
       # Re-read off the built env by {#synthesized_namespaces} so the analysis layer can surface an `:info`
@@ -38,6 +38,10 @@ module Rigor
       # into the set {MethodDispatcher} resolves to `Dynamic[Top]` (no false `call.undefined-method`).
       SYNTHETIC_STUB_BUFFER = "(rigor: synthesized stub types)"
 
+      # The buffer name `Cache::RbsEnvironmentMarshalPatch` reconstructs every `RBS::Location` behind on a
+      # cache HIT. Never a real path, so it must never be reported as one (issue #696).
+      CACHED_LOCATION_BUFFER_NAME = "<cached>"
+
       # Cap on how many quarantined `signature_paths:` files {#warn_about_quarantined_signatures} lists by name
       # before collapsing the tail to "… and N more" — a broken generator can emit many, and a wall of parse
       # errors buries the signal.
@@ -63,7 +67,7 @@ module Rigor
         # Vendored gem stubs (`data/vendored_gem_sigs/<gem>/`) are loaded on top of `signature_paths` so the
         # per-gem RBS bundled with Rigor itself is in scope for every analysis run. The gem stubs are
         # intentionally read-only and appended LAST so user-supplied `signature_paths` win on name conflicts.
-        def build_env_for(libraries:, signature_paths:, virtual_rbs: [])
+        def build_env_for(libraries:, signature_paths:, virtual_rbs: [], deferred_signature_paths: [])
           rbs_loader = RBS::EnvironmentLoader.new
           libraries = libraries_without_shadowed_bigdecimal_math(libraries)
           loaded_libraries = libraries.select do |library|
@@ -80,11 +84,14 @@ 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)
-          add_project_signatures(env, signature_paths)
+          project_files = project_sig_files(signature_paths)
+          add_project_signatures(env, signature_paths, deferred_signature_paths)
           add_virtual_rbs(env, 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
@@ -153,32 +160,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
@@ -287,13 +323,112 @@ module Rigor
         # Buffer names are the file's absolute path (matching {.project_sig_files}) so {.project_entry?} — which
         # attributes a `class_decls` entry to the project by buffer name — still recognises these declarations.
         # Sorted for a deterministic add order (the env feeds the cache, ADR-54).
-        def add_project_signatures(env, signature_paths)
-          project_sig_files(signature_paths).sort.each do |file|
+        def add_project_signatures(env, signature_paths, deferred_paths = [])
+          deferred = project_sig_files(deferred_paths)
+          (project_sig_files(signature_paths) - deferred).sort.each do |file|
             parsed = parse_signature_file(file)
             next if parsed.nil? # quarantined (unparseable) or unreadable — skip so the env survives
 
             buffer, directives, decls = parsed
-            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?".
+        #
+        # `plugins/rigor-activerecord/sig` declares `class Relation[Elem]`; `rbs collection install` ships a
+        # NON-generic `ActiveRecord::Relation`. Two declarations of one class with different arity make
+        # `RBS::DefinitionBuilder` raise `GenericParameterMismatchError`, and Rigor keeps the class KNOWN
+        # after a failed build, so every call INTO a relation reads `Dynamic[top]` — the plugin and
+        # `rigor-project-init`'s own advice to install the collection cancel each other out.
+        #
+        # The plugin stands down, not the user's source, for the reason `Reflection.constant_type_at`
+        # already encodes: the project's own sources are authoritative for the project. Standing down is
+        # strictly better than the collision it replaces — the collection's own declaration builds, where
+        # today NEITHER does — and it cannot regress a project without a colliding declaration, because
+        # nothing triggers.
+        #
+        # Granularity is the FILE, not the declaration: a bundled plugin's `sig/` file is single-purpose
+        # (rigor-activerecord's is `relation.rbs`, declaring exactly `Relation`), so dropping the file drops
+        # exactly the conflicting declaration. Splitting a plugin file that mixes a colliding class with
+        # innocent ones is the change to make if that ever stops being true.
+        def add_deferred_signatures(env, deferred_files)
+          deferred_files.sort.each do |file|
+            parsed = parse_signature_file(file)
+            next if parsed.nil?
+
+            buffer, directives, decls = parsed
+            next if generic_arity_conflict(env, 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
+        # 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
+        # absent from it, and the source that displaced it is still there with its own arity.
+        def deferred_standdowns(env, deferred_paths)
+          return [] if env.nil? || deferred_paths.nil? || deferred_paths.empty?
+
+          project_sig_files(deferred_paths).sort.filter_map do |file|
+            parsed = parse_signature_file(file)
+            next if parsed.nil?
+
+            conflict = generic_arity_conflict(env, parsed[2])
+            conflict && [file, *conflict]
+          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.
+        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)
+
+            existing = entry.type_params&.size
+            return [name, existing, arity] if existing && existing != arity
+          end
+          nil
+        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
+        # comparing a relative `Relation` against it would silently never match.
+        def each_declared_class(decls, prefix = [], &block)
+          decls.each do |decl|
+            case decl
+            when ::RBS::AST::Declarations::Module
+              each_declared_class(decl.members, prefix + [decl.name.to_s], &block)
+            when ::RBS::AST::Declarations::Class
+              inner = prefix + [decl.name.to_s]
+              block.call("::#{inner.join('::')}", decl.type_params.size)
+              each_declared_class(decl.members, inner, &block)
+            end
           end
         end
 
@@ -348,6 +483,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}.
         #
@@ -758,6 +942,79 @@ module Rigor
           end
         end
 
+        # @param path [String, Pathname] typically an entry from an {RbsLoader} instance's
+        #   {#signature_paths}.
+        # @return [Boolean] 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).
+        #   `GEM_OVERLAY_SIGS_ROOT` is defined inside this `class << self` block, so it is reachable from
+        #   here directly but NOT as `RbsLoader::GEM_OVERLAY_SIGS_ROOT` from outside — this method is the
+        #   public seam callers outside this class use instead of reaching for the constant themselves.
+        def under_gem_overlay_root?(path)
+          path.to_s.start_with?("#{GEM_OVERLAY_SIGS_ROOT}/")
+        end
+
+        # The twin of {.under_gem_overlay_root?}, for the OTHER copy of the same declarations. ADR-72 ships
+        # each overlay's surface twice — as `data/gem_overlay/<gem>/` and as the opt-in plugin's own `sig/` —
+        # and a project can reach the second WITHOUT the plugin registry, by naming it in `signature_paths:`
+        # (issue #672). Two callers ask, for different reasons:
+        #
+        # - `Environment.gem_overlay_paths` asks per gem, so the overlay stands down instead of loading
+        #   alongside the twin and collapsing every class they share;
+        # - `CheckRules#gem_overlay_loaded?` asks across all of them, because the twin's `sig/` carries no
+        #   plugin manifest, so `open_receivers:` cannot protect the partial `ActiveSupport::Duration`
+        #   declaration it nonetheless loads.
+        #
+        # **Both ask what an entry LOADS, not what it looks like.** Comparing path strings is wrong in both
+        # directions, and the false-positive direction is the expensive one: an entry naming the twin's
+        # `.rbs` FILE, or a subdirectory of the twin that does not exist, matches as a string while the
+        # loader reads nothing from it ({.project_sig_files} takes directories only — the same fact
+        # {Rigor::SignaturePathAudit} reports as `:not_directory` / `:missing`). Standing an overlay down for
+        # those leaves the project with NEITHER copy, so ordinary `3.minutes` draws `call.undefined-method`
+        # on correct code. The quiet direction is the mirror: a symlink to the twin, or a case-variant
+        # spelling of it where the filesystem folds case, loads the twin while matching no prefix. Asking
+        # {.project_sig_files} for the twin's files and canonicalising both sides answers both.
+        #
+        # Lives here rather than on {Rigor::Environment} because it is an internal seam, not ADR-2 public
+        # API: `spec/rigor/public_api_drift_spec.rb` pins `Environment`'s singleton surface, and a predicate
+        # two call sites share is not a promise to plugin authors. Here it sits beside the overlay-side
+        # 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
+        #   {#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)
+          # `GEM_OVERLAY_PLUGIN_IDS` is ADR-72 eligibility policy and stays owned by `Environment`; it is
+          # read here only to enumerate which bundled plugins HAVE an overlay twin.
+          GEM_OVERLAY_PLUGIN_IDS.each_value.any? do |plugin_id|
+            bundled_overlay_twin_signatures_loaded?(plugin_id, signature_paths)
+          end
+        end
+
+        # The per-plugin half of {.gem_overlay_twin_signatures_loaded?}. `Environment` owns the gem → plugin
+        # 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"`.
+        def bundled_overlay_twin_signatures_loaded?(plugin_id, signature_paths)
+          return false if signature_paths.nil? || signature_paths.empty?
+
+          # In-method for the reason `Plugin::FirstParty` documents at its own `require`: the plugin
+          # subsystem's load graph reaches back into the environment, and only the overlay path calls this —
+          # a run with no eligible overlay gem never pays them.
+          require_relative "../plugin/first_party"
+          require_relative "../plugin/loader"
+          twin = Plugin::Loader.bundled_plugin_sig_path("#{Plugin::FirstParty::GEM_PREFIX}#{plugin_id}")
+          return false unless twin
+
+          twin_files = project_sig_files([twin]).filter_map { |file| canonical_real_path(file) }
+          return false if twin_files.empty?
+
+          signature_paths.any? { |entry| signature_entry_loads?(entry, twin_files) }
+        end
+
         def vendored_gem_sig_paths
           return [] unless File.directory?(VENDORED_GEM_SIGS_ROOT)
 
@@ -778,6 +1035,34 @@ module Rigor
             File.file?(File.join(VENDORED_GEM_SIGS_ROOT, child))
           end
         end
+
+        # Everything below is internal to {.bundled_overlay_twin_signatures_loaded?}. `private` (not
+        # `private_class_method`) because inside `class << self` these are instance methods of the
+        # singleton class; `private_class_method` looks for them one level further out and raises NameError
+        # at load. Placed last so the modifier cannot capture a method that is meant to be reachable.
+        private
+
+        # Whether one `signature_paths:` entry is a directory the loader would read one of `twin_files`
+        # from. Both sides are canonicalised first, which is what makes a symlinked or case-variant
+        # spelling of the twin answer the same as the twin itself.
+        def signature_entry_loads?(entry, twin_files)
+          dir = canonical_real_path(entry)
+          return false unless dir && File.directory?(dir)
+
+          prefix = "#{dir}#{File::SEPARATOR}"
+          twin_files.any? { |file| file.start_with?(prefix) }
+        end
+
+        # `File.realpath` rather than `File.expand_path`: it resolves symlinks and, on a case-insensitive
+        # filesystem, the on-disk spelling — the two ways a path can reach the twin's files without looking
+        # like it. It raises for a path that does not exist, which is the answer we want (an entry that
+        # resolves to nothing loads nothing), so the rescue returns nil rather than falling back to a
+        # lexical expansion that would resurrect the string match.
+        def canonical_real_path(path)
+          File.realpath(path.to_s)
+        rescue SystemCallError
+          nil
+        end
       end
 
       attr_reader :libraries, :signature_paths, :cache_store, :virtual_rbs
@@ -797,15 +1082,24 @@ module Rigor
       #   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.
-      def initialize(libraries: [], signature_paths: [], cache_store: nil, virtual_rbs: [])
+      def initialize(libraries: [], signature_paths: [], cache_store: nil, virtual_rbs: [],
+                     deferred_signature_paths: [])
         @libraries = libraries.map(&:to_s).freeze
         @signature_paths = signature_paths.map { |p| Pathname(p) }.freeze
+        # Issue #610 — the subset of `signature_paths:` a bundled PLUGIN contributed. Loaded last and
+        # allowed to stand down against a colliding generic arity ({.add_deferred_signatures}). Every entry
+        # is also in `@signature_paths`, so the env cache descriptor already digests these files.
+        @deferred_signature_paths = deferred_signature_paths.map { |p| Pathname(p) }.freeze
         @cache_store = cache_store
         @virtual_rbs = virtual_rbs.map { |name, content| [name.to_s.dup.freeze, content.to_s.dup.freeze].freeze }.freeze
         # Per-loader memoization bucket. Held as a single mutable Hash so the loader instance itself can be
         # `.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`,
-        # `:builder`, `:reflection`, `:instance_definitions_table`, `:singleton_definitions_table`.
+        # `: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`,
+        # `: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`.
@@ -835,16 +1129,75 @@ module Rigor
       #
       # @return [Array<Array(String, String)>] 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 }
+          (
+            parse_quarantined +
+            collision_quarantined.reject { |entry| parse_paths.include?(entry[0]) }
+          ).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.
+      def signature_standdowns
+        @state[:signature_standdowns] ||= self.class.deferred_standdowns(env, @deferred_signature_paths).freeze
+      end
+
+      # Issue #735 — the class / module names whose PRIMARY declaration lives under the project's own
+      # `signature_paths:`, top-level prefix stripped ("::Admin::Widget" reads back as "Admin::Widget").
+      #
+      # The distinction it exists to draw: a BUNDLED declaration (core, stdlib, a gem's RBS) is
+      # authoritative about its class, so a project `def` on that class is a monkey-patch and ADR-17 has
+      # the analyzer report it rather than adopt it. A declaration the project wrote itself — by hand or
+      # through `rigor sig-gen --write` — is a sidecar of the same source tree, and a `def` in another of
+      # the project's own files is not a monkey-patch, just the second file of an ordinary class. Reading
+      # a partial sidecar as authoritative made `sig-gen --write` on redmine report 5.9x more
+      # `call.undefined-method` than the same project with no `sig/` at all.
+      #
+      # Memoised per loader: one pass over `class_decls` (~1-2k entries), and every consumer is a check
+      # rule on the analysis hot path. Attribution is by buffer NAME, which survives the ADR-54 environment
+      # cache since #725 — an environment blob written before that carries the `<cached>` sentinel instead,
+      # which lands every class outside this set and leaves the pre-#735 behaviour, never a new silence.
+      def project_declared_classes
+        @state[:project_declared_classes] ||= build_project_declared_classes
+      end
+
+      def build_project_declared_classes
+        environment = env
+        return Set.new.freeze if environment.nil?
+
+        project_files = self.class.project_sig_files(@signature_paths)
+        return Set.new.freeze if project_files.empty?
+
+        names = environment.class_decls.each_with_object(Set.new) do |(rbs_name, entry), acc|
+          acc << rbs_name.to_s.delete_prefix("::") if self.class.project_entry?(entry, project_files)
+        end
+        names.freeze
+      rescue ::RBS::BaseError
+        Set.new.freeze
+      end
+      private :build_project_declared_classes
+
+      # True when `class_name`'s RBS declaration is one the project wrote (see {#project_declared_classes}).
+      def project_declared_class?(class_name)
+        project_declared_classes.include?(class_name.to_s.delete_prefix("::"))
       end
 
       # 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,
       #   conflicting_buffer_names]`, or nil when the environment built successfully.
@@ -853,6 +1206,30 @@ module Rigor
         @state[:env_build_failure]
       end
 
+      # Issue #696 — the PER-CLASS sibling of {#env_build_failure}, one tier quieter in consequence: an
+      # `RBS::DefinitionBuilder` failure ({#build_instance_definition} / {#build_singleton_definition}'s
+      # rescue) leaves the class KNOWN but with no method surface, so every call on it — real methods and
+      # typos alike — reads `Dynamic[top]` and stops being checkable. `class_known?` consults
+      # {#known_class_names_set}, never a definition build, so nothing downstream can tell the difference.
+      #
+      # NOT forced the way {#env_build_failure} forces `env`, and it MUST NOT be: definition builds are lazy
+      # (ADR-54 WD1 — per class, on first demand), so this answers "which classes has THIS loader failed to
+      # build so far". A reader that forces would have to build every known class, which is a different and
+      # far more expensive question than the run asked. The consequence for callers is a timing contract: a
+      # snapshot taken before the per-file loop reads empty. `Runner::PoolCoordinator` reads it after.
+      #
+      # Recorded, not derived. The two conditions this sits beside are re-derivable from the built env
+      # ({#quarantined_signatures} re-parses; {#virtual_rbs_collision_quarantined} inspects buffers), but a
+      # definition-build failure leaves no trace in the env at all — the env is fine; it is the BUILD over it
+      # that raised — so the rescue is the only place that ever knows.
+      #
+      # @return [Array<Array(String, String, String, Array<String>)>] `[class_name, error_class_name,
+      #   first_error_line, conflicting_buffer_names]`, one per class, in first-failure order. Empty for a
+      #   healthy sig set, which is the common case.
+      def definition_build_failures
+        (@state[:definition_build_failures] || []).dup.freeze
+      end
+
       # Virtual (inline-synthesized) contributions dropped by the collision quarantine
       # ({.resolve_quarantining_virtual_collisions}): buffer names absent from the built env even though the
       # entry's content is non-empty and parses (a parse failure is the synthesizer's own WD6 skip, reported
@@ -951,8 +1328,25 @@ module Rigor
         # silently the way the v0.0.9 cache `Cache::Descriptor` regression did.
       end
 
+      # Yields every type-alias declaration loaded into the environment (`type foo = ...`).
+      # Yields `(RBS::TypeName, RBS::Environment::TypeAliasEntry)` pairs.
+      def each_type_alias_decl
+        return enum_for(:each_type_alias_decl) unless block_given?
+        return unless env
+
+        env.type_alias_decls.each do |type_name, decl_entry|
+          yield [type_name, decl_entry]
+        end
+      end
+
       # ADR-20 slice 2e — iterates over every `%a{...}` annotation attached to a class- or module-level
       # declaration in the loaded RBS environment, yielding `(annotation_string, source_location)` pairs.
+      #
+      # Declarations come from {.entry_declarations}, NOT from a direct `entry.each_decl`: that accessor is
+      # RBS 4.x-only, so the direct call raised `NoMethodError` on every RBS 3.x host — inside a rescue that
+      # deliberately does not swallow `NoMethodError`. It stayed latent because nothing the `rbs-compat` job
+      # runs reached an annotated declaration until #672 added a spec under `spec/rigor/environment` that
+      # drives a whole `Runner`.
       # Used by {Rigor::Inference::HktRegistry.scan_rbs_loader} to find `rigor:v1:hkt_register` /
       # `rigor:v1:hkt_define` directives in user-authored overlays and merge them into the per-`Environment`
       # HKT registry. Yields nothing when the env failed to build (fail-soft, same shape as
@@ -962,7 +1356,7 @@ module Rigor
         return if env.nil?
 
         env.class_decls.each_value do |entry|
-          entry.each_decl do |decl|
+          self.class.entry_declarations(entry).each do |decl|
             next unless decl.respond_to?(:annotations)
 
             decl.annotations.each { |a| yield a.string, a.location }
@@ -983,7 +1377,7 @@ module Rigor
         return if env.nil?
 
         env.class_decls.each do |rbs_name, entry|
-          entry.each_decl do |decl|
+          self.class.entry_declarations(entry).each do |decl|
             next unless decl.respond_to?(:annotations)
 
             decl.annotations.each { |a| yield rbs_name.to_s, a.string, a.location }
@@ -1029,11 +1423,22 @@ module Rigor
       # keeps the per-process short-circuit. ADR-54 WD1 retired the definitions disk blob: given a cached
       # env, `Marshal.load`-ing every definition was measurably slower (and allocation-heavier) than
       # rebuilding the ones a run actually touches.
+      #
+      # Issue #696 — the report fires HERE, on the result, rather than in `build_*`'s rescue, and it fires on
+      # a memo hit too. `#prewarm`'s cached producers walk every known class through this method, so by the
+      # time a run demands `String` the nil is already memoised and the rescue will never run again; a report
+      # wired to the rescue would say nothing. The guard keeps the cost on the hot path at one `@state` read,
+      # and only on the nil branch — `nil` here is overwhelmingly an unknown class, not a failed build.
       def instance_definition(class_name)
         key = class_name.to_s
-        return @instance_definition_cache[key] if @instance_definition_cache.key?(key)
-
-        @instance_definition_cache[key] = build_instance_definition(class_name)
+        definition =
+          if @instance_definition_cache.key?(key)
+            @instance_definition_cache[key]
+          else
+            @instance_definition_cache[key] = build_instance_definition(class_name)
+          end
+        report_definition_build_failure(class_name) if definition.nil? && @state[:definition_build_details]
+        definition
       end
 
       # @return [RBS::Definition::Method, nil]
@@ -1091,7 +1496,14 @@ module Rigor
         name = name.absolute! unless name.absolute?
         return nil unless env.type_alias_decls.key?(name)
 
-        builder.expand_alias2(name, rbs_alias.args)
+        # Memoized per (name, args): the env is immutable for the loader's lifetime, so the expansion is a
+        # pure function of the pair, and #529's translator wiring re-expands the same handful of aliases
+        # (`Prism::node`, `int`, `string`, …) at every call site — the memo recoups most of that wall cost.
+        memo = (@state[:type_alias_expansions] ||= {})
+        key = [name, rbs_alias.args]
+        return memo[key] if memo.key?(key)
+
+        memo[key] = builder.expand_alias2(name, rbs_alias.args)
       rescue ::RBS::BaseError, StandardError
         nil
       end
@@ -1103,11 +1515,18 @@ module Rigor
       #
       # Built on demand from the env with a per-process memo; the same on-demand discipline as
       # {#instance_definition} (ADR-54 WD1).
+      #
+      # The singleton twin of {#instance_definition}, reporting on the same terms (issue #696).
       def singleton_definition(class_name)
         key = class_name.to_s
-        return @singleton_definition_cache[key] if @singleton_definition_cache.key?(key)
-
-        @singleton_definition_cache[key] = build_singleton_definition(class_name)
+        definition =
+          if @singleton_definition_cache.key?(key)
+            @singleton_definition_cache[key]
+          else
+            @singleton_definition_cache[key] = build_singleton_definition(class_name)
+          end
+        report_definition_build_failure(class_name) if definition.nil? && @state[:definition_build_details]
+        definition
       end
 
       # @return [RBS::Definition::Method, nil] the class method on `class_name`. For example,
@@ -1150,6 +1569,47 @@ module Rigor
         @hierarchy.class_ordering(lhs, rhs)
       end
 
+      # The ancestor chain of ONE class, as {RbsHierarchy} asks it to order two classes.
+      #
+      # Issue #696 review (second pass) — this used to live in the hierarchy, which branched on
+      # `cache_store`: with a store it built the whole `RbsClassAncestorTable` and read one key, without a
+      # store it demanded that one class. Three configurations, three different answers to "which classes
+      # failed to build" for one project — 504 classes on a cold store, 0 on a warm one, 2 with no store —
+      # and on the DEFAULT `--workers=0` path, where nothing pre-warms the store first, the cold answer was
+      # the one written into the run-result cache and replayed on every warm run after it.
+      #
+      # The fix is {#during_internal_demand} on BOTH sides, not the removal of the branch. Collapsing to a
+      # per-class demand everywhere was tried first and measured 50x slower on the warm path a cached run
+      # actually takes (200 orderings: 0.0035s reading the table, 0.18s building 400 definitions), which is
+      # the wrong trade for a determinism the marking already buys. What has to be identical across cache
+      # states is the diagnostic, and with both sides marked neither contributes to it: the reported set is
+      # the classes whose METHOD SURFACE the analysis demanded, in every configuration. The memo-hit report
+      # in {#instance_definition} is what makes that hold — a class this path built and memoised as nil is
+      # still reported when a real demand for it arrives later.
+      #
+      # The table side goes through {#ancestor_names_table}, the loader's own marked accessor, rather than
+      # `Cache::RbsClassAncestorTable.fetch` directly. That direct fetch was the bypass: it walked every
+      # known class through the public {#instance_definition} with nothing marking it.
+      #
+      # Answers are identical on both sides — the table's producer computes exactly this, keyed the same
+      # 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.
+      def ancestor_names_for(class_name)
+        key = class_name.to_s.delete_prefix("::")
+        during_internal_demand do
+          next ancestor_names_table.fetch(key, [].freeze) if cache_store
+
+          definition = instance_definition(key)
+          next [].freeze if definition.nil?
+
+          definition.ancestors.ancestors.map { |ancestor| ancestor.name.to_s.delete_prefix("::") }.uniq.freeze
+        end
+      rescue ::RBS::BaseError, StandardError
+        [].freeze
+      end
+
       # @return [Array<String>] 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.
@@ -1210,16 +1670,23 @@ module Rigor
       # No-op when `cache_store` is nil — without a Store the worker has no choice but to build env via the
       # loader, so the caller MUST ensure pool mode runs with caching enabled. Returns `self` so the call
       # chains cleanly from the `Runner` pre-spawn hook.
+      #
+      # Issue #696 — the whole body is a {#during_internal_demand}, not only the producers that happen to walk
+      # definitions today. On a COLD store `RbsClassTypeParamNames.compute` and `RbsClassAncestorTable.compute`
+      # ask {#instance_definition} for every known class; marking each producer covers that, and marking
+      # `#prewarm` itself covers whichever producer grows the same appetite next.
       def prewarm
         return self if cache_store.nil?
 
-        env
-        known_class_names_set
-        constant_type_table
-        type_param_names_table
-        ancestor_names_table
-        instance_definitions_table
-        singleton_definitions_table
+        during_internal_demand do
+          env
+          known_class_names_set
+          constant_type_table
+          type_param_names_table
+          ancestor_names_table
+          instance_definitions_table
+          singleton_definitions_table
+        end
         self
       end
 
@@ -1318,21 +1785,21 @@ module Rigor
       end
 
       def constant_type_table
-        @constant_type_table ||= begin
+        @constant_type_table ||= during_internal_demand do
           require_relative "../cache/rbs_constant_table"
           fetch_or_compute_producer(Cache::RbsConstantTable)
         end
       end
 
       def known_class_names_set
-        @known_class_names_set ||= begin
+        @known_class_names_set ||= during_internal_demand do
           require_relative "../cache/rbs_known_class_names"
           fetch_or_compute_producer(Cache::RbsKnownClassNames)
         end
       end
 
       def type_param_names_table
-        @type_param_names_table ||= begin
+        @type_param_names_table ||= during_internal_demand do
           require_relative "../cache/rbs_class_type_param_names"
           fetch_or_compute_producer(Cache::RbsClassTypeParamNames)
         end
@@ -1352,7 +1819,7 @@ module Rigor
       # the existing `RbsClassAncestorTable` producer when `cache_store` is set; falls back to the
       # producer's `compute` otherwise. Used by {#reflection}.
       def ancestor_names_table
-        @ancestor_names_table ||= begin
+        @ancestor_names_table ||= during_internal_demand do
           require_relative "../cache/rbs_class_ancestor_table"
           fetch_or_compute_producer(Cache::RbsClassAncestorTable)
         end
@@ -1378,11 +1845,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]
 
@@ -1420,10 +1886,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
@@ -1509,15 +1976,20 @@ module Rigor
       # all definitions from a cached env is faster), so the eager-table cost is now a compute, not a load.
       # Keys stay in `RBS::TypeName#to_s` form (top-level prefixed `"::Hash"`) — the shape
       # {Environment::Reflection} documents.
+      #
+      # {#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 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] ||= build_definitions_table do |name|
-          build_instance_definition(name)
+        @state[:instance_definitions_table] ||= during_internal_demand do
+          build_definitions_table { |name| build_instance_definition(name) }
         end
       end
 
       def singleton_definitions_table
-        @state[:singleton_definitions_table] ||= build_definitions_table do |name|
-          build_singleton_definition(name)
+        @state[:singleton_definitions_table] ||= during_internal_demand do
+          build_definitions_table { |name| build_singleton_definition(name) }
         end
       end
 
@@ -1538,7 +2010,8 @@ module Rigor
         self.class.build_env_for(
           libraries: @libraries,
           signature_paths: @signature_paths,
-          virtual_rbs: @virtual_rbs
+          virtual_rbs: @virtual_rbs,
+          deferred_signature_paths: @deferred_signature_paths
         )
       end
 
@@ -1552,6 +2025,7 @@ module Rigor
 
         builder.build_instance(rbs_name)
       rescue ::RBS::BaseError => e
+        store_definition_build_detail(class_name, e)
         warn_about_definition_build_failure(class_name, e)
         nil
       end
@@ -1566,10 +2040,115 @@ module Rigor
 
         builder.build_singleton(rbs_name)
       rescue ::RBS::BaseError => e
+        store_definition_build_detail(class_name, e)
         warn_about_definition_build_failure(class_name, e)
         nil
       end
 
+      # Issue #696 — the DETAIL half of the same rescue: what went wrong for this class, remembered so
+      # {#definition_build_failures} can report it. Split from the REPORTING decision on purpose, and the
+      # split is the whole fix.
+      #
+      # Recording in the rescue is wrong in both directions at once. Too loud: `#prewarm` and the cached
+      # table producers walk EVERY known class, so on a cold store they enter this rescue for every class a
+      # collision took down — 1,336 of them for one `class Object` duplicate — and the diagnostic named all
+      # of them under `--workers=N` with a cold cache while naming 3 under every other configuration. Too
+      # quiet: {#instance_definition} memoises the nil, so once that walk has run, the FIRST real demand
+      # never re-enters the rescue and would record nothing at all.
+      #
+      # So the rescue only remembers, keyed by the `::`-stripped name (the eager walk spells it `::Acme`,
+      # a dispatch site spells it `Acme`, and they are one class — the {#synthesized_namespaces}
+      # convention), and {#report_definition_build_failure} decides. First writer wins: the instance and
+      # singleton sides fail for the same underlying collision, and the first is the one a caller hit.
+      def store_definition_build_detail(class_name, error)
+        key = class_name.to_s.delete_prefix("::")
+        details = (@state[:definition_build_details] ||= {})
+        return if details.key?(key)
+
+        details[key] = [key, error.class.name.to_s, definition_build_member(error),
+                        definition_build_conflict_buffers(error)].freeze
+      end
+
+      # Issue #696 — the REPORTING half: promote a remembered detail into {#definition_build_failures}
+      # because something the run was actually doing asked for this class's definition and got nothing.
+      #
+      # Called from {#instance_definition} / {#singleton_definition} — the demand entries — rather than from
+      # the rescue, so it fires on a MEMO HIT too. That is what survives a pre-warm: the walk builds the
+      # definition, fails, memoises nil, and never enters the rescue again, but the next real demand still
+      # reads nil here and still reports. Reporting from the rescue could only ever see the first build.
+      #
+      # Silent inside a whole-universe walk ({#during_internal_demand}): a producer that touches every known
+      # class is asking a question the RUN did not ask, and letting it contribute makes the reported class
+      # list depend on whether a cache was cold — the same project saying different things under
+      # `--workers=N` than under `--workers=0`, which is the defect this diagnostic exists to end.
+      def report_definition_build_failure(class_name)
+        return if @state[:internal_demand]
+
+        details = @state[:definition_build_details]
+        return if details.nil?
+
+        key = class_name.to_s.delete_prefix("::")
+        detail = details[key]
+        return if detail.nil?
+
+        reported = (@state[:definition_build_reported] ||= {})
+        return if reported[key]
+
+        reported[key] = true
+        (@state[:definition_build_failures] ||= []) << detail
+      end
+
+      # Marks a definition demand that is RIGOR'S OWN, not the analysed program's, so
+      # {#report_definition_build_failure} stays silent for the duration.
+      #
+      # The diagnostic reports classes whose METHOD SURFACE the analysis asked to resolve — that is what its
+      # message promises, and it is the only demand set that does not vary with how the run was invoked. Two
+      # kinds of demand are Rigor's own and must be excluded:
+      #
+      # - a whole-universe cache producer ({#prewarm}'s tables), which asks about every known class;
+      # - the hierarchy oracle's ancestry lookup ({#ancestor_names_for}), which asks whether two classes are
+      #   ordered, not whether either one's methods resolve.
+      #
+      # Both were cache-state-dependent before this, and each produced a DIFFERENT class list per
+      # configuration for the same project — the second one on the DEFAULT `--workers=0` path (issue #696
+      # 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 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
+      # host that did (`language_server/debouncer.rb` runs analysis on a `Thread`) could have one analysis
+      # 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
+        # `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,
       # once per class per PROCESS, a `RBS::DefinitionBuilder` failure caught in
       # {#build_instance_definition} / {#build_singleton_definition}'s rescue. Without it, `class_known?`
@@ -1580,21 +2159,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 =
@@ -1607,13 +2198,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
@@ -1624,22 +2244,53 @@ module Rigor
       # `#location`. Falls back to an empty list — the warning still names the class and the exception's own
       # message — for the remainder (e.g. `SuperclassMismatchError`, which carries neither).
       def definition_build_conflict_buffers(error)
-        locations =
-          if error.respond_to?(:members) && error.members
-            Array(error.members).map(&:location)
-          elsif error.respond_to?(:member) && error.member
-            [error.member.location]
-          elsif error.respond_to?(:location)
-            [error.location]
-          else
-            []
-          end
-
-        locations.compact.filter_map { |loc| loc.buffer&.name }.map(&:to_s).uniq.freeze
+        definition_build_error_locations(error)
+          .compact.filter_map { |loc| loc.buffer&.name }.map(&:to_s)
+          .reject { |name| name == CACHED_LOCATION_BUFFER_NAME }.uniq.freeze
       rescue ::RBS::BaseError, StandardError
         [].freeze
       end
 
+      # The `RBS::Location`s an error carries, by whichever accessor its class happens to expose (see the
+      # shape survey above). Split out so the buffer-name extraction reads as one pipeline.
+      def definition_build_error_locations(error)
+        return Array(error.members).map(&:location) if error.respond_to?(:members) && error.members
+        return [error.member.location] if error.respond_to?(:member) && error.member
+        return [error.location] if error.respond_to?(:location)
+
+        []
+      end
+
+      # The member the failure is ABOUT, taken off the error object rather than parsed out of its message.
+      #
+      # Issue #696 — the message cannot serve here. It is built from `RBS::Location`s, and the ADR-54 env
+      # cache drops their POSITIONS, so a warm run's message would name no line and the same project would
+      # report different text cold and warm. These accessors are `RBS::TypeName`s and Symbols, so they
+      # survive the marshal round trip unchanged — and they name the class that actually CARRIES the
+      # duplicate, which the failed-class list does not: a collision on `::Object#blank?` fails `String`,
+      # `Integer` and `Array`, none of which is where the fix goes. (The buffer NAME does survive, since the
+      # second review pass; it is the file list that uses it, not this.)
+      #
+      # Shapes vary by error class (`references/rbs`'s `lib/rbs/errors.rb`): the two duplicated-definition
+      # errors expose `#qualified_method_name` directly; `InvalidOverloadMethodError` has `#type_name` +
+      # `#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)
+
+        type_name = error.respond_to?(:type_name) ? error.type_name : nil
+        type_name ||= error.respond_to?(:name) ? error.name : nil
+        return nil if type_name.nil?
+
+        method_name = error.respond_to?(:method_name) ? error.method_name : nil
+        method_name.nil? ? type_name.to_s : "#{type_name}##{method_name}"
+      rescue ::RBS::BaseError, StandardError
+        nil
+      end
+
       # Resolve an RBS class/module ALIAS to its canonical declared name. `class Mutex = Thread::Mutex`
       # lives only in `class_alias_decls`, so `class_known?` reports it (it checks that table) but the
       # definition builder — which only knows `class_decls` — could not enumerate its methods, leaving alias
@@ -1688,6 +2339,5 @@ module Rigor
         false
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end