rigortype 0.1.5 → 0.1.6

data/lib/rigor/cli/type_of_command.rb

@@ -3,6 +3,7 @@
 require "optionparser"
 require "prism"
 
+require_relative "../analysis/buffer_binding"
 require_relative "../configuration"
 require_relative "../environment"
 require_relative "../scope"
@@ -38,35 +39,73 @@ module Rigor
       # @return [Integer] CLI exit status.
       def run
         options = parse_options
+        buffer = resolve_buffer_binding(options)
+        return CLI::EXIT_USAGE if buffer == :usage_error
 
         target = parse_position_argument(@argv)
         return CLI::EXIT_USAGE if target.nil?
 
-        execute(target: target, options: options)
+        execute(target: target, options: options, buffer: buffer)
       end
 
       private
 
       def parse_options
-        options = { format: "text", trace: false, config: nil }
+        options = { format: "text", trace: false, config: nil, tmp_file: nil, instead_of: nil }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
           opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
           opts.on("--trace", "Record fail-soft fallbacks via FallbackTracer") { options[:trace] = true }
           opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          opts.on("--tmp-file=PATH",
+                  "Editor mode: read source bytes from PATH instead of --instead-of (paired)") do |value|
+            options[:tmp_file] = value
+          end
+          opts.on("--instead-of=PATH",
+                  "Editor mode: the logical project path the buffer represents (paired with --tmp-file)") do |value|
+            options[:instead_of] = value
+          end
         end
         parser.parse!(@argv)
 
         options
       end
 
-      def execute(target:, options:)
+      # Mirrors `Rigor::CLI#resolve_buffer_binding` (the `check`
+      # path). Returns nil / BufferBinding / :usage_error. The
+      # symbol return path lets the caller translate to
+      # `CLI::EXIT_USAGE` without raising.
+      def resolve_buffer_binding(options)
+        tmp = options[:tmp_file]
+        instead = options[:instead_of]
+        return nil if tmp.nil? && instead.nil?
+
+        if tmp.nil? || instead.nil?
+          @err.puts("--tmp-file and --instead-of must appear together")
+          return :usage_error
+        end
+
+        unless File.file?(tmp)
+          @err.puts("--tmp-file #{tmp.inspect}: no such file or not readable")
+          return :usage_error
+        end
+
+        Rigor::Analysis::BufferBinding.new(logical_path: instead, physical_path: tmp)
+      end
+
+      def execute(target:, options:, buffer: nil)
         file, line, column = target
-        return 1 unless file_exists?(file)
+        # Under editor mode the logical `file` may not exist on disk
+        # (user editing a new file); the runtime check is only that
+        # the BUFFER is readable, which `resolve_buffer_binding`
+        # has already enforced. For non-editor mode `file` must
+        # exist.
+        physical = buffer ? buffer.resolve(file) : file
+        return 1 unless file_exists?(buffer ? physical : file)
 
         configuration = Configuration.load(options.fetch(:config))
-        source = File.read(file)
+        source = File.read(physical)
         parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
         return 1 if parse_errors?(parse_result, file)
 

data/lib/rigor/cli.rb

@@ -25,7 +25,8 @@ module Rigor
       "type-scan" => :run_type_scan,
       "explain" => :run_explain,
       "diff" => :run_diff,
-      "sig-gen" => :run_sig_gen
+      "sig-gen" => :run_sig_gen,
+      "lsp" => :run_lsp
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -69,24 +70,22 @@ module Rigor
 
     def run_check
       require_relative "analysis/runner"
+      require_relative "analysis/buffer_binding"
       require_relative "cache/store"
 
       options = parse_check_options
+      buffer = resolve_buffer_binding(options)
+      return EXIT_USAGE if buffer == :usage_error
 
       configuration = Configuration.load(options.fetch(:config))
       cache_root = configuration.cache_path
       handle_clear_cache(cache_root) if options.fetch(:clear_cache)
-      cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
 
