rigortype 0.4.6 → 0.4.8

data/lib/rigor/environment/reflection.rb

@@ -2,21 +2,21 @@
 
 module Rigor
   class Environment
-    # Frozen, `Ractor.shareable?` read-only RBS query facade.
+    # Frozen read-only RBS query facade.
     # [ADR-15](../../../docs/adr/15-ractor-concurrency.md) Phase 2b extracts the read-only surface of
     # {RbsLoader} into this carrier so future Ractor-isolated workers can share one Reflection across the
     # pool while keeping the per-Ractor mutable accelerator state (per-process memo Hashes) where it belongs.
     #
     # Backing tables (all frozen at construction):
     #
-    # - `known_class_names` — `Set<String>` of every class / module / alias name in the loaded RBS
-    #   environment. Top-level prefixed (`"::Hash"`); plain queries normalise via {#normalise}.
-    # - `instance_definitions` — `Hash<String, RBS::Definition>` keyed on `RBS::TypeName#to_s` (top-level
+    # - `known_class_names` — every class / module / alias name in the loaded RBS environment.
+    #   Top-level prefixed (`"::Hash"`); the query methods accept either form.
+    # - `instance_definitions` — `RBS::Definition` per class, keyed on `RBS::TypeName#to_s` (top-level
     #   prefixed).
     # - `singleton_definitions` — same shape, singleton side.
-    # - `type_param_names` — `Hash<String, Array<Symbol>>` of declared type parameters per class.
-    # - `constant_types` — `Hash<String, Rigor::Type>` of translated constant declarations.
-    # - `ancestor_names` — `Hash<String, Array<String>>` of normalised ancestor chains per class.
+    # - `type_param_names` — declared type parameters per class.
+    # - `constant_types` — translated constant declarations.
+    # - `ancestor_names` — normalised ancestor chains per class.
     #
     # Each `Reflection` instance is `frozen?` at construction — every cached table is frozen, `self` is
     # frozen. **NOT** `Ractor.shareable?`: the `instance_definitions` / `singleton_definitions` tables hold

data/lib/rigor/environment/required_features.rb

@@ -296,17 +296,14 @@ module Rigor
         name.start_with?(TOKEN_PREFIX) ? name.delete_prefix(TOKEN_PREFIX) : nil
       end
 
-      # The vendored directory basenames a library list activates.
       def active_dirs(library_names)
         library_names.filter_map { |name| VENDORED_DIRS[feature_of_token(name)] }
       end
 
-      # Whether `dir_basename` is one of the gated directories.
       def gated_dir?(dir_basename)
         VENDORED_DIRS.value?(dir_basename)
       end
 
-      # The feature a gated directory loads for.
       def feature_for_dir(dir_basename)
         VENDORED_DIRS.key(dir_basename)
       end

data/lib/rigor/environment/ruby_library_roots.rb

@@ -28,7 +28,7 @@ module Rigor
     #
     # The directories are resolved at load time, on the main Ractor: `RbConfig::CONFIG` and `Gem.default_dir`
     # read non-shareable constants and raise `Ractor::IsolationError` inside a pool worker. The scan itself runs
-    # lazily (about 0.1 s), memoised per loader, and only for a class about to be reported.
+    # lazily (about 0.1 s), memoised per process, and only for a class about to be reported.
     module RubyLibraryRoots
       STDLIB_ROOT = begin
         ::RBS::Repository::DEFAULT_STDLIB_ROOT.to_s.dup.freeze

