rigortype 0.1.4 → 0.1.6

data/lib/rigor/analysis/runner.rb

@@ -11,11 +11,17 @@ require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "../inference/coverage_scanner"
 require_relative "../inference/scope_indexer"
+require_relative "../inference/synthetic_method_scanner"
+require_relative "../inference/project_patched_scanner"
 require_relative "../inference/method_dispatcher/file_folding"
+require_relative "buffer_binding"
 require_relative "check_rules"
 require_relative "dependency_source_inference"
 require_relative "diagnostic"
+require_relative "project_scan"
 require_relative "result"
+require_relative "run_stats"
+require_relative "worker_session"
 
 module Rigor
   module Analysis
@@ -35,19 +41,77 @@ module Rigor
       #   run; the CLI's `--no-cache` flag wires `nil` through.
       #   v0.0.9 group A slice 1 introduces the surface; later
       #   slices route real producers through it.
-      def initialize(configuration:, explain: false,
+      # @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.
+      # @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
+      #   `class_decl_paths` snapshot has real source attribution.
+      #   Set to false to skip the stats summary entirely; the
+      #   CLI's `--no-stats` threads `false` through to keep
+      #   trivial-fixture runs from warming `.rigor/cache`.
+      # @param prebuilt [Rigor::Analysis::ProjectScan, nil] when
+      #   supplied, the runner adopts the pre-built plugin
+      #   registry / dependency-source index / scanner outputs
+      #   from the snapshot and skips the per-call pre-passes
+      #   that produce them. Used by long-lived integrations
+      #   (`Rigor::LanguageServer::ProjectContext`) to keep
+      #   per-buffer requests fast — scanners walk the project
+      #   once per generation rather than once per request, and
+      #   plugin `#prepare` runs once per generation rather than
+      #   once per request. Watched-file invalidation is the
+      #   owner's responsibility; the runner trusts the snapshot
+      #   it was given.
+      # @param environment [Rigor::Environment, nil] opt-in
+      #   Environment override. When supplied, sequential mode uses
+      #   the provided env instance in `#analyze_files` instead of
+      #   building a fresh one via `Environment.for_project`, and
+      #   attaches the runner's per-run reporter pair onto the
+      #   env's mutable `Reporters` slot via
+      #   `Environment#attach_reporters!`. Long-lived consumers
+      #   (LSP `ProjectContext`) pass a shared env so per-publish
+      #   work doesn't repeat the `Environment.for_project` build
+      #   (bundler / lockfile / collection discovery, RbsLoader
+      #   construction). Pool mode ignores the override — each
+      #   worker continues to build its own Environment.
+      def initialize(configuration:, explain: false, # rubocop:disable Metrics/ParameterLists
                      cache_store: Cache::Store.new(root: DEFAULT_CACHE_ROOT),
-                     plugin_requirer: nil)
+                     plugin_requirer: nil, workers: 0, collect_stats: true,
+                     buffer: nil, prebuilt: nil, environment: nil)
         @configuration = configuration
         @explain = explain
-        @cache_store = cache_store
+        @cache_store = enforce_read_only_cache(cache_store, buffer)
         @plugin_requirer = plugin_requirer
+        @workers = workers
+        @collect_stats = collect_stats
+        @buffer = buffer
+        @prebuilt = prebuilt
+        @environment_override = environment
         @plugin_registry = Plugin::Registry::EMPTY
         @dependency_source_index = DependencySourceInference::Index::EMPTY
         @rbs_extended_reporter = RbsExtended::Reporter.new
         @boundary_cross_reporter = DependencySourceInference::BoundaryCrossReporter.new
+        # `#run` resets these for each invocation; pre-seed them to
+        # empty containers so `build_run_stats` / `pre_file_diagnostics`
+        # (private, called only from `#run`) can read them without
+        # nil-guards.
+        @class_decl_paths_snapshot = {}.freeze
+        @signature_paths_snapshot = [].freeze
+        @cached_plugin_prepare_diagnostics = [].freeze
+        @project_discovered_classes = {}.freeze
       end
 
+      # ADR-pending editor mode — present when the runner is wired
+      # for the `--tmp-file` / `--instead-of` buffer-binding shape
+      # (`docs/design/20260516-editor-mode.md`). Nil for normal
+      # project runs.
+      attr_reader :buffer
+
       # Walks every Ruby file under `paths`, parses it, builds a
       # per-node scope index through
       # `Rigor::Inference::ScopeIndexer`, and runs the
@@ -60,29 +124,189 @@ module Rigor
         Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths =
           @configuration.fold_platform_specific_paths
 
