rigortype 0.4.6 → 0.4.8

data/lib/rigor/environment/rbs_loader.rb

@@ -10,8 +10,12 @@ require_relative "member_consistency"
 require_relative "required_features"
 require_relative "gated_signature_guard"
 require_relative "gated_signature_plan"
+require_relative "deferred_signature_plan"
+require_relative "vendored_signature_plan"
 require_relative "ruby_library_roots"
+require_relative "core_root"
 require_relative "../rooted_glob"
+require_relative "../typing_state"
 
 module Rigor
   class Environment
@@ -32,6 +36,12 @@ module Rigor
     # See docs/internal-spec/inference-engine.md for the binding contract.
     # rubocop:disable-next Metrics/ClassLength
     class RbsLoader
+      # ADR-129 G4 — keyed on the class name, answered from the loader's RBS environment (or, for `class_known?`, the
+      # known-name set cached for it), fixed for the loader's lifetime. `@state` is not declared: beside its lazy
+      # derivations it holds warn-once flags and failure counters.
+      TypingState.memo_field(self, :@instance_definition_cache, :@singleton_definition_cache, :@class_known_cache,
+                             reason: "keyed on the class name; a function of the loader's RBS environment")
+
       # 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`
       # diagnostic naming the project's malformed-RBS namespaces — robust across the marshalled env cache,
@@ -60,13 +70,27 @@ module Rigor
           .compact.map { |root| "#{root}/".freeze }.freeze
       rescue StandardError
         [].freeze
-      end
+      end.freeze
 
       # 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.
       QUARANTINE_WARN_LIMIT = 10
 
+      # ADR-129 WD1 — a Frame: {.with_core_root} installs the core root for one environment build and restores the
+      # previous one on the way out. It changes answers (a loader built under it reads a different `core/`), and the
+      # installed value is a {CoreRoot.validate!}d frozen String or nil. Per thread (per fiber), so a concurrent build
+      # on another thread keeps its own.
+      CORE_ROOT = TypingState.frame(
+        :rbs_core_root,
+        reason: "installed per environment build by with_core_root; selects the core/ directory every loader of the " \
+                "build reads (a validated absolute path, or nil for the rbs gem's own)",
+        # G1′: the build installs the core root and reads it, and every analysing entry point builds the environment
+        # before anything types ({Environment.for_project}, `eager:`; #2883), so no `type_of` reads it.
+        typing_never_reads: true
+      )
+      private_constant :CORE_ROOT
+
       class << self
         # Issue #1902 — the fixed total order that picks ONE detail tuple for a class out of several: its two
         # sides in {#report_definition_build_failure}, or a fresh and a replayed record in
@@ -96,14 +120,40 @@ 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: [], deferred_signature_paths: [])
-          inputs = [signature_paths, virtual_rbs, deferred_signature_paths]
+        #
+        # @param project_signature_paths — issue #2422 — the project's own `signature_paths:` (not the collection,
+        #   gem or plugin directories also on `signature_paths`): a plugin member another source declares composes
+        #   with it as an overload unless that source is the project's own ({DeferredSignaturePlan}).
+        # @param core_root — issue #2517 — a validated {CoreRoot} directory loaded in place of the `rbs` gem's
+        #   `core/`, or nil for the default core.
+        # @param subordinate_signature_paths — issue #2978 — the subset of `signature_paths` that loads right after
+        #   the other `signature_paths` files and stands down member by member to them ({.add_project_signatures}).
+        # @param collection_signature_paths — issue #3030 — the subset of `signature_paths` that are `rbs collection`
+        #   gem directories, read without their `_`-prefixed directories ({.project_sig_files}).
+        def build_env_for(libraries:, signature_paths:, virtual_rbs: [], deferred_signature_paths: [], # rubocop:disable Metrics/ParameterLists
+                          project_signature_paths: [], core_root: nil, subordinate_signature_paths: [],
+                          collection_signature_paths: [])
+          inputs = [signature_paths, virtual_rbs, deferred_signature_paths, project_signature_paths,
+                    subordinate_signature_paths, collection_signature_paths]
+          with_core_root(core_root) { build_env_from(libraries, inputs) }
+        end
+
+        # Issue #2517 — the core root {.library_loader} builds every loader of one environment build against. Held
+        # for the build rather than threaded through each attempt, because every trial and fallback of
+        # {.build_env_from} must read the same core, and a parameter missed on one of them would build that attempt
+        # against the default core without a sign. Thread-local, so a concurrent build on another thread keeps its
+        # own.
+        def with_core_root(core_root, &)
+          TypingState.current.with(CORE_ROOT, core_root, &)
+        end
+
+        def build_env_from(libraries, inputs)
           env, gated_dirs = whole_gated_attempt(libraries, inputs)
           return env if gated_dirs.empty?
 
           # Issue #1700 — a {RequiredFeatures}-gated directory joined; keep it whole only if it does not cost the
           # environment anything ({.gated_failures}).
-          failed, quarantined = env ? gated_failures(env, gated_dirs, signature_paths, virtual_rbs) : [[], 1]
+          failed, quarantined = env ? gated_failures(env, gated_dirs, inputs) : [[], 1]
           return env if failed.empty? && quarantined.zero?
 
           tokens = gated_dirs.map { |dir| RequiredFeatures.token(RequiredFeatures.feature_for_dir(dir)) }
@@ -114,7 +164,7 @@ module Rigor
           trouble = failed.size + quarantined
           return fallback if env.nil?
 
-          gated_trouble(fallback, gated_dirs, signature_paths, virtual_rbs) < trouble ? fallback : env
+          gated_trouble(fallback, gated_dirs, inputs) < trouble ? fallback : env
         end
 
         # The first attempt, with every activated gated directory whole. rbs 3.x validates a class's generic
@@ -142,7 +192,7 @@ module Rigor
           plan = GatedSignaturePlan.build(roots, fallback)
           if plan.changed
             env = gated_plan_attempt(libraries, inputs, plan)
-            failed, quarantined = env ? gated_failures(env, gated_dirs, inputs[0], inputs[1]) : [failed, 0]
+            failed, quarantined = env ? gated_failures(env, gated_dirs, inputs) : [failed, 0]
             return env if env && failed.empty? && quarantined.zero?
           end
           return nil if failed.empty?
@@ -151,7 +201,7 @@ module Rigor
           env = gated_plan_attempt(libraries, inputs, plan)
           return nil if env.nil?
 
-          failed, quarantined = gated_failures(env, gated_dirs, inputs[0], inputs[1])
+          failed, quarantined = gated_failures(env, gated_dirs, inputs)
           env if failed.empty? && quarantined.zero?
         end
 
@@ -171,7 +221,28 @@ module Rigor
         #
         # @param gated_plan — issue #1713 — a {GatedSignaturePlan} loaded in place of the gated directories: its
         #   kept declarations where the directories would have loaded, its shells after the project's signatures.
-        def build_env_attempt(libraries, signature_paths, virtual_rbs, deferred_signature_paths, gated_plan: nil)
+        #
+        # Issue #2470 — re-made without each {VendoredSignaturePlan} taker the attempt quarantined
+        # ({.quarantined_takers}), so a vendored member stands down only to a file the env keeps. Each round adds
+        # at least one file to the excluded set, and a round that adds none returns, so the loop ends.
+        def build_env_attempt(libraries, *inputs, gated_plan: nil)
+          excluded = Set.new
+          loop do
+            env, gated_dirs, plan = planned_env_attempt(libraries, *inputs, gated_plan: gated_plan,
+                                                                            vendored_excluded: excluded)
+            dropped = quarantined_takers(env, plan)
+            return [env, gated_dirs] if dropped.empty? || dropped.subset?(excluded)
+
+            excluded |= dropped
+          end
+        end
+
+        # One {.build_env_attempt} round, which also returns its {VendoredSignaturePlan}.
+        #
+        # @param vendored_excluded — signature files the vendored plan is made without.
+        def planned_env_attempt(libraries, signature_paths, virtual_rbs, deferred_signature_paths, # rubocop:disable Metrics/ParameterLists
+                                project_signature_paths = [], subordinate_signature_paths = [],
+                                collection_signature_paths = [], gated_plan: nil, vendored_excluded: Set.new)
           libraries = libraries_without_shadowed_bigdecimal_math(libraries)
           rbs_loader, loaded_libraries = library_loader(libraries)
           gated_dirs = loadable_gated_dirs(libraries, loaded_libraries)
@@ -181,15 +252,20 @@ module Rigor
           # type-of query then degrades to `Dynamic[top]` — the "sig looks harmful" failure of the 2026-07-06
           # mastodon coverage note). Per-file loading quarantines the broken file instead. Vendored / core-overlay
           # sigs are Rigor-shipped and trusted, so they stay on the loader's fast batch path.
-          add_bundled_signatures(rbs_loader, loaded_libraries.to_set(&:to_s), gated_plan ? [] : gated_dirs)
-          env = unload_upstream_core_shims(RBS::Environment.from_loader(rbs_loader), rbs_loader)
+          project_files = project_sig_files(signature_paths, collection_signature_paths)
+          undeferred_files = project_files - project_sig_files(deferred_signature_paths)
+          env, vendored_plan = bundled_env(rbs_loader, loaded_libraries, gated_plan ? [] : gated_dirs,
+                                           undeferred_files, vendored_excluded)
           gated_plan&.leading&.each { |source| add_parsed_decls(env, *source) }