data/lib/rigor/environment/vendored_signature_plan.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "rbs"
+require_relative "../rooted_glob"
+require_relative "gated_signature_plan"
+
+module Rigor
+  class Environment
+    # Issue #2470 — a `data/vendored_gem_sigs/<gem>/` member another signature source also declares stands down,
+    # so the other source's declaration binds instead of the two failing the class's definition build.
+    #
+    # The vendored directories load on `RBS::EnvironmentLoader`'s batch path, ahead of the project's
+    # `signature_paths:` (its own `sig/`, an `rbs collection install`, a gem's `sig/`). A file there that reopens
+    # a vendored class and declares one of its methods again — the activerecord 8.1 collection's `patch.rbs`
+    # writes `def async_exec` on `PG::Connection`, where the vendored `pg.rbs` has `alias async_exec exec` — made
+    # `RBS::DefinitionBuilder` raise `DuplicatedMethodDefinitionError` for the class, which Rigor keeps known, so
+    # every call into it read `Dynamic[top]`.
+    #
+    # {.build} is the #1713 member rule ({GatedSignaturePlan}) applied to the ungated directories, planned from
+    # the signature files themselves rather than from a trial build: the vendored copy is Rigor's guess at a gem's
+    # surface, and the project chose the other source, so the other source wins (`RbsLoader.build_env_for`'s
+    # stated precedence). Only a directory with a member to leave out is planned; the rest stay on the batch path.
+    # An overload continuation (`def m: ... | ...`) declares nothing of its own and keeps the vendored base.
+    #
+    # The plan is a pure function of the vendored files and the signature files, both of which the env-cache key
+    # digests, so a cold and a warm run build the same environment.
+    module VendoredSignaturePlan
+      # `dirs` — the vendored directories (Pathnames) to keep off the batch path; `sources` — their files as
+      # `[buffer, directives, decls]`, the taken members left out, to add right after the batch; `takers` — the
+      # signature files a member stood down to. A member stands down only to a file that stays in the env: the
+      # caller re-plans without each taker the build quarantined (`RbsLoader.build_env_attempt`), or the method
+      # would have no declaration at all.
+      Plan = Data.define(:dirs, :sources, :takers)
+      EMPTY = Plan.new(dirs: [].freeze, sources: [].freeze, takers: Set.new.freeze)
+
+      # A `class` / `module` header, after any `%a{...}` / `%a(...)` / `%a[...]` annotations on the same line.
+      ANNOTATED_HEADER = /^\s*(?:%a(?:\{[^}]*\}|\([^)]*\)|\[[^\]]*\])\s*)*(?:class|module)\s+(?:::)?/
+
+      module_function
+
+      # @param roots — the ungated vendored directories this build loads.
+      # @param signature_files — the absolute paths of the signature files that outrank them.
+      # @param excluded — signature files to plan without: takers a previous build of this env quarantined.
+      def build(roots, signature_files, excluded = Set.new)
+        files = signature_files.reject { |file| excluded.include?(file) }
+        return EMPTY if roots.empty? || files.empty?
+
+        parsed = roots.to_h { |root| [root, parsed_sources(root)] }
+        taken = taken_keys(files, header_pattern(parsed.values.flatten(1)))
+        return EMPTY if taken.empty?
+
+        takers = Set.new
+        planned = parsed.filter_map do |root, sources|
+          kept = plan_sources(sources, taken, takers)
+          [root, kept] if kept
+        end
+        return EMPTY if planned.empty?
+
+        Plan.new(dirs: planned.map(&:first), sources: planned.flat_map(&:last), takers: takers.freeze)
+      end
+
+      # A vendored directory's files, parsed, under the Pathname buffer names the loader's batch path gives them,
+      # in the set `RBS::EnvironmentLoader#add(path:)` reads: every `.rbs` under it.
+      def parsed_sources(root)
+        RootedGlob.glob(root, "**/*.rbs").sort.filter_map { |file| RbsLoader.parse_signature_file(Pathname(file)) }
+      end
+
+      # `sources` with the taken members left out, or nil when nothing is taken from any of them.
+      def plan_sources(sources, taken, takers)
+        kept = sources.map do |buffer, directives, decls|
+          [buffer, directives, plan_decls(decls, nil, taken, takers)]
+        end
+        kept unless kept.zip(sources).all? { |(_, _, after), (_, _, before)| unchanged?(after, before) }
+      end
+
+      # A header naming one of the vendored top-level types, which every declaration of a vendored type (nested or
+      # `A::B`-qualified) starts from. A pre-filter only: the matches are parsed.
+      def header_pattern(parsed)
+        heads = parsed.flat_map do |_buffer, _directives, decls|
+          decls.filter_map { |decl| GatedSignaturePlan.type_declaration?(decl) && decl.name.to_s.delete_prefix("::") }
+        end
+        segments = heads.map { |name| Regexp.escape(name.split("::").first) }.uniq
+        return nil if segments.empty?
+
+        /#{ANNOTATED_HEADER}(?:#{segments.join('|')})\b/
+      end
+
+      # `{type name => {[method, kind] => Set[file]}}` over the signature files that declare a vendored top-level
+      # type.
+      def taken_keys(signature_files, pattern)
+        taken = Hash.new { |hash, name| hash[name] = Hash.new { |keys, key| keys[key] = Set.new } }
+        return taken if pattern.nil?
+
+        signature_files.sort.each do |file|
+          text = RbsLoader.read_signature_text(file)
+          next if text.nil? || !text.match?(pattern)
+
+          decls = RbsLoader.parse_signature_source(file, text)
+          collect_keys(decls, nil, taken, file) if decls
+        end
+        taken
+      end
+
+      def collect_keys(decls, namespace, taken, file)
+        decls.each do |decl|
+          next unless GatedSignaturePlan.type_declaration?(decl)
+
+          name = GatedSignaturePlan.qualify(namespace, decl.name)
+          decl.members.each do |member|
+            RbsLoader.member_method_keys(member).each { |key| taken[name][key] << file }
+          end
+          collect_keys(decl.members, name, taken, file)
+        end
+      end
+
+      # `decls` with every member `taken` declares for its type left out, nested types planned the same way, and
+      # the files each left-out member stood down to added to `takers`. A declaration nothing is taken from is
+      # returned as itself, which is how {.build} tells a directory unchanged.
+      def plan_decls(decls, namespace, taken, takers)
+        decls.map do |decl|
+          next decl unless GatedSignaturePlan.type_declaration?(decl)
+
+          plan_type(decl, GatedSignaturePlan.qualify(namespace, decl.name), taken, takers)
+        end
+      end
+
+      def unchanged?(after, before)
+        after.size == before.size && after.zip(before).all? { |a, b| a.equal?(b) }
+      end
+
+      def plan_type(decl, name, taken, takers)
+        keys = taken.fetch(name, nil)
+        members = decl.members.filter_map do |member|
+          if GatedSignaturePlan.type_declaration?(member)
+            plan_type(member, GatedSignaturePlan.qualify(name, member.name), taken, takers)
+          elsif keys
+            plan_member(member, keys, takers)
+          else
+            member
+          end
+        end
+        return decl if unchanged?(members, decl.members)
+
+        GatedSignaturePlan.rebuild(decl, members: members)
+      end
+
+      def plan_member(member, keys, takers)
+        RbsLoader.member_method_keys(member).each { |key| takers.merge(keys[key]) if keys.key?(key) }
+        GatedSignaturePlan.untaken(member, keys)
+      end
+    end
+  end
+end

