rigortype 0.4.6 → 0.4.7

data/lib/rigor/environment/rbs_loader.rb

@@ -10,7 +10,10 @@ 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"
 
 module Rigor
@@ -96,8 +99,33 @@ 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.
+        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]
+          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)
+          previous = Thread.current[:rigor_rbs_core_root]
+          Thread.current[:rigor_rbs_core_root] = core_root
+          yield
+        ensure
+          Thread.current[:rigor_rbs_core_root] = previous
+        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?
 
@@ -171,7 +199,27 @@ 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,
+                                project_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,13 +229,16 @@ 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)
-          gated_plan&.leading&.each { |source| add_parsed_decls(env, *source) }
           project_files = project_sig_files(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) }
           # 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)
           gated_plan&.shells&.each { |source| add_parsed_decls(env, *source) }
@@ -201,16 +252,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 = Thread.current[:rigor_rbs_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)
@@ -579,7 +666,6 @@ 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)
         end
 
         # Issue #777 — add one project signature transactionally. `RBS::Environment#add_source` appends to
@@ -617,7 +703,15 @@ 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.
+        def add_deferred_signatures(env, deferred_files, own = Set.new)
           deferred_files.sort.each do |file|
             parsed = parse_signature_file(file)
             next if parsed.nil?
@@ -625,8 +719,7 @@ module Rigor
             buffer, directives, decls = parsed
             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 +741,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 +801,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
@@ -1133,11 +1244,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 +1275,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 +1302,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 +1382,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_]*)*)/
@@ -1428,8 +1562,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 +1583,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
@@ -1632,7 +1782,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
 
       # @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 +1796,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,8 +1804,12 @@ 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!}).
+      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)
+        @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)
@@ -1725,8 +1880,14 @@ 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.
       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)
+        ).freeze
       end
 
       # Issue #1713 — what stood down from each {RequiredFeatures}-gated vendored directory this loader's library
@@ -1858,6 +2019,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,8 +2124,24 @@ 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
@@ -1917,7 +2150,7 @@ module Rigor
       end
       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?
 
@@ -1977,7 +2210,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 +2234,13 @@ 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 #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 +2326,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
+          self.class.project_sig_files(@signature_paths) - self.class.project_sig_files(@deferred_signature_paths),
+          @virtual_rbs, proof: proof
         ).records
       end
 
@@ -2214,6 +2455,32 @@ module Rigor
       end
       private :mixin_parent
 
+      # 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 +2497,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 +2555,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
@@ -2509,7 +2776,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 +2806,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 +3103,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 +3138,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 +3147,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 +3272,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 +3313,9 @@ 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
         )
       end
 
@@ -3034,6 +3342,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 +3380,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 +3532,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 +3569,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 +3585,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 +3631,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 +3644,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