rigortype 0.3.6 → 0.3.7

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,7 +84,7 @@ 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)
+          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)
@@ -173,7 +177,7 @@ module Rigor
             raise unless env.respond_to?(:unload)
 
             culprits = e.decls.filter_map { |decl| decl.location&.buffer&.name }
-                              .uniq.select { |name| virtual_names.include?(name) }
+                        .uniq.select { |name| virtual_names.include?(name) }
             raise if culprits.empty?
 
             env = env.unload(culprits)
@@ -287,14 +291,98 @@ 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)
           end
+          add_deferred_signatures(env, deferred)
+        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_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
 
         # The quarantine note for a file rejected by {.invalid_encoding?} — worded to be distinct from any
@@ -758,6 +846,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 +939,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 +986,22 @@ 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`,
+        # `:internal_demand`, `: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`.
@@ -838,6 +1034,54 @@ module Rigor
         @state[:quarantined] ||= self.class.quarantined_project_signatures(@signature_paths).freeze
       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`:
@@ -853,6 +1097,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 +1219,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 +1247,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 +1268,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 +1314,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 +1387,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 +1406,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 +1460,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 +1561,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 +1676,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 +1710,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
@@ -1509,15 +1867,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 banner is deliberately left armed here, byte-for-byte as
+      # before.
       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 +1901,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 +1916,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 +1931,94 @@ 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.
+      #
+      # 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]
+        @state[:internal_demand] = true
+        yield
+      ensure
+        @state[:internal_demand] = previous
+      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?`
@@ -1624,22 +2073,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 +2168,5 @@ module Rigor
         false
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end