rigortype 0.1.19 → 0.2.1

data/lib/rigor/configuration.rb

@@ -233,6 +233,9 @@ module Rigor
     # included files first (in declaration order), then the
     # current file's own keys override. Relative paths inside
     # each file are resolved against that file's directory.
+    # Public so the CLI can run the include-aware load before
+    # applying `--treat-all-as-inline-rbs`'s plugin injection
+    # (see {CLI::CheckCommand#load_check_configuration}).
     def self.load_with_includes(path, visited: Set.new)
       absolute = File.expand_path(path)
       raise ArgumentError, "circular include: #{absolute}" if visited.include?(absolute)
@@ -328,7 +331,7 @@ module Rigor
       out["source_inference"] = left_si + right_si unless both_empty # rigor:disable flow.always-truthy-condition
       out
     end
-    private_class_method :load_with_includes, :merge_includes, :resolve_paths_in, :deep_merge,
+    private_class_method :merge_includes, :resolve_paths_in, :deep_merge,
                          :merge_value, :merge_dependencies_hash
 
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
@@ -437,6 +440,32 @@ module Rigor
       }
     end
 
+    # ADR-50 § WD2 — returns a sibling Configuration whose bleeding-edge
+    # selection (and the derived `bleeding_edge_severity_overrides` the two
+    # {SeverityProfile.resolve} sites consult) is replaced by `value`,
+    # leaving every other field shared with the receiver. `value` takes the
+    # same forms as the `bleeding_edge:` config key — `false` / `true` / a
+    # feature-id Array / `{ "all" => true, "except" => [...] }` — and is
+    # normalised through the same {#coerce_bleeding_edge} path, so an unknown
+    # id stays inert.
+    #
+    # The CLI's `--bleeding-edge[=ids]` / `--no-bleeding-edge` flag uses this
+    # to override the configured selection for a single run (the same
+    # CLI-over-config precedence `--workers` and `--no-cache` follow). It is a
+    # frozen `dup` with the two bleeding-edge ivars re-set: `dup` returns an
+    # unfrozen shallow copy (every other ivar is the receiver's deeply-frozen
+    # value, safe to share read-only), the two replacements are themselves
+    # deeply frozen, and the re-`freeze` keeps the result `Ractor.shareable?`
+    # for the worker path.
+    def with_bleeding_edge(value)
+      selector = coerce_bleeding_edge(value)
+      copy = dup
+      copy.instance_variable_set(:@bleeding_edge, selector)
+      copy.instance_variable_set(:@bleeding_edge_severity_overrides,
+                                 BleedingEdge.severity_overrides_for(selector))
+      copy.freeze
+    end
+
     private
 
     # ADR-17 slice 4 — `pre_eval:` glob expansion. Each entry is
@@ -499,10 +528,9 @@ module Rigor
       s.dup.freeze
     end
 
-    # Slice 2 only accepts `:disabled` for the network policy. The
-    # YAML scalar may arrive as a String (`"disabled"`) or already
-    # as the Symbol; coerce to the canonical Symbol shape so the
-    # downstream `TrustPolicy` constructor stays strict.
+    # YAML scalar may arrive as a String or already as a Symbol;
+    # coerce to the canonical Symbol shape so the downstream
+    # `TrustPolicy` constructor stays strict.
     #
     # The accepted set is duplicated from
     # {Rigor::Plugin::TrustPolicy::VALID_NETWORK_POLICIES} so
@@ -572,6 +600,18 @@ module Rigor
       raise ArgumentError, "severity_overrides must be a Hash, got #{value.inspect}" unless value.is_a?(Hash)
 
       value.to_h do |k, v|
+        # YAML 1.1 parses bare `off`/`on`/`no`/`yes`/`true`/`false`
+        # as booleans, so a user who wrote `off` (a valid severity)
+        # without quotes hands us `false`. Catch the non-Symbol /
+        # non-String case before `to_sym` blows up with a backtrace.
+        unless v.is_a?(String) || v.is_a?(Symbol)
+          hint = v == false ? %( — did you mean the string "off"?) : ""
+          raise ArgumentError,
+                "severity_overrides[#{k.inspect}] is #{v.inspect}, a YAML boolean#{hint} " \
+                "Bare off/on/no/yes/true/false are parsed as booleans; quote the severity " \
+                "(e.g. \"off\")."
+        end
+
         sym = v.to_sym
         unless SeverityProfile::VALID_SEVERITIES.include?(sym)
           raise ArgumentError,