+        wall_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         target_ruby_error = validate_target_ruby
         return Result.new(diagnostics: [target_ruby_error]) if target_ruby_error
 
-        @plugin_registry = load_plugins
-        @dependency_source_index = DependencySourceInference::Builder.build(@configuration.dependencies)
-        environment = Environment.for_project(
-          libraries: @configuration.libraries,
-          signature_paths: @configuration.signature_paths,
-          cache_store: @cache_store,
-          plugin_registry: @plugin_registry,
-          dependency_source_index: @dependency_source_index,
-          rbs_extended_reporter: @rbs_extended_reporter,
-          boundary_cross_reporter: @boundary_cross_reporter
-        )
         expansion = expand_paths(paths)
+        @class_decl_paths_snapshot = {}.freeze
+        @signature_paths_snapshot = []
+
+        if @prebuilt
+          adopt_prebuilt_project_scan(@prebuilt)
+        else
+          run_project_pre_passes(expansion: expansion)
+        end
 
         diagnostics = pre_file_diagnostics(expansion)
-        diagnostics += expansion.fetch(:files).flat_map { |path| analyze_file(path, environment) }
+        diagnostics += analyze_files(target_files(expansion))
         diagnostics += rbs_extended_reporter_diagnostics
         diagnostics += boundary_cross_diagnostics
 