-      paths = @argv.empty? ? configuration.paths : @argv
-      runner = Analysis::Runner.new(
-        configuration: configuration,
-        explain: options.fetch(:explain),
-        cache_store: cache_store,
-        collect_stats: options.fetch(:stats),
-        workers: resolve_workers(options, configuration)
+      runner = build_check_runner(
+        configuration: configuration, options: options,
+        buffer: buffer, cache_root: cache_root
       )
-      result = runner.run(paths)
+      result = runner.run(@argv.empty? ? configuration.paths : @argv)
 
       write_result(result, options.fetch(:format))
       write_run_stats(result.stats) if result.stats
@@ -94,6 +93,49 @@ module Rigor
       result.success? ? 0 : 1
     end
 
+    def build_check_runner(configuration:, options:, buffer:, cache_root:)
+      cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
+      Analysis::Runner.new(
+        configuration: configuration,
+        explain: options.fetch(:explain),
+        cache_store: cache_store,
+        collect_stats: options.fetch(:stats),
+        workers: resolve_workers(options, configuration),
+        buffer: buffer
+      )
+    end
+
+    # Editor-mode CLI envelope. The `--tmp-file=PATH` /
+    # `--instead-of=PATH` pair binds an in-flight buffer file to
+    # the logical project path it represents (see
+    # `docs/design/20260516-editor-mode.md`). Both flags must
+    # appear together; either alone is a usage error. The
+    # physical file must be readable; missing-file is a usage
+    # error too so editors get one consistent failure shape.
+    #
+    # Returns:
+    # - `nil` when neither flag was supplied (legacy path).
+    # - `Rigor::Analysis::BufferBinding` when the pair is valid.
+    # - `:usage_error` after writing one diagnostic to stderr;
+    #   the caller MUST translate this to `EXIT_USAGE`.
+    def resolve_buffer_binding(options)
+      tmp = options[:tmp_file]
+      instead = options[:instead_of]
+      return nil if tmp.nil? && instead.nil?
+
+      if tmp.nil? || instead.nil?
+        @err.puts("--tmp-file and --instead-of must appear together")
+        return :usage_error
+      end
+
+      unless File.file?(tmp)
+        @err.puts("--tmp-file #{tmp.inspect}: no such file or not readable")
+        return :usage_error
+      end
+
+      Analysis::BufferBinding.new(logical_path: instead, physical_path: tmp)
+    end
+
     # ADR-15 Phase 4c — resolves the worker count by
     # precedence: CLI `--workers=N` (most explicit) > env
     # `RIGOR_RACTOR_WORKERS` > config `.rigor.yml`
@@ -112,7 +154,7 @@ module Rigor
       configuration.parallel_workers
     end
 
-    def parse_check_options
+    def parse_check_options # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
       options = {
         # `nil` triggers `Configuration.discover` (`.rigor.yml` then
         # `.rigor.dist.yml`); an explicit `--config=PATH` overrides.
@@ -133,7 +175,12 @@ module Rigor
         # `RIGOR_RACTOR_WORKERS` then `.rigor.yml`
         # `parallel.workers:` then 0 (sequential). See
         # `resolve_workers` for the precedence chain.
-        workers: nil
+        workers: nil,
+        # Editor mode (`docs/design/20260516-editor-mode.md`).
+        # Both must appear together; the runner uses the pair
+        # to bind an in-flight buffer file to its logical path.
+        tmp_file: nil,
+        instead_of: nil
       }
       parser = OptionParser.new do |opts|
         opts.banner = "Usage: rigor check [options] [paths]"
@@ -151,6 +198,14 @@ module Rigor
                 "Dispatch per-file analysis across N Ractor workers (default: 0; sequential)") do |value|
           options[:workers] = value
         end
+        opts.on("--tmp-file=PATH",
+                "Editor mode: read source bytes from PATH instead of --instead-of (paired)") do |value|
+          options[:tmp_file] = value
+        end
+        opts.on("--instead-of=PATH",
+                "Editor mode: the logical project path the buffer represents (paired with --tmp-file)") do |value|
+          options[:instead_of] = value
+        end
       end
       parser.parse!(@argv)
       options
@@ -336,6 +391,12 @@ module Rigor
       SigGenCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_lsp
+      require_relative "cli/lsp_command"
+
+      LspCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"
@@ -376,6 +437,7 @@ module Rigor
           explain    Print the description of one or all CheckRules
           diff       Compare current diagnostics to a saved baseline JSON
           sig-gen    Emit RBS skeletons inferred from .rb sources (ADR-14)
+          lsp        Run the Rigor Language Server (LSP) over stdio
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/configuration.rb

@@ -49,6 +49,16 @@ module Rigor
       "disable" => [],
       "libraries" => [],
       "signature_paths" => nil,