data/lib/rigor/environment.rb

@@ -16,6 +16,8 @@ require_relative "environment/bundle_sig_discovery"
 require_relative "environment/lockfile_resolver"
 require_relative "environment/installed_gem_set"
 require_relative "environment/rbs_collection_discovery"
+require_relative "library_probe"
+require_relative "environment/project_path_gems"
 require_relative "environment/source_rbs_synthesis"
 require_relative "plugin/isolation"
 require_relative "cache/engine_source"
@@ -39,7 +41,7 @@ module Rigor
     DEFAULT_PROJECT_SIG_DIR = "sig"
     private_constant :DEFAULT_PROJECT_SIG_DIR
 
-    # `DEFAULT_LIBRARIES` is defined in the light `environment/default_libraries.rb` (required below) so the
+    # `DEFAULT_LIBRARIES` is defined in the light `environment/default_libraries.rb` (required above) so the
     # ADR-87 WD4 boot-slimming probe can read it without loading the inference engine.
 
     # ADR-72 — a Gemfile.lock gem name mapped to the opt-in plugin id that ships the SAME core-ext RBS. When
@@ -48,6 +50,19 @@ module Rigor
     # `RbsCoverageReport` reports.
     GEM_OVERLAY_PLUGIN_IDS = { "activesupport" => "activesupport-core-ext" }.freeze
 
+    # Issue #2857 — the `RbsCoverageReport` sources each gem's bundled overlay may load under, when they
+    # differ from the ADR-72 `:missing` default every unlisted overlay keeps. `addressable` is the first
+    # exception: its overlay exists to CORRECT the `Addressable::URI.parse` signature `rbs collection`
+    # ships (`parse(nil)` returns nil; the collection declares `(String | URI) -> URI`), so it loads only
+    # under `:rbs_collection` coverage, where the deferred-signature plan composes it over the collection
+    # copy as an overload continuation. Under `:missing` coverage — no sigs at all — it stays unloaded:
+    # the overlay's partial `Addressable::URI` declaration would make every member it omits a false
+    # `call.undefined-method`, a worse answer than the `Dynamic` silence a sig-less gem already has.
+    # Frozen arrays, not Sets: `Ractor.shareable?` rejects a Set even frozen (ractor_readiness_spec).
+    GEM_OVERLAY_COVERAGE_SOURCES = { "addressable" => [:rbs_collection].freeze }.freeze
+    GEM_OVERLAY_DEFAULT_COVERAGE_SOURCES = [:missing].freeze
+    private_constant :GEM_OVERLAY_DEFAULT_COVERAGE_SOURCES
+
     attr_reader :class_registry, :rbs_loader, :plugin_registry, :dependency_source_index,
                 :reporters, :name_scope,
                 :synthetic_method_index, :project_patched_methods
@@ -117,6 +132,13 @@ module Rigor
     # stage that failed and the other stage still runs, so this getter never raises into its callers —
     # neither into a file's `analyze_body` rescue nor out of the run-owned demands, which have no rescue
     # above them at all.
+    # Issue #2883 — builds the RBS environment now, if it is not built yet, so typing never builds it. A no-op for an
+    # environment with no loader. Answers the environment.
+    def prepare_for_typing!
+      rbs_loader&.prepare_for_typing!
+      self
+    end
+
     def hkt_registry
       @hkt_registry_holder.fetch do
         pre_scan = pre_scan_hkt_registry
