rigortype 0.1.18 → 0.2.0

data/lib/rigor/analysis/runner.rb

@@ -58,11 +58,10 @@ module Rigor
       #   slices route real producers through it.
       # @param workers [Integer] ADR-15 Phase 4b — when greater
       #   than zero, per-file analysis dispatches across a pool of
-      #   N Ractor workers built around {WorkerSession}. Default
-      #   `0` keeps the sequential code path bit-for-bit
-      #   unchanged. Phase 4c will wire the CLI / `.rigor.yml`
-      #   surface that produces non-zero values; this slice
-      #   leaves the parameter as a programmatic opt-in only.
+      #   N workers. Default `0` keeps the sequential code path
+      #   bit-for-bit unchanged. Controlled via the
+      #   `RIGOR_RACTOR_WORKERS` env var or `.rigor.yml`
+      #   `parallel.workers:` (Phase 4c, fully wired).
       # @param collect_stats [Boolean] when true (default), `#run`
       #   builds a {RunStats} summary exposed via `result.stats`
       #   — this forces the RBS env build at end-of-run so the
@@ -155,6 +154,7 @@ module Rigor
         @cached_plugin_prepare_diagnostics = [].freeze
         @project_discovered_classes = {}.freeze
         @project_discovered_def_nodes = {}.freeze
+        @project_discovered_singleton_def_nodes = {}.freeze
         @project_discovered_def_sources = {}.freeze
         @project_discovered_superclasses = {}.freeze
         @project_discovered_includes = {}.freeze
@@ -162,6 +162,7 @@ module Rigor
         @project_discovered_method_visibilities = {}.freeze
         @project_discovered_methods = {}.freeze
         @project_data_member_layouts = {}.freeze
+        @project_struct_member_layouts = {}.freeze
         build_collaborators
       end
 
@@ -457,7 +458,7 @@ module Rigor
       # discovery tables at their frozen-empty constructor defaults
       # (the bundle carries `nil` for them, matching the original
       # adopt path that never touched them).
-      def apply_pre_passes_result(result)
+      def apply_pre_passes_result(result) # rubocop:disable Metrics/AbcSize
         @plugin_registry = result.plugin_registry
         @dependency_source_index = result.dependency_source_index
         @cached_plugin_prepare_diagnostics = result.cached_plugin_prepare_diagnostics
@@ -466,6 +467,9 @@ module Rigor
         @pre_eval_diagnostics_from_scanner = result.pre_eval_diagnostics_from_scanner
         @project_discovered_classes = result.discovered_classes if result.discovered_classes
         @project_discovered_def_nodes = result.discovered_def_nodes if result.discovered_def_nodes
+        if result.discovered_singleton_def_nodes
+          @project_discovered_singleton_def_nodes = result.discovered_singleton_def_nodes
+        end
         @project_discovered_def_sources = result.discovered_def_sources if result.discovered_def_sources
         @project_discovered_superclasses = result.discovered_superclasses if result.discovered_superclasses
         @project_discovered_includes = result.discovered_includes if result.discovered_includes
@@ -475,6 +479,7 @@ module Rigor
         end
         @project_discovered_methods = result.discovered_methods if result.discovered_methods
         @project_data_member_layouts = result.data_member_layouts if result.data_member_layouts
+        @project_struct_member_layouts = result.struct_member_layouts if result.struct_member_layouts
       end
       private :run_project_pre_passes, :adopt_prebuilt_project_scan, :apply_pre_passes_result
 
@@ -636,30 +641,44 @@ module Rigor
       # `#diagnostics_for_file` or declared a `node_rule` are visited
       # (`contribution_index.for_file_diagnostics`); a skipped plugin's
       # two hooks could only have returned `[]`.
-      def plugin_emitted_diagnostics(path, root, scope)
+      def plugin_emitted_diagnostics(path, root, scope, node_results)
         return [] if @plugin_registry.empty?
 
-        # ADR-52 WD4 — one engine-owned AST walk per file dispatches each
-        # node to every matching (plugin, rule); the per-plugin results
-        # are bucketed in registry order so emission stays plugin-major
-        # (byte-identical with the old per-plugin walk).
-        node_results = node_rule_results_by_plugin(path, root, scope)
-
         @plugin_registry.contribution_index.for_file_diagnostics.flat_map do |plugin|
           collect_plugin_diagnostics(plugin, path, root, scope, node_results[plugin])
         end
       end
 