+      # ADR-17 — project-side monkey-patch pre-evaluation.
+      # Empty by default; users opt in by listing explicit files
+      # that the analyzer walks before per-file inference so
+      # patched-method declarations are visible across the
+      # project (e.g. `lib/core_ext/string_extensions.rb`). Slice 1
+      # plumbing only — listed files are validated at config-load
+      # time (`pre-eval.file-not-found` on a missing path), but
+      # the dispatcher tier consuming the registry lands in
+      # slice 2.
+      "pre_eval" => [],
       "fold_platform_specific_paths" => false,
       "cache" => {
         "path" => ".rigor/cache"
@@ -145,7 +155,7 @@ module Rigor
     # MUST be resolved relative to the config file's directory.
     # `exclude:` is intentionally NOT in this list — its entries
     # are glob patterns (`**/vendor/**`), not paths.
-    PATH_KEYS = %w[paths signature_paths].freeze
+    PATH_KEYS = %w[paths signature_paths pre_eval].freeze
     private_constant :PATH_KEYS
 
     attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :disabled_rules,
@@ -155,7 +165,8 @@ module Rigor
                 :severity_profile, :severity_overrides,
                 :dependencies, :parallel_workers,
                 :bundler_bundle_path, :bundler_auto_detect, :bundler_lockfile,
-                :rbs_collection_lockfile, :rbs_collection_auto_detect
+                :rbs_collection_lockfile, :rbs_collection_auto_detect,
+                :pre_eval
 
     # Loads a configuration file.
     #
@@ -307,6 +318,9 @@ module Rigor
       @libraries = Array(data.fetch("libraries", DEFAULTS.fetch("libraries"))).map(&:to_s).freeze
       sig_paths = data.fetch("signature_paths", DEFAULTS.fetch("signature_paths"))
       @signature_paths = sig_paths.nil? ? nil : Array(sig_paths).map(&:to_s).freeze
+      @pre_eval = expand_pre_eval_entries(
+        Array(data.fetch("pre_eval", DEFAULTS.fetch("pre_eval"))).map(&:to_s)
+      )
       @fold_platform_specific_paths = data.fetch(
         "fold_platform_specific_paths", DEFAULTS.fetch("fold_platform_specific_paths")
       ) == true
@@ -357,6 +371,7 @@ module Rigor
         "disable" => disabled_rules,
         "libraries" => libraries,
         "signature_paths" => signature_paths,
+        "pre_eval" => pre_eval,
         "fold_platform_specific_paths" => fold_platform_specific_paths,
         "cache" => {
           "path" => cache_path
@@ -386,6 +401,27 @@ module Rigor
 
     private
 
+    # ADR-17 slice 4 — `pre_eval:` glob expansion. Each entry is
+    # accepted as either a literal path (slice 1 contract) OR a
+    # `File.fnmatch?`-shaped glob pattern (`lib/core_ext/**/*.rb`).
+    # Glob meta characters (`*`, `?`, `[`) trigger `Dir.glob`
+    # expansion; the resulting file list is folded into the
+    # `pre_eval:` set with `uniq`. Literal entries that don't
+    # exist on disk continue to surface as `pre-eval.file-not-found`
+    # `:error` (slice 1 behaviour); glob entries that match
+    # nothing degrade silently to "no contribution from this
+    # entry" so a templated `**` pattern in a fresh project
+    # doesn't generate an error per match-less pattern.
+    def expand_pre_eval_entries(entries)
+      entries.flat_map do |entry|
+        glob_pattern?(entry) ? Dir.glob(entry, sort: true) : [entry]
+      end.uniq.freeze
+    end
+
+    def glob_pattern?(path)
+      path.include?("*") || path.include?("?") || path.include?("[")
+    end
+
     # Accepts either `"rigor-foo"` (gem-name shorthand) or
     # `{ "gem" => "rigor-foo", "id" => "foo", "config" => {...} }`
     # (full form). Returns the canonical hash form so the loader

data/lib/rigor/environment/hkt_registry_holder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # ADR-20 slice 2e — mutable single-slot memoization
+    # container for the per-Environment HKT registry. Held by
+    # {Environment} so the otherwise-frozen instance can
+    # still cache a computed value on first access.
+    #
+    # Concurrent {#fetch} calls from multiple threads against
+    # one Environment are NOT serialised here — the LSP
+    # single-publish-at-a-time discipline and the Ractor
+    # pool's per-worker Environment shape already prevent
+    # cross-thread races. If a future caller introduces a
+    # multi-threaded reader path against a shared
+    # Environment, the synchronisation belongs at that
+    # caller's seam, not here.
+    class HktRegistryHolder
+      def initialize
+        @loaded = false
+        @value = nil
+      end
+
+      def fetch
+        return @value if @loaded
+
+        @value = yield
+        @loaded = true
+        @value
+      end
+    end
+  end
+end

data/lib/rigor/environment/rbs_coverage_report.rb

@@ -42,7 +42,7 @@ 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", "idn-ruby", "mysql2", "nokogiri", "pg", "redis"
+        "bcrypt", "idn-ruby", "mysql2", "nokogiri", "pg", "prism", "redis"
       ].freeze
 
       # @param locked_gems [Hash{String => LockfileResolver::LockedGem}]

data/lib/rigor/environment/rbs_loader.rb

@@ -83,7 +83,7 @@ module Rigor
         VENDORED_GEM_SIGS_ROOT = File.expand_path(
           "../../../data/vendored_gem_sigs",
           __dir__
-        )
+        ).freeze
         private_constant :VENDORED_GEM_SIGS_ROOT
 
         def vendored_gem_sig_paths