-        Result.new(diagnostics: apply_severity_profile(diagnostics))
+        Result.new(
+          diagnostics: apply_severity_profile(diagnostics),
+          stats: @collect_stats ? build_run_stats(wall_started_at: wall_started_at, expansion: expansion) : nil
+        )
+      end
+
+      # Runs every project-wide pre-pass (`load_plugins` +
+      # `plugin#prepare` + dependency-source builder +
+      # synthetic-method scanner + project-patched scanner)
+      # exactly once, then returns a frozen
+      # {Rigor::Analysis::ProjectScan} snapshot.
+      #
+      # Long-lived integrations (`Rigor::LanguageServer::ProjectContext`)
+      # call this once per project-state generation and feed the
+      # snapshot back into `Runner.new(prebuilt: scan)` for every
+      # subsequent per-buffer publish. The cold pre-pass cost is
+      # paid once per generation rather than once per keystroke.
+      #
+      # Notes for callers:
+      # - The runner this method is called on may be a "build only"
+      #   instance — `@buffer` is typically nil so the scanners
+      #   observe on-disk bytes for the full project. Callers that
+      #   want pre-passes to see a particular buffer's edits should
+      #   build the runner WITH `buffer:` set.
+      # - The returned ProjectScan is frozen and shareable; the
+      #   underlying `plugin_registry` is the same object that ran
+      #   `#prepare`, so the per-plugin `services.fact_store` is
+      #   already populated for subsequent dispatch use.
+      def prepare_project_scan(paths: @configuration.paths)
+        expansion = expand_paths(paths)
+        run_project_pre_passes(expansion: expansion)
+        ProjectScan.new(
+          plugin_registry: @plugin_registry,
+          dependency_source_index: @dependency_source_index,
+          synthetic_method_index: @synthetic_method_index,
+          project_patched_methods: @project_patched_methods,
+          plugin_prepare_diagnostics: @cached_plugin_prepare_diagnostics.dup.freeze,
+          pre_eval_diagnostics: @pre_eval_diagnostics_from_scanner.dup.freeze
+        )
+      end
+
+      # Internal: drives every project-wide pre-pass and stores
+      # the results on instance variables in the order the
+      # downstream `#run` body expects. Extracted so
+      # `#prepare_project_scan` and the prebuilt-less `#run` path
+      # share one implementation.
+      def run_project_pre_passes(expansion:)
+        @plugin_registry = load_plugins
+        @dependency_source_index = DependencySourceInference::Builder.build(@configuration.dependencies)
+        # ADR-18 slice 3 — plugin prepare MUST run before the
+        # synthetic-method scanner so cross-plugin facts
+        # (`:dry_type_aliases` etc.) are already published when
+        # the scanner resolves Tier C `returns_from_arg:`
+        # lookups. The diagnostics produced by prepare are
+        # captured here so `pre_file_diagnostics` can re-emit
+        # them in the existing order without invoking prepare
+        # twice. Pool mode still re-runs prepare per worker
+        # (workers don't see this early invocation), preserving
+        # the existing Phase 4b contract.
+        @cached_plugin_prepare_diagnostics =
+          pool_mode? ? [] : plugin_prepare_diagnostics
+        # ADR-16 slice 2b — Tier C pre-pass. Built once per run
+        # against the resolved file set + the loaded plugin
+        # registry's `heredoc_templates` so synthetic methods are
+        # visible cross-file when per-file inference dispatches.
+        @synthetic_method_index = Inference::SyntheticMethodScanner.scan(
+          plugin_registry: @plugin_registry,
+          paths: expansion.fetch(:files),
+          environment: nil,
+          fact_store: shared_fact_store,
+          buffer: @buffer
+        )
+        # ADR-17 slice 2 — pre-eval pre-pass. Built once per run
+        # from the `pre_eval:` entries that exist on disk
+        # (slice-1's `pre-eval.file-not-found` `:error` already
+        # surfaced any missing entries; the scanner skips them
+        # here). The resulting {ProjectPatchedMethods} registry
+        # is consulted by the dispatcher tier between plugins
+        # and dependency-source inference so project-side
+        # patches resolve cross-file.
+        existing_pre_eval = @configuration.pre_eval.select { |path| File.file?(path) }
+        pre_eval_outcome = Inference::ProjectPatchedScanner.scan(existing_pre_eval, buffer: @buffer)
+        @project_patched_methods = pre_eval_outcome.registry
+        @pre_eval_diagnostics_from_scanner = pre_eval_outcome.diagnostics
+        # Cross-file class discovery — walks every project file
+        # for `class Foo` / `module Bar` declarations so a
+        # `Foo.method_call` receiver in one file resolves a
+        # `class Foo` declared in a sibling file. Without this
+        # pre-pass each file's `discovered_classes` was per-file
+        # only, and lexical lookup fell back to stdlib `::Foo`
+        # for any user class shadowing a stdlib name (e.g.
+        # `Google::Cloud::Storage::File`). Cost is one extra
+        # parse pass over the project; small projects pay
+        # tens of ms, larger projects ~1s. Future optimisation
+        # can share parses with the existing scanner passes.
+        @project_discovered_classes =
+          Inference::ScopeIndexer.discovered_classes_for_paths(expansion.fetch(:files), buffer: @buffer)
+      end
+
+      # Internal: adopts a frozen {ProjectScan} snapshot supplied
+      # to `Runner.new(prebuilt: ...)` by storing each slot on
+      # the runner's ivar surface, mirroring what
+      # `run_project_pre_passes` would have produced.
+      def adopt_prebuilt_project_scan(scan)
+        @plugin_registry = scan.plugin_registry
+        @dependency_source_index = scan.dependency_source_index
+        @synthetic_method_index = scan.synthetic_method_index
+        @project_patched_methods = scan.project_patched_methods
+        @cached_plugin_prepare_diagnostics = scan.plugin_prepare_diagnostics
+        @pre_eval_diagnostics_from_scanner = scan.pre_eval_diagnostics
+      end
+      private :run_project_pre_passes, :adopt_prebuilt_project_scan
+
+      # ADR-15 Phase 4b — routes per-file analysis to either the
+      # sequential coordinator-side Environment (legacy path,
+      # default) or a Ractor worker pool built around
+      # {WorkerSession} (opt-in via `workers:`). The sequential
+      # path is bit-for-bit unchanged from v0.1.4 / earlier; the
+      # pool path is the substrate exercised by phase 4c when
+      # `RIGOR_RACTOR_WORKERS` / `.rigor.yml` `parallel.workers:`
+      # is wired.
+      #
+      # Sequential mode also snapshots `class_decl_paths` from the
+      # local environment after the per-file loop completes so
+      # `RunStats` can attribute the RBS class universe between
+      # project-sig and bundled sources. The env stays a LOCAL
+      # variable (not an ivar) so it goes GC-eligible when the
+      # method returns — holding it as long-lived state added
+      # memory pressure that surfaced as a Bus Error during the
+      # spec suite under Ruby 4.0 + rbs 4.0.2.
+      def analyze_files(files)
+        return [] if files.empty?
+
+        if pool_mode?
+          analyze_files_in_pool(files)
+        else
+          environment = resolve_sequential_environment
+          result = files.flat_map { |path| analyze_file(path, environment) }
+          if @collect_stats
+            loader = environment.rbs_loader
+            @class_decl_paths_snapshot = loader&.class_decl_paths || {}.freeze
+            @signature_paths_snapshot = loader&.signature_paths || [].freeze
+          end
+          result
+        end
+      end
+
+      # Sequential-mode environment resolver. Returns the supplied
+      # `environment:` override (with the runner's fresh per-run
+      # reporter pair attached so dispatcher events route to THIS
+      # runner's diagnostics) when present; otherwise builds a
+      # fresh Environment per-call via {#build_runner_environment}
+      # — preserving the pre-override behaviour bit-for-bit.
+      def resolve_sequential_environment
+        return build_runner_environment unless @environment_override
+
+        @environment_override.attach_reporters!(
+          rbs_extended_reporter: @rbs_extended_reporter,
+          boundary_cross_reporter: @boundary_cross_reporter
+        )
+        @environment_override
       end