-      def node_rule_results_by_plugin(path, root, scope)
+      # ADR-52 WD4 + ADR-53 B4 — one engine-owned AST walk per file
+      # dispatches each node to every matching (plugin, rule) AND drives
+      # the built-in node collectors (`node_collectors`), so the file is
+      # walked once for both. The per-plugin results are bucketed in
+      # registry order so plugin emission stays plugin-major
+      # (byte-identical with the old per-plugin walk); the collectors are
+      # populated in place for `diagnose` to consume.
+      #
+      # When no plugin declares a node rule, the walk still runs to drive
+      # the collectors (the converged path replaces the standalone
+      # `RuleWalk.run`); `node_collectors` nil means a caller that does
+      # not need built-in collection from this walk.
+      def node_rule_results_by_plugin(path, root, scope, node_collectors, scope_index)
         walk = @plugin_registry.node_rule_walk
-        return {}.compare_by_identity if walk.empty?
+        driver = node_collectors && CheckRules.node_collector_driver(node_collectors)
+        return {}.compare_by_identity if walk.empty? && driver.nil?
 
-        results = walk.diagnostics_for_file(path: path, scope: scope, root: root)
+        results = walk.diagnostics_for_file(
+          path: path, scope: scope, root: root, collector_driver: driver
+        )
+        CheckRules.shadow_verify_converged_collectors(path, root, scope_index, node_collectors) if shadow_rule_walk?
         results.each_with_object({}.compare_by_identity) do |result, by_plugin|
           by_plugin[result.plugin] = result
         end
       end
 
+      def shadow_rule_walk?
+        ENV.fetch("RIGOR_SHADOW_RULE_WALK", nil)
+      end
+
       def collect_plugin_diagnostics(plugin, path, root, scope, node_result)
         raw = Array(plugin.diagnostics_for_file(path: path, scope: scope, root: root))
         # A node-rule context/rule raise isolates the whole plugin's
@@ -807,6 +826,9 @@ module Rigor
         tables = {}
         tables[:discovered_classes] = @project_discovered_classes unless @project_discovered_classes.empty?
         tables[:discovered_def_nodes] = @project_discovered_def_nodes unless @project_discovered_def_nodes.empty?
+        unless @project_discovered_singleton_def_nodes.empty?
+          tables[:discovered_singleton_def_nodes] = @project_discovered_singleton_def_nodes
+        end
         tables[:discovered_def_sources] = @project_discovered_def_sources unless @project_discovered_def_sources.empty?
         unless @project_discovered_superclasses.empty?
           tables[:discovered_superclasses] = @project_discovered_superclasses
@@ -816,7 +838,7 @@ module Rigor
           tables[:discovered_method_visibilities] = @project_discovered_method_visibilities
         end
         tables[:discovered_methods] = @project_discovered_methods unless @project_discovered_methods.empty?
-        tables[:data_member_layouts] = @project_data_member_layouts unless @project_data_member_layouts.empty?
+        seed_member_layout_tables(tables)
         # ADR-46 slice 1 — the class-declaration source map is read only by
         # the ancestry accessors during dependency recording, so seed it
         # only when recording is on; a normal run never carries it.
@@ -826,6 +848,16 @@ module Rigor
         tables
       end
 
+      # ADR-48 — seed the Data + Struct member-layout tables (each only when
+      # non-empty). Extracted to keep {#project_scope_seed_tables} under the
+      # complexity budget.
+      def seed_member_layout_tables(tables)
+        tables[:data_member_layouts] = @project_data_member_layouts unless @project_data_member_layouts.empty?
+        return if @project_struct_member_layouts.empty?
+
+        tables[:struct_member_layouts] = @project_struct_member_layouts
+      end
+
       # ADR-46 slice 1 — when dependency recording is enabled, wrap the
       # per-file analysis so the cross-file reads its inference makes are
       # captured into `file_dependencies[path]`. Off by default: a normal
@@ -861,15 +893,8 @@ module Rigor
         self_call_record = with_self_call_recording(path) do
           index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
         end
