rigortype 0.2.8 → 0.3.0

data/lib/rigor/plugin/loader.rb

@@ -12,7 +12,8 @@ module Rigor
     #
     # Steps per entry (in order):
     #
-    # 1. Normalise the entry into `{ gem:, id:, config: }`.
+    # 0. Skip the entry entirely when it carries `enabled: false` (the ADR-93 WD2 opt-out).
+    # 1. Normalise the entry into `{ gem:, id:, config:, enabled: }`.
     # 2. `require` the gem (failures surface as a {LoadError}).
     # 3. Look up the registered plugin class by id (or by gem name if the entry omitted an explicit id).
     # 4. Validate the user's config against the manifest's `config_schema`.
@@ -22,18 +23,57 @@ module Rigor
     # entries that resolve to the same gem. Failures do not abort the run; the loader collects them on the
     # {Registry} so the runner can convert each one into a `:plugin_loader` diagnostic.
     class Loader # rubocop:disable Metrics/ClassLength
-      attr_reader :services, :requirer
+      attr_reader :services, :requirer, :feature_resolver
+
+      # #194 slice 1 — resolve the file that satisfied `require <gem>` by scanning `$LOADED_FEATURES` for the
+      # entry ending in `/<gem>.rb`, LAST match preferred. Provenance-agnostic: it pins the actual file for a
+      # Bundler path gem, an installed gem, and a `-I`-injected checkout alike, and — because the feature is
+      # already present from the first load — it still resolves when `require` no-ops on a repeat in-process
+      # load (ADR-88 WD4b). Returns nil, never raises, in the degenerate cases: a gem whose entry-file
+      # basename differs from the gem name, and a spec's fake requirer that never populated `$LOADED_FEATURES`.
+      FEATURE_RESOLVER = lambda do |gem_name|
+        suffix = "/#{gem_name}.rb"
+        $LOADED_FEATURES.rfind { |feature| feature.end_with?(suffix) }
+      end
+
+      # #194 slice 2 (ADR-93 WD5) — the engine's own root, anchored from THIS file's location: the loader
+      # lives at `<root>/lib/rigor/plugin/loader.rb`, so three levels up is the engine root. It resolves
+      # identically in a git checkout and inside an installed `rigortype` gem, because the gem packages the
+      # `plugins/` tree at the same relative path — which is exactly what makes it a trustworthy anchor for
+      # the engine's own bundled plugin copies.
+      ENGINE_ROOT = File.expand_path("../../..", __dir__)
 
       # @param services [Rigor::Plugin::Services]
-      # @param requirer [#call] takes a gem name and returns truthy on successful require. Defaulted to
-      #   `Kernel.require` via a lambda; the spec injects a fake to avoid touching the real load path.
-      def initialize(services:, requirer: ->(name) { require name })
+      # @param requirer [#call] takes a gem name OR an absolute file path (#194 slice 2 — a bundled plugin is
+      #   required by its {.bundled_plugin_path}) and returns truthy on successful require. Defaulted to
+      #   `Kernel.require` via a lambda, which accepts both forms; the spec injects a fake to avoid touching
+      #   the real load path.
+      # @param feature_resolver [#call] takes a gem name and returns the absolute path `require` resolved it
+      #   to (or nil). Defaulted to {FEATURE_RESOLVER}; the spec injects a fake so it never has to mutate the
+      #   real `$LOADED_FEATURES` global.
+      def initialize(services:, requirer: ->(name) { require name }, feature_resolver: FEATURE_RESOLVER)
         @services = services
         @requirer = requirer
+        @feature_resolver = feature_resolver
+      end
+
+      def self.load(configuration:, services:, requirer: ->(name) { require name }, feature_resolver: FEATURE_RESOLVER)
+        new(services: services, requirer: requirer, feature_resolver: feature_resolver).load(configuration.plugins)
       end
 
-      def self.load(configuration:, services:, requirer: ->(name) { require name })
-        new(services: services, requirer: requirer).load(configuration.plugins)
+      # #194 slice 2 (ADR-93 WD5) — the absolute path of the engine's OWN bundled copy of a plugin gem
+      # (`<ENGINE_ROOT>/plugins/<gem>/lib/<gem>.rb`), or nil when the engine does not bundle it. A bundled
+      # plugin is required by this path rather than by gem name, so a stale installed `rigortype` gem can
+      # never displace the engine's own versioned copy through RubyGems name resolution — the engine and its
+      # bundled plugins are versioned together. Returns nil for a third-party / project-bundle plugin and for
+      # a trimmed packaging (the ADR-27 single-binary target that ships no `plugins/` tree), where the caller
+      # falls back to today's gem-name require so no install mode regresses. The rule is uniform across the
+      # auto-wired `rigor-rbs-inline` default and every user-listed entry, because the skew mechanism is
+      # identical for both. Also read by `rigor doctor`'s skew check (#194 slice 3) to decide which loaded
+      # plugins the engine bundles.
+      def self.bundled_plugin_path(gem_name)
+        path = File.join(ENGINE_ROOT, "plugins", gem_name, "lib", "#{gem_name}.rb")
+        File.file?(path) ? path : nil
       end
 
       # @param entries [Array<String, Hash>] the raw `plugins:` list from the configuration.