@@ -146,7 +168,7 @@ module Rigor
     # code (`Plugin::Registry#hkt_overlay_registry` reads each manifest); before this it sat one line ABOVE
     # the #784 rescue, so a raise there escaped {#hkt_registry} entirely. Post-#788 that is not a per-file
     # crash storm but an uncaught abort: {HktRegistryHolder#fetch} memoises only on success, so the raise
-    # is re-attempted at every demand, and the run-owned demands (`Runner::PoolCoordinator#hkt_scan_outcome`
+    # is re-attempted at every demand, and the run-owned demands (`Runner::RunLevelFacts::Collect.hkt_scan_failure`
     # after the file loop, `Analysis::WorkerSession#drain_reporters`) sit outside any rescue.
     #
     # The degradation is narrower than the scan's: only the plugin overlay is dropped, and the RBS scan
@@ -246,11 +268,14 @@ module Rigor
     end
 
     class << self
+      # Issue #2883 — the shared default environment is built here too, not on the first `type_of` that needs it, so
+      # code that types against it (`Scope.empty`, the narrowing defaults, the incremental session's summary
+      # evaluator) never builds it from inside typing. A non-main Ractor keeps the lazy build.
       def default
         @default ||= new(
           rbs_loader: RbsLoader.default,
           hkt_registry: Builtins::HktBuiltins.registry
-        ).freeze
+        ).freeze.tap { |environment| environment.prepare_for_typing! if Ractor.main? }
       end
 
       # Builds an Environment that consults the project's local signatures and any opt-in stdlib libraries on
@@ -265,8 +290,14 @@ module Rigor
       #   `nil` (the default), the canonical project layout `<root>/sig` is used if it exists, otherwise no
       #   signature path is loaded.
       # @param cache_store — persistent cache threaded into the underlying
-      #   {Environment::RbsLoader} so constant lookups (and, in later v0.0.9 slices, other reflection
-      #   artefacts) consult the cache. Pass `nil` (the default) to skip caching for this environment.
+      #   {Environment::RbsLoader} so constant lookups consult the cache. Pass `nil` (the default) to skip
+      #   caching for this environment.
+      # @param core_root — issue #2517 — a core signature directory loaded in place of the `rbs` gem's `core/`
+      #   ({Configuration#core_root}); nil (the default) loads the gem's core.
+      # @param eager — issue #2883 — whether the RBS environment is built here, before anything types. Typing then
+      #   never builds it, so the core-root Frame the build reads (ADR-129 G1') is never read inside a `type_of`. The
+      #   one caller that passes `false` is the runner's pre-cache build, which a warm result-cache hit must not pay
+      #   for; it calls {#prepare_for_typing!} on the analysis path.
       # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
       def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil, # rubocop:disable Metrics/AbcSize
                       plugin_registry: nil, dependency_source_index: nil,
@@ -276,7 +307,8 @@ module Rigor
                       bundler_lockfile: nil,
                       rbs_collection_lockfile: nil, rbs_collection_auto_detect: false,
                       synthetic_method_index: nil, project_patched_methods: nil,
-                      source_files: [], locked_gems: nil, required_features: nil)
+                      source_files: [], locked_gems: nil, required_features: nil, core_root: nil,
+                      paths: nil, exclude_patterns: nil, exclude_base: nil, eager: true)
         resolved_paths = project_signature_roots(signature_paths, root: root)
         # O4 MVP — append per-gem `sig/` directories discovered under the target project's bundler install
         # root. Empty array when neither an explicit path nor auto-detection finds a bundle. Order: user
@@ -309,38 +341,55 @@ module Rigor
         )
         # O4 Layer 3 slice 2 — when `rbs collection install` has been run for the target project, parse the
         # resulting `rbs_collection.lock.yaml` and feed each gem's `<collection_path>/<name>/<version>/`
-        # directory into `signature_paths:`. Stdlib-typed entries are skipped (already covered by
-        # `DEFAULT_LIBRARIES`), as are gems whose RBS rigor already loads from another source —
+        # directory into `signature_paths:`. Stdlib-typed entries have no such directory; they load as libraries
+        # (issue #2946, below). Skipped too are gems whose RBS rigor already loads from another source —
         # stdlib-extracted default gems (`cgi`, `logger`, …, shipped by the collection under a `git` source)
         # and the `data/vendored_gem_sigs/` bundle (`redis`, `nokogiri`, `pg`, …). `skip_gem_names:` passes
         # both sets so the collection copy doesn't double-declare against rigor's bundled RBS (the
         # `RBS::DuplicatedDeclarationError` hazard).
         # Issue #1700 — plus the gated vendored directories this run's source activates ({#feature_tokens}).