@@ -593,7 +633,7 @@ module Rigor
       case value
       when nil, false then { "mode" => "none" }
       when true then { "mode" => "all" }
-      when Array then { "mode" => "list", "ids" => value.map(&:to_s).freeze }
+      when Array then { "mode" => "list", "ids" => freeze_ids(value) }
       when Hash then coerce_bleeding_edge_hash(value)
       else
         raise ArgumentError,
@@ -605,12 +645,22 @@ module Rigor
     def coerce_bleeding_edge_hash(value)
       hash = value.to_h { |k, v| [k.to_s, v] }
       if hash.fetch("all", false) == true
-        { "mode" => "all", "except" => Array(hash["except"]).map(&:to_s).freeze }
+        { "mode" => "all", "except" => freeze_ids(Array(hash["except"])) }
       else
         { "mode" => "none" }
       end
     end
 
+    # Feature ids reach `coerce_bleeding_edge` from YAML, a `to_h` round-trip,
+    # or the CLI's `--bleeding-edge=a,b` (all runtime-created, non-frozen
+    # Strings). Each id String is frozen so the normalized selector — and thus
+    # the whole Configuration — stays deeply frozen and `Ractor.shareable?`
+    # for the worker path (the same invariant `#initialize`'s final `freeze`
+    # upholds for every other field).
+    def freeze_ids(ids)
+      ids.map { |id| id.to_s.dup.freeze }.freeze
+    end
+
     # Renders the normalized selector back into the user-facing
     # `bleeding_edge:` form for `#to_h` round-trips.
     def bleeding_edge_to_h

data/lib/rigor/environment/bundle_sig_discovery.rb

@@ -4,7 +4,7 @@ require "yaml"
 
 module Rigor
   class Environment
-    # Open item O4 — target-project Bundler awareness.
+    # Target-project Bundler awareness (O4, implemented).
     #
     # Walks a Bundler-installed gem tree (e.g., the project's
     # `vendor/bundle` or a Docker-mounted bundle root) and
@@ -84,11 +84,12 @@ module Rigor
       #   supplied) minus any whose `(name, version, platform)`
       #   does not match a lockfile entry.
       def self.discover(bundle_path:, project_root: Dir.pwd, auto_detect: true,
-                        skip_gems: SKIPPED_GEMS_BY_DEFAULT, locked_gems: nil)
+                        skip_gems: SKIPPED_GEMS_BY_DEFAULT, locked_gems: nil, home: nil)
         resolved = resolve_bundle_path(
           bundle_path: bundle_path,
           project_root: project_root,
-          auto_detect: auto_detect
+          auto_detect: auto_detect,
+          home: home
         )
         return [] if resolved.nil?
 
@@ -143,7 +144,7 @@ module Rigor
       # Returns `Pathname` resolved bundle path, or `nil` when
       # neither explicit nor auto-detected. Public for the stats
       # banner so end users can see what rigor picked up.
-      def self.resolve_bundle_path(bundle_path:, project_root: Dir.pwd, auto_detect: true)
+      def self.resolve_bundle_path(bundle_path:, project_root: Dir.pwd, auto_detect: true, home: nil)
         if bundle_path
           path = Pathname.new(File.expand_path(bundle_path.to_s, project_root))
           return path if path.directory?
@@ -153,31 +154,77 @@ module Rigor
 
         return nil unless auto_detect
 
-        detected = auto_detect(project_root: project_root)
+        detected = auto_detect(project_root: project_root, home: home)
         Pathname.new(detected) if detected
       end
 
-      # Auto-detection order:
+      # Auto-detection order — project-local strategies win over the
+      # user-global one, mirroring Bundler's own config precedence:
       # 1. `<project_root>/.bundle/config` carries `BUNDLE_PATH:`
       #    set by `bundle config set --local path <dir>`.
       # 2. `<project_root>/vendor/bundle/` — the conventional
       #    in-tree install location when a developer ran
       #    `bundle install --path vendor/bundle`.