+      private :resolve_sequential_environment
 
       # Pre-file diagnostic streams that fire once per run rather
       # than per analyzed file: plugin load / prepare envelopes,
@@ -90,15 +314,81 @@ module Rigor
       # `expand_paths` errors for `paths:` entries that don't
       # exist or aren't `.rb`. Aggregated here so `#run` stays
       # under the ABC budget.
+      #
+      # ADR-15 Phase 4b — `plugin_prepare_diagnostics` runs on
+      # the coordinator's plugin registry under sequential mode;
+      # under pool mode each worker re-runs `prepare` against
+      # its own plugin instances, so the pool path drains the
+      # first worker's prepare-diagnostic snapshot into the
+      # aggregated diagnostic stream instead (see
+      # {#analyze_files_in_pool}). Skipping the coordinator
+      # prepare in pool mode avoids double-running `#prepare`
+      # against the coordinator-side plugin instances (which
+      # the pool path never consults for per-file analysis).
       def pre_file_diagnostics(expansion)
+        # ADR-18 slice 3 — prepare diagnostics are captured
+        # earlier in #run (before the synthetic-method scanner)
+        # so cross-plugin facts are available to the scanner.
+        # We re-surface the captured diagnostics here so the
+        # existing pre_file_diagnostics ordering is preserved.
+        prepare = pool_mode? ? [] : @cached_plugin_prepare_diagnostics
         plugin_load_diagnostics +
-          plugin_prepare_diagnostics +
+          prepare +
+          pre_eval_diagnostics +
           dependency_source_diagnostics +
           dependency_source_budget_diagnostics +
           dependency_source_config_conflict_diagnostics +
+          rbs_coverage_diagnostics +
           expansion.fetch(:errors)
       end
 
+      # Returns the per-run shared `Plugin::FactStore` instance.
+      # All loaded plugins share this store through their
+      # respective `Plugin::Services` (the same instance is
+      # threaded by `Plugin::Loader.load`). Returns `nil` when
+      # no plugins are loaded.
+      def shared_fact_store
+        return nil if @plugin_registry.nil? || @plugin_registry.empty?
+
+        @plugin_registry.plugins.first&.services&.fact_store
+      end
+
+      # ADR-17 slice 1 — surface a `:error` diagnostic for each
+      # `pre_eval:` entry whose resolved path doesn't exist on
+      # disk. Loud failure mode (`:error`, not `:warning`):
+      # a missing pre_eval path is a configuration mistake the
+      # user must fix before analysis is meaningful.
+      #
+      # Slice 2 adds the `:warning` `pre-eval.parse-error`
+      # stream from the pre-pass scanner — accumulated as
+      # `@pre_eval_diagnostics_from_scanner` during {#run} and
+      # merged here so both diagnostics flow through the same
+      # severity / ordering pipeline.
+      def pre_eval_diagnostics
+        not_found = @configuration.pre_eval.filter_map do |path|
+          next if File.file?(path)
+
+          Diagnostic.new(
+            path: ".rigor.yml", line: 1, column: 1,
+            message: "pre_eval entry not found: #{path.inspect}. " \
+                     "Pre-evaluation requires the file to exist on disk; remove the entry " \
+                     "or create the file before re-running analysis.",
+            severity: :error,
+            rule: "pre-eval.file-not-found",
+            source_family: :builtin
+          )
+        end
+        not_found + Array(@pre_eval_diagnostics_from_scanner).map { |hash| diagnostic_from_hash(hash) }
+      end
+
+      def diagnostic_from_hash(hash)
+        Diagnostic.new(
+          path: hash.fetch(:path), line: hash.fetch(:line), column: hash.fetch(:column),
+          message: hash.fetch(:message), severity: hash.fetch(:severity),
+          rule: hash.fetch(:rule), source_family: :builtin
+        )
+      end
+
       # `target_ruby` flows through to Prism's `version:` option.
       # Prism enforces the supported range and raises
       # `ArgumentError` for versions it does not recognise. Run a
@@ -120,6 +410,291 @@ module Rigor
 
       private
 