-        merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s) +
+        # Issue #2946 — plus the lockfile's `source: { type: stdlib }` entries, as libraries ({BaseLibraries.resolve}).
+        merged_libraries = (BaseLibraries.resolve(libraries, rbs_collection_lockfile: rbs_collection_lockfile,
+                                                             rbs_collection_auto_detect: rbs_collection_auto_detect,
+                                                             root: root) +
                             feature_tokens(required_features, source_files, libraries)).uniq
-        skip_gem_names = collection_skip_gem_names(merged_libraries)
+        # Issue #2441 — plus the project's own path gems ({ProjectPathGems}), whose collection copy would
+        # double-declare the project's `sig/`.
+        project_gems = ProjectPathGems.names(locked, paths: paths, root: root, exclude_patterns: exclude_patterns,
+                                                     exclude_base: exclude_base || root)
+        skip_gem_names = collection_skip_gem_names(merged_libraries) + project_gems.to_a
         collection_paths = RbsCollectionDiscovery.discover(
           lockfile_path: rbs_collection_lockfile,
           project_root: root,
           auto_detect: rbs_collection_auto_detect,
           skip_gem_names: skip_gem_names
         ).map(&:to_s)
+        # Issue #3030 — a gem the project's `signature_paths:` already loads a copy of (a gem_rbs_collection working
+        # tree next to its `_test/` lockfile) loads from there alone. The coverage classification below still sees
+        # the whole list: the gem has RBS either way.
+        covered_collection_paths = collection_paths
+        collection_paths = RbsCollectionDiscovery.without_signature_path_copies(collection_paths, resolved_paths)
+        # Issue #2978 — the collection copies of the locked gems whose own `sig/` the bundle discovery loaded.
+        behind_gem_sig_paths = collection_paths_behind_gem_sigs(collection_paths, gem_sig_paths, locked)
         # ADR-25 — RBS signature directories contributed by loaded plugins via their manifest
         # `signature_paths:`. Resolved to absolute dirs by `Plugin::Base#signature_paths`; additive, ranked
         # below the user's explicit `signature_paths:` and above the opportunistic bundle / collection
         # discovery. A duplicate-declaration conflict degrades through the same O7 failure-memo path.
         plugin_sig_paths = plugin_registry ? plugin_registry.signature_paths.map(&:to_s) : []
-        # ADR-72 — Gemfile.lock-gated bundled RBS overlays. For each locked gem that ships no RBS through any
-        # resolution path (`:missing`) and has a Rigor-bundled overlay, load that overlay so its core-class
-        # extensions resolve (e.g. `Integer#minutes` on a Rails project) — turning a systematic false
-        # `call.undefined-method` into a no-op while a project WITHOUT the gem still sees the genuine
-        # diagnostic. Appended last so any RBS the project already supplies wins, and skipped for a gem whose
-        # opt-in plugin twin is REACHABLE — loaded as a plugin, or wired in by `signature_paths:` (#672) —
-        # so the two never both declare the methods. The paths ride in `loader_signature_paths`, so the env
-        # cache descriptor digests them for free.
+        # ADR-72 — Gemfile.lock-gated bundled RBS overlays. For each locked gem whose coverage source its
+        # overlay may load under ({GEM_OVERLAY_COVERAGE_SOURCES} — `:missing` for every overlay but
+        # addressable's `:rbs_collection` correction, #2857) and that has a Rigor-bundled overlay, load that
+        # overlay so its core-class extensions resolve (e.g. `Integer#minutes` on a Rails project) —
+        # turning a systematic false `call.undefined-method` into a no-op while a project WITHOUT the gem
+        # still sees the genuine diagnostic. Appended last so any RBS the project already supplies wins,
+        # and skipped for a gem whose opt-in plugin twin is REACHABLE — loaded as a plugin, or wired in by
+        # `signature_paths:` (#672) — so the two never both declare the methods. The paths ride in
+        # `loader_signature_paths`, so the env cache descriptor digests them for free.
+        # Issue #2441 — the project's own path gems are neither missing RBS nor overlay-eligible: the project's
+        # `sig/` declares them, and an overlay (`data/gem_overlay/activesupport`) would collide with it.
         missing_gems, overlay_paths = missing_gems_and_overlay_paths(
-          locked: locked, default_libraries: merged_libraries, bundle_sig_paths: gem_sig_paths,
-          rbs_collection_paths: collection_paths, plugin_registry: plugin_registry,
+          locked: locked.except(*project_gems), default_libraries: merged_libraries, bundle_sig_paths: gem_sig_paths,
+          rbs_collection_paths: covered_collection_paths, plugin_registry: plugin_registry,
           signature_paths: resolved_paths, bundle_root: bundle_root
         )
         loader_signature_paths = resolved_paths + plugin_sig_paths + gem_sig_paths +
@@ -364,9 +413,19 @@ module Rigor
           # Issue #610 — the plugin-contributed subset is loaded LAST and may stand down against a colliding
           # generic arity. Only the bundled plugins' own `sig/` is deferred: the user's `signature_paths:`,
           # the bundle walk and `rbs collection install` all stay authoritative.