-          project_files = project_sig_files(signature_paths)
           # Issue #1075 — decided from the inputs before either side enters `env`: the consistency rule may
           # stand the `.rbs` member down, and that has to happen before its file is added.
-          consistency = member_consistency_for(project_files, virtual_rbs)
+          # Issue #2422 — a bundled plugin's deferred files are not the project's: they never take part in the
+          # inline-vs-`.rbs` consistency rule, and stand down to an inline member like to any other source.
+          consistency = member_consistency_for(undeferred_files, virtual_rbs)
           add_project_signatures(env, signature_paths, deferred_signature_paths,
-                                 standdowns: consistency.signature_standdowns)
+                                 standdowns: consistency.signature_standdowns,
+                                 subordinate_paths: subordinate_signature_paths,
+                                 collection_paths: collection_signature_paths)
           gated_plan&.shells&.each { |source| add_parsed_decls(env, *source) }
           # Issue #928 — the capability-role catalog goes in AFTER the project's own signatures, per
           # declaration, so a project that already declares one of these interface names keeps its own
@@ -201,16 +277,52 @@ module Rigor
           # Issues #824 / #1075 — every member a `.rbs` file also declares was ranked above; the inline side of
           # each pair the `.rbs` won stands down here ({.add_virtual_rbs}), so the two never collide.
           add_virtual_rbs(env, virtual_rbs, inline_standdowns: consistency.inline_standdowns)
+          # Issues #610 / #2422 — the plugins' files last, so each is planned against every other source.
+          add_plugin_signatures(env, deferred_signature_paths, project_signature_paths, virtual_rbs)
           synthesize_missing_namespaces(env)
           # Issue #777 — resolve-time backstop: also unload colliding PROJECT buffers (class-vs-module /
           # constant redeclarations against bundled RBS). Virtual culprits are preferred when both appear.
           env, resolved = resolve_quarantining_virtual_collisions(env, virtual_rbs, project_files: project_files)
-          [stub_missing_referenced_types(env, resolved, project_files), gated_dirs]
+          [stub_missing_referenced_types(env, resolved, project_files), gated_dirs, vendored_plan]
+        end
+
+        # Issue #2470 — the {VendoredSignaturePlan} takers `env` does not hold: a file the build quarantined after a
+        # vendored member stood down to it (a `DuplicatedDeclarationError`, a class-vs-module clash). The answer reads
+        # only the build's inputs, so a cold, a warm and a `--no-cache` run agree.
+        def quarantined_takers(env, plan)
+          return Set.new if plan.takers.empty? || env.nil?
+
+          buffers = loaded_signature_buffers(env)
+          return Set.new if buffers.nil?
+
+          present = buffers.to_set { |buffer| buffer.name.to_s }
+          plan.takers.reject { |file| present.include?(file) }.to_set
+        end
+
+        # The environment of the loader's libraries and the Rigor-shipped signatures. Issue #2470 — a vendored
+        # directory with a member a `signature_files` file also declares loads from its {VendoredSignaturePlan},
+        # right after the batch, instead of whole on it.
+        def bundled_env(rbs_loader, loaded_libraries, gated_dirs, signature_files, excluded)
+          loaded_library_names = loaded_libraries.to_set(&:to_s)
+          plan = vendored_signature_plan(loaded_library_names, signature_files, excluded)
+          add_bundled_signatures(rbs_loader, loaded_library_names, gated_dirs, planned: plan.dirs)
+          env = unload_upstream_core_shims(RBS::Environment.from_loader(rbs_loader), rbs_loader)
+          plan.sources.each { |source| add_parsed_decls(env, *source) }
+          [env, plan]
+        end
+
+        # Issue #2422 — {.add_deferred_signatures} over the plugins' files, with the buffer names of the project's
+        # own signature sources, which a plugin member stands down to rather than composing with: its
+        # `signature_paths:` files and its inline RBS.
+        def add_plugin_signatures(env, deferred_signature_paths, project_signature_paths, virtual_rbs)
+          own = project_sig_files(project_signature_paths) | virtual_rbs.to_set { |name, _| name.to_s }
+          add_deferred_signatures(env, project_sig_files(deferred_signature_paths), own)
         end
 
         # An `RBS::EnvironmentLoader` with every library of `libraries` that resolves added, and those libraries.
         def library_loader(libraries)
-          rbs_loader = RBS::EnvironmentLoader.new
+          core_root = TypingState.current[CORE_ROOT]
+          rbs_loader = core_root ? RBS::EnvironmentLoader.new(core_root: Pathname(core_root)) : RBS::EnvironmentLoader.new
           # Issue #1700 — a `RequiredFeatures` token names a gated vendored directory, never an RBS library.
           loaded_libraries = libraries.select do |library|
             next false if RequiredFeatures.feature_of_token(library)
@@ -233,14 +345,16 @@ module Rigor
         # rather than a comparison of declarations because it answers exactly what RBS itself decides — an
         # overload continuation (`| ...`), a superclass written relative or absolute, a type parameter — with no
         # second reading of the rules to drift. It runs only when a gated directory joined, on an env-cache miss.
-        def gated_trouble(env, dirs, signature_paths, virtual_rbs)
-          failed, quarantined = gated_failures(env, dirs, signature_paths, virtual_rbs)
+        def gated_trouble(env, dirs, inputs)
+          failed, quarantined = gated_failures(env, dirs, inputs)
           failed.size + quarantined
         end
 
         # {.gated_trouble} split in two: the gated type names whose definitions fail, and the number of quarantined
-        # signature sources that declare one. Issue #1713 re-plans against the first.
-        def gated_failures(env, dirs, signature_paths, virtual_rbs)
+        # signature sources that declare one. Issue #1713 re-plans against the first. `inputs` is
+        # {.build_env_for}'s list: the signature paths, the virtual RBS, and (last) the collection directories.
+        def gated_failures(env, dirs, inputs)
+          signature_paths, virtual_rbs = inputs
           type_names = gated_type_names(dirs)
           builder = RBS::DefinitionBuilder.new(env: env)
           failed = type_names.select do |type_name|
@@ -257,7 +371,8 @@ module Rigor
             true
           end
           declares = gated_declaration_pattern(type_names)
-          quarantined = collision_quarantined_project_signatures(env, signature_paths).count do |file, _note|
+          collided = collision_quarantined_project_signatures(env, signature_paths, inputs[5] || [])
+          quarantined = collided.count do |file, _note|
             File.read(file).match?(declares)
           rescue SystemCallError, IOError, ArgumentError
             false
@@ -546,12 +661,22 @@ module Rigor
         # The absolute paths of every `.rbs` file under the project's `signature_paths:` (NOT vendored /
         # stdlib RBS — those are well-formed, so attempting to build them would only waste time). Used to
         # scope the referenced-type build sweep.
-        def project_sig_files(signature_paths)
+        #
+        # @param collection_paths — issue #3030 — the entries of `signature_paths` that are `rbs collection` gem
+        #   directories, read without the files below a `_`-prefixed directory, as rbs reads a collection gem
+        #   ({RbsCollectionDiscovery.hidden_file?}). Compared by spelling, as the loader receives both lists from
+        #   one `Environment.for_project` call.
+        def project_sig_files(signature_paths, collection_paths = [])
+          collection = collection_paths.to_set(&:to_s)
           signature_paths.flat_map do |path|
             path = Pathname(path) unless path.is_a?(Pathname)
             next [] unless path.directory?
 
-            RootedGlob.glob(path, "**/*.rbs").map { |p| File.expand_path(p) }
+            files = RootedGlob.glob(path, "**/*.rbs")
+            if collection.include?(path.to_s)
+              files = files.reject { |file| RbsCollectionDiscovery.hidden_file?(path, file) }
+            end
+            files.map { |p| File.expand_path(p) }
           end.to_set
         end
 
@@ -569,9 +694,16 @@ module Rigor
         # @param standdowns — issue #1075 — `{signature_path => Set[[class, method, kind]]}`, the members an
         #   inline declaration displaced because it was the more precise side of a consistent pair
         #   ({MemberConsistency::Resolution#signature_standdowns}). They are removed before the file is added.
-        def add_project_signatures(env, signature_paths, deferred_paths = [], standdowns: {})
-          deferred = project_sig_files(deferred_paths)
-          (project_sig_files(signature_paths) - deferred).sort.each do |file|
+        # @param subordinate_paths — issue #2978 — the subset loaded after the rest, planned against them as a deferred
+        #   file is ({.add_deferred_signatures}) with every one of them as `own`: a member any of them declares stands
+        #   down from the subordinate file instead of failing the class's definition build. A gem's `rbs collection`
+        #   copy sits behind the gem's own `sig/` this way, so `Bar#a` in both binds the gem's, and `Bar#b` in the
+        #   copy alone still loads.
+        def add_project_signatures(env, signature_paths, deferred_paths = [], standdowns: {}, subordinate_paths: [],
+                                   collection_paths: [])
+          subordinate = project_sig_files(subordinate_paths, collection_paths) - project_sig_files(deferred_paths)
+          eager = project_sig_files(signature_paths, collection_paths) - project_sig_files(deferred_paths) - subordinate
+          eager.sort.each do |file|
             parsed = parse_signature_file(file)
             next if parsed.nil? # quarantined (unparseable) or unreadable — skip so the env survives
 