+      # Editor mode § "Scope choice — option A". Under
+      # `buffer:` non-nil the per-file analysis emits diagnostics
+      # ONLY for the buffer's logical path; the rest of `paths:`
+      # is consumed by the project-wide pre-passes (synthetic
+      # methods, project-patched methods, plugin facts) but
+      # contributes no per-file diagnostics. This is the v1 cut
+      # before a per-file diagnostic cache exists; option B (full
+      # project + incremental cache) is queued.
+      #
+      # The buffer's logical path is added to the file list even
+      # if it's not under `paths:` — per design § "Failure
+      # envelope": "--instead-of=Y with Y not under any paths:
+      # directory → treated as a valid logical identity for the
+      # buffer".
+      def target_files(expansion)
+        files = expansion.fetch(:files)
+        return files if @buffer.nil?
+
+        [@buffer.logical_path]
+      end
+
+      # Editor mode (`buffer:` non-nil) auto-flips the cache store
+      # to `read_only: true` so multiple debounced editor invocations
+      # against the same project don't churn the on-disk cache or
+      # race on schema-version writes. Cache reads continue
+      # unchanged; misses still run the producer block but the
+      # result is not persisted. Per design doc § "Cache behaviour".
+      def enforce_read_only_cache(cache_store, buffer)
+        return cache_store if buffer.nil?
+        return cache_store if cache_store.nil?
+        return cache_store if cache_store.read_only?
+
+        Cache::Store.new(root: cache_store.root, read_only: true)
+      end
+
+      # ADR-15 Phase 4b — pool mode is enabled when `@workers > 0`.
+      # Editor mode (`buffer:` non-nil) silently overrides pool
+      # mode to sequential: per design § "Ractor pool mode", the
+      # pool's warm-up cost dominates one-file wall time, so the
+      # pool gains nothing on a per-buffer invocation. The override
+      # is part of the contract — not a degradation diagnostic —
+      # because `--workers=N` is a project-scale knob and editor
+      # mode is per-buffer; the conflict resolves toward the more
+      # specific axis.
+      def pool_mode?
+        return false unless @workers.is_a?(Integer) && @workers.positive?
+
+        @buffer.nil?
+      end
+
+      # Coordinator-side Environment used by the sequential code
+      # path. Pool mode builds one Environment per worker inside
+      # the worker Ractor's body instead.
+      def build_runner_environment
+        Environment.for_project(
+          libraries: @configuration.libraries,
+          signature_paths: @configuration.signature_paths,
+          cache_store: @cache_store,
+          plugin_registry: @plugin_registry,
+          dependency_source_index: @dependency_source_index,
+          rbs_extended_reporter: @rbs_extended_reporter,
+          boundary_cross_reporter: @boundary_cross_reporter,
+          bundler_bundle_path: @configuration.bundler_bundle_path,
+          bundler_auto_detect: @configuration.bundler_auto_detect,
+          bundler_lockfile: @configuration.bundler_lockfile,
+          rbs_collection_lockfile: @configuration.rbs_collection_lockfile,
+          rbs_collection_auto_detect: @configuration.rbs_collection_auto_detect,
+          synthetic_method_index: @synthetic_method_index,
+          project_patched_methods: @project_patched_methods
+        )
+      end
+
+      # ADR-15 Phase 4b — Ractor pool around {WorkerSession}.
+      # Spawns `@workers` Ractors; each takes the shareable
+      # payload (Configuration, cache_root String, plugin
+      # Blueprint Array, explain Boolean) and builds its OWN
+      # WorkerSession internally. Files are distributed
+      # round-robin across the pool; each worker writes back to
+      # the main Ractor's mailbox via `Ractor.main.send` with
+      # one of three message kinds:
+      #
+      # - `[:prepare, diagnostics]` — once at startup, the
+      #   session's `prepare_diagnostics` snapshot. The
+      #   coordinator keeps the FIRST worker's snapshot only
+      #   (plugin `#prepare` is deterministic per plugin, so
+      #   each worker produces the same diagnostic set; surfacing
+      #   them once avoids N× duplication).
+      # - `[:file, path, diagnostics]` — one per analysed file.
+      # - `[:done, drained_reporters]` — once at exit, the
+      #   per-worker reporter snapshots for end-of-pool merge.
+      #
+      # The Ruby 4.0+ Ractor model uses a single per-Ractor
+      # mailbox (no `Ractor.yield`); workers push back via
+      # `Ractor.main.send`. The coordinator drains its mailbox
+      # via `Ractor.receive` until it has counted exactly
+      # `pool.size` `:done` messages.
+      #
+      # Diagnostic order: original path order. Workers may
+      # complete files out of order; the coordinator re-orders
+      # via the `results_by_path` Hash before flattening.
+      #
+      # Reporter merge: per-worker `RbsExtended::Reporter` and
+      # `BoundaryCrossReporter` entries are replayed into the
+      # runner-side accumulators via their `record_*` APIs,
+      # which dedupe on the same keys as a single-session run
+      # would. Net result: reporter state is identical to the
+      # sequential path.
+      def analyze_files_in_pool(files) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity
+        # Pre-warm class-level lazy memos on the MAIN Ractor.
+        # `Environment::ClassRegistry.default` is the
+        # default kwarg threaded through `Environment.new`
+        # inside each worker session; lazy-initialising it
+        # from a non-main Ractor would trip
+        # `Ractor::IsolationError`. Touching it here forces
+        # the (shareable) registry into the class-ivar cache
+        # before any worker reads.
+        Environment::ClassRegistry.default
+
+        # ADR-15 Phase 4b.x — pre-warm the RBS cache so
+        # workers serve every reflection query from the
+        # Marshal blob on disk. Without this, the first
+        # cache MISS inside a worker falls through to
+        # `RBS::EnvironmentLoader.new`, which reads a chain
+        # of non-`Ractor.shareable?` RubyGems / RBS module
+        # constants and raises `Ractor::IsolationError`.
+        # Pre-warming requires a `cache_store`; the run aborts
+        # to sequential mode otherwise. See ADR-15 Phase 4b.x
+        # for the full chain of failing constants.
+        if @cache_store.nil?
+          return analyze_files_sequentially_fallback(
+            files, reason: "pool mode requires a cache_store (--no-cache disables pool)"
+          )
+        end
+        prewarm_rbs_cache_for_pool
+
+        configuration = @configuration
+        cache_root = @cache_store&.root
+        blueprints = @plugin_registry.blueprints
+        explain = @explain
+
+        pool = Array.new(@workers) do
+          Ractor.new(configuration, cache_root, blueprints, explain) do |configuration, cache_root, blueprints, explain|
+            cache_store = cache_root ? Rigor::Cache::Store.new(root: cache_root) : nil
+            session = Rigor::Analysis::WorkerSession.new(
+              configuration: configuration,
+              cache_store: cache_store,
+              plugin_blueprints: blueprints,
+              explain: explain
+            )
+            main = Ractor.main
+            main.send([:prepare, session.prepare_diagnostics])
+
+            loop do
+              msg = Ractor.receive
+              break if msg.nil?
+
+              main.send([:file, msg, session.analyze(msg)])
+            end
+
+            main.send([:done, session.drain_reporters])
+          end
+        end
+
+        files.each_with_index { |path, index| pool[index % pool.size].send(path) }
+        pool.each { |worker| worker.send(nil) }
+
+        prepare_diagnostics = nil
+        results_by_path = {}
+        done_count = 0
+
+        while done_count < pool.size
+          message = Ractor.receive
+          case message.first
+          when :prepare
+            prepare_diagnostics ||= message.last
+          when :file
+            results_by_path[message[1]] = message[2]
+          when :done
+            merge_worker_reporters(message.last)
+            done_count += 1
+          end
+        end
+
+        pool.each(&:join)
+
+        Array(prepare_diagnostics) + files.flat_map { |path| results_by_path.fetch(path, []) }
+      end
+
+      # End-of-run telemetry. Walks the cached
+      # `class_decl_paths` snapshot (sequential mode: from
+      # the coordinator's environment; pool mode: from the
+      # first worker's `:prepare` payload) and partitions the
+      # RBS class universe into "project sig/" (paths under
+      # `signature_paths`) vs "bundled" (everything else).
+      # Gem source-walk counts come from `dependency_source_index`
+      # which is already constructed regardless of pool mode.
+      # Wall + RSS are single syscalls; total cost is bounded
+      # by the snapshot size (~1000-2000 entries).
+      def build_run_stats(wall_started_at:, expansion:)
+        snapshot = @class_decl_paths_snapshot
+        project_sig, bundled = RunStats.partition_classes(
+          class_decl_paths: snapshot,
+          signature_paths: @signature_paths_snapshot
+        )
+        RunStats.new(
+          wall_seconds: Process.clock_gettime(Process::CLOCK_MONOTONIC) - wall_started_at,
+          peak_rss_bytes: RunStats.peak_rss_bytes,
+          target_files: expansion.fetch(:files).size,
+          rbs_classes_total: snapshot.size,
+          rbs_classes_project_sig: project_sig,
+          rbs_classes_bundled: bundled,
+          rbs_attribution_available: RunStats.attribution_available?(class_decl_paths: snapshot),
+          gem_walk_classes: @dependency_source_index.class_to_gem.size,
+          gem_walk_gems: @dependency_source_index.resolved_gems.size
+        )
+      end
+
+      # ADR-15 Phase 4b.x — drives every cached RBS producer
+      # on the main Ractor so each worker can serve all
+      # reflection queries from disk (Marshal-load only).
+      # Builds a single coordinator-side {Environment} for
+      # this purpose; the env object is discarded immediately
+      # after the cache is warm — workers build their own
+      # `Environment.for_project` inside the Ractor body,
+      # which then routes through `cached_env` instead of
+      # `RBS::EnvironmentLoader.new`.
+      def prewarm_rbs_cache_for_pool
+        warm_env = Environment.for_project(
+          libraries: @configuration.libraries,
+          signature_paths: @configuration.signature_paths,
+          cache_store: @cache_store,
+          bundler_bundle_path: @configuration.bundler_bundle_path,
+          bundler_auto_detect: @configuration.bundler_auto_detect,
+          bundler_lockfile: @configuration.bundler_lockfile,
+          rbs_collection_lockfile: @configuration.rbs_collection_lockfile,
+          rbs_collection_auto_detect: @configuration.rbs_collection_auto_detect
+        )
+        warm_env.rbs_loader&.prewarm
+      end
+
+      # ADR-15 Phase 4b.x — pool-mode safety net. When pool
+      # mode is configured but a precondition fails (currently:
+      # `--no-cache` would force workers through
+      # `EnvironmentLoader.new`), degrade to sequential
+      # analysis with a `:warning` `pool-degraded` diagnostic
+      # at run start. The actual per-file analysis runs on
+      # the coordinator, identical to the default sequential
+      # path.
+      def analyze_files_sequentially_fallback(files, reason:)
+        environment = build_runner_environment
+        diagnostics = files.flat_map { |path| analyze_file(path, environment) }
+        loader = environment.rbs_loader
+        @class_decl_paths_snapshot = loader&.class_decl_paths || {}.freeze
+        @signature_paths_snapshot = loader&.signature_paths || [].freeze
+        diagnostics.unshift(
+          Diagnostic.new(
+            path: ".rigor.yml", line: 1, column: 1,
+            message: "pool mode degraded to sequential: #{reason}",
+            severity: :warning, rule: "pool-degraded", source_family: :builtin
+          )
+        )
+      end
+
+      def merge_worker_reporters(drained)
+        rbs = drained.fetch(:rbs_extended)
+        rbs.fetch(:unresolved_payloads).each do |entry|
+          @rbs_extended_reporter.record_unresolved(
+            payload: entry.payload, source_location: entry.source_location
+          )
+        end
+        rbs.fetch(:lossy_projections).each do |entry|
+          @rbs_extended_reporter.record_lossy_projection(
+            head: entry.head, source_location: entry.source_location
+          )
+        end
+        drained.fetch(:boundary_cross).each do |entry|
+          @boundary_cross_reporter.record(
+            class_name: entry.class_name,
+            method_name: entry.method_name,
+            gem_name: entry.gem_name,
+            rbs_display: entry.rbs_display
+          )
+        end
+      end
+
       # Loads project-configured plugins through {Rigor::Plugin::Loader}
       # and returns the resulting {Rigor::Plugin::Registry}. Loader
       # failures are isolated: each surfaces as a `:plugin_loader`