-          deferred_signature_paths: plugin_sig_paths,
+          # Issue #2974 — the ADR-72 gem overlays are Rigor-shipped too, and deferred with them: an overlay member
+          # the project's `sig/` also declares (`Integer#ordinalize`, `ActiveSupport::NumericWithFormat#to_fs`)
+          # stands down member by member (#2422) instead of failing the class's definition build.
+          deferred_signature_paths: plugin_sig_paths + overlay_paths,
           project_signature_paths: resolved_paths,
-          required_features: required_features || RequiredFeatures.scan(source_files, sig_paths: resolved_paths)
+          # Issue #2978 — a gem's collection copy loads behind the gem's own `sig/`: each member that `sig/` (or any
+          # other eagerly loaded signature file) declares stands down from the copy (#2422), and the rest loads.
+          subordinate_signature_paths: behind_gem_sig_paths,
+          # Issue #3030 — the collection gem directories, loaded as rbs loads a library: without the files below a
+          # `_`-prefixed directory (each gem's `_test/` fixtures).
+          collection_signature_paths: collection_paths,
+          required_features: required_features || RequiredFeatures.scan(source_files, sig_paths: resolved_paths),
+          core_root: core_root
         )
         # Issues #824 / #1075 — the rows ADR-112 WD5's consistency rule reports for members the project's
         # own `sig/` and an inline source both declare: an error per contradiction (or per refinement that
@@ -376,6 +435,12 @@ module Rigor
         # on every run, so the member-level outcome needs no plumbing of its own. Costs nothing for a project
         # with no inline RBS: the loader's reader short-circuits on an empty `virtual_rbs`.
         record_member_consistency(loader, source_rbs_synthesis_reporter, root)
+        # Issue #2517 — a selected core is built here, not lazily. The env is first demanded from inside a file's
+        # analysis, under rescues that turn any raise into one `internal analyzer error` row per file; building it
+        # now raises the {CoreRootError} once, before analysis, where the CLI reports it as a configuration error.
+        # Issue #2883 — the default core is built here too (`eager:`), so no `type_of` builds the environment.
+        # A non-main Ractor worker keeps the lazy build: the `rbs` gem's unshareable constants are unreadable there.
+        eager && Ractor.main? ? loader.prepare_for_typing! : loader.verify_core_root!
         # ADR-20 slice 2c + 2e — seed hkt_registry with the bundled builtins. The Environment's
         # `#hkt_registry` getter then LAZILY merges in the RBS env scan on first call so fast paths that
         # don't consult HKT (e.g. `rigor check --cache-stats --no-stats`) don't pay the eager env-build cost
@@ -399,10 +464,20 @@ module Rigor
       # The project-owned `sig/` roots a run reads: the explicit `signature_paths:` when given, else the
       # auto-detected `<root>/sig` (or none). Public so {Cache::IncrementalSnapshot} digests exactly the
       # directories the environment loads, including the auto-detected one a `nil` `signature_paths:` hides.
+      # The default branch is {project_signature_root_candidates} narrowed to the directories that exist.
       def project_signature_roots(signature_paths, root: Dir.pwd)
         signature_paths || default_signature_paths(root)
       end
 
+      # Issue #1619 — the single spelling of "the configured `signature_paths:`, else the conventional `sig`
+      # directory", as the CANDIDATES a run watches whether or not they exist yet. {project_signature_roots}
+      # narrows this to what the loader reads (a default only once it is a directory); the run slot's presence
+      # rows and the incremental write guard take it whole, because a `sig/` appearing mid-run must move the
+      # fingerprint and refuse the slot write — a question only a row for a path that need not exist can ask.
+      def project_signature_root_candidates(signature_paths)
+        signature_paths || [DEFAULT_PROJECT_SIG_DIR]
+      end
+
       private
 
       # Issue #1700 — the `RequiredFeatures` library tokens for the gated vendored directories this run asks for:
@@ -416,13 +491,31 @@ module Rigor
       # The gem names an `rbs collection` copy must not double-declare against: the library list and every
       # vendored directory except a `RequiredFeatures`-gated one. A gated directory stands down for any other
       # copy of its declarations (`GatedSignatureGuard`), so the collection's copy is kept and wins.
+      #
+      # Issue #2971 — a `libraries:` name that is not an RBS library (`foogem`, collection-installed) is dropped by
+      # the loader's `has_library?` filter, so it declares nothing to double-declare against; it stays out of the
+      # skip set so the collection's copy still loads. Issue #2978 — that holds for a gem whose own `sig/` the bundle
+      # loaded too: its collection copy loads behind that `sig/` ({.collection_paths_behind_gem_sigs}).
       def collection_skip_gem_names(library_names)