@@ -579,7 +711,7 @@ module Rigor
             strip_members!(decls, standdowns[file]) if standdowns.key?(file)
             add_project_parsed_decls(env, buffer, directives, decls)
           end
-          add_deferred_signatures(env, deferred, standdowns)
+          add_deferred_signatures(env, subordinate, eager, standdowns: standdowns)
         end
 
         # Issue #777 — add one project signature transactionally. `RBS::Environment#add_source` appends to
@@ -617,16 +749,26 @@ module Rigor
         # (rigor-activerecord's is `relation.rbs`, declaring exactly `Relation`), so dropping the file drops
         # exactly the conflicting declaration. Splitting a plugin file that mixes a colliding class with
         # innocent ones is the change to make if that ever stops being true.
-        def add_deferred_signatures(env, deferred_files, standdowns = {})
+        #
+        # Issue #2422 — at equal arity the plugin reopens the class, and a method both sources declare fails the
+        # definition build (`DuplicatedMethodDefinitionError`) for the class and everything under it; a constant
+        # both declare raises `DuplicatedDeclarationError` and drops the plugin's whole file. So the file is planned
+        # against the env before it is added ({DeferredSignaturePlan}): a colliding method composes with another
+        # source's `def` as an overload continuation, or stands down when the other source is the project's own
+        # (`own`, buffer names) or cannot be continued; a colliding declaration stands down on its own; the rest
+        # of the file loads. {.deferred_member_standdowns} reads what stood down back off the built env.
+        #
+        # @param standdowns — issue #2978 — {.add_project_signatures}' members to remove before a file is planned.
+        def add_deferred_signatures(env, deferred_files, own = Set.new, standdowns: {})
           deferred_files.sort.each do |file|
             parsed = parse_signature_file(file)
             next if parsed.nil?
 
             buffer, directives, decls = parsed
+            strip_members!(decls, standdowns[file]) if standdowns.key?(file)
             next if generic_arity_conflict(env, decls)
 
-            strip_members!(decls, standdowns[file]) if standdowns.key?(file)
-            add_project_parsed_decls(env, buffer, directives, decls)
+            add_project_parsed_decls(env, buffer, directives, DeferredSignaturePlan.plan(decls, env, own))
           end
         end
 
@@ -648,6 +790,24 @@ module Rigor
           end
         end
 
+        # Issue #2422 — the members {.add_deferred_signatures} left out of each deferred file it loaded, as
+        # `[absolute_path, declaration, nil, nil, cause_file, :member]` — `declaration` reading `Object#acts_like?`
+        # or `Time.at`, `cause_file` the buffer of the source that declares it, or nil when that cannot be named.
+        # Derived from the built env for {.deferred_standdowns}' reason; a file that stood down whole is
+        # {.deferred_standdowns}' row, and one the env does not hold has nothing to read back.
+        def deferred_member_standdowns(env, deferred_paths)
+          return [] if env.nil? || deferred_paths.nil? || deferred_paths.empty?
+
+          loaded = loaded_signature_buffers(env)&.to_set { |buffer| buffer.name.to_s } || Set.new
+          project_sig_files(deferred_paths).sort.flat_map do |file|
+            parsed = loaded.include?(file) ? parse_signature_file(file) : nil
+            next [] if parsed.nil? || generic_arity_conflict(env, parsed[2])
+
+            rows = DeferredSignaturePlan.standdown_rows(env, file, parsed[2]).sort_by(&:first)
+            rows.map { |label, cause| [file, label, nil, nil, cause, :member] }
+          end
+        end
+
         # The first `[class_name, existing_arity, incoming_arity, existing_file]` where `decls` would
         # re-declare a class the env already has with a DIFFERENT number of type parameters, or nil when
         # they agree everywhere. Equal arity is not a conflict: RBS reopens the class, which is the ordinary
@@ -690,9 +850,9 @@ module Rigor
           decls.each do |decl|
             case decl
             when ::RBS::AST::Declarations::Module
-              each_declared_class(decl.members, prefix + [decl.name.to_s], &block)
+              each_declared_class(decl.members, declared_class_path(decl, prefix), &block)
             when ::RBS::AST::Declarations::Class
-              inner = prefix + [decl.name.to_s]
+              inner = declared_class_path(decl, prefix)
               block.call("::#{inner.join('::')}", decl.type_params.size)
               each_declared_class(decl.members, inner, &block)
             end
@@ -733,8 +893,8 @@ module Rigor
         # {.add_project_signatures} so the warning fires even on a cache hit (where the env was already built
         # with the file quarantined). Cheap: it only re-parses the user's own (usually small) `sig/` set, and
         # returns empty immediately when there is no `signature_paths:`.
-        def quarantined_project_signatures(signature_paths)
-          project_sig_files(signature_paths).sort.filter_map do |file|
+        def quarantined_project_signatures(signature_paths, collection_paths = [])
+          project_sig_files(signature_paths, collection_paths).sort.filter_map do |file|
             # The note carries the path itself because the warn composer prints only this element — a
             # `ParsingError` message embeds its `path:line:` prefix, so the composer never adds one.
             content = File.read(file, encoding: "UTF-8")
@@ -765,7 +925,7 @@ module Rigor
         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)
+        def collision_quarantined_project_signatures(env, signature_paths, collection_paths = [])
           return [] if env.nil?
 
           present = env.buffers.to_set do |buffer|
@@ -777,7 +937,7 @@ module Rigor
             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|
+          project_sig_files(signature_paths, collection_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)
@@ -1133,11 +1293,12 @@ module Rigor
         end
 
         # `[owners, shadowable]`. `owners` is `{[class_name, method_name, kind] => [signature_path, member,
-        # visibility]}` for every method-shaped member the project's own `signature_paths:` files declare and
-        # the inline sources also name; the first file in sorted order owns a key two `.rbs` files declare
-        # (that pair fails the definition build anyway). `shadowable` is every `::` segment of every class /
-        # module name the inline sources and the signature files declare — the names a relative reference
-        # might resolve to inside an enclosing namespace ({MemberConsistency::Comparator#faithful?}).
+        # visibility]}` for every method-shaped or instance-variable member the project's own
+        # `signature_paths:` files declare and the inline sources also name; the first file in sorted order
+        # owns a key two `.rbs` files declare (that pair fails the definition build anyway). `shadowable` is
+        # every `::` segment of every class / module name the inline sources and the signature files declare
+        # — the names a relative reference might resolve to inside an enclosing namespace
+        # ({MemberConsistency::Comparator#faithful?}).
         #
         # The parse is scoped by a substring pre-filter over each file's text: a declaration has to spell its
         # own name, so a signature file mentioning none of the names the inline sources declare cannot
@@ -1163,14 +1324,14 @@ module Rigor
         def index_signature_members(index, file, decls)
           return if decls.nil?
 
-          each_declared_member(decls) do |class_name, member, visibility|
-            member_method_keys(member).each do |method_name, kind|
+          each_declared_member(decls) do |class_name, member, visibility, nesting|
+            member_keys(member, nesting).each do |method_name, kind|
               index[[class_name, method_name, kind]] ||= [file, member, visibility].freeze
             end
           end
         end
 
-        # The directive heads a refinement {MemberConsistency.refinement_conflicts} checks, used to skip
+        # The directive heads a refinement {MemberConsistency::Comparator#refinement_conflicts} checks, used to skip
         # parsing an inline source that carries none when no `.rbs` overlaps it. Narrower than `rigor:v1:` on
         # purpose: rbs-inline's output marks every skeleton `%a{rigor:v1:inferred-return}`, so that prefix is
         # in nearly every synthesized source.
@@ -1190,49 +1351,65 @@ module Rigor
             decls = parse_signature_source(name, content)
             next if decls.nil?
 
-            each_declared_member(decls) do |class_name, member, visibility|
-              entries << [name.to_s, class_name, member, visibility]
+            each_declared_member(decls) do |class_name, member, visibility, nesting|
+              entries << [name.to_s, class_name, member, visibility, nesting]
             end
           end
         end
 
-        # Removes, in place, every member contributing a key in `keys` (a Set of `[class, method, kind]`).
-        # Nested declarations are descended into after the rejection, and a declaration member contributes no
-        # method key, so nesting is never itself removed.
-        def strip_members!(decls, keys, prefix = [])
+        # Removes, in place, every member contributing a key in `keys` (a Set of `[class, method, kind]`,
+        # instance-variable keys included, #2440). Nested declarations are descended into after the
+        # rejection, and a declaration member contributes no key, so nesting is never itself removed.
+        def strip_members!(decls, keys, prefix = [], written = [])
           Array(decls).each do |decl|
             next unless declaration_with_members?(decl)
 
-            inner = prefix + [decl.name.to_s.delete_prefix("::")]
+            inner = declared_class_path(decl, prefix)
+            nesting = written + [decl.name.to_s]
             class_name = inner.join("::")
             decl.members.reject! do |member|
-              member_method_keys(member).any? { |method_name, kind| keys.include?([class_name, method_name, kind]) }
+              member_keys(member, nesting.join("/")).any? do |method_name, kind|
+                keys.include?([class_name, method_name, kind])
+              end
             end
-            strip_members!(decl.members, keys, inner)
+            strip_members!(decl.members, keys, inner, nesting)
           end
         end
 