@@ -118,7 +118,20 @@ module Rigor
         @libraries = libraries.map(&:to_s).freeze
         @signature_paths = signature_paths.map { |p| Pathname(p) }.freeze
         @cache_store = cache_store
-        @state = { env: nil, builder: nil }
+        # Per-loader memoization bucket. Held as a single
+        # mutable Hash so the loader instance itself can be
+        # `.freeze`d (per ADR-15 reflection-facade contract)
+        # without losing the lazy-memo behaviour. Slot names
+        # currently consulted: `:env`, `:env_loaded`,
+        # `:env_build_warned`, `:builder`, `:reflection`,
+        # `:instance_definitions_table`,
+        # `:singleton_definitions_table`. Constructed via
+        # `Hash.new` (NOT a `{ ... }` literal) so Rigor's
+        # `HashShape` narrowing doesn't infer a fixed key set
+        # from the initial state and fold post-initial slot
+        # reads (e.g. `@state[:env_loaded]`) to a constant
+        # `nil`.
+        @state = Hash.new # rubocop:disable Style/EmptyLiteral
         @instance_definition_cache = {}
         @singleton_definition_cache = {}
         @class_known_cache = {}
@@ -165,6 +178,36 @@ module Rigor
         # v0.0.9 cache `Cache::Descriptor` regression did.
       end
 
+      # ADR-20 slice 2e — iterates over every `%a{...}`
+      # annotation attached to a class- or module-level
+      # declaration in the loaded RBS environment, yielding
+      # `(annotation_string, source_location)` pairs. Used by
+      # {Rigor::Inference::HktRegistry.scan_rbs_loader} to
+      # find `rigor:v1:hkt_register` / `rigor:v1:hkt_define`
+      # directives in user-authored overlays and merge them
+      # into the per-`Environment` HKT registry. Yields nothing
+      # when the env failed to build (fail-soft, same shape as
+      # {#each_known_class_name}).
+      def each_class_decl_annotation
+        return enum_for(:each_class_decl_annotation) unless block_given?
+        return if env.nil?
+
+        env.class_decls.each_value do |entry|
+          entry.each_decl do |decl|
+            next unless decl.respond_to?(:annotations)
+
+            decl.annotations.each { |a| yield a.string, a.location }
+          end
+        end
+      rescue ::RBS::BaseError, ::Ractor::IsolationError
+        # fail-soft: matches each_known_class_name's policy.
+        # Ractor::IsolationError surfaces when the scan is
+        # invoked from a non-main Ractor pool worker before
+        # ADR-15's full deep-freeze migration completes — the
+        # worker falls back to the base (builtins-only)
+        # registry rather than crashing.
+      end
+
       # Returns a frozen `Hash<String, String>` mapping each loaded
       # class / module name (top-level prefixed) to the file path of
       # its FIRST declaration's RBS source. Used by