-        library_names + RbsLoader.vendored_gem_names.reject { |name| RequiredFeatures.gated_dir?(name) }
+        LibraryProbe.loadable(library_names) + RbsLoader.vendored_gem_names.reject do |name|
+          RequiredFeatures.gated_dir?(name)
+        end
+      end
+
+      # Issue #2978 — the `collection_paths` (`<collection>/<name>/<version>/`) of the locked gems whose own `sig/` is
+      # among `gem_sig_paths` ({BundleSigDiscovery.locked_names_of}, keyed by name and version).
+      def collection_paths_behind_gem_sigs(collection_paths, gem_sig_paths, locked)
+        return [] if collection_paths.empty? || gem_sig_paths.empty?
+
+        names = BundleSigDiscovery.locked_names_of(gem_sig_paths.map { |dir| Pathname.new(dir) }, locked).to_set
+        collection_paths.select { |path| names.include?(Pathname.new(path).parent.basename.to_s) }
       end
 
       def default_signature_paths(root)
-        sig = Pathname(root) / DEFAULT_PROJECT_SIG_DIR
-        sig.directory? ? [sig] : []
+        project_signature_root_candidates(nil).filter_map do |candidate|
+          path = Pathname(root) / candidate.to_s
+          path if path.directory?
+        end
       end
 
       # ADR-82 WD9 — the resolved bundle root for the missing-gem constant index, doubling (ADR-90) as the
@@ -445,9 +538,12 @@ module Rigor
         bundle_root
       end
 
-      # The `:missing` classification (locked gems with no RBS through any resolution path), computed once
-      # and consumed twice: as `[gem_name, version, variants]` entries for the ADR-82 WD9 constant-ownership
-      # index, and as the eligible-gem set for the ADR-72 overlay resolution. Returns `[entries, overlay_paths]`.
+      # The per-gem RBS coverage classification (locked gems against every resolution path), computed
+      # once and consumed twice: its `:missing` rows become `[gem_name, version, variants]` entries for
+      # the ADR-82 WD9 constant-ownership index, and the full row set feeds the ADR-72 overlay resolution,
+      # which admits a gem when its row's source is one the gem's overlay may load under
+      # ({GEM_OVERLAY_COVERAGE_SOURCES} — `:missing` by default, `:rbs_collection` for addressable).
+      # Returns `[entries, overlay_paths]`.
       def missing_gems_and_overlay_paths(locked:, default_libraries:, bundle_sig_paths:,
                                          rbs_collection_paths:, plugin_registry:, signature_paths: [],
                                          bundle_root: nil)
@@ -455,10 +551,10 @@ module Rigor
           return unlocked_missing_gems(default_libraries, bundle_sig_paths, rbs_collection_paths, bundle_root)
         end
 
-        rows = missing_rows(locked, default_libraries, bundle_sig_paths, rbs_collection_paths)
+        coverage = coverage_rows(locked, default_libraries, bundle_sig_paths, rbs_collection_paths)
+        rows = coverage.select { |row| row.source == :missing }
         overlays = gem_overlay_paths(
-          missing_gem_names: rows.map(&:gem_name), plugin_registry: plugin_registry,
-          signature_paths: signature_paths
+          coverage: coverage, plugin_registry: plugin_registry, signature_paths: signature_paths
         )
         [index_entries(rows, locked), overlays]
       end
@@ -485,14 +581,20 @@ module Rigor
       end
 
       def missing_rows(gems, default_libraries, bundle_sig_paths, rbs_collection_paths)
+        coverage_rows(gems, default_libraries, bundle_sig_paths, rbs_collection_paths)
+          .select { |row| row.source == :missing }
+      end
+
+      def coverage_rows(gems, default_libraries, bundle_sig_paths, rbs_collection_paths)
         RbsCoverageReport.classify(
           locked_gems: gems, default_libraries: default_libraries,
           bundle_sig_paths: bundle_sig_paths, rbs_collection_paths: rbs_collection_paths
-        ).select { |row| row.source == :missing }
+        )
       end
 
       # ADR-72 — resolve the bundled RBS overlay directories to load for this project. A gem is eligible when
-      # it is classified `:missing` (see {missing_rbs_gem_rows}) and its conflicting opt-in plugin twin (if
+      # its coverage row's source is one the gem's overlay may load under ({GEM_OVERLAY_COVERAGE_SOURCES};
+      # `:missing` for every overlay the map does not name) and its conflicting opt-in plugin twin (if
       # any) is NOT already reachable. Returns `[Pathname]`, deterministically ordered, or `[]` when no
       # eligible gem.
       #
@@ -506,20 +608,29 @@ module Rigor
       # all); `RbsLoader.bundled_overlay_twin_signatures_loaded?` answers the filesystem half, beside the
       # overlay-side answer to the same question, and carries the reasoning for why it asks what an entry
       # LOADS rather than what it looks like.