-        diagnostics = CheckRules.diagnose(
-          path: path,
-          root: parse_result.value,
-          scope_index: index,
-          self_call_misses: self_call_record ? self_call_record.calls : [],
-          comments: parse_result.comments,
-          disabled_rules: @configuration.disabled_rules
-        )
-        diagnostics += plugin_emitted_diagnostics(path, parse_result.value, scope)
+        self_call_misses = self_call_record ? self_call_record.calls : []
+        diagnostics = rule_and_plugin_diagnostics(path, parse_result, scope, index, self_call_misses)
         diagnostics + explain_diagnostics(path, parse_result.value, scope)
       rescue Errno::ENOENT => e
         [
@@ -893,6 +918,28 @@ module Rigor
         ]
       end
 
+      # ADR-53 B4 — the built-in node collectors and the plugin node rules
+      # share ONE traversal of the file. The collectors are built here (they
+      # need the completed `index`) and populated by the converged plugin
+      # walk; `node_results` carries the per-plugin node-rule output. Both
+      # the built-in `diagnose` output and the plugin diagnostics are then
+      # built from that single walk's results.
+      def rule_and_plugin_diagnostics(path, parse_result, scope, index, self_call_misses)
+        root = parse_result.value
+        node_collectors = CheckRules.build_node_collectors(path, index)
+        node_results = node_rule_results_by_plugin(path, root, scope, node_collectors, index)
+        diagnostics = CheckRules.diagnose(
+          path: path,
+          root: root,
+          scope_index: index,
+          self_call_misses: self_call_misses,
+          comments: parse_result.comments,
+          disabled_rules: @configuration.disabled_rules,
+          node_collectors: node_collectors
+        )
+        diagnostics + plugin_emitted_diagnostics(path, root, scope, node_results)
+      end
+
       # ADR-24 slice 4a — runs `block` (the typing pass) with the self-call
       # recorder active when either the test-only `record_self_calls:` flag is
       # set or the `call.self-undefined-method` rule resolves to a firing
@@ -928,7 +975,8 @@ module Rigor
           else
             Configuration::SeverityProfile.resolve(
               rule: rule, authored_severity: :warning,
-              profile: @configuration.severity_profile, overrides: @configuration.severity_overrides
+              profile: @configuration.severity_profile, overrides: @configuration.severity_overrides,
+              bleeding_edge_overrides: @configuration.bleeding_edge_severity_overrides
             ) != :off
           end
       end

data/lib/rigor/analysis/self_call_resolution_recorder.rb

@@ -21,10 +21,9 @@ module Rigor
     # reach the recorder. This module is the ADR-46 / ADR-47 "collect at
     # evaluation time, never recompute" lesson applied to self-calls.
     #
-    # A later slice consumes the recorded misses behind a confidently-
-    # closed-class gate to emit `call.self-undefined-method`, behind its
-    # own external-corpus false-positive gate. This slice (4a) lands the
-    # plumbing OFF by default — {active?} is false on a normal run, so the
+    # ADR-24 slice 4 (`call.self-undefined-method`) consumes the recorded
+    # misses behind a confidently-closed-class gate (see `CheckRules` L775).
+    # The rule ships `:off` by default — {active?} is false on a normal run, so the
     # instrumented choke-point pays a single integer read and records
     # nothing. Recording is purely observational; it never changes a
     # diagnostic.

data/lib/rigor/analysis/worker_session.rb

@@ -21,21 +21,19 @@ module Rigor
   module Analysis
     # ADR-15 Phase 4a — per-worker analysis substrate.
     # [ADR-15](../../../docs/adr/15-ractor-concurrency.md)
-    # § Phase 4 carves the eventual Ractor-isolated worker pool
-    # into three sub-phases; this is the substrate that 4b will
-    # wrap in `Ractor.new` and 4c will gate behind
-    # `RIGOR_RACTOR_WORKERS`. NO Ractor in the loop yet — 4a
-    # exists so the per-worker ownership boundary is testable in
-    # the absence of any Ractor coordination.
+    # § Phase 4 carves the Ractor-isolated worker pool into sub-phases;
+    # 4a/4b/4c all landed, but the Ractor pool (4b) is blocked by Ruby
+    # Bug #22075 (UAF) — the active pool backend is fork (ADR-15 Amendment).
+    # This class exists so the per-worker ownership boundary is testable
+    # independently of any pool coordinator.
     #
     # The constructor takes only `Ractor.shareable?` inputs:
     #
     # - `configuration` — Phase 2a ({Rigor::Configuration} is
     #   `Ractor.shareable?`).