-        # Yields `[class_name, member, visibility]` for every member of every class / module declaration in
-        # `decls`, descending through nesting. The enclosing path is accumulated and the name rendered
-        # `::`-stripped, so a `module Foo; class Bar` and a `class Foo::Bar` elsewhere key the same — which is
-        # what makes a `sig/` declaration and an inline one comparable at all. `visibility` is the member's
-        # own (`private def x`) or else the one the enclosing `private` / `public` section sets; a singleton
-        # method takes no section, as in Ruby.
-        def each_declared_member(decls, prefix = [], &block)
+        # The class path a declaration contributes to member keys: its name `::`-stripped, under the enclosing
+        # path unless the name is absolute. A leading `::` resets the path, as RBS resolves `module A; class
+        # ::Abs` to the top-level `Abs` (issue #2474), and so do the children of that declaration. The
+        # `nesting` a mixin is keyed by is not reset: it keeps the names as written, which is the lexical
+        # scope a relative mixin name resolves through.
+        def declared_class_path(decl, prefix)
+          base = decl.name.to_s.start_with?("::") ? [] : prefix
+          base + [decl.name.to_s.delete_prefix("::")]
+        end
+
+        # Yields `[class_name, member, visibility, nesting]` for every member of every class / module
+        # declaration in `decls`, descending through nesting. The enclosing path is accumulated and the name
+        # rendered `::`-stripped, so a `module Foo; class Bar` and a `class Foo::Bar` elsewhere key the same —
+        # which is what makes a `sig/` declaration and an inline one comparable at all. `visibility` is the
+        # member's own (`private def x`) or else the one the enclosing `private` / `public` section sets; a
+        # singleton method takes no section, as in Ruby. `nesting` is the declaration names exactly as
+        # written, outermost first, joined by `/` (`Foo/Bar` against `Foo::Bar`): a mixin's relative name
+        # resolves through it, so {MemberConsistency.member_keys} keys a mixin by it (#2440).
+        def each_declared_member(decls, prefix = [], written = [], &block)
           Array(decls).each do |decl|
             next unless declaration_with_members?(decl)
 
-            inner = prefix + [decl.name.to_s.delete_prefix("::")]
+            inner = declared_class_path(decl, prefix)
+            nesting = written + [decl.name.to_s]
             class_name = inner.join("::")
             section = :public
             decl.members.each do |member|
               case member
               when ::RBS::AST::Members::Private then section = :private
               when ::RBS::AST::Members::Public then section = :public
-              else block.call(class_name, member, member_visibility(member, section))
+              else block.call(class_name, member, member_visibility(member, section), nesting.join("/"))
               end
             end
-            each_declared_member(decl.members, inner, &block)
+            each_declared_member(decl.members, inner, nesting, &block)
           end
         end
 
@@ -1254,6 +1431,12 @@ module Rigor
           MemberConsistency.member_method_keys(member)
         end
 