@@ -304,6 +879,70 @@ module Rigor
         end
       end
 
+      # O4 Layer 3 slice 3 — graceful-degradation coverage
+      # report. When the project has a `Gemfile.lock` (slice 1)
+      # and one or more locked gems are not covered by ANY of
+      # the four RBS resolution paths (`DEFAULT_LIBRARIES`,
+      # `data/vendored_gem_sigs/`, slice-1 bundle-shipped
+      # `sig/`, slice-2 `rbs_collection.lock.yaml`), emit a
+      # single `:info` diagnostic summarising the uncovered set
+      # so the user can act on it (run `rbs collection install`,
+      # opt the gem into `dependencies.source_inference:`, or
+      # accept the `Dynamic[T]` fallback).
+      #
+      # Suppressed when the lockfile is empty, when every gem
+      # is covered, or when slice 1's `bundler.lockfile`
+      # discovery returned nothing (no lockfile to read).
+      def rbs_coverage_diagnostics
+        locked = Environment::LockfileResolver.locked_gems(
+          lockfile_path: @configuration.bundler_lockfile,
+          project_root: Dir.pwd,
+          auto_detect: @configuration.bundler_auto_detect
+        )
+        return [] if locked.empty?
+
+        bundle_sig_paths = Environment::BundleSigDiscovery.discover(
+          bundle_path: @configuration.bundler_bundle_path,
+          project_root: Dir.pwd,
+          auto_detect: @configuration.bundler_auto_detect,
+          locked_gems: locked
+        )
+        collection_paths = Environment::RbsCollectionDiscovery.discover(
+          lockfile_path: @configuration.rbs_collection_lockfile,
+          project_root: Dir.pwd,
+          auto_detect: @configuration.rbs_collection_auto_detect
+        )
+        rows = Environment::RbsCoverageReport.classify(
+          locked_gems: locked,
+          default_libraries: Environment::DEFAULT_LIBRARIES,
+          bundle_sig_paths: bundle_sig_paths,
+          rbs_collection_paths: collection_paths
+        )
+        missing = Environment::RbsCoverageReport.missing(rows)
+        return [] if missing.empty?
+
+        [build_rbs_coverage_missing_diagnostic(missing)]
+      end
+
+      def build_rbs_coverage_missing_diagnostic(missing)
+        sample_size = 5
+        sample = missing.first(sample_size).map(&:gem_name)
+        suffix = missing.size > sample_size ? ", and #{missing.size - sample_size} more" : ""
+        Diagnostic.new(
+          path: ".rigor.yml",
+          line: 1,
+          column: 1,
+          message: "#{missing.size} gem(s) in Gemfile.lock have no RBS available: " \
+                   "#{sample.join(', ')}#{suffix}. " \
+                   "Consider `rbs collection install` to fetch community RBS from " \
+                   "`ruby/gem_rbs_collection`, ship `sig/` in the gem itself, or " \
+                   "opt the gem into `dependencies.source_inference:` in `.rigor.yml`.",
+          severity: :info,
+          rule: "rbs.coverage.missing-gem",
+          source_family: :builtin
+        )
+      end
+
       # ADR-13 slice 3b — drains the per-run
       # {RbsExtended::Reporter} into one diagnostic per accumulated
       # event:
