rigortype 0.1.18 → 0.2.0

data/lib/rigor/configuration.rb

@@ -2,6 +2,7 @@
 
 require "yaml"
 
+require_relative "bleeding_edge"
 require_relative "configuration/dependencies"
 require_relative "configuration/severity_profile"
 
@@ -87,6 +88,15 @@ module Rigor
       },
       "severity_profile" => "balanced",
       "severity_overrides" => {},
+      # ADR-50 § WD2 — bleeding-edge overlay opt-in. Selects which of
+      # the *next major's* queued changes ({Rigor::BleedingEdge}) this
+      # project adopts early. Orthogonal to `severity_profile:`. Accepts
+      # `false` (default — adopt none), `true` (adopt the whole
+      # overlay), a list of feature ids (adopt only those), or
+      # `{ all: true, except: [ids] }` (adopt all but the named). The
+      # overlay is empty today, so every form is currently a no-op; it
+      # becomes live when the first discipline is queued for a major.
+      "bleeding_edge" => false,
       "dependencies" => {
         "source_inference" => [],
         "budget_per_gem" => Configuration::Dependencies::DEFAULT_BUDGET_PER_GEM
@@ -181,6 +191,7 @@ module Rigor
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
                 :severity_profile, :severity_overrides,
+                :bleeding_edge, :bleeding_edge_severity_overrides,
                 :dependencies, :parallel_workers,
                 :bundler_bundle_path, :bundler_auto_detect, :bundler_lockfile,
                 :rbs_collection_lockfile, :rbs_collection_auto_detect,
@@ -222,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)
@@ -317,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
@@ -355,6 +369,10 @@ module Rigor
       @severity_overrides = coerce_severity_overrides(
         data.fetch("severity_overrides", DEFAULTS.fetch("severity_overrides"))
       )
+      @bleeding_edge = coerce_bleeding_edge(
+        data.fetch("bleeding_edge", DEFAULTS.fetch("bleeding_edge"))
+      )
+      @bleeding_edge_severity_overrides = BleedingEdge.severity_overrides_for(@bleeding_edge)
       @dependencies = Dependencies.from_h(
         data.fetch("dependencies", DEFAULTS.fetch("dependencies"))
       )
@@ -383,7 +401,7 @@ module Rigor
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
-    def to_h # rubocop:disable Metrics/MethodLength
+    def to_h # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
       {
         "target_ruby" => target_ruby,
         "paths" => paths,
@@ -405,6 +423,7 @@ module Rigor
         },
         "severity_profile" => severity_profile.to_s,
         "severity_overrides" => severity_overrides.to_h { |k, v| [k, v.to_s] },
+        "bleeding_edge" => bleeding_edge_to_h,
         "dependencies" => dependencies.to_h,
         "parallel" => {
           "workers" => parallel_workers
@@ -421,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
@@ -483,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
@@ -566,5 +610,55 @@ module Rigor
         [k.to_s, sym]
       end.freeze
     end
+
+    # ADR-50 § WD2 — normalizes the `bleeding_edge:` selector to a
+    # canonical `{ "mode" => … }` hash (interpreted by
+    # {Rigor::BleedingEdge}). Validates *shape* only; membership against
+    # the overlay is intentionally NOT checked here (an unknown id stays
+    # inert, like an unknown `severity_overrides:` rule). Deep-frozen so
+    # the Configuration stays `Ractor.shareable?`.
+    def coerce_bleeding_edge(value)
+      case value
+      when nil, false then { "mode" => "none" }
+      when true then { "mode" => "all" }
+      when Array then { "mode" => "list", "ids" => freeze_ids(value) }
+      when Hash then coerce_bleeding_edge_hash(value)
+      else
+        raise ArgumentError,
+              "bleeding_edge must be true, false, a list of feature ids, " \
+              "or { all: true, except: [...] }, got #{value.inspect}"
+      end.freeze
+    end
+
+    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" => 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
+      case bleeding_edge["mode"]
+      when "all"
+        except = bleeding_edge["except"] || []
+        except.empty? || { "all" => true, "except" => except }
+      when "list" then bleeding_edge["ids"] || []
+      else false
+      end
+    end
   end
 end

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

@@ -88,6 +88,15 @@ module Rigor
           vendored_gem_sig_paths.each do |path|
             rbs_loader.add(path: path) if path.directory?
           end
+          # Rigor-owned core overlay — loaded LAST so an upstream
+          # declaration always wins on conflict; these reopenings only
+          # fill genuine holes (e.g. `Numeric#to_f`/`to_i`/`to_r`, which
+          # upstream RBS declares on the concrete subclasses but not on
+          # the abstract `Numeric` that Rigor's arithmetic-chain widening
+          # produces).
+          core_overlay_sig_paths.each do |path|
+            rbs_loader.add(path: path) if path.directory?
+          end
           env = RBS::Environment.from_loader(rbs_loader)
           add_virtual_rbs(env, virtual_rbs)
           synthesize_missing_namespaces(env)
@@ -298,6 +307,22 @@ module Rigor
         ).freeze
         private_constant :VENDORED_GEM_SIGS_ROOT
 
+        # Rigor-owned core-overlay RBS (`data/core_overlay/`). Reopens
+        # Ruby core classes to add methods upstream `ruby/rbs` omits but
+        # which every concrete value answers at runtime — loaded last so
+        # upstream always wins on conflict. Public so the cache descriptor
+        # can digest these files into the env-blob key.
+        CORE_OVERLAY_SIGS_ROOT = File.expand_path(
+          "../../../data/core_overlay",
+          __dir__
+        ).freeze
+
+        def core_overlay_sig_paths
+          return [] unless File.directory?(CORE_OVERLAY_SIGS_ROOT)
+
+          [Pathname(CORE_OVERLAY_SIGS_ROOT)]
+        end
+
         def vendored_gem_sig_paths
           return [] unless File.directory?(VENDORED_GEM_SIGS_ROOT)
 
@@ -338,11 +363,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
@@ -618,6 +643,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
@@ -1009,6 +1057,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)
@@ -1020,6 +1070,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)
@@ -1027,6 +1079,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.
@@ -123,6 +125,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
@@ -453,11 +456,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 +507,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`