-      # 3. `nil` — let the caller proceed without bundle sig
+      # 3. The user-global bundler config `<home>/.bundle/config`
+      #    `BUNDLE_PATH:` (`bundle config set --global path <dir>`),
+      #    resolved relative to the project root and used only when
+      #    it points at an existing directory — the last resort for
+      #    a project with no in-tree bundle. Purely additive: it is
+      #    consulted only when steps 1–2 found nothing, so it never
+      #    changes an already-working detection.
+      # 4. `nil` — let the caller proceed without bundle sig
       #    discovery (rigor's vendored RBS still loads).
-      def self.auto_detect(project_root:)
-        from_config = read_bundle_config_path(project_root)
+      #
+      # Note (ADR-27): rigor reads the *project* as data, so
+      # detection is limited to paths recorded in project-local or
+      # user-global Bundler config files. The pure-default install
+      # location — gems in the active Ruby's GEM_HOME with no `path`
+      # configured — is the *project's* Ruby's gem home, which the
+      # isolated analyzer cannot know without running the project's
+      # toolchain. Point rigor at it with `bundler.bundle_path:`, or
+      # supply signatures via `rbs collection install` /
+      # `dependencies.source_inference:`. `BUNDLE_PATH` from rigor's
+      # own environment is deliberately NOT consulted — it describes
+      # rigor's bundle, not the analyzed project's.
+      #
+      # `home:` defaults to the invoking user's home directory; it is
+      # a parameter so tests stay hermetic (no read of the real
+      # `~/.bundle/config`).
+      def self.auto_detect(project_root:, home: nil)
+        from_config = read_bundle_config_path(File.join(project_root, ".bundle", "config"))
         return File.expand_path(from_config, project_root) if from_config
 
         vendor = File.join(project_root, "vendor", "bundle")
         return vendor if File.directory?(vendor)
 
+        global_bundle_path(project_root: project_root, home: home)
+      end
+
+      # Resolves the user-global `BUNDLE_PATH` against the project
+      # root, returning it only when it is an existing directory.
+      # Returns nil when there is no global config, no home, or the
+      # configured path does not exist.
+      def self.global_bundle_path(project_root:, home:)
+        home ||= default_home
+        return nil if home.nil?
+
+        configured = read_bundle_config_path(File.join(home, ".bundle", "config"))
+        return nil unless configured
+
+        resolved = File.expand_path(configured, project_root)
+        File.directory?(resolved) ? resolved : nil
+      end
+      private_class_method :global_bundle_path
+
+      def self.default_home
+        Dir.home
+      rescue StandardError
         nil
       end
+      private_class_method :default_home
 
-      def self.read_bundle_config_path(project_root)
-        config_path = File.join(project_root, ".bundle", "config")
-        return nil unless File.exist?(config_path)
+      def self.read_bundle_config_path(config_path)
+        return nil unless config_path && File.exist?(config_path)
 
         # `.bundle/config` is YAML with all-caps env-style keys.
         # `BUNDLE_PATH:` is the canonical key (Bundler 2.x); the
@@ -185,7 +232,8 @@ module Rigor
         data = YAML.safe_load_file(config_path)
         return nil unless data.is_a?(Hash)
 
-        data["BUNDLE_PATH"]
+        path = data["BUNDLE_PATH"]
+        path && !path.to_s.empty? ? path.to_s : nil
       rescue StandardError
         # Malformed `.bundle/config` should not break analysis;
         # silently skip auto-detection.

data/lib/rigor/environment/class_registry.rb

@@ -7,8 +7,8 @@ module Rigor
     # Resolves Ruby Class/Module objects to Rigor::Type::Nominal instances.
     # The hardcoded list spans the core classes the literal typer (Slice 1)
     # and the constant-resolution path (Slice 2 strengthening) need.
-    # Slice 4 will extend the registry by reading RBS Definitions through
-    # Rigor::Environment::RbsLoader.
+    # This is the static fast path for built-ins; `Environment` falls through
+    # to `RbsLoader` for all other names — the two tiers are complementary.
     #
     # See docs/internal-spec/inference-engine.md for the binding contract
     # (every entry below MUST always be recognised).