+        # {MemberConsistency.member_keys} — the method keys plus an instance variable's and a mixin's (#2440),
+        # which is what the inline-vs-`sig/` consistency rule indexes and strips by.
+        def member_keys(member, nesting = nil)
+          MemberConsistency.member_keys(member, nesting)
+        end
+
         # A class / module declaration header, as the pre-filter in {.signature_member_index} reads it out of
         # synthesized RBS text.
         INLINE_DECLARATION_NAME = /^[ \t]*(?:class|module)[ \t]+([A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)/
@@ -1402,7 +1585,8 @@ module Rigor
         # add self-contained declarations) and stay unconditional.
         LIBRARY_SUPPLEMENT_CORE_OVERLAYS = {
           "resolv.rbs" => "resolv",
-          "string_scanner.rbs" => "strscan"
+          "string_scanner.rbs" => "strscan",
+          "bigdecimal.rbs" => "bigdecimal"
         }.freeze
         private_constant :LIBRARY_SUPPLEMENT_CORE_OVERLAYS
 
@@ -1428,8 +1612,12 @@ module Rigor
         #
         # @param loaded_library_names — libraries that actually resolved on this loader.
         # @param gated_dirs — the {RequiredFeatures}-gated directory basenames this library list activates.
-        def add_bundled_signatures(rbs_loader, loaded_library_names, gated_dirs = [])
+        #
+        # @param planned — issue #2470 — the {VendoredSignaturePlan} directories, which load from the plan instead.
+        def add_bundled_signatures(rbs_loader, loaded_library_names, gated_dirs = [], planned: [])
           vendored_gem_sig_paths.each do |path|
+            next if planned.include?(path)
+
             rbs_loader.add(path: path) if vendored_dir_loads?(path, loaded_library_names, gated_dirs)
           end
           core_overlay_sig_paths.each do |dir|
@@ -1445,6 +1633,18 @@ module Rigor
           end
         end
 
+        # Issue #2470 — the ungated vendored directories this build loads, planned against the signature files
+        # that outrank them ({VendoredSignaturePlan}). The gated ones have their own plan (#1713).
+        #
+        # @param signature_files — the `signature_paths:` files a bundled plugin did not contribute: the project's
+        #   own, a collection's and a gem's. A plugin's files are planned against the env instead (#2422).
+        def vendored_signature_plan(loaded_library_names, signature_files, excluded = Set.new)
+          roots = vendored_gem_sig_paths.select do |path|
+            !RequiredFeatures.gated_dir?(path.basename.to_s) && vendored_dir_loads?(path, loaded_library_names, [])
+          end
+          VendoredSignaturePlan.build(roots, signature_files, excluded)
+        end
+
         # Issue #1700 — the {RequiredFeatures}-gated directories `libraries` activates, less one whose feature
         # resolved as an RBS library here (`libraries: [prime]` on a host whose `prime` gem ships its `sig/`),
         # whose own copy is then already loaded. {.build_env_for} then keeps a directory that joined only if the
@@ -1487,17 +1687,19 @@ module Rigor
         end
 
         # Rigor-owned per-gem RBS overlays (`data/gem_overlay/<gem>/`), ADR-72. Unlike the unconditional
-        # `core_overlay`, each gem's overlay is loaded ONLY when that gem is locked in the project's
-        # Gemfile.lock but ships no RBS of its own — {Environment.for_project} decides eligibility and passes
-        # the already-filtered gem-name set here. One directory per gem name keeps the membership check a
-        # cheap `File.directory?`.
+        # `core_overlay`, each gem's overlay is loaded only when that gem is locked in the project's
+        # Gemfile.lock AND {Environment.for_project} finds its coverage source overlay-eligible
+        # ({Environment::GEM_OVERLAY_COVERAGE_SOURCES} — `:missing` for every overlay but addressable's
+        # `:rbs_collection` correction, #2857) with no reachable plugin twin; this method receives the
+        # already-filtered gem-name set. One directory per gem name keeps the membership check a cheap
+        # `File.directory?`.
         GEM_OVERLAY_SIGS_ROOT = File.expand_path(
           "../../../data/gem_overlay",
           __dir__
         ).freeze
 
-        # @param gem_names — overlay-eligible Gemfile.lock gem names (the caller filters
-        #   to the `:missing`-coverage, no-conflicting-plugin set).
+        # @param gem_names — overlay-eligible Gemfile.lock gem names (the caller filters to the
+        #   coverage-source-eligible, no-conflicting-plugin set).
         # @return the bundled overlay directory for each gem that ships one; empty when
         #   none match or the overlay root is absent.
         def gem_overlay_sig_paths(gem_names)
@@ -1511,13 +1713,16 @@ module Rigor
 
         # @param path — typically an entry from an {RbsLoader} instance's
         #   {#signature_paths}.
-        # @return whether `path` sits under the bundled gem-overlay root — what
-        #   `CheckRules::GEM_OVERLAY_OPEN_RECEIVERS`'s gate consults so that a class name's membership in
-        #   that list alone never grants the open-receiver exemption; the overlay directory that made the
-        #   entry true must have actually loaded THIS run too (issue #632, tracked further by #660).
-        #   `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.
+        # @return whether `path` sits under the bundled gem-overlay root — the prefix half of
+        #   "this run loaded a `data/gem_overlay/` directory". Callers needing ONE gem's overlay ask
+        #   {.gem_overlay_sig_paths} for that gem's directory instead: `signature_standdowns` uses this
+        #   to recognise overlay rows across every gem, while `CheckRules#gem_overlay_loaded?` keys on
+        #   the activesupport overlay alone (#3041 — a project can load the addressable overlay without
+        #   the activesupport one, and only the latter may open `ActiveSupport::Duration` /
+        #   `ActiveSupport::Concern`). `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
@@ -1632,7 +1837,8 @@ module Rigor
         end
       end
 
-      attr_reader :libraries, :signature_paths, :cache_store, :virtual_rbs, :deferred_signature_paths
+      attr_reader :libraries, :signature_paths, :cache_store, :virtual_rbs, :deferred_signature_paths,
+                  :project_signature_paths, :core_root, :subordinate_signature_paths, :collection_signature_paths
 
       # @param libraries — stdlib library names to load on top of core (e.g.,
       #   `["pathname", "json"]`). Empty by default. Each entry MUST correspond to a directory under the
@@ -1645,7 +1851,7 @@ module Rigor
       #   `RbsEnvironment`, `RbsKnownClassNames`, `RbsConstantTable`, `RbsClassAncestorTable`, and
       #   `RbsClassTypeParamNames` producers. Pass `nil` (the default) to skip caching; the runner threads
       #   its own Store through here when enabled.
-      # @param virtual_rbs — >] ADR-32 WD4 — `[virtual_filename, rbs_source]` pairs
+      # @param virtual_rbs — ADR-32 WD4 — `[virtual_filename, rbs_source]` pairs
       #   synthesised from project source by a plugin's `Manifest#source_rbs_synthesizer`. Merged into the
       #   env after `signature_paths:` and the vendored stubs. Pass `[]` (the default) when no
       #   synthesizer-emitting plugin is loaded.
@@ -1653,15 +1859,22 @@ module Rigor
       #   contributed (issue #610): loaded last and allowed to stand down against a colliding generic
       #   arity. Read back by the env-cache producer, which rebuilds the env from the loader's readers on
       #   a miss — a list it cannot read is a stand-down that runs only on a `--no-cache` build.
-      def initialize(libraries: [], signature_paths: [], cache_store: nil, virtual_rbs: [],
-                     deferred_signature_paths: [], project_signature_paths: [], required_features: [])
+      # @param core_root — issue #2517 — a directory loaded in place of the `rbs` gem's `core/`, or nil (the
+      #   default) for that core. Validated here, so a bad selection fails at construction ({CoreRoot.validate!}).
+      # @param subordinate_signature_paths — issue #2978 — the subset of `signature_paths:` that stands down member by
+      #   member to the rest of it (a bundle gem's `rbs collection` copy, behind the gem's own `sig/`).
+      # @param collection_signature_paths — issue #3030 — the subset of `signature_paths:` that are `rbs collection`
+      #   gem directories, read without the files below their `_`-prefixed directories ({.project_sig_files}).
+      def initialize(libraries: [], signature_paths: [], cache_store: nil, virtual_rbs: [], # rubocop:disable Metrics/ParameterLists
+                     deferred_signature_paths: [], project_signature_paths: [], required_features: [], core_root: nil,
+                     subordinate_signature_paths: [], collection_signature_paths: [])
+        @core_root = core_root.nil? ? nil : CoreRoot.validate!(core_root)
+        CoreRoot.reject_overlap!(@core_root, project_signature_paths) if @core_root
         @libraries = libraries.map(&:to_s).freeze
         @signature_paths = signature_paths.map { |p| Pathname(p) }.freeze
         assign_reopen_inputs(project_signature_paths, required_features)
-        # 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
+        assign_partition(deferred_signature_paths, subordinate_signature_paths)
+        @collection_signature_paths = collection_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
@@ -1702,9 +1915,9 @@ module Rigor
       # @return empty when every `signature_paths:` file parses.
       def quarantined_signatures
         @state[:quarantined] ||= begin
-          parse_quarantined = self.class.quarantined_project_signatures(@signature_paths)
+          parse_quarantined = self.class.quarantined_project_signatures(@signature_paths, @collection_signature_paths)
           collision_quarantined = self.class.collision_quarantined_project_signatures(
-            @state[:env], @signature_paths
+            @state[:env], @signature_paths, @collection_signature_paths
           )
           parse_paths = parse_quarantined.to_set { |path, _note| path }
           # Issue #610 — a deferred file that STOOD DOWN is absent from the env by design, which is exactly
@@ -1725,8 +1938,17 @@ module Rigor
       # plugin sig collides, which is every project that has not run `rbs collection install` for a gem a
       # bundled plugin also declares. Reported as `rbs.coverage.plugin-signature-stood-down` (`:info`); the
       # same file MUST NOT also appear in {#quarantined_signatures}.
+      #
+      # Issue #2422 — followed by the members a deferred file that did load left out because another source
+      # declares them ({.deferred_member_standdowns}), one row each.
+      #
+      # Issue #2974 — a gem overlay's rows are left out: the overlay is Rigor's own default, deferred so it stands
+      # down to any source that declares the same thing, and that is not news to report (#2470's reasoning).
       def signature_standdowns
-        @state[:signature_standdowns] ||= self.class.deferred_standdowns(env, @deferred_signature_paths).freeze
+        @state[:signature_standdowns] ||= (
+          self.class.deferred_standdowns(env, @deferred_signature_paths) +
+          self.class.deferred_member_standdowns(env, @deferred_signature_paths)
+        ).reject { |row| self.class.under_gem_overlay_root?(row.first) }.freeze
       end
 
       # Issue #1713 — what stood down from each {RequiredFeatures}-gated vendored directory this loader's library
@@ -1745,7 +1967,7 @@ module Rigor
         end
         return [] if roots.empty?
 
-        GatedSignaturePlan.standdowns(env, roots, self.class.project_sig_files(@signature_paths))
+        GatedSignaturePlan.standdowns(env, roots, signature_files)
       end
       private :derive_vendored_standdowns
 
@@ -1781,7 +2003,7 @@ module Rigor
         environment = env
         return Set.new.freeze if environment.nil?
 
-        project_files = self.class.project_sig_files(@signature_paths)
+        project_files = signature_files
         virtual_names = @virtual_rbs.to_set(&:first)
         return Set.new.freeze if project_files.empty? && virtual_names.empty?
 
@@ -1851,6 +2073,22 @@ module Rigor
       # Issue #2174 — the subset of `signature_paths:` the user configured (every entry is also in
       # `@signature_paths`), and the features the project's source requires: read only by
       # {#ruby_library_reopen?}.
+      # 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}). Issue #2978 — and the subset that stands
+      # down member by member to the rest. Every entry of either is also in `@signature_paths`, so the env cache
+      # descriptor already digests these files.
+      # Issue #3030 — every `.rbs` file this loader reads from its `signature_paths:`, the `_`-prefixed directories of
+      # its `rbs collection` gem directories left out ({.project_sig_files}).
+      def signature_files
+        self.class.project_sig_files(@signature_paths, @collection_signature_paths)
+      end
+      private :signature_files
+
+      def assign_partition(deferred_signature_paths, subordinate_signature_paths)
+        @deferred_signature_paths = deferred_signature_paths.map { |p| Pathname(p) }.freeze
+        @subordinate_signature_paths = subordinate_signature_paths.map { |p| Pathname(p) }.freeze
+      end
+
       def assign_reopen_inputs(project_signature_paths, required_features)
         @project_signature_paths = project_signature_paths.map { |p| Pathname(p) }.freeze
         @required_features = required_features.map { |feature| feature.to_s.dup.freeze }.freeze
@@ -1858,6 +2096,62 @@ module Rigor
       private :assign_reopen_inputs
       private :ruby_library_roots
 
+      # Issue #2438 — true when every RBS declaration of `class_name` is the project's own
+      # ({#project_authored_classes}) and none of them declares a member of the class itself: no method, attribute,
+      # alias or mixin, only nested class / module / constant / type declarations (and variable or visibility
+      # lines, which add no method). `rigor sig-gen --write` writes exactly this for a namespace whose source
+      # lists no methods of its own (`module NS; class Foo; …; end; end`), while the namespace's methods live
+      # where the generator cannot see them: a file outside `paths:`, a mixin, a hook. Such a declaration
+      # names the class without describing its surface. Bundled (core, stdlib, gem) declarations never count.
+      def memberless_project_class?(class_name)
+        memberless_project_classes.key?(class_name.to_s.delete_prefix("::"))
+      end
+
+      # The superclass a member-less project declaration of `class_name` writes (`class Poll < ::ApplicationRecord`),
+      # as RBS spells it (rooted), or nil when none of its declarations writes one or the class is not member-less.
+      def memberless_project_superclass(class_name)
+        memberless_project_classes[class_name.to_s.delete_prefix("::")]
+      end
+
+      def memberless_project_classes
+        @state[:memberless_project_classes] ||= build_memberless_project_classes
+      end
+      private :memberless_project_classes
+
+      SURFACE_MEMBERS = [
+        ::RBS::AST::Members::MethodDefinition, ::RBS::AST::Members::Attribute,
+        ::RBS::AST::Members::Alias, ::RBS::AST::Members::Mixin
+      ].freeze
+      private_constant :SURFACE_MEMBERS
+
+      def build_memberless_project_classes
+        authored = project_authored_classes
+        environment = env
+        return {}.freeze if authored.empty? || environment.nil?
+
+        environment.class_decls.each_with_object({}) do |(rbs_name, entry), acc|
+          name = rbs_name.to_s.delete_prefix("::")
+          next unless authored.include?(name)
+
+          decls = self.class.entry_declarations(entry)
+          acc[name] = declared_superclass_name(decls) if decls.none? { |decl| surface_member?(decl) }
+        end.freeze
+      rescue ::RBS::BaseError
+        {}.freeze
+      end
+
+      def surface_member?(decl)
+        members = decl.respond_to?(:members) ? decl.members : []
+        members.any? { |member| SURFACE_MEMBERS.any? { |kind| member.is_a?(kind) } }
+      end
+      private :surface_member?
+
+      def declared_superclass_name(decls)
+        decls.filter_map { |decl| decl.respond_to?(:super_class) && decl.super_class&.name&.to_s }.first&.freeze
+      end
+      private :declared_superclass_name
+      private :build_memberless_project_classes
+
       # The class / module names every one of whose declarations is the project's own
       # ({#project_authored_entry?}, which {#inline_only_entry?} asks behind its inline-only gate).
       def project_authored_classes
@@ -1907,17 +2201,33 @@ module Rigor
       # the interpreter implements, as opposed to a stdlib library written in Ruby (`Logger` rewrites `@level` in
       # its `initialize`). Same attribution, same cache behaviour.
       def core_class?(class_name)
-        (@state[:core_classes] ||= build_core_stdlib_classes(CORE_ROOTS)).include?(class_name.to_s.delete_prefix("::"))
+        (@state[:core_classes] ||= build_core_stdlib_classes(core_roots)).include?(class_name.to_s.delete_prefix("::"))
+      end
+
+      # Issue #2517 — the `core/` prefixes a declaration's buffer name is tested against: the selected
+      # {#core_root} when there is one, which is what the environment loaded core from, else the `rbs` gem's.
+      def core_roots
+        @core_root ? ["#{@core_root}/".freeze].freeze : CORE_ROOTS
       end
+      private :core_roots
+
+      # {CORE_STDLIB_ROOTS} with {#core_roots} in place of the `rbs` gem's `core/`.
+      def core_stdlib_roots
+        return CORE_STDLIB_ROOTS unless @core_root
+        return [].freeze if CORE_STDLIB_ROOTS.empty?
+
+        (core_roots + (CORE_STDLIB_ROOTS - CORE_ROOTS)).freeze
+      end
+      private :core_stdlib_roots
 
       CORE_ROOTS = begin
         [::RBS::EnvironmentLoader::DEFAULT_CORE_ROOT].compact.map { |root| "#{root}/".freeze }.freeze
       rescue StandardError
         [].freeze
-      end
+      end.freeze
       private_constant :CORE_ROOTS
 
-      def build_core_stdlib_classes(roots = CORE_STDLIB_ROOTS)
+      def build_core_stdlib_classes(roots = core_stdlib_roots)
         environment = env
         return Set.new.freeze if environment.nil? || roots.empty?
 
@@ -1941,6 +2251,96 @@ module Rigor
         core_stdlib_classes.include?(class_name.to_s.delete_prefix("::"))
       end
 
+      # Issue #2884 — true when every declaration of `method_definition` (an `RBS::Definition::Method`) is in a named
+      # buffer outside the `rbs` gem's `core/` and `stdlib/` trees: a project, gem or collection signature wrote it.
+      # Attributed by buffer name, as {#core_or_stdlib_class?} is; a declaration whose buffer name is lost (an old
+      # environment blob's `<cached>` sentinel) answers false, which switches the caller's feature off.
+      def declared_outside_core_stdlib?(method_definition)
+        roots = core_stdlib_roots
+        type_defs = method_definition.defs
+        return false if roots.empty? || type_defs.empty?
+
+        type_defs.all? do |type_def|
+          name = self.class.declaration_buffer_name(type_def.member)
+          !name.nil? && roots.none? { |root| name.start_with?(root) }
+        end
+      end
+
+      # Issue #2884 — true when `method_definition`, a class's singleton `new`, is one `X.new` answers through: every
+      # definition is an explicit `def self.new` (not the `new` `RBS::DefinitionBuilder` derives from `initialize`,
+      # which returns the declaring class), written outside core / stdlib ({#declared_outside_core_stdlib?}), on a
+      # class core / stdlib does not declare (a project signature reopening `String` does not change `String.new`).
+      def honoured_singleton_new?(method_definition)
+        method_definition.defs.all? { |type_def| explicit_singleton_new_member?(type_def.member) } &&
+          declared_outside_core_stdlib?(method_definition) &&
+          !core_or_stdlib_class?(method_definition.defined_in.to_s)
+      end
+
+      def explicit_singleton_new_member?(member)
+        member.is_a?(::RBS::AST::Members::MethodDefinition) && member.name == :new && member.kind != :instance
+      end
+      private :explicit_singleton_new_member?
+
+      # Issue #2884 — true when `method_definition`, a singleton `new`, answers what `Nominal[receiver]` answers for
+      # every receiver that inherits it: each overload returns `instance`, untyped, `top`, `bot` or `void`, or the
+      # declaring class itself, compared by its resolved full name. `self` is the receiver's class object, not its
+      # instance, so it does not count. The dispatcher answers `Nominal[receiver]` for an inherited declaration this
+      # holds of, and {#singleton_new_departs_from_instance?} is built from the same test, so the two cannot drift.
+      def answers_instance_for_subclass?(method_definition)
+        owner = method_definition.defined_in.to_s.delete_prefix("::")
+        method_definition.method_types.all? do |method_type|
+          returned = method_type.type.return_type
+          INSTANCE_LIKE_RETURNS.any? { |base| returned.is_a?(base) } ||
+            (returned.is_a?(::RBS::Types::ClassInstance) && returned.name.to_s.delete_prefix("::") == owner)
+        end
+      end
+
+      INSTANCE_LIKE_RETURNS = [
+        ::RBS::Types::Bases::Instance, ::RBS::Types::Bases::Any, ::RBS::Types::Bases::Top,
+        ::RBS::Types::Bases::Bottom, ::RBS::Types::Bases::Void
+      ].freeze
+      private_constant :INSTANCE_LIKE_RETURNS
+
+      # Issue #2884 — true when some class declares a {#honoured_singleton_new?} `new` that is not
+      # {#answers_instance_for_subclass?}: only such a declaration answers a Ruby subclass with something other than
+      # the `Nominal[subclass]` the dispatcher gives without one, so the dispatcher walks a subclass's ancestry, and
+      # files that walk's dependency edges, only when this holds. Memoised per loader: one pass over `class_decls` for
+      # the classes whose own non-core declaration writes `def self.new`, then their definitions.
+      def singleton_new_departs_from_instance?
+        return @state[:singleton_new_departs] if @state.key?(:singleton_new_departs)
+
+        @state[:singleton_new_departs] = scan_singleton_new_departs
+      end
+
+      def scan_singleton_new_departs
+        during_internal_demand do
+          singleton_new_declarers.any? do |class_name|
+            definition = singleton_method(class_name: class_name, method_name: :new)
+            definition && honoured_singleton_new?(definition) && !answers_instance_for_subclass?(definition)
+          end
+        end
+      rescue ::RBS::BaseError
+        true
+      end
+      private :scan_singleton_new_departs
+
+      def singleton_new_declarers
+        environment = env
+        roots = core_stdlib_roots
+        return [] if environment.nil? || roots.empty?
+
+        environment.class_decls.filter_map do |type_name, entry|
+          declares = self.class.entry_declarations(entry).any? do |decl|
+            name = self.class.declaration_buffer_name(decl)
+            next false if name.nil? || roots.any? { |root| name.start_with?(root) }
+
+            decl.members.any? { |member| explicit_singleton_new_member?(member) }
+          end
+          type_name.to_s if declares
+        end
+      end
+      private :singleton_new_declarers
+
       # 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("::"))
@@ -1977,7 +2377,7 @@ module Rigor
           next if type.is_a?(Type::Bot)
 
           path = self.class.declaration_buffer_name(entry.decl)
-          acc[name.to_sym] = [type, !path.nil? && CORE_STDLIB_ROOTS.any? { |root| path.start_with?(root) }].freeze
+          acc[name.to_sym] = [type, !path.nil? && core_stdlib_roots.any? { |root| path.start_with?(root) }].freeze
         end
         table.freeze
       rescue ::RBS::BaseError
@@ -2001,6 +2401,20 @@ module Rigor
         @state[:env_build_failure]
       end
 
+      # Issue #2517 — builds the environment now when a core is selected, so a core it does not build from raises
+      # its {CoreRootError} at the caller rather than at the first query inside analysis. No-op for the default core.
+      def verify_core_root!
+        env if @core_root
+        nil
+      end
+
+      # Issue #2883 — builds the environment now, for the default core as {#verify_core_root!} does for a selected one,
+      # so no `type_of` builds it lazily (ADR-129 G1': the core-root Frame the build reads is never read inside typing).
+      def prepare_for_typing!
+        env
+        nil
+      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
@@ -2086,7 +2500,8 @@ module Rigor
       def member_consistency(proof: nil)
         key = proof ? :member_consistency_proven : :member_consistency
         @state[key] ||= self.class.member_consistency_for(
-          self.class.project_sig_files(@signature_paths), @virtual_rbs, proof: proof
+          signature_files - self.class.project_sig_files(@deferred_signature_paths),
+          @virtual_rbs, proof: proof
         ).records
       end
 
@@ -2214,6 +2629,77 @@ module Rigor
       end
       private :mixin_parent
 
+      # Issue #2681 — every method name declared, on either side, by `name`'s RBS declarations and by the classes and
+      # modules they inherit, include, prepend or extend, `::`-stripped names in `skip` excepted. Read from the
+      # declarations as {#declared_ancestry} reads them, not through the definition builder: a definition that fails to
+      # build reports a coverage diagnostic each time it is asked for. A superset of what the built definitions hold
+      # is harmless to the one reader, a gate in front of ADR-43's override walk. Empty when the environment is
+      # unavailable; the walk stops at 64 owners.
+      def declared_method_names(name, skip: [])
+        return Set.new if env.nil?
+
+        names = Set.new
+        pending = [name.to_s.delete_prefix("::")]
+        seen = Set.new
+        until pending.empty? || seen.size > 64
+          owner = pending.shift
+          next if seen.include?(owner) || skip.include?(owner)
+
+          seen << owner
+          entry = env.class_decls[parse_type_name(owner)]
+          self.class.entry_declarations(entry).each { |decl| read_declared_methods(decl, names, pending) } if entry
+        end
+        names
+      rescue ::RBS::BaseError
+        Set.new
+      end
+
+      def read_declared_methods(decl, names, pending)
+        superclass = decl.respond_to?(:super_class) ? decl.super_class : nil
+        pending << superclass.name.to_s.delete_prefix("::") if superclass
+        return unless decl.respond_to?(:members)
+
+        decl.members.each do |member|
+          case member
+          when ::RBS::AST::Members::MethodDefinition, ::RBS::AST::Members::AttrReader
+            names << member.name
+          when ::RBS::AST::Members::AttrAccessor, ::RBS::AST::Members::AttrWriter
+            names << member.name << :"#{member.name}="
+          when ::RBS::AST::Members::Alias
+            names << member.new_name
+          when ::RBS::AST::Members::Include, ::RBS::AST::Members::Prepend, ::RBS::AST::Members::Extend
+            pending << member.name.to_s.delete_prefix("::") unless member.name.interface?
+          end
+        end
+      end
+      private :read_declared_methods
+
+      # Issue #2321 — every class name an RBS class declaration names as its superclass, `::`-stripped: a class
+      # absent from the set has no RBS-declared subclass. `nil` when the environment is unavailable or fails to read,
+      # so a caller cannot mistake an unread environment for one without subclasses. Memoised per loader.
+      def superclass_names
+        return @state[:superclass_names] if @state.key?(:superclass_names)
+
+        @state[:superclass_names] = build_superclass_names&.freeze
+      end
+
+      def build_superclass_names
+        return nil if env.nil?
+
+        names = Set.new
+
+        env.class_decls.each_value do |entry|
+          self.class.entry_declarations(entry).each do |decl|
+            superclass = decl.respond_to?(:super_class) ? decl.super_class : nil
+            names << superclass.name.to_s.delete_prefix("::") if superclass
+          end
+        end
+        names
+      rescue ::RBS::BaseError
+        nil
+      end
+      private :build_superclass_names
+
       # Yields every known class / module / alias name (top-level prefixed) currently loaded into the
       # environment. The cache producer that materialises the known-name set uses this so it never recurses
       # back through {#class_known?}.
@@ -2230,7 +2716,7 @@ module Rigor
       end
 
       # Yields every type-alias declaration loaded into the environment (`type foo = ...`).
-      # Yields `(RBS::TypeName, RBS::Environment::TypeAliasEntry)` pairs.
+      # Yields `[type_name, decl_entry]` pairs.
       def each_type_alias_decl
         return enum_for(:each_type_alias_decl) unless block_given?
         return unless env
@@ -2288,7 +2774,7 @@ module Rigor
         # fail-soft: see #each_class_decl_annotation.
       end
 
-      # Returns a frozen `Hash<String, String>` mapping each loaded class / module name (top-level prefixed)
+      # Returns a frozen mapping from each loaded class / module name (top-level prefixed)
       # to the file path of its FIRST declaration's RBS source. Used by {Rigor::Analysis::RunStats} to
       # attribute the type universe between "project sig/" (paths under the configured `signature_paths`)
       # and "bundled" (everything else — RBS core, stdlib libraries, gem-bundled RBS). Each value is a frozen
@@ -2408,6 +2894,34 @@ module Rigor
         nil
       end
 
+      # #775 — the memo {Inference::RbsTypeTranslator} keeps, per loader, for the translated form of a closed alias
+      # expansion (keyed by the expansion). It lives here because the translation reads this loader's environment
+      # through any alias nested in the expansion ({#expand_type_alias}): another loader's `b` may differ under an
+      # equal `a`, and the entry goes with the loader. The translator is its only reader and writer.
+      def closed_alias_translations
+        @state[:closed_alias_translations] ||= {}
+      end
+
+      # An independent resolver for a read-only consumer. Its memo belongs to the caller, never the loader cache.
+      def type_name_resolver
+        environment = env
+        return nil if environment.nil?
+
+        klass = ::RBS::Resolver::TypeNameResolver
+        if klass.respond_to?(:build)
+          klass.build(environment)
+        else
+          # Older RBS 3.x takes the environment instead of the current constructor's name tables.
+          klass.new(environment) # rigor:disable call.wrong-arity
+        end
+      end
+
+      # The resolved alias declaration, without substituting type arguments or translating its AST.
+      def type_alias_declaration(name)
+        declarations = env&.type_alias_decls
+        declarations&.[](name)&.decl
+      end
+
       # @return the resolved singleton (class object) definition for `class_name`. The
       #   methods on this definition are the *class methods* of `class_name`, including those inherited from
       #   `Class` and `Module` for class types. Returns nil for unknown names and on RBS build errors
@@ -2509,7 +3023,7 @@ module Rigor
       # singleton methods (e.g., `Array.new`) parameterize over the same `Elem` as instance methods.
       #
       # Returns an empty array for non-generic classes and for unknown names (the loader stays fail-soft).
-      # NOTE: in the `rbs` gem, `RBS::Definition#type_params` returns `Array<Symbol>` directly, not the AST
+      # NOTE: in the `rbs` gem, `RBS::Definition#type_params` returns the names directly, not the AST
       # `TypeParam` object (those live on the AST level).
       #
       # When `cache_store` is set, the loader fetches the entire type-parameter-name table once (per
@@ -2539,6 +3053,31 @@ module Rigor
       NO_TYPE_PARAMS = [].freeze
       private_constant :NO_TYPE_PARAMS
 
+      # Issue #2436 — the `RBS::AST::TypeParam` list a loaded declaration of `class_name` spells (`[unchecked out
+      # E]` for `Array`), read off the declarations rather than through {#class_type_param_names}: a definition
+      # build validates the entry and raises on one whose declarations already disagree, which is the env sig-gen
+      # is asked to repair. The first declaration answers, as it is the one rbs compares every other against
+      # ({.generic_arity_conflict}). Empty for a non-generic or unknown name, and when the environment did not
+      # build.
+      def class_declaration_type_params(class_name)
+        memo = (@state[:declaration_type_params] ||= {})
+        key = class_name.to_s.delete_prefix("::")
+        memo.fetch(key) { memo[key] = read_declaration_type_params(key) }
+      end
+
+      def read_declaration_type_params(key)
+        rbs_name = parse_type_name(key)
+        entry = rbs_name && env&.class_decls&.[](rbs_name)
+        return NO_TYPE_PARAMS if entry.nil?
+
+        first = self.class.entry_declarations(entry).first
+        params = first.respond_to?(:type_params) ? first.type_params : nil
+        params.nil? || params.empty? ? NO_TYPE_PARAMS : params.dup.freeze
+      rescue ::RBS::BaseError
+        NO_TYPE_PARAMS
+      end
+      private :read_declaration_type_params
+
       def class_ordering(lhs, rhs)
         @hierarchy.class_ordering(lhs, rhs)
       end
@@ -2811,7 +3350,7 @@ module Rigor
         producer.send(:compute, self)
       end
 
-      # ADR-15 Phase 2b — `Hash<String, Array<String>>` of normalised ancestor chains per class. Consumes
+      # ADR-15 Phase 2b — the normalised ancestor chain of each class. Consumes
       # the existing `RbsClassAncestorTable` producer when `cache_store` is set; falls back to the
       # producer's `compute` otherwise. Used by {#reflection}.
       def ancestor_names_table
@@ -2846,6 +3385,7 @@ module Rigor
       # 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
+        raise @state[:core_root_error] if @state[:core_root_error]
         return @state[:env] if @state[:env_loaded]
 
         @state[:env_loaded] = true
@@ -2854,11 +3394,24 @@ module Rigor
         warn_about_virtual_rbs_collisions
         @state[:env]
       rescue ::RBS::BaseError => e
+        # Issue #2517 — an environment that does not build from an explicitly selected core is not analysed
+        # against at all: the degraded `Dynamic[top]` env would report the very APIs the selection removes as
+        # fine. Memoised like the nil env, so every later reader raises the same error instead of rebuilding.
+        raise(@state[:core_root_error] = core_root_build_error(e)) if @core_root
+
         record_env_build_failure(e)
         warn_about_env_build_failure_once(e)
         @state[:env] = nil
       end
 
+      def core_root_build_error(error)
+        CoreRootError.new(
+          "core_root: #{@core_root.inspect} did not build an RBS environment " \
+          "(#{error.class.name}: #{error.message.lines.first.to_s.strip})"
+        )
+      end
+      private :core_root_build_error
+
       # Tell the user, once per run, which of their `signature_paths:` `.rbs` files were skipped because they
       # do not parse ({RbsLoader.add_project_signatures} quarantines them so the rest of the env survives). A
       # skipped file's types are absent, so calls into them read `Dynamic[top]` — silently, without this. This
@@ -2966,7 +3519,7 @@ module Rigor
         Cache::RbsEnvironment.fetch(loader: self, store: cache_store)
       end
 
-      # Full `Hash<String, RBS::Definition>` tables for the {#prewarm} / {#reflection} consumers (ADR-15
+      # Full tables of `RBS::Definition` per class for the {#prewarm} / {#reflection} consumers (ADR-15
       # Phase 2b/4b.x), which need every definition materialised up front. Built from the (cached) env via
       # `RBS::DefinitionBuilder` — ADR-54 WD1 retired the disk blobs these used to `Marshal.load` (building
       # all definitions from a cached env is faster), so the eager-table cost is now a compute, not a load.
@@ -3007,7 +3560,11 @@ module Rigor
           libraries: @libraries,
           signature_paths: @signature_paths,
           virtual_rbs: @virtual_rbs,
-          deferred_signature_paths: @deferred_signature_paths
+          deferred_signature_paths: @deferred_signature_paths,
+          project_signature_paths: @project_signature_paths,
+          core_root: @core_root,
+          subordinate_signature_paths: @subordinate_signature_paths,
+          collection_signature_paths: @collection_signature_paths
         )
       end
 