-      def gem_overlay_paths(missing_gem_names:, plugin_registry:, signature_paths: [])
-        return [] if missing_gem_names.empty?
+      def gem_overlay_paths(coverage:, plugin_registry:, signature_paths: [])
+        return [] if coverage.empty?
 
         loaded_ids = plugin_registry ? plugin_registry.ids.to_set : Set.new
-        eligible = missing_gem_names.reject do |gem_name|
-          plugin_id = GEM_OVERLAY_PLUGIN_IDS[gem_name]
-          next false unless plugin_id
+        eligible = coverage.filter_map do |row|
+          next unless overlay_coverage_source?(row.gem_name, row.source)
+
+          plugin_id = GEM_OVERLAY_PLUGIN_IDS[row.gem_name]
+          next if plugin_id &&
+                  (loaded_ids.include?(plugin_id) ||
+                   RbsLoader.bundled_overlay_twin_signatures_loaded?(plugin_id, signature_paths))
 
-          loaded_ids.include?(plugin_id) ||
-            RbsLoader.bundled_overlay_twin_signatures_loaded?(plugin_id, signature_paths)
-        end.sort
+          row.gem_name
+        end.uniq.sort
         RbsLoader.gem_overlay_sig_paths(eligible)
       end
 
+      # Whether `source` — a `RbsCoverageReport` source — is one `gem_name`'s bundled overlay may load
+      # under: the gem's {GEM_OVERLAY_COVERAGE_SOURCES} entry when it has one, else ADR-72's `:missing`.
+      def overlay_coverage_source?(gem_name, source)
+        (GEM_OVERLAY_COVERAGE_SOURCES[gem_name] || GEM_OVERLAY_DEFAULT_COVERAGE_SOURCES).include?(source)
+      end
+
       # ADR-32 WD4 + WD5 — for each project source file, invoke every plugin-registered synthesizer once and
       # collect non-nil returns. The returned array is `[[virtual_filename, rbs_source], ...]`; the loader
       # threads it through to `RbsLoader.new(virtual_rbs: ...)`.
@@ -644,6 +755,8 @@ module Rigor
       def record_member_undecided(reporter, record, root)
         plugin_id, path = split_virtual_source_name(record.virtual_name)
         return if path.nil?
+        return record_variable_undecided(reporter, record, root, plugin_id, path) if
+          MemberConsistency.variable_kind?(record.kind)
 
         reporter.record(
           plugin_id: plugin_id, path: path, kind: :not_honoured,
@@ -656,8 +769,22 @@ module Rigor
         )
       end
 
+      # Issue #2440 — an instance variable declared by both sides with different types. `sig/` binds
+      # (the coordinator's ruling on #2440, ADR-5): the row is `:info`, never `rbs.contradicting-signature`.
+      def record_variable_undecided(reporter, record, root, plugin_id, path)
+        reporter.record(
+          plugin_id: plugin_id, path: path, kind: :not_honoured,
+          message: "`#{member_label(record)}` is also declared in " \
+                   "`#{path_relative_to(record.signature_path, root)}` with a different type " \
+                   "(#{record.detail}), so the `.rbs` declaration binds and the inline one was dropped. " \
+                   "RBS rejects two declarations of one instance variable, so only one can stay; " \
+                   "regenerate the committed `.rbs` (`rbs-inline --output`) or align the two types."
+        )
+      end
+
+      # `Demo#m` / `Demo.m` for a method, `Demo#@x` / `Demo.@x` for an instance / class instance variable.
       def member_label(record)
-        separator = record.kind == :singleton ? "." : "#"
+        separator = %i[singleton class_instance_variable].include?(record.kind) ? "." : "#"
         "#{record.class_name}#{separator}#{record.method_name}"
       end
 

data/lib/rigor/flow_contribution/merger.rb

@@ -26,13 +26,13 @@ module Rigor
     #
     # ## Composition rules (ADR-2)
     #
-    # - `:return_type` — Intersect via `Type::Combinator.intersection`; collapse to bot raises
-    #   `:return_type_collapse`.
+    # - `:return_type` — Intersect via `Type::Combinator.intersection`; collapse to bot records a
+    #   `:return_type_collapse` conflict.
     # - `:truthy_fact` / `:falsey_fact` / `:post_return_fact` — Edge-local; accumulate while deduping by
     #   payload equality.
     # - `:mutation` / `:invalidation` / `:role` — Union; dedupe by equality.
-    # - `:exception` — Single-valued. Two non-`nil` non-equal exceptional effects raise
-    #   `:exceptional_disagreement`.
+    # - `:exception` — Single-valued. Two non-`nil` non-equal exceptional effects record an
+    #   `:exceptional_disagreement` conflict.
     #
     # ## Cross-tier contradictions
     #