-    # - `cache_store` — frozen-shareable handle is NOT a precondition;
-    #   future 4b workers build their OWN Store at the shared
-    #   `cache_root` directory. 4a accepts an already-built Store
-    #   for the no-Ractor coordinator path.
+    # - `cache_store` — the fork backend passes the parent runner's
+    #   pre-built Store (`cache_store: @cache_store` in PoolCoordinator);
+    #   workers share it rather than building their own at `cache_root`.
     # - `plugin_blueprints` — Phase 3a
     #   (`Array<Plugin::Blueprint>` is `Ractor.shareable?`).
     # - `explain` — Boolean.
@@ -175,14 +173,18 @@ module Rigor
 
         scope = seed_project_scope(Scope.empty(environment: @environment, source_path: path))
         index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
+        # ADR-53 B4 — built-in collectors + plugin node rules share one walk.
+        node_collectors = CheckRules.build_node_collectors(path, index)
+        node_results = node_rule_results_by_plugin(path, parse_result.value, scope, node_collectors, index)
         diagnostics = CheckRules.diagnose(
           path: path,
           root: parse_result.value,
           scope_index: index,
           comments: parse_result.comments,
-          disabled_rules: @configuration.disabled_rules
+          disabled_rules: @configuration.disabled_rules,
+          node_collectors: node_collectors
         )
-        diagnostics += plugin_emitted_diagnostics(path, parse_result.value, scope)
+        diagnostics += plugin_emitted_diagnostics(path, parse_result.value, scope, node_results)
         diagnostics + explain_diagnostics(path, parse_result.value, scope)
       rescue Errno::ENOENT => e
         [analyzer_error(path, e.message)]
@@ -230,11 +232,9 @@ module Rigor
         Prism.parse(File.read(physical), filepath: path, version: @configuration.target_ruby)
       end
 
-      # Mirrors {Runner#build_trust_policy}. Workers under Phase
-      # 4b will need the same trust derivation, and the
-      # configuration is already shareable, so deriving it inside
+      # Mirrors {Runner#build_trust_policy}. Deriving trust inside
       # the session keeps the substrate decoupled from the
-      # coordinator's helper.
+      # coordinator; configuration is already Ractor-shareable.
       def build_trust_policy
         trusted_gems = @configuration.plugins.map { |entry| trusted_gem_name(entry) }.uniq
         roots = [Dir.pwd]
@@ -294,24 +294,30 @@ module Rigor
         )
       end
 
-      def plugin_emitted_diagnostics(path, root, scope)
+      def plugin_emitted_diagnostics(path, root, scope, node_results)
         return [] if @plugin_registry.empty?
 
-        # ADR-52 WD4 — single engine-owned node-rule walk per file; the
-        # results are bucketed per plugin (registry order) so emission
-        # stays plugin-major and byte-identical with the per-plugin walk.
-        node_results = node_rule_results_by_plugin(path, root, scope)
-
         @plugin_registry.plugins.flat_map do |plugin|
           collect_plugin_diagnostics(plugin, path, root, scope, node_results[plugin])
         end
       end
 
-      def node_rule_results_by_plugin(path, root, scope)
+      # ADR-52 WD4 + ADR-53 B4 — single engine-owned walk per file drives
+      # both the plugin node rules (bucketed per plugin in registry order,
+      # plugin-major emission) and the built-in node collectors
+      # (`node_collectors`, populated in place). Runs even with no node-rule
+      # plugins so the collectors still get driven (converged path).
+      def node_rule_results_by_plugin(path, root, scope, node_collectors, scope_index)
         walk = @plugin_registry.node_rule_walk
-        return {}.compare_by_identity if walk.empty?
+        driver = node_collectors && CheckRules.node_collector_driver(node_collectors)
+        return {}.compare_by_identity if walk.empty? && driver.nil?
 