@@ -3034,6 +3591,15 @@ module Rigor
         rbs_name = canonical_module_name(rbs_name)
         return nil unless env.class_decls.key?(rbs_name)
 
+        # rbs's `AncestorBuilder#singleton_ancestors` has no cycle check: a class whose superclass chain loops
+        # (`class S < ::S`, which a collection copy of the same class used to hide, #2441) recurses until the stack
+        # runs out and aborts the run, where `#instance_ancestors` raises `RBS::RecursiveAncestorError`. Walking the
+        # instance side first turns the loop into that error, so it is this class's build failure. Memoised by the
+        # builder, so a class whose instance side was already built pays nothing. Any other stack exhaustion stays
+        # fatal: it depends on how deep the analysis already was, and must not be memoised as a build failure.
+        if env.class_decls[rbs_name].is_a?(::RBS::Environment::ClassEntry)
+          builder.ancestor_builder.instance_ancestors(rbs_name)
+        end
         builder.build_singleton(rbs_name)
       rescue ::RBS::BaseError => e
         store_definition_build_detail(class_name, e)
@@ -3063,7 +3629,8 @@ module Rigor
         key = class_name.to_s.delete_prefix("::")
         details = ((@state[:definition_build_details] ||= {})[key] ||= [])
         details << [key, error.class.name.to_s, definition_build_member(error),
-                    definition_build_conflict_buffers(error), unresolved_type_name_detail(error)].freeze
+                    definition_build_conflict_buffers(error, key), unresolved_type_name_detail(error),
+                    variable_mixin_count(error, key)].freeze
       end
 
       # Issue #997 — the `RBS::NoTypeFoundError` twin of {#definition_build_member}: `nil` for every other