data/lib/rigor/environment/reporters.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Mutable container for the per-run analysis reporters
+    # ({Rigor::RbsExtended::Reporter} and
+    # {Rigor::Analysis::DependencySourceInference::BoundaryCrossReporter}).
+    # Held by {Environment} as a single attr; the reporters can be
+    # swapped through {Environment#attach_reporters!} so long-lived
+    # integrations (the LSP `ProjectContext`, future editor-mode
+    # daemons) can share one Environment across many `Runner.run`
+    # calls without each call's diagnostic events accumulating into
+    # a single reporter pair.
+    #
+    # Per-publish reset is the contract: at the start of every
+    # `Runner.run` in sequential mode, the runner stamps the
+    # environment's `Reporters` slot with the runner's own
+    # freshly-built reporter pair. Dispatchers / `RbsExtended`
+    # consumers continue to write through
+    # `environment.rbs_extended_reporter` /
+    # `environment.boundary_cross_reporter` — the lookup just hops
+    # through the `Reporters` slot rather than reading a frozen
+    # ivar.
+    #
+    # Construction default is `nil` on both slots so existing
+    # callers that don't care about reporters (project-default
+    # `Environment.default`, test scopes that don't drive
+    # dispatch) keep their current behaviour: reporter lookups
+    # return nil, and the consumer sites short-circuit on
+    # `reporter.nil?`.
+    class Reporters
+      attr_accessor :rbs_extended, :boundary_cross
+
+      def initialize(rbs_extended: nil, boundary_cross: nil)
+        @rbs_extended = rbs_extended
+        @boundary_cross = boundary_cross
+      end
+    end
+  end
+end

data/lib/rigor/environment.rb

@@ -3,11 +3,16 @@
 require_relative "environment/class_registry"
 require_relative "environment/rbs_loader"
 require_relative "environment/reflection"
+require_relative "environment/reporters"
+require_relative "environment/hkt_registry_holder"
 require_relative "environment/bundle_sig_discovery"
 require_relative "environment/lockfile_resolver"
 require_relative "environment/rbs_collection_discovery"
 require_relative "environment/rbs_coverage_report"
 require_relative "inference/synthetic_method_index"
+require_relative "inference/project_patched_methods"
+require_relative "inference/hkt_registry"
+require_relative "builtins/hkt_builtins"
 require_relative "type_node/name_scope"
 require_relative "type_node/resolver_chain"
 
@@ -57,8 +62,8 @@ module Rigor
     ].freeze
 
     attr_reader :class_registry, :rbs_loader, :plugin_registry, :dependency_source_index,
-                :rbs_extended_reporter, :boundary_cross_reporter, :name_scope,
-                :synthetic_method_index
+                :reporters, :name_scope,
+                :synthetic_method_index, :project_patched_methods
 
     # @param class_registry [Rigor::Environment::ClassRegistry]
     # @param rbs_loader [Rigor::Environment::RbsLoader, nil] when nil the
@@ -79,24 +84,105 @@ module Rigor
     #   sources the dispatcher consults BELOW RBS dispatch.
     #   When nil (the default), no dep-source contribution
     #   participates and the dispatcher tier is a no-op.
-    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil,
+    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil, # rubocop:disable Metrics/ParameterLists
                    plugin_registry: nil, dependency_source_index: nil,
                    rbs_extended_reporter: nil, boundary_cross_reporter: nil,
-                   synthetic_method_index: nil)
+                   synthetic_method_index: nil, project_patched_methods: nil,
+                   hkt_registry: nil)
       @class_registry = class_registry
       @rbs_loader = rbs_loader
       @plugin_registry = plugin_registry
       @dependency_source_index = dependency_source_index
-      @rbs_extended_reporter = rbs_extended_reporter
-      @boundary_cross_reporter = boundary_cross_reporter
+      # ADR-pending — reporters live in a mutable container so
+      # long-lived integrations (LSP `ProjectContext`) can swap
+      # them per `Runner.run` without rebuilding the env. The
+      # existing `#rbs_extended_reporter` / `#boundary_cross_reporter`
+      # accessors below preserve the public lookup shape.
+      @reporters = Reporters.new(
+        rbs_extended: rbs_extended_reporter,
+        boundary_cross: boundary_cross_reporter
+      )
       @synthetic_method_index = synthetic_method_index || Inference::SyntheticMethodIndex::EMPTY
+      @project_patched_methods = project_patched_methods || Inference::ProjectPatchedMethods::EMPTY
+      # ADR-20 slice 2c + 2e — the per-env HKT registry
+      # consulted by the reducer when resolving `Type::App`
+      # carriers. Defaults to {Inference::HktRegistry::EMPTY};
+      # the {.default} / {.for_project} class methods seed it
+      # with the bundled builtins (`json::value`, …) plus any
+      # `%a{rigor:v1:hkt_register / hkt_define}` annotations
+      # the RBS loader exposes. The hkt_registry getter
+      # (defined below) MEMOIZES the result of merging the
+      # base with the RBS scan so the scan is paid at most
+      # once per Environment lifetime — and only when first
+      # consulted, leaving fast paths like `rigor check
+      # --cache-stats --no-stats` from doing the RBS env
+      # build at all.
+      @hkt_registry_base = hkt_registry || Inference::HktRegistry::EMPTY
+      @hkt_registry_holder = HktRegistryHolder.new
       @name_scope = build_name_scope
       freeze
     end
 