-        results = walk.diagnostics_for_file(path: path, scope: scope, root: root)
+        results = walk.diagnostics_for_file(
+          path: path, scope: scope, root: root, collector_driver: driver
+        )
+        if ENV["RIGOR_SHADOW_RULE_WALK"]
+          CheckRules.shadow_verify_converged_collectors(path, root, scope_index, node_collectors)
+        end
         results.each_with_object({}.compare_by_identity) do |result, by_plugin|
           by_plugin[result.plugin] = result
         end

data/lib/rigor/bleeding_edge.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Rigor
+  # ADR-50 § WD2 — the bleeding-edge overlay.
+  #
+  # A Rigor-maintained set of the *next major's* queued changes —
+  # severity-map promotions and new-discipline rule enablements — that a
+  # user can adopt early, before they become default-on at a major
+  # (ADR-50 § WD7). It is orthogonal to `severity_profile:` (how loud
+  # *today's* rules are) and is versioned with the gem, NOT a
+  # user-supplied file: the inspectable counterpart to PHPStan's
+  # `bleedingEdge` include.
+  #
+  # The overlay is **empty today** — no discipline has yet been queued
+  # for the next major. This module is the WD2 *foundation* (the v0.1.19
+  # slice): the surface (`bleeding_edge:` config, the
+  # `rigor show-bleedingedge` command, the severity-composition hook in
+  # {Configuration::SeverityProfile.resolve}) exists and is wired
+  # end-to-end, so the first real feature lands as a single {FEATURES}
+  # entry with no engine plumbing.
+  #
+  # Each feature carries a **stable feature id** — part of the ADR-50
+  # WD1 contract vocabulary: the config, the `show` command, and the
+  # eventual CHANGELOG migration note all name the same id, and a
+  # feature graduates to default-on at a major by being removed from
+  # {FEATURES}.
+  module BleedingEdge
+    # One queued change.
+    #
+    # @!attribute id
+    #   @return [String] the stable feature id (contract vocabulary).
+    # @!attribute summary
+    #   @return [String] a one-line description of what it changes.
+    # @!attribute severity_overrides
+    #   @return [Hash{String => Symbol}] canonical rule id → the
+    #     severity this feature imposes. Composed *below* the user's own
+    #     `severity_overrides:` and *above* the active `severity_profile`
+    #     (see {Configuration::SeverityProfile.resolve}).
+    Feature = Data.define(:id, :summary, :severity_overrides) do
+      def to_h
+        {
+          "id" => id,
+          "summary" => summary,
+          "severity_overrides" => severity_overrides.transform_values(&:to_s)
+        }
+      end
+    end
+
+    # The overlay. Empty until the first next-major discipline is
+    # queued; add a {Feature} here (with a stable id) when one is.
+    FEATURES = [].freeze
+
+    module_function
+
+    # @return [Array<Feature>] the whole overlay.
+    def features
+      FEATURES
+    end
+
+    # @return [Array<String>] every feature id in the overlay.
+    def feature_ids
+      FEATURES.map(&:id)
+    end
+
+    # @param id [String]
+    # @return [Feature, nil]
+    def feature(id)
+      FEATURES.find { |f| f.id == id }
+    end
+
+    # Resolves a normalized `bleeding_edge:` selector (see
+    # {Configuration#bleeding_edge}) to the active {Feature} list.
+    # Unknown ids in a `list` / `except` selector are simply absent from
+    # the overlay and contribute nothing — symmetric with how
+    # `severity_overrides:` keeps an unknown rule id inert until it
+    # lands (robust across gem versions).
+    #
+    # @param selector [Hash] `{ "mode" => "none" }`,
+    #   `{ "mode" => "all" }`, `{ "mode" => "all", "except" => [ids] }`,
+    #   or `{ "mode" => "list", "ids" => [ids] }`.
+    # @return [Array<Feature>]
+    def active_features(selector)
+      case selector["mode"]
+      when "all"
+        except = selector["except"] || []
+        FEATURES.reject { |f| except.include?(f.id) }
+      when "list"
+        ids = selector["ids"] || []
+        FEATURES.select { |f| ids.include?(f.id) }
+      else
+        []
+      end
+    end
+
+    # The merged severity-override map the active features impose for a
+    # selector. Frozen so the result is `Ractor.shareable?`.
+    #
+    # @param selector [Hash] see {#active_features}.
+    # @return [Hash{String => Symbol}]
+    def severity_overrides_for(selector)
+      active_features(selector).each_with_object({}) do |feature, acc|
+        acc.merge!(feature.severity_overrides)
+      end.freeze
+    end
+
+    # Feature ids named by a selector that are NOT in the overlay
+    # (typo / graduated / from a newer gem). Surfaced by
+    # `rigor show-bleedingedge` as a hint; never an error.
+    #
+    # @param selector [Hash] see {#active_features}.
+    # @return [Array<String>]
+    def unknown_selected_ids(selector)
+      named =
+        case selector["mode"]
+        when "list" then selector["ids"] || []
+        when "all"  then selector["except"] || []
+        else []
+        end
+      known = feature_ids
+      named.reject { |id| known.include?(id) }
+    end
+  end
+end