@@ -3214,7 +3781,7 @@ module Rigor
       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
+      # once per class per loader, a `RBS::DefinitionBuilder` failure caught in
       # {#build_instance_definition} / {#build_singleton_definition}'s rescue. Without it, `class_known?`
       # stays true (it only consults {#known_class_names_set}, never a definition build), so every call on
       # the class — real methods and typos alike — silently degrades to `Dynamic[top]`.
@@ -3251,14 +3818,14 @@ module Rigor
 
       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)
+        buffers = definition_build_conflict_buffers(error, class_name)
         collisions =
           if buffers.empty?
             ""
           else
             listed = buffers.first(QUARANTINE_WARN_LIMIT)
             more = buffers.size - listed.size
-            lines = listed.map { |name| "    - #{name}" }
+            lines = listed.map { |name| "    - #{signature_source_label(name)}" }
             lines << "    … and #{more} more" if more.positive?
             "\n  Colliding declaration(s):\n#{lines.join("\n")}"
           end
@@ -3267,6 +3834,14 @@ module Rigor
           "`Dynamic[top]` — real methods and typos alike — instead of resolving normally.#{collisions}"
       end
 
+      # Issue #2440 — a `virtual:<plugin>:<path>` buffer named by the `.rb` file it was synthesized from.
+      def signature_source_label(name)
+        prefix, plugin_id, path = name.to_s.split(":", 3)
+        return name.to_s unless prefix == "virtual" && plugin_id && path && !path.empty?
+
+        "#{path} (inline RBS via #{plugin_id})"
+      end
+
       def warn_about_deferred_definition_build_failures
         return if @state[:definition_build_summary_warned]
 