@@ -42,12 +82,21 @@ module Rigor
         plugins = []
         load_errors = []
         seen_ids = {}
+        # #194 slice 1 — `gem name => resolved file path` for every gem the loader successfully required.
+        # A frozen plugin instance (e.g. `rigor-rbs-inline` self-freezes per ADR-32) can't carry the path,
+        # so it rides on the Registry keyed by gem name; the `rigor plugins` loaded row reads it back.
+        @resolved_gem_paths = {}
 
         Array(entries).each_with_index do |raw, index|
           entry = normalise_entry(raw, index)
         rescue LoadError => e
           load_errors << e
         else
+          # ADR-93 WD2 — `enabled: false` opts a listed plugin out entirely: it is neither required nor
+          # trusted nor id-checked. This is the project-level opt-out for the auto-wired `rigor-rbs-inline`
+          # default (a user re-lists it with `enabled: false`), but it works for any entry.
+          next unless entry[:enabled]
+
           begin
             plugin = resolve_and_instantiate(entry, seen_ids)
             plugins << plugin if plugin
@@ -64,19 +113,23 @@ module Rigor
         load_errors.concat(sort_errors)
 
         blueprints = plugins.map { |plugin| Blueprint.new(klass_name: plugin.class.name, config: plugin.config) }
-        Registry.new(plugins: plugins, blueprints: blueprints, load_errors: load_errors)
+        Registry.new(plugins: plugins, blueprints: blueprints, load_errors: load_errors,
+                     resolved_gem_paths: @resolved_gem_paths)
       end
 
       private
 
       # Accepts:
-      #   "rigor-rails"
-      #   { "gem" => "rigor-rails", "id" => "rails", "config" => {...} }
-      #   { gem: "rigor-rails", id: "rails", config: {...} }
+      #   "rigor-activerecord"
+      #   { "gem" => "rigor-activerecord", "id" => "activerecord", "config" => {...} }
+      #   { gem: "rigor-activerecord", id: "activerecord", config: {...} }
+      #
+      # The `id:` form selects one plugin from a gem that registers several — the bare-string form
+      # raises for those (see `lookup_plugin_class!`).
       def normalise_entry(raw, index)
         case raw
         when String
-          { gem: raw, id: nil, config: {} }
+          { gem: raw, id: nil, config: {}, enabled: true }
         when Hash
           string_keyed = raw.to_h { |k, v| [k.to_s, v] }
           gem_name = string_keyed["gem"] || string_keyed["id"]
@@ -87,7 +140,9 @@ module Rigor
             )
           end
 