@@ -28,7 +28,8 @@ module Rigor
       # Common Ruby core classes that user code routinely names by constant
       # reference. Adding them to the registry lets `nominal_for_name`
       # resolve `Array`, `Hash`, etc. without each call site re-listing
-      # them; Slice 4's RBS loader will subsume these once it lands.
+      # them. The static registry is the cheap fast path; `RbsLoader`
+      # extends coverage to all other RBS-declared names (Slice 4, landed).
       SLICE_2_BUILT_INS = [
         Array,
         Hash,

data/lib/rigor/environment/constant_type_cache_holder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Per-key memoization container for {Environment#constant_for_name}.
+    # Held by {Environment} so the otherwise-frozen instance can cache
+    # constant-resolution results on first access — the sibling of
+    # {HktRegistryHolder}, generalised from one slot to a name-keyed map.
+    #
+    # Why this exists: `constant_for_name` is a pure function of its
+    # name for a given Environment (both the predefined-constant
+    # refinement table and the RBS loader's constant table are fixed for
+    # the Environment's lifetime), yet it is the hottest non-dispatch
+    # path on a large Rails app. {ExpressionTyper#resolve_constant_name}
+    # peels a lexical-candidate ladder per constant reference, so the
+    # same qualified names recur thousands of times across files — and
+    # each miss runs a `const_get` walk that raises + rescues `NameError`
+    # for every project-defined constant (the common case). Caching the
+    # result collapses the repeats to a hash lookup.
+    #
+    # Caches `nil` results too (a name that resolves to no refined /
+    # RBS constant type stays unresolved for the run), so the
+    # const_get-and-rescue is paid at most once per distinct name.
+    #
+    # Concurrency: single-threaded use only, the same discipline as
+    # {HktRegistryHolder} — the Ractor pool builds a per-worker
+    # Environment and the LSP single-publish invariant serialises the
+    # shared-Environment reader path. If a future caller introduces a
+    # multi-threaded reader against one Environment, the synchronisation
+    # belongs at that caller's seam, not here.
+    class ConstantTypeCacheHolder
+      def initialize
+        @cache = {}
+      end
+
+      def fetch(key)
+        return @cache[key] if @cache.key?(key)
+
+        @cache[key] = yield
+      end
+    end
+  end
+end

data/lib/rigor/environment/lockfile_resolver.rb

@@ -2,7 +2,7 @@
 
 module Rigor
   class Environment
-    # Open item O4 Layer 3 — Gemfile.lock parse.
+    # Gemfile.lock parser for target-project bundler awareness (O4 Layer 3, implemented).
     #
     # Parses a target project's `Gemfile.lock` via Bundler's
     # `LockfileParser` and exposes the locked gem set as a frozen

data/lib/rigor/environment/rbs_collection_discovery.rb

@@ -4,8 +4,7 @@ require "yaml"
 
 module Rigor
   class Environment
-    # Open item O4 Layer 3 slice 2 — `rbs collection install`
-    # awareness.
+    # `rbs collection install` awareness (O4 Layer 3 slice 2, implemented).
     #
     # When the target project has been set up with `rbs
     # collection install` (the standard RBS-ecosystem flow for

data/lib/rigor/environment/rbs_coverage_report.rb

@@ -42,7 +42,8 @@ module Rigor
       # enough that hard-coding is acceptable; a directory walk
       # at every call would add stat-cost to no benefit.)
       VENDORED_GEM_NAMES = Set[
-        "bcrypt", "bundler", "cgi", "did_you_mean", "idn-ruby", "mysql2", "nokogiri", "pg", "prism", "redis", "rubygems"
+        "ast", "bcrypt", "bundler", "cgi", "did_you_mean",
+        "idn-ruby", "mysql2", "nokogiri", "pg", "prism", "redis", "rubygems"
       ].freeze
 
       # @param locked_gems [Hash{String => LockfileResolver::LockedGem}]

data/lib/rigor/environment/rbs_loader.rb

@@ -323,6 +323,33 @@ module Rigor
           [Pathname(CORE_OVERLAY_SIGS_ROOT)]
         end
 
+        # Rigor-owned per-gem RBS overlays (`data/gem_overlay/<gem>/`),
+        # ADR-72. Unlike the unconditional `core_overlay`, each gem's
+        # overlay is loaded ONLY when that gem is locked in the
+        # project's Gemfile.lock but ships no RBS of its own —
+        # {Environment.for_project} decides eligibility and passes the
+        # already-filtered gem-name set here. One directory per gem name
+        # keeps the membership check a cheap `File.directory?`.
+        GEM_OVERLAY_SIGS_ROOT = File.expand_path(
+          "../../../data/gem_overlay",
+          __dir__
+        ).freeze
+
+        # @param gem_names [Enumerable<String>] overlay-eligible
+        #   Gemfile.lock gem names (the caller filters to the
+        #   `:missing`-coverage, no-conflicting-plugin set).
+        # @return [Array<Pathname>] the bundled overlay directory for
+        #   each gem that ships one; empty when none match or the
+        #   overlay root is absent.
+        def gem_overlay_sig_paths(gem_names)
+          return [] unless File.directory?(GEM_OVERLAY_SIGS_ROOT)
+
+          gem_names.filter_map do |name|
+            dir = File.join(GEM_OVERLAY_SIGS_ROOT, name.to_s)
+            Pathname(dir) if File.directory?(dir)
+          end
+        end
+
         def vendored_gem_sig_paths
           return [] unless File.directory?(VENDORED_GEM_SIGS_ROOT)
 
@@ -363,11 +390,11 @@ module Rigor
       #   out at build time so the loader stays robust to fixtures and
       #   bare repositories.
       # @param cache_store [Rigor::Cache::Store, nil] the persistent
-      #   cache the loader consults for translated constant lookups
-      #   (and, in later v0.0.9 slices, other Marshal-clean
-      #   reflection artefacts). Pass `nil` (the default) to skip
-      #   the cache entirely; the runner threads its own Store
-      #   through here when caching is enabled.
+      #   cache the loader threads through to `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 [Array<[String, String]>] ADR-32 WD4 —
       #   `[virtual_filename, rbs_source]` pairs synthesised from
       #   project source by a plugin's
@@ -643,6 +670,29 @@ module Rigor
         interface_definition(interface_name)&.methods&.keys
       end
 
+      # @param rbs_alias [RBS::Types::Alias] a type-alias reference (`string`,
+      #   `int`, `range[int?]`, …) appearing in a method signature.
+      # @return [RBS::Types::t, nil] the alias's aliased type one level out,
+      #   with type arguments substituted for a generic alias (`string` →
+      #   `::String | ::_ToStr`; `range[int?]` → `::Range[int?] |
+      #   ::_Range[int?]`), or nil for an unresolved name. Lets a caller see
+      #   through the alias that {Inference::RbsTypeTranslator} otherwise
+      #   degrades to `untyped`, which is why an interface/alias parameter
+      #   does not reject `nil`. `expand_alias2` handles the (rarer) generic
+      #   case — a `range[T]` param previously fell back to "admits", which
+      #   suppressed e.g. `MatchData#[](nil)`.
+      def expand_type_alias(rbs_alias)
+        return nil if env.nil?
+
+        name = rbs_alias.name
+        name = name.absolute! unless name.absolute?
+        return nil unless env.type_alias_decls.key?(name)
+
+        builder.expand_alias2(name, rbs_alias.args)
+      rescue ::RBS::BaseError, StandardError
+        nil
+      end
+
       # @return [RBS::Definition, nil] the resolved singleton (class
       #   object) definition for `class_name`. The methods on this
       #   definition are the *class methods* of `class_name`, including
@@ -1034,6 +1084,8 @@ module Rigor
         rbs_name = parse_type_name(class_name)
         return nil unless rbs_name
         return nil if env.nil?
+
+        rbs_name = canonical_module_name(rbs_name)
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_instance(rbs_name)
@@ -1045,6 +1097,8 @@ module Rigor
         rbs_name = parse_type_name(class_name)
         return nil unless rbs_name
         return nil if env.nil?
+
+        rbs_name = canonical_module_name(rbs_name)
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_singleton(rbs_name)
@@ -1052,6 +1106,23 @@ module Rigor
         nil
       end
 
+      # Resolve an RBS class/module ALIAS to its canonical declared name.
+      # `class Mutex = Thread::Mutex` lives only in `class_alias_decls`, so
+      # `class_known?` reports it (it checks that table) but the definition
+      # builder — which only knows `class_decls` — could not enumerate its
+      # methods, leaving alias classes (`Mutex`, and any `X = Y`) with no
+      # resolvable method surface. Normalising via the env (RBS's own alias
+      # resolution) before the `class_decls` guard fixes dispatch AND the
+      # `call.undefined-method` existence check on them. A non-alias name, or
+      # one that does not normalise, is returned unchanged.
+      def canonical_module_name(rbs_name)
+        return rbs_name unless env.class_alias_decls.key?(rbs_name)
+
+        env.normalize_module_name?(rbs_name) || rbs_name
+      rescue ::RBS::BaseError
+        rbs_name
+      end
+
       # Memoised on `@state` (the per-loader store also holding `:env` /
       # `:builder`): `RBS::TypeName.parse` is a pure, deterministic
       # function of the normalised string, and the `RBS::TypeName` it

data/lib/rigor/environment.rb

@@ -7,6 +7,7 @@ require_relative "environment/rbs_loader"
 require_relative "environment/reflection"
 require_relative "environment/reporters"
 require_relative "environment/hkt_registry_holder"
+require_relative "environment/constant_type_cache_holder"
 require_relative "environment/bundle_sig_discovery"
 require_relative "environment/lockfile_resolver"
 require_relative "environment/rbs_collection_discovery"
@@ -15,12 +16,13 @@ require_relative "inference/synthetic_method_index"
 require_relative "inference/project_patched_methods"
 require_relative "inference/hkt_registry"
 require_relative "builtins/hkt_builtins"
+require_relative "builtins/predefined_constant_refinements"
 require_relative "type_node/name_scope"
 require_relative "type_node/resolver_chain"
 
 module Rigor
   # The engine's view of the type universe outside the current scope.
-  # Slice 1 only exposed the class registry; Slice 4 adds the RBS loader,
+  # Slice 1 exposed only the class registry; Slice 4 added the RBS loader,
   # which threads through ExpressionTyper and MethodDispatcher to type
   # constant references and method calls that the literal-typer and
   # constant-folding tiers cannot answer.
@@ -63,6 +65,13 @@ module Rigor
       prism rbs
     ].freeze
 
+    # ADR-72 — a Gemfile.lock gem name mapped to the opt-in plugin id
+    # that ships the SAME core-ext RBS. When that plugin is loaded the
+    # auto-overlay for the gem stands down, so the two never both
+    # declare the methods (which would raise a duplicate-declaration
+    # error). Keyed on the gem name `RbsCoverageReport` reports.
+    GEM_OVERLAY_PLUGIN_IDS = { "activesupport" => "activesupport-core-ext" }.freeze
+
     attr_reader :class_registry, :rbs_loader, :plugin_registry, :dependency_source_index,
                 :reporters, :name_scope,
                 :synthetic_method_index, :project_patched_methods
@@ -123,6 +132,7 @@ module Rigor
       # build at all.
       @hkt_registry_base = hkt_registry || Inference::HktRegistry::EMPTY
       @hkt_registry_holder = HktRegistryHolder.new
+      @constant_type_cache = ConstantTypeCacheHolder.new
       @name_scope = build_name_scope
       freeze
     end
@@ -288,7 +298,24 @@ module Rigor
         # 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) : []
-        loader_signature_paths = resolved_paths + plugin_sig_paths + gem_sig_paths + collection_paths
+        # 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 loaded (no duplicate
+        # declaration). The paths ride in `loader_signature_paths`, so
+        # the env cache descriptor digests them for free.
+        overlay_paths = gem_overlay_paths(
+          locked: locked, default_libraries: merged_libraries,
+          bundle_sig_paths: gem_sig_paths, rbs_collection_paths: collection_paths,
+          plugin_registry: plugin_registry
+        )
+        loader_signature_paths = resolved_paths + plugin_sig_paths + gem_sig_paths +
+                                 collection_paths + overlay_paths
         # ADR-32 WD4 + WD5 — invoke each loaded plugin's
         # `source_rbs_synthesizer` once per project source file
         # and collect non-nil `[filename, rbs_source]` pairs.
@@ -343,6 +370,30 @@ module Rigor
         sig.directory? ? [sig] : []
       end
 
+      # ADR-72 — resolve the bundled RBS overlay directories to load for
+      # this project. A gem is eligible when it is locked in the
+      # Gemfile.lock, classified `:missing` by {RbsCoverageReport}
+      # (no RBS through default-library / vendored / bundle-`sig/` /
+      # rbs-collection), and its conflicting opt-in plugin (if any) is
+      # not loaded. Returns `[Pathname]`, deterministically ordered, or
+      # `[]` when no lockfile / no eligible gem.
+      def gem_overlay_paths(locked:, default_libraries:, bundle_sig_paths:,
+                            rbs_collection_paths:, plugin_registry:)
+        return [] if locked.empty?
+
+        missing = RbsCoverageReport.classify(
+          locked_gems: locked, default_libraries: default_libraries,
+          bundle_sig_paths: bundle_sig_paths, rbs_collection_paths: rbs_collection_paths
+        ).select { |row| row.source == :missing }.map(&:gem_name)
+
+        loaded_ids = plugin_registry ? plugin_registry.ids.to_set : Set.new
+        eligible = missing.reject do |gem_name|
+          plugin_id = GEM_OVERLAY_PLUGIN_IDS[gem_name]
+          plugin_id && loaded_ids.include?(plugin_id)
+        end.sort
+        RbsLoader.gem_overlay_sig_paths(eligible)
+      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,
@@ -453,11 +504,11 @@ module Rigor
       def invoke_synthesizer_safely(callable, path)
         callable.call(path.to_s)
       rescue StandardError
-        # WD6 fail-soft — a synthesizer that raises does NOT
-        # crash analysis. Slice 2b will turn this into a
-        # `source-rbs-synthesis-failed` info diagnostic; for now
-        # the contract is "no analysis crash on a misbehaving
-        # synthesizer".
+        # WD6 fail-soft — a synthesizer that raises does NOT crash
+        # analysis. Unlike the `[:error, msg]` return path (which
+        # the runner surfaces as `source-rbs-synthesis-failed`),
+        # an unhandled raise is swallowed silently; the
+        # unexamined-raise channel is deliberately silent per WD6.
         nil
       end
     end
@@ -504,7 +555,14 @@ module Rigor
     def constant_for_name(name)
       return nil if rbs_loader.nil?
 
-      rbs_loader.constant_type(name.to_s)
+      # Pure function of `name` for this Environment's lifetime — the
+      # refinement table and the RBS constant table are both fixed — so
+      # memoise across the lexical-candidate ladder's heavy name reuse.
+      key = name.to_s
+      @constant_type_cache.fetch(key) do
+        Builtins::PredefinedConstantRefinements.lookup(key) ||
+          rbs_loader.constant_type(key)
+      end
     end
 
     # Returns true when the constant name is known to either the static

data/lib/rigor/flow_contribution/fact.rb

@@ -18,7 +18,7 @@ module Rigor
     #    (`Rigor::RbsExtended::PredicateEffect`).
     # 3. RBS::Extended `assert*` directives
     #    (`Rigor::RbsExtended::AssertEffect`).
-    # 4. Future plugin contributions (slice 5 emission protocol).
+    # 4. Plugin contributions via `type_specifier` DSL (ADR-52).
     #
     # Each of those four carriers translates to / from Fact at
     # its boundary; downstream of {Rigor::FlowContribution#to_element_list}

data/lib/rigor/flow_contribution.rb

@@ -20,11 +20,9 @@ module Rigor
   # contract — see ADR-2 § "Flow Contribution Bundle" for the binding
   # definition.
   #
-  # The element-list flattening (`to_element_list`) ADR-2 mentions is
-  # intentionally not implemented yet: it is the analyzer-internal
-  # bookkeeping behind the merge policy and will land alongside the
-  # plugin contribution merger in v0.1.0. Plugin authors should not
-  # rely on it.
+  # `to_element_list` and `Merger` are implemented; plugin authors
+  # should not depend on the `Element` shape — the bundle is the
+  # public contract.
   class FlowContribution
     # Provenance carries the metadata every contribution needs for
     # diagnostic attribution and cache invalidation. `source_family`