data/lib/rigor/builtins/predefined_constant_refinements.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Builtins
+    # Refined types for predefined Ruby / stdlib constants whose upstream
+    # RBS signatures are broader than the constants' documented runtime
+    # invariants.
+    #
+    # Resolution is two-tiered:
+    #
+    # **Tier 1 — exact-value whitelist** (`FOLDED_CONSTANTS`):
+    # Constants whose value is bit-for-bit identical across every Ruby
+    # version and platform are folded to `Constant[T]`: the `Math::PI`
+    # / `Math::E` math constants (C's `M_PI` / `M_E`) and the four
+    # IEEE 754 binary64 magnitude constants `Float::INFINITY` /
+    # `::MAX` / `::MIN` / `::EPSILON` (each a single format-mandated bit
+    # pattern). Add new entries only when the value is truly
+    # cross-implementation invariant AND compares reflexively under
+    # `==` — the latter is why `Float::NAN` is deliberately EXCLUDED:
+    # `NaN == NaN` is `false`, so a `Constant[NAN]` would violate the
+    # `Type::Constant` `==` / `eql?` / `hash` contract (it would hash
+    # equal to itself yet compare unequal), corrupting type-equality
+    # and union dedup. The binary64 *integer* shape parameters
+    # (`Float::DIG` / `MANT_DIG` / `MAX_EXP` / …) are intentionally NOT
+    # folded: upstream RBS hedges them as "Usually defaults to …", and
+    # as plain `Integer`s they fall through Tier 2 to the RBS type
+    # harmlessly. `Complex::I` is deferred (no complex-fold consumer).
+    #
+    # **Tier 2 — runtime String inspection**:
+    # For any other constant, the module resolves it via `const_get`
+    # against the analyzer's own Ruby runtime.  Core / stdlib constants
+    # (e.g. `RUBY_VERSION`, `RUBY_PLATFORM`) are always loaded into the
+    # analyzer process; project-defined constants are not (they live only
+    # in ASTs), so their `const_get` raises `NameError` and the lookup
+    # falls through to the RBS type tier.
+    #
+    # For a successfully resolved `String` value:
+    # - empty string  → no refinement (fall through to RBS `String`)
+    # - a Ruby numeric literal  → `numeric-string`
+    # - non-empty otherwise  → `non-empty-string`
+    #
+    # **Exclusion set** (`RUNTIME_INSPECTION_EXCLUDED`):
+    # String constants that appear non-empty in the current runtime but
+    # are documented to be potentially empty in some build configuration
+    # or alternative implementation.  Exclusions are populated by
+    # scanning Ruby's C source (version.c, etc.) and RBS comments for
+    # any constant whose documentation says "may be empty" or
+    # "platform-specific default".  None are known today; the set
+    # exists as a safety net.
+    #
+    # This module is consulted by `Environment#constant_for_name` BEFORE
+    # the RBS constant-type table (widest types) but AFTER in-source
+    # constant writes (the user's own `Math::PI = 0.0` takes precedence
+    # via the lexical-candidate walk in `ExpressionTyper`).
+    module PredefinedConstantRefinements
+      # --- tier 1 -------------------------------------------------------
+
+      # Exact-value fold whitelist.  Keys are unqualified constant paths
+      # (no leading "::") matching what `Environment#constant_for_name`
+      # receives.
+      FOLDED_CONSTANTS = {
+        # Math module — IEEE 754 bit-identical across all MRI / JRuby /
+        # TruffleRuby builds; folding enables precise constant arithmetic.
+        "Math::PI" => Type::Combinator.constant_of(::Math::PI).freeze,
+        "Math::E" => Type::Combinator.constant_of(::Math::E).freeze,
+
+        # Float magnitude limits — each a single format-mandated IEEE 754
+        # binary64 bit pattern (`+Inf`, `DBL_MAX`, `DBL_MIN`,
+        # `DBL_EPSILON`), reflexive under `==`. `Float::NAN` is excluded
+        # (non-reflexive `==` — see the module-level note).
+        "Float::INFINITY" => Type::Combinator.constant_of(::Float::INFINITY).freeze,
+        "Float::MAX" => Type::Combinator.constant_of(::Float::MAX).freeze,
+        "Float::MIN" => Type::Combinator.constant_of(::Float::MIN).freeze,
+        "Float::EPSILON" => Type::Combinator.constant_of(::Float::EPSILON).freeze
+      }.freeze
+      private_constant :FOLDED_CONSTANTS
+
+      # --- tier 2 -------------------------------------------------------
+
+      # String constants whose runtime value is non-empty in the current
+      # Ruby but that should NOT be narrowed because they are documented
+      # to be potentially empty in some build or implementation.
+      #
+      # Methodology: grep Ruby's version.c and similar C sources, and the
+      # RBS comment corpus, for any constant annotated with "may be empty"
+      # or "platform-specific default".  Add the full qualified path
+      # (without leading "::") when a genuine risk is found.
+      RUNTIME_INSPECTION_EXCLUDED = Set[].freeze
+      private_constant :RUNTIME_INSPECTION_EXCLUDED
+
+      NON_EMPTY_STRING = Type::Combinator.non_empty_string.freeze
+      NUMERIC_STRING   = Type::Combinator.numeric_string.freeze
+      private_constant :NON_EMPTY_STRING, :NUMERIC_STRING
+
+      # --- public API ---------------------------------------------------
+
+      # @param name [String] unqualified constant name (e.g. `"Math::PI"`,
+      #   `"RUBY_VERSION"`, `"Ruby::ENGINE"`)
+      # @return [Rigor::Type, nil] refined type, or nil to fall through
+      def self.lookup(name)
+        FOLDED_CONSTANTS[name] || inspect_runtime_string(name)
+      end
+
+      # --- private ------------------------------------------------------
+
+      # Resolves `name` via `const_get` in the analyzer's runtime and
+      # returns a refined String carrier, or nil.
+      def self.inspect_runtime_string(name)
+        return nil if RUNTIME_INSPECTION_EXCLUDED.include?(name)
+
+        mod = ::Object
+        name.split("::").each do |part|
+          # Resolve only constants already present — never let analysing a
+          # reference drive the analyzer's own runtime to autoload or run a
+          # `const_missing` hook. A `Digest::UUID` reference in project code
+          # otherwise makes `const_get` trigger `Digest.const_missing` →
+          # `require "digest/uuid"`, and a missing optional library raises
+          # `LoadError` (a `ScriptError`, not the `NameError` the const_get
+          # walk expects), which would abort the whole run rather than fall
+          # through to the RBS tier. `const_defined?(part, false)` answers
+          # the same "is this resolvable here" question without the side
+          # effect — a project-defined constant (the common case) is simply
+          # absent and returns nil, no exception raised.
+          return nil unless mod.is_a?(::Module) && mod.const_defined?(part, false)
+
+          mod = mod.const_get(part, false)
+        end
+
+        return nil unless mod.is_a?(::String) && !mod.empty?
+
+        classify_string(mod)
+      rescue ::NameError, ::TypeError, ::LoadError
+        nil
+      end
+      private_class_method :inspect_runtime_string
+
+      # @param value [String] a non-empty string
+      # @return [Rigor::Type]
+      def self.classify_string(value)
+        if Type::Refined.ruby_numeric_literal?(value)
+          NUMERIC_STRING
+        else
+          NON_EMPTY_STRING
+        end
+      end
+      private_class_method :classify_string
+    end
+  end
+end