@@ -520,7 +1159,11 @@ module Rigor
         Array(paths).each do |path|
           if File.directory?(path)
             files.concat(reject_excluded(Dir.glob(File.join(path, RUBY_GLOB))))
-          elsif File.file?(path) && path.end_with?(".rb")
+          # Editor-mode bypass: the buffer's logical path is treated
+          # as a real `.rb` file regardless of on-disk presence —
+          # `parse_source` reads bytes from the buffer's physical
+          # path. Common case: LSP client editing a brand-new file.
+          elsif accept_as_ruby_file?(path)
             files << path
           elsif File.exist?(path)
             errors << path_error(path, "not a Ruby file (expected `.rb` or a directory)")
@@ -531,6 +1174,11 @@ module Rigor
         { files: files, errors: errors }
       end
 
+      def accept_as_ruby_file?(path)
+        (File.file?(path) && path.end_with?(".rb")) ||
+          (@buffer && path == @buffer.logical_path)
+      end
+
       # `Configuration#exclude_patterns` is a list of glob patterns
       # checked against each globbed path via `File.fnmatch?` (without
       # `FNM_PATHNAME`, so `**` and `*` both span path separators —
@@ -560,11 +1208,25 @@ module Rigor
         )
       end
 
+      # Reads + parses the source at `path`. Under editor mode
+      # (`@buffer` set) reads bytes from `@buffer.physical_path`
+      # when `path` matches the logical binding, then parses with
+      # `filepath: path` so Prism's location data carries the
+      # LOGICAL path. Non-binding paths go through the cheaper
+      # `Prism.parse_file` codepath unchanged.
+      def parse_source(path)
+        physical = @buffer ? @buffer.resolve(path) : path
+        return Prism.parse_file(physical, version: @configuration.target_ruby) if physical == path
+
+        Prism.parse(File.read(physical), filepath: path, version: @configuration.target_ruby)
+      end
+
       def analyze_file(path, environment) # rubocop:disable Metrics/MethodLength
-        parse_result = Prism.parse_file(path, version: @configuration.target_ruby)
+        parse_result = parse_source(path)
         return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
 
         scope = Scope.empty(environment: environment, source_path: path)
+        scope = scope.with_discovered_classes(@project_discovered_classes) unless @project_discovered_classes.empty?
         index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
         diagnostics = CheckRules.diagnose(
           path: path,