@@ -3305,10 +3880,11 @@ module Rigor
       # `InvalidOverloadMethodError` carry `#members` (each with a `#location`);
       # `DuplicatedInterfaceMethodDefinitionError` carries a single `#member`; most others
       # (`NoSuperclassFoundError`, `UnknownMethodAliasError`, `RecursiveAncestorError`, …) carry only a bare
-      # `#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)
-        definition_build_error_locations(error)
+      # `#location`. A duplicated instance variable carries one location and a `SuperclassMismatchError` none,
+      # so both read the class entry's declarations for the other side (#2440). Falls back to an empty list —
+      # the warning still names the class and the exception's own message — for the remainder.
+      def definition_build_conflict_buffers(error, class_name = nil)
+        definition_build_error_locations(error, class_name)
           .compact.filter_map { |loc| loc.buffer&.name }.map(&:to_s)
           .reject { |name| name == CACHED_LOCATION_BUFFER_NAME }.uniq.freeze
       rescue ::RBS::BaseError, StandardError
@@ -3317,14 +3893,100 @@ module Rigor
 
       # 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)
+      def definition_build_error_locations(error, class_name = nil)
         return Array(error.members).map(&:location) if error.respond_to?(:members) && error.members
         return [error.member.location] if error.respond_to?(:member) && error.member
+        # `VariableDuplicationError` is younger than the rbs floor the gemspec allows.
+        if defined?(::RBS::VariableDuplicationError) && error.is_a?(::RBS::VariableDuplicationError)
+          return variable_duplication_locations(error, class_name)
+        end
+        return superclass_mismatch_locations(error) if error.is_a?(::RBS::SuperclassMismatchError)
         return [error.location] if error.respond_to?(:location)
 
         []
       end
 
+      # Issue #2440 — a duplicated `@x` / `self.@x` carries the location of ONE of its two declarations, so
+      # the file list named only that side (typically the `virtual:rbs-inline:` buffer, leaving out the
+      # committed `.rbs` the user can actually edit). The class entry's declarations name the rest: every
+      # declaration of the class that declares the same variable, of the same kind. When the variable's
+      # owner is a module the failing class mixes in (rbs counts it once per declaration that does), the
+      # declarations of the failing class that mix that module in are named too: they are the duplicate.
+      def variable_duplication_locations(error, class_name = nil)
+        [error.location, *variable_declarations(error).map(&:location), *mixin_locations(class_name, error.type_name)]
+      end
+
+      # Every declaration of the variable the error names, of the error's kind, in its owner's entry.
+      def variable_declarations(error)
+        member_class =
+          if error.is_a?(::RBS::ClassInstanceVariableDuplicationError)
+            ::RBS::AST::Members::ClassInstanceVariable
+          else
+            ::RBS::AST::Members::InstanceVariable
+          end
+        class_entry_decls(error.type_name).flat_map do |decl|
+          decl_members(decl).select { |m| m.instance_of?(member_class) && m.name == error.variable_name }
+        end
+      end
+
+      # Issue #2440 — how many times `class_name`'s own declarations mix in the module that owns the
+      # duplicated variable, when that is what duplicated it: the owner is another module, it declares the
+      # variable exactly once, and the class mixes it in at least twice (in one declaration or across
+      # several). nil otherwise — a variable duplicated in the owner itself and inherited (`Sub < Base`)
+      # is not a double mixin. Carried in the failure tuple's sixth slot so the advice can tell the two
+      # apart on a replayed tuple too.
+      def variable_mixin_count(error, class_name)
+        return nil unless defined?(::RBS::VariableDuplicationError) && error.is_a?(::RBS::VariableDuplicationError)
+
+        owner = parse_type_name(class_name)
+        return nil if owner.nil? || owner == error.type_name
+        return nil unless variable_declarations(error).size == 1
+
+        count = class_entry_decls(owner).sum do |decl|
+          decl_members(decl).count { |m| mixin_of?(m, error.type_name) }
+        end
+        count >= 2 ? count : nil
+      rescue ::RBS::BaseError, StandardError
+        nil
+      end
+
+      MIXIN_MEMBERS = [::RBS::AST::Members::Include, ::RBS::AST::Members::Extend,
+                       ::RBS::AST::Members::Prepend].freeze
+      private_constant :MIXIN_MEMBERS
+
+      # `resolve_type_names` has made every mixin name absolute.
+      def mixin_of?(member, module_name)
+        MIXIN_MEMBERS.any? { |klass| member.is_a?(klass) } && member.name == module_name
+      end
+
+      def mixin_locations(class_name, module_name)
+        return [] if class_name.nil?
+
+        owner = parse_type_name(class_name)
+        return [] if owner.nil? || owner == module_name
+
+        class_entry_decls(owner).filter_map do |decl|
+          decl.location if decl_members(decl).any? { |m| mixin_of?(m, module_name) }
+        end
+      end
+
+      def decl_members(decl)
+        decl.respond_to?(:members) ? Array(decl.members) : []
+      end
+
+      # Issue #2440 — `SuperclassMismatchError` carries the class entry and no location of its own: the
+      # colliding declarations are the ones that name a superclass. {.entry_declarations} reads the entry on
+      # both rbs majors (`each_decl` on 4.x, `MultiEntry::D` wrappers on 3.x).
+      def superclass_mismatch_locations(error)
+        decls = self.class.entry_declarations(error.entry)
+        decls.select { |decl| decl.respond_to?(:super_class) && decl.super_class }.map(&:location)
+      end
+
+      def class_entry_decls(type_name)
+        entry = env&.class_decls&.[](type_name)
+        entry.nil? ? [] : self.class.entry_declarations(entry)
+      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