rigortype 0.4.7 → 0.4.8

data/lib/rigor/environment/rbs_loader.rb

@@ -15,6 +15,7 @@ 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
@@ -35,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,
@@ -63,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
@@ -105,9 +126,15 @@ module Rigor
         #   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.
-        def build_env_for(libraries:, signature_paths:, virtual_rbs: [], deferred_signature_paths: [],
-                          project_signature_paths: [], core_root: nil)
-          inputs = [signature_paths, virtual_rbs, deferred_signature_paths, project_signature_paths]
+        # @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
 
@@ -116,22 +143,17 @@ module Rigor
         # {.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)
-          previous = Thread.current[:rigor_rbs_core_root]
-          Thread.current[:rigor_rbs_core_root] = core_root
-          yield
-        ensure
-          Thread.current[:rigor_rbs_core_root] = previous
+        def with_core_root(core_root, &)
+          TypingState.current.with(CORE_ROOT, core_root, &)
         end
 
         def build_env_from(libraries, inputs)
-          signature_paths, virtual_rbs = 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)) }
@@ -142,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
@@ -170,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?
@@ -179,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
 
@@ -218,8 +240,9 @@ module Rigor
         # 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,
-                                project_signature_paths = [], gated_plan: nil, vendored_excluded: Set.new)
+        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)
@@ -229,7 +252,7 @@ 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.
-          project_files = project_sig_files(signature_paths)
+          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)
@@ -240,7 +263,9 @@ module Rigor
           # 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
@@ -296,7 +321,7 @@ module Rigor
 
         # An `RBS::EnvironmentLoader` with every library of `libraries` that resolves added, and those libraries.
         def library_loader(libraries)
-          core_root = Thread.current[:rigor_rbs_core_root]
+          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|
@@ -320,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|
@@ -344,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
@@ -633,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
 
@@ -656,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
 
@@ -666,6 +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, subordinate, eager, standdowns: standdowns)
         end
 
         # Issue #777 — add one project signature transactionally. `RBS::Environment#add_source` appends to
@@ -711,12 +757,15 @@ module Rigor
         # 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.
-        def add_deferred_signatures(env, deferred_files, own = Set.new)
+        #
+        # @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)
 
             add_project_parsed_decls(env, buffer, directives, DeferredSignaturePlan.plan(decls, env, own))
@@ -844,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")
@@ -876,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|
@@ -888,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)
@@ -1536,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
 
@@ -1637,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)
@@ -1661,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
@@ -1783,7 +1838,7 @@ module Rigor
       end
 
       attr_reader :libraries, :signature_paths, :cache_store, :virtual_rbs, :deferred_signature_paths,
-                  :project_signature_paths, :core_root
+                  :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
@@ -1806,17 +1861,20 @@ module Rigor
       #   a miss — a list it cannot read is a stand-down that runs only on a `--no-cache` build.
       # @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)
+                     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
@@ -1857,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
@@ -1883,11 +1941,14 @@ module Rigor
       #
       # 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) +
           self.class.deferred_member_standdowns(env, @deferred_signature_paths)
-        ).freeze
+        ).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
@@ -1906,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
 
@@ -1942,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?
 
@@ -2012,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
@@ -2147,7 +2224,7 @@ module Rigor
         [::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)
@@ -2174,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("::"))
@@ -2241,6 +2408,13 @@ module Rigor
         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
@@ -2326,7 +2500,7 @@ 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) - self.class.project_sig_files(@deferred_signature_paths),
+          signature_files - self.class.project_sig_files(@deferred_signature_paths),
           @virtual_rbs, proof: proof
         ).records
       end
@@ -2455,6 +2629,51 @@ 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.
@@ -2675,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
@@ -3315,7 +3562,9 @@ module Rigor
           virtual_rbs: @virtual_rbs,
           deferred_signature_paths: @deferred_signature_paths,
           project_signature_paths: @project_signature_paths,
-          core_root: @core_root
+          core_root: @core_root,
+          subordinate_signature_paths: @subordinate_signature_paths,
+          collection_signature_paths: @collection_signature_paths
         )
       end