-          { gem: gem_name, id: string_keyed["id"], config: string_keyed["config"] || {} }
+          # `enabled:` defaults to true; only the explicit `false` disables (nil / absent stays enabled).
+          { gem: gem_name, id: string_keyed["id"], config: string_keyed["config"] || {},
+            enabled: string_keyed["enabled"] != false }
         else
           raise LoadError.new(
             "plugin entry ##{index} must be a String or Hash, got #{raw.class}",
@@ -99,9 +154,24 @@ module Rigor
       def resolve_and_instantiate(entry, seen_ids) # rubocop:disable Metrics/AbcSize
         before = Plugin.registered.keys.to_set
         require_gem!(entry)
+        # The require SUCCEEDED — pin the file it resolved to (nil when the resolver can't, never a raise).
+        # Recorded before the fallible steps below so a config/init failure can still name the loaded copy.
+        @resolved_gem_paths[entry[:gem]] = @feature_resolver.call(entry[:gem])
         after = Plugin.registered.keys.to_set
         newly_registered = (after - before).to_a
 
+        # ADR-88 WD4b — `require` runs a gem's body (and its `Rigor::Plugin.register` calls) at most ONCE per
+        # process. A first load captures the gem's ids in `newly_registered` and memoises the gem→ids mapping;
+        # a SECOND in-process load (the `--verify-incremental` full-run oracle, the incremental session's
+        # subset re-analysis, LSP re-loads) sees `require` no-op and an empty delta, so a bare-string
+        # (`id:`-less) entry recovers the gem's ids from the memo instead of raising "did not register any
+        # plugin". An explicit `id:` entry never needs this — it resolves by id directly in `lookup_plugin_class!`.
+        if newly_registered.any?
+          Plugin.record_gem_registration(entry[:gem], newly_registered)
+        elsif entry[:id].nil?
+          newly_registered = Plugin.ids_for_gem(entry[:gem])
+        end
+
         plugin_class = lookup_plugin_class!(entry, newly_registered)
         manifest = plugin_class.manifest
 
@@ -118,6 +188,13 @@ module Rigor
         plugin = instantiate(plugin_class, entry[:config])
         validate_signature_paths!(plugin)
         plugin
+      rescue LoadError => e
+        # #194 slice 1 — annotate a POST-require failure (bad config, a raising `#init`, a missing signature
+        # dir, a duplicate id, no/many registrations) with the file the gem loaded from, so the surfaced
+        # diagnostic names the exact plugin copy. A require that failed outright never populated the map for
+        # this gem, so the lookup is nil and the message is left unchanged.
+        e.resolved_path ||= @resolved_gem_paths[entry[:gem]]
+        raise
       end
 
       # ADR-25 — a plugin's manifest-declared `signature_paths:` are resolved (by
@@ -137,8 +214,13 @@ module Rigor
         end
       end
 
+      # #194 slice 2 (ADR-93 WD5) — a bundled plugin is required by its engine-anchored absolute path; every
+      # other gem keeps today's bare-name require. The injectable `requirer` seam therefore widens from gem
+      # names to name-or-absolute-path (both are valid arguments to `Kernel.require`). The slice-1
+      # `feature_resolver` is unaffected: an absolute-path require's `$LOADED_FEATURES` entry still ends in
+      # `/<gem>.rb`, the suffix {FEATURE_RESOLVER} matches.
       def require_gem!(entry)
-        @requirer.call(entry[:gem])
+        @requirer.call(self.class.bundled_plugin_path(entry[:gem]) || entry[:gem])
       rescue ::LoadError => e
         raise LoadError.new(
           "could not load plugin gem #{entry[:gem].inspect}: #{e.message}",

data/lib/rigor/plugin/node_rule_walk.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "node_context"
+require_relative "../source/node_children"
 require_relative "../source/node_walker"
 require_relative "../analysis/check_rules/rule_walk"
 
@@ -82,8 +83,9 @@ module Rigor
       # The single converged DFS pre-order traversal. Threads both the live `ancestors` stack (for plugin
       # {NodeContext}) and the immutable built-in {RuleWalk::Context} (for the collectors), derived together
       # as the walk descends — the cheap-ancestors option from the ADR-53 B4 design note. Identical pre-order
-      # over `compact_child_nodes` to both the legacy `Source::NodeWalker.each_with_ancestors` and
-      # `RuleWalk.walk`, so every node is visited in the same order each side saw before.
+      # over each node's children (`#rigor_each_child`, which yields `compact_child_nodes` order) to
+      # both the legacy `Source::NodeWalker.each_with_ancestors` and `RuleWalk.walk`, so every node is visited in
+      # the same order each side saw before.
       def walk_node(node, ancestors, context, path, scope, states, collector_driver)
         return unless node.is_a?(Prism::Node)
 
@@ -92,7 +94,7 @@ module Rigor
 
         child_context = collector_driver&.descend(node, context)
         ancestors.push(node)
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_node(child, ancestors, child_context, path, scope, states, collector_driver)
         end
         ancestors.pop

data/lib/rigor/plugin/registry.rb

@@ -37,7 +37,7 @@ module Rigor
       end
 
       def dynamic?(plugin) = @dynamic.include?(plugin)
-      def type_specifier?(plugin) = @type_specifier.include?(plugin)
+      def narrowing_facts?(plugin) = @narrowing_facts.include?(plugin)
 
       # O(1) "could any plugin contribute a return type for a call named `method_name`?" — false only when
       # every `dynamic_return` rule is `methods:`-gated on other names, in which case the ungated walk would
@@ -48,12 +48,12 @@ module Rigor
         @dynamic_global_gate.include?(method_name)
       end
 
-      # O(1) statement-path sibling of {#dispatch_candidate?} over the `type_specifier` rules (which are
+      # O(1) statement-path sibling of {#dispatch_candidate?} over the `narrowing_facts` rules (which are
       # always `methods:`-gated).
       def statement_candidate?(method_name)
-        return true if @type_specifier_global_gate.nil?
+        return true if @narrowing_facts_global_gate.nil?
 
-        @type_specifier_global_gate.include?(method_name)
+        @narrowing_facts_global_gate.include?(method_name)
       end
 
       # Per-plugin gate: false when the plugin declares no `dynamic_return` rules at all, or when every rule
@@ -67,11 +67,11 @@ module Rigor
         gate.nil? || gate.include?(method_name)
       end
 
-      # Per-plugin gate over `type_specifier` rules; same contract as {#dynamic_candidate_for?}.
-      def type_specifier_candidate_for?(plugin, method_name)
-        return false unless @type_specifier.include?(plugin)
+      # Per-plugin gate over `narrowing_facts` rules; same contract as {#dynamic_candidate_for?}.
+      def narrowing_facts_candidate_for?(plugin, method_name)
+        return false unless @narrowing_facts.include?(plugin)
 
-        gate = @type_specifier_gates[plugin]
+        gate = @narrowing_facts_gates[plugin]
         gate.nil? || gate.include?(method_name)
       end
 
@@ -101,13 +101,13 @@ module Rigor
       def compile_memberships(plugins)
         plugins.each { |p| reject_legacy_flow_hook!(p) }
         @dynamic = plugins.reject { |p| p.class.dynamic_returns.empty? }.to_set
-        @type_specifier = plugins.reject { |p| p.class.type_specifiers.empty? }.to_set
+        @narrowing_facts = plugins.reject { |p| p.class.narrowing_facts_rules.empty? }.to_set
         compile_collector_subsets(plugins)
       end
 
       def compile_collector_subsets(plugins)
         @for_method_dispatch = plugins.select { |p| @dynamic.include?(p) }.freeze
-        @for_statement = plugins.select { |p| @type_specifier.include?(p) }.freeze
+        @for_statement = plugins.select { |p| @narrowing_facts.include?(p) }.freeze
         @for_file_diagnostics =
           plugins.select { |p| file_diagnostics_overridden?(p) || !p.class.node_rules.empty? }.freeze
       end
@@ -115,9 +115,9 @@ module Rigor
       # The per-plugin and registry-global method-name gates.
       def compile_gates
         @dynamic_gates = build_name_gates(@dynamic) { |p| p.class.dynamic_returns }
-        @type_specifier_gates = build_name_gates(@type_specifier) { |p| p.class.type_specifiers }
+        @narrowing_facts_gates = build_name_gates(@narrowing_facts) { |p| p.class.narrowing_facts_rules }
         @dynamic_global_gate = union_gate(@dynamic_gates)
-        @type_specifier_global_gate = union_gate(@type_specifier_gates)
+        @narrowing_facts_global_gate = union_gate(@narrowing_facts_gates)
       end
 
       # ADR-52 WD3 — the legacy ungated `flow_contribution_for` hook was deleted pre-1.0. A plugin still
@@ -215,7 +215,7 @@ module Rigor
     # Ractor. The eventual Phase 4 pool ships `blueprints` across the boundary and calls {.materialize}
     # per-Ractor; the live `plugins` carriage on the coordinator registry stays unchanged.
     class Registry
-      attr_reader :plugins, :load_errors, :blueprints, :contribution_index
+      attr_reader :plugins, :load_errors, :blueprints, :contribution_index, :resolved_gem_paths
 
       # @param plugins [Array<Rigor::Plugin::Base>] instantiated plugin instances in deterministic order.
       # @param load_errors [Array<Rigor::Plugin::LoadError>] failures surfaced during loading. Each error is
@@ -223,20 +223,17 @@ module Rigor
       # @param blueprints [Array<Rigor::Plugin::Blueprint>] frozen, Ractor-shareable replay descriptors
       #   aligned 1:1 with `plugins`. The loader fills this in; callers that construct Registry manually MAY
       #   pass `[]` and accept that {.materialize} cannot replay the set.
-      def initialize(plugins: [], load_errors: [], blueprints: [])
+      # @param resolved_gem_paths [Hash{String=>String,nil}] #194 slice 1 — `gem name => resolved file path`
+      #   for each successfully required plugin gem, so `rigor plugins` can print where a loaded (and
+      #   possibly frozen) plugin actually loaded from. Defaults to empty; a worker registry built by
+      #   {.materialize} carries none (the provenance surface runs only on the coordinator).
+      def initialize(plugins: [], load_errors: [], blueprints: [], resolved_gem_paths: {})
         @plugins = plugins.dup.freeze
         @load_errors = load_errors.dup.freeze
         @blueprints = blueprints.dup.freeze
+        @resolved_gem_paths = resolved_gem_paths.dup.freeze
         @contribution_index = ContributionIndex.new(@plugins)
-        # ADR-52 WD1 — aggregate queries the engine issues per def / per diagnostic candidate / per path are
-        # compiled once here (the registry is frozen, so the flat_map-on-every-call versions re-derived an
-        # invariant). `@contracts_by_path` is a mutable per-path memo inside the frozen registry — safe
-        # because the contract set and the glob semantics are fixed for the lifetime of the run.
-        @additional_initializers = @plugins.flat_map { |p| safe_manifest(p)&.additional_initializers || [] }.freeze
-        @open_receivers = @plugins.flat_map { |p| (safe_manifest(p)&.open_receivers || []).map(&:to_s) }.uniq.freeze
-        @open_receivers_set = @open_receivers.to_set.freeze
-        @protocol_contracts = @plugins.flat_map { |p| safe_protocol_contracts(p) }.freeze
-        @contracts_by_path = {}
+        compile_aggregates
         # ADR-52 WD4 — the single engine-owned node-rule walk, compiled once per run from the node-rule
         # plugin subset (registry order). The runner reuses it for every file; it builds fresh per-file
         # state internally, so it is safe to freeze and share.
@@ -372,6 +369,18 @@ module Rigor
 
       private
 
+      # ADR-52 WD1 — aggregate queries the engine issues per def / per diagnostic candidate / per path are
+      # compiled once at construction (the registry is frozen, so the flat_map-on-every-call versions
+      # re-derived an invariant). `@contracts_by_path` is a mutable per-path memo inside the frozen registry
+      # — safe because the contract set and the glob semantics are fixed for the lifetime of the run.
+      def compile_aggregates
+        @additional_initializers = @plugins.flat_map { |p| safe_manifest(p)&.additional_initializers || [] }.freeze
+        @open_receivers = @plugins.flat_map { |p| (safe_manifest(p)&.open_receivers || []).map(&:to_s) }.uniq.freeze
+        @open_receivers_set = @open_receivers.to_set.freeze
+        @protocol_contracts = @plugins.flat_map { |p| safe_protocol_contracts(p) }.freeze
+        @contracts_by_path = {}
+      end
+
       def path_matches_glob?(glob, path)
         File.fnmatch?(glob, path, FNMATCH_FLAGS) ||
           File.fnmatch?(File.join("**", glob), path, FNMATCH_FLAGS)

data/lib/rigor/plugin.rb

@@ -19,6 +19,15 @@ require_relative "plugin/inflector"
 module Rigor
   module Plugin
     @registered = {}
+    # ADR-88 WD4b — process-global map `gem name (String) => [registered plugin id, ...]`, recorded by the
+    # loader the FIRST time a gem's `require` runs its body and registers plugins. A second in-process
+    # `Loader.load` of the same bare-string (`id:`-less) entry sees `require` return false (the gem is already
+    # loaded, so its `Rigor::Plugin.register` calls do not re-run) and an empty newly-registered delta — the
+    # loader recovers the gem's plugin id(s) from this memo instead of failing with "did not register any
+    # plugin". Populated by {.record_gem_registration}, read by {.ids_for_gem}. This is what makes a second
+    # in-process analysis (the `--verify-incremental` full-run oracle, the incremental session's subset
+    # re-analysis, the LSP's re-loads) load the same plugins the first run did.
+    @gem_registrations = {}
     @mutex = Mutex.new
 
     class << self
@@ -52,10 +61,27 @@ module Rigor
         @mutex.synchronize { @registered.dup.freeze }
       end
 
+      # ADR-88 WD4b — remember, for a gem loaded for the first time this process, the plugin id(s) its
+      # `require` registered. Idempotent (a repeated first-load records the same ids). See {@gem_registrations}.
+      def record_gem_registration(gem_name, ids)
+        return if gem_name.nil? || ids.nil? || ids.empty?
+
+        @mutex.synchronize { @gem_registrations[gem_name.to_s] = ids.map(&:to_s).freeze }
+        nil
+      end
+
+      # ADR-88 WD4b — the plugin id(s) `gem_name` registered on its first in-process load, or `[]` when the gem
+      # was never loaded this process. The loader consults this when a re-load's `require` no-ops and the
+      # newly-registered delta is empty, so a bare-string plugin entry still resolves on the second load.
+      def ids_for_gem(gem_name)
+        @mutex.synchronize { @gem_registrations[gem_name.to_s] } || []
+      end
+
       def unregister!(id = nil)
         @mutex.synchronize do
           if id.nil?
             @registered.clear
+            @gem_registrations.clear
           else
             @registered.delete(id.to_s)
           end

data/lib/rigor/protection/mutator.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../scope"
 require_relative "../inference/scope_indexer"
+require_relative "../source/node_children"
 
 module Rigor
   # ADR-63 Tier 2 — the productized subset of the dev-only mutation-testing harness (`tool/mutation/`, ADR-62).
@@ -111,7 +112,7 @@ module Rigor
         return if node.nil?
 
         blk.call(node)
-        node.compact_child_nodes.each { |child| walk(child, &blk) }
+        node.rigor_each_child { |child| walk(child, &blk) }
       end
 
       def collect(node, out)
@@ -136,7 +137,7 @@ module Rigor
             @anchor_for[arg] = [node.receiver, node.name.to_s] if literal?(arg)
           end
         end
-        node.compact_child_nodes.each { |child| index_literal_anchors(child) }
+        node.rigor_each_child { |child| index_literal_anchors(child) }
       end
 
       def literal?(node)

data/lib/rigor/reflection.rb

@@ -93,6 +93,11 @@ module Rigor
     # Returns the type of the named constant. Joins in-source constants (recorded by
     # `ScopeIndexer`) and RBS-side constants. In-source wins on collision because the user's
     # source is the authoritative declaration.
+    #
+    # This is the flat lookup keyed on the literal `constant_name`. Callers that need Ruby's
+    # lexical constant resolution (walking the enclosing class path, and folding in registry
+    # classes / source-discovered classes as `Singleton` / class types) use
+    # {.resolve_constant_type} instead.
     def constant_type_for(constant_name, scope: Scope.empty)
       key = constant_name.to_s
       in_source = scope.in_source_constants[key]
@@ -101,6 +106,65 @@ module Rigor
       scope.environment.constant_for_name(constant_name)
     end
 
+    # Resolves a constant *reference* to its type through Ruby's lexical constant lookup: the
+    # most-qualified candidate first (the enclosing class path joined to `name`), then
+    # progressively less-qualified, then the bare `name`. Each candidate consults, in order,
+    # the class registry (yielding a `Singleton[C]`), source-discovered classes, in-source
+    # value constants, and finally RBS-side constants — in-source value constants winning over
+    # RBS because the user's source is authoritative for its own constants. Returns the matched
+    # `Rigor::Type`, or nil when no source knows the constant.
+    #
+    # This is the shared owner of the lexical-constant resolution: `Inference::ExpressionTyper`
+    # reads it to type a constant read, and `Inference::Narrowing` reads it to recognise a
+    # value-pinned `Constant[Regexp]` match-predicate operand.
+    def resolve_constant_type(name, scope: Scope.empty)
+      env = scope.environment
+      discovered = scope.discovered_classes
+      in_source = scope.in_source_constants
+      lexical_constant_candidates(name, scope: scope).each do |candidate|
+        singleton = env.singleton_for_name(candidate)
+        return singleton if singleton
+
+        in_source_class = discovered[candidate]
+        return in_source_class if in_source_class
+
+        # In-source value-bearing constants take precedence over RBS constant decls because
+        # user code is the authoritative source for its own constants.
+        in_source_value = in_source[candidate]
+        return in_source_value if in_source_value
+
+        value = env.constant_for_name(candidate)
+        return value if value
+      end
+      nil
+    end
+
+    # The candidate qualified names to try, in Ruby's lexical order: most-qualified first (the
+    # enclosing class path joined to `name`), then progressively less-qualified, then the bare
+    # `name`. A top-level scope (no `self_type`) yields only `[name]`.
+    def lexical_constant_candidates(name, scope: Scope.empty)
+      prefix = enclosing_class_path(scope)
+      candidates = []
+      while prefix && !prefix.empty?
+        candidates << "#{prefix}::#{name}"
+        idx = prefix.rindex("::")
+        prefix = idx ? prefix[0, idx] : nil
+      end
+      candidates << name
+      candidates
+    end
+    private_class_method :lexical_constant_candidates
+
+    # Pulls the enclosing qualified class name out of `scope.self_type` when one is set.
+    # `Nominal[T]` and `Singleton[T]` both expose `class_name`. Returns nil at the top level.
+    def enclosing_class_path(scope)
+      st = scope.self_type
+      case st
+      when Type::Nominal, Type::Singleton then st.class_name
+      end
+    end
+    private_class_method :enclosing_class_path
+
     # Returns the RBS `RBS::Definition::Method` for the instance method, or nil when the
     # class or method is not in RBS. The source-side discovered-method facts are reachable
     # through {.discovered_method?}; a future slice will unify the two under a

data/lib/rigor/runtime/jit.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Rigor
+  # Process-level runtime concerns that sit beside the analyzer rather than
+  # inside it. Currently just deferred YJIT enablement.
+  module Runtime
+    # Deferred YJIT enablement for the long-running analysis commands.
+    #
+    # Ruby 3.3+ ships YJIT but leaves it off unless the process opts in
+    # (`--yjit`, `RUBY_YJIT_ENABLE=1`, or `RubyVM::YJIT.enable`). Enabling it
+    # unconditionally at boot is a net LOSS on short `rigor check` / `coverage`
+    # runs: the JIT compile cost is paid up front, but a run that finishes in a
+    # couple of seconds ends before it amortizes. Measured cold A/B (2026-07-13,
+    # Ruby 4.0.5): mastodon `app/models` 4.0s -> 5.0s (0.80x), kramdown `lib`
+    # 1.7s -> 2.55s (0.66x), dependabot 1.6s -> 2.34s (0.68x). Long runs win big
+    # in the same measurement: mastodon `app`+`lib` 25.2s -> 14.9s (1.69x),
+    # redmine `app/models` 8.6s -> 5.5s (1.56x). Allocations and diagnostics are
+    # byte-identical under YJIT — the tradeoff is purely wall-time.
+    #
+    # The resolution is to enable YJIT only once a run has proven long enough to
+    # amortize the compile cost. {enable_after} spawns one daemon thread that
+    # sleeps the deadline then enables: a run that finishes before the deadline
+    # never pays JIT compile (the sub-deadline penalty zone is avoided by
+    # construction), while a long run enables mid-flight and JITs the remaining
+    # — dominant — work. Long-lived servers (`rigor lsp` / `rigor mcp`) instead
+    # enable at boot via {enable_now}, since they always run long.
+    #
+    # Opt-out: `RIGOR_DISABLE_YJIT=1` makes every entry point a no-op (the pin
+    # the byte-identical-diagnostics gate uses). If YJIT is already enabled (the
+    # user passed `--yjit` / `RUBY_YJIT_ENABLE=1`) or is unavailable (a build
+    # without YJIT, or a non-MRI Ruby), both entry points are no-ops too.
+    module Jit
+      # Opt-out switch: `RIGOR_DISABLE_YJIT=1` disables both entry points.
+      DISABLE_ENV = "RIGOR_DISABLE_YJIT"
+
+      # Advanced / calibration override of the {enable_after} deadline, in
+      # float seconds. Unset (or unparseable / negative) falls back to
+      # {DEFAULT_DEADLINE_SECONDS}. Exposed so the deadline can be swept during
+      # calibration and tuned per-project without an engine change.
+      DEADLINE_ENV = "RIGOR_YJIT_DEADLINE"
+
+      # The amortization deadline for {enable_after}, in seconds.
+      #
+      # Calibrated by interleaved cold A/B measurement on 2026-07-13 (Ruby
+      # 4.0.5, arm64-darwin25). Enabling YJIT mid-run costs a ~1s compile burst,
+      # so a run whose length is only ~0-1s longer than the deadline pays the
+      # burst without time to amortize and LOSES (measured: `app/models` at a
+      # 3.0s deadline regressed 4.14s -> 4.68s). The short-run cases cluster at
+      # <=1.7s (kramdown / dependabot) and ~4.0-4.9s (mastodon `app/models` ~4.1s,
+      # mail ~4.9s), with the next case at redmine ~7s. 5.0s parks that danger
+      # zone in the empty 5-6s gap: every case <=4.9s finishes before the
+      # deadline fires (guaranteed no-YJIT parity — the sleeping thread is killed
+      # at exit), while runs long enough to pay off (>=~15s: gitlab, mastodon
+      # `app`+`lib`) enable mid-flight and JIT their dominant tail — the mastodon
+      # `app`+`lib` win is preserved ~100% (25.4s -> 15.1s, vs 15.1s always-on).
+      DEFAULT_DEADLINE_SECONDS = 5.0
+
+      module_function
+
+      # Enables YJIT now, unless opted out, already enabled, or unavailable.
+      #
+      # An imperative command, not a query — the boolean reports whether this
+      # call is what enabled YJIT (so the `?`-suffix predicate convention does
+      # not apply; hence the Naming/PredicateMethod exemption).
+      #
+      # @return [Boolean] true if this call enabled YJIT; false if it was a
+      #   no-op (unavailable / opted out / already enabled).
+      def enable_now # rubocop:disable Naming/PredicateMethod
+        return false unless available?
+        return false if disabled?
+        return false if RubyVM::YJIT.enabled?
+
+        RubyVM::YJIT.enable
+        true
+      end
+
+      # Spawns one background thread that sleeps `seconds` then calls
+      # {enable_now}. The thread is a daemon in effect — Ruby kills all live
+      # threads when the main thread exits — so a run that finishes before the
+      # deadline simply never enables YJIT, which is the point.
+      #
+      # Returns nil (and spawns no thread) when the feature is already a no-op
+      # up front (unavailable / opted out / already enabled), so callers never
+      # pay for a thread that could only no-op.
+      #
+      # @param seconds [Numeric] the amortization deadline.
+      # @return [Thread, nil] the deadline thread, or nil when no-op up front.
+      def enable_after(seconds)
+        return nil unless available?
+        return nil if disabled?
+        return nil if RubyVM::YJIT.enabled?
+
+        thread = Thread.new do
+          sleep(seconds)
+          enable_now
+        end
+        # A background perf optimization must never spill a backtrace onto the
+        # run's stderr; on any unexpected failure, stay silent and leave YJIT
+        # off. The deadline sleep gives ample time to set this before the body
+        # could raise.
+        thread.report_on_exception = false
+        thread
+      end
+
+      # The resolved {enable_after} deadline: {DEADLINE_ENV} when it parses to a
+      # non-negative float, else {DEFAULT_DEADLINE_SECONDS}.
+      #
+      # @return [Numeric]
+      def deadline_seconds
+        raw = ENV.fetch(DEADLINE_ENV, nil)
+        return DEFAULT_DEADLINE_SECONDS if raw.nil? || raw.empty?
+
+        value = Float(raw, exception: false)
+        value && value >= 0 ? value : DEFAULT_DEADLINE_SECONDS
+      end
+
+      # @return [Boolean] whether this Ruby exposes `RubyVM::YJIT.enable`.
+      def available?
+        defined?(RubyVM::YJIT.enable) ? true : false
+      end
+
+      # @return [Boolean] whether the opt-out env switch is set.
+      def disabled?
+        ENV[DISABLE_ENV] == "1"
+      end
+    end
+  end
+end

data/lib/rigor/scope/discovery_index.rb

@@ -21,13 +21,15 @@ module Rigor
       :discovered_def_nodes,
       :discovered_singleton_def_nodes,
       :discovered_def_sources,
+      :discovered_singleton_def_sources,
       :discovered_method_visibilities,
       :discovered_superclasses,
       :discovered_includes,
       :discovered_class_sources,
       :data_member_layouts,
       :struct_member_layouts,
-      :param_inferred_types
+      :param_inferred_types,
+      :run_generation
     )
 
     class DiscoveryIndex
@@ -48,6 +50,7 @@ module Rigor
         discovered_def_nodes: EMPTY_TABLE,
         discovered_singleton_def_nodes: EMPTY_TABLE,
         discovered_def_sources: EMPTY_TABLE,
+        discovered_singleton_def_sources: EMPTY_TABLE,
         discovered_method_visibilities: EMPTY_TABLE,
         discovered_superclasses: EMPTY_TABLE,
         discovered_includes: EMPTY_TABLE,
@@ -60,7 +63,14 @@ module Rigor
         # `{param_name(Symbol) => Rigor::Type}` map of the union of resolved call-site argument types. Empty on
         # every normal run; only the `coverage --protection` collection pass populates it today, so a `check` run
         # leaves it empty and seeds nothing (byte-identical).
-        param_inferred_types: EMPTY_TABLE
+        param_inferred_types: EMPTY_TABLE,
+        # ADR-84 WD2 — the run-scope identity token `Analysis::Runner#run_analysis` mints per run (a frozen
+        # bare Object) and seeds through `project_scope_seed_tables`. The user-method return memo keys its
+        # bucket on this token's identity so hits cross consumer-file boundaries within one run but never
+        # cross a run boundary (LSP / ADR-62 warm-loop re-runs land in a fresh bucket). Nil on scopes that
+        # never see the runner seed (single-file probes, `run_source` before the seed applies): the memo
+        # falls back to today's per-file `discovered_def_nodes` identity for those.
+        run_generation: nil
       )
     end
   end