+    # ADR-20 slices 2e + 6 — lazy HKT registry getter.
+    # Merge order on first call: builtins (base) ← plugin
+    # manifest aggregation ← RBS env scan. Last-write-wins on
+    # URI collisions so user-authored `.rbs` overlays beat
+    # plugin entries, which beat the bundled JSON_VALUE.
+    # Memoised; single-threaded use only (under the Ractor
+    # pool path each worker has its own Environment so
+    # cross-worker mutation is impossible; the LSP
+    # single-publish-at-a-time invariant serialises here).
+    def hkt_registry
+      @hkt_registry_holder.fetch do
+        with_plugin_overlay = if @plugin_registry.respond_to?(:hkt_overlay_registry)
+                                @hkt_registry_base.merge(@plugin_registry.hkt_overlay_registry)
+                              else
+                                @hkt_registry_base
+                              end
+        Inference::HktRegistry.scan_rbs_loader(
+          @rbs_loader,
+          base: with_plugin_overlay,
+          reporter: rbs_extended_reporter
+        )
+      end
+    end
+
+    # Backwards-compatible reporter accessors — every existing
+    # consumer (rbs_extended, method_dispatcher) calls these. The
+    # frozen `@reporters` container is mutable for slot reassignment
+    # via {#attach_reporters!} below.
+    def rbs_extended_reporter
+      @reporters.rbs_extended
+    end
+
+    def boundary_cross_reporter
+      @reporters.boundary_cross
+    end
+
+    # Replaces the env's per-run reporter slots. Intended for
+    # long-lived integrations (LSP `ProjectContext`) that share one
+    # Environment instance across many `Runner.run` calls: each call
+    # attaches its own fresh reporter pair so per-call diagnostic
+    # events stay scoped to that call rather than accumulating
+    # across publishes.
+    #
+    # Single-threaded use only. Concurrent publishes against one
+    # Environment must serialise — the LSP `Server` debouncer +
+    # synchronized writer already enforces this for the editor
+    # path. The Ractor pool path builds a per-worker Environment
+    # and does not reach this surface.
+    def attach_reporters!(rbs_extended_reporter:, boundary_cross_reporter:)
+      @reporters.rbs_extended = rbs_extended_reporter
+      @reporters.boundary_cross = boundary_cross_reporter
+      nil
+    end
+
     class << self
       def default
-        @default ||= new(rbs_loader: RbsLoader.default).freeze
+        @default ||= new(
+          rbs_loader: RbsLoader.default,
+          hkt_registry: Builtins::HktBuiltins.registry
+        ).freeze
       end
 
       # Builds an Environment that consults the project's local
@@ -127,7 +213,7 @@ module Rigor
                       bundler_bundle_path: nil, bundler_auto_detect: false,
                       bundler_lockfile: nil,
                       rbs_collection_lockfile: nil, rbs_collection_auto_detect: false,
-                      synthetic_method_index: nil)
+                      synthetic_method_index: nil, project_patched_methods: nil)
         resolved_paths = signature_paths || default_signature_paths(root)
         # O4 MVP — append per-gem `sig/` directories discovered
         # under the target project's bundler install root. Empty
@@ -173,13 +259,24 @@ module Rigor
           signature_paths: loader_signature_paths,
           cache_store: cache_store
         )
+        # ADR-20 slice 2c + 2e — seed hkt_registry with the
+        # bundled builtins. The Environment's `#hkt_registry`
+        # getter then LAZILY merges in the RBS env scan on
+        # first call so fast paths that don't consult HKT
+        # (e.g. `rigor check --cache-stats --no-stats`) don't
+        # pay the eager env-build cost up front. URI
+        # collisions let the user-authored overlay win over
+        # the bundled builtin (last-write-wins per ADR-20
+        # OQ3 tentative).
         new(
           rbs_loader: loader,
           plugin_registry: plugin_registry,
           dependency_source_index: dependency_source_index,
           rbs_extended_reporter: rbs_extended_reporter,
           boundary_cross_reporter: boundary_cross_reporter,
-          synthetic_method_index: synthetic_method_index
+          synthetic_method_index: synthetic_method_index,
+          project_patched_methods: project_patched_methods,
+          hkt_registry: Builtins::HktBuiltins.registry
         )
       end
       # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists