rigortype 0.2.7 → 0.2.8

data/lib/rigor/analysis/runner/pool_coordinator.rb

@@ -11,27 +11,21 @@ require_relative "../../rbs_extended/conformance_checker"
 module Rigor
   module Analysis
     class Runner
-      # Owns the per-file analysis dispatch: the sequential coordinator
-      # path (default) and both worker-pool backends — the ADR-15
-      # Phase 4b Ractor pool and the ADR-15 Amendment fork pool, plus the
-      # pool-degraded fallback. Builds the coordinator-side Environment,
-      # snapshots the end-of-pass RBS tables into the shared
-      # {RunSnapshots}, and merges per-worker reporter drains back into
-      # the runner's reporter accumulators.
+      # Owns the per-file analysis dispatch: the sequential coordinator path (default) and both worker-pool
+      # backends — the ADR-15 Phase 4b Ractor pool and the ADR-15 Amendment fork pool, plus the
+      # pool-degraded fallback. Builds the coordinator-side Environment, snapshots the end-of-pass RBS
+      # tables into the shared {RunSnapshots}, and merges per-worker reporter drains back into the runner's
+      # reporter accumulators.
       #
-      # Sequential-equivalence contract (docs/internal-spec/
-      # worker-session.md): the pool path MUST produce the same
-      # diagnostics, in the same order, as the sequential path. The
-      # coordinator re-orders worker results by original path order and
-      # replays per-worker reporter entries through the dedupe-on-record
+      # Sequential-equivalence contract (docs/internal-spec/ worker-session.md): the pool path MUST produce
+      # the same diagnostics, in the same order, as the sequential path. The coordinator re-orders worker
+      # results by original path order and replays per-worker reporter entries through the dedupe-on-record
       # APIs so reporter state matches a single-session run.
       #
-      # Per-run varying prepass state (plugin registry, dependency-source
-      # index, synthetic-method / project-patched indexes) is read
-      # through injected reader procs; the actual per-file analysis is
-      # delegated back through an injected `analyze_file` callable so the
-      # CheckRules / recorder / plugin-emission machinery stays on the
-      # {Runner}.
+      # Per-run varying prepass state (plugin registry, dependency-source index, synthetic-method /
+      # project-patched indexes) is read through injected reader procs; the actual per-file analysis is
+      # delegated back through an injected `analyze_file` callable so the CheckRules / recorder /
+      # plugin-emission machinery stays on the {Runner}.
       class PoolCoordinator # rubocop:disable Metrics/ClassLength
         # @param configuration [Rigor::Configuration]
         # @param cache_store [Rigor::Cache::Store, nil]
@@ -41,17 +35,15 @@ module Rigor
         # @param buffer [BufferBinding, nil]
         # @param environment_override [Rigor::Environment, nil]
         # @param rbs_extended_reporter [RbsExtended::Reporter]
-        # @param boundary_cross_reporter
-        #   [DependencySourceInference::BoundaryCrossReporter]
-        # @param source_rbs_synthesis_reporter
-        #   [Plugin::SourceRbsSynthesisReporter]
+        # @param boundary_cross_reporter [DependencySourceInference::BoundaryCrossReporter]
+        # @param source_rbs_synthesis_reporter [Plugin::SourceRbsSynthesisReporter]
         # @param snapshots [RunSnapshots] shared end-of-pass snapshot sink.
         # @param plugin_registry [#call] reader for the current registry.
         # @param dependency_source_index [#call] reader.
         # @param synthetic_method_index [#call] reader.
         # @param project_patched_methods [#call] reader.
-        # @param project_scope_seed [#call] reader for the cross-file
-        #   pre-pass seed tables (`Runner#project_scope_seed_tables`).
+        # @param project_scope_seed [#call] reader for the cross-file pre-pass seed tables
+        #   (`Runner#project_scope_seed_tables`).
         # @param analyze_file [#call] `(path, environment) -> diagnostics`.
         def initialize(configuration:, cache_store:, explain:, workers:, collect_stats:, # rubocop:disable Metrics/ParameterLists
                        buffer:, environment_override:, rbs_extended_reporter:,
@@ -78,38 +70,29 @@ module Rigor
           @analyze_file = analyze_file
         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.
+        # 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
 
-        # 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.
+        # 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.
+        # 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, environment: nil)
           return [] if files.empty?
           return dispatch_pool(files) if pool_mode?
@@ -118,19 +101,15 @@ module Rigor
         end
 
         def analyze_files_sequentially(files, environment)
-          # Snapshot the small synthesized-namespace name list (NOT the
-          # env — see the method comment) so #run can surface the
-          # malformed-RBS `:info` diagnostic without rebuilding the env.
-          # Gated on the project actually declaring `signature_paths:`:
-          # synthesis only matters for the project's own RBS, and
-          # `#synthesized_namespaces` forces the (otherwise-lazy) RBS env
-          # to build — doing so when there is no project sig set would
-          # warm `.rigor/cache` on a bare `--no-stats` run.
+          # Snapshot the small synthesized-namespace name list (NOT the env — see the method comment) so
+          # #run can surface the malformed-RBS `:info` diagnostic without rebuilding the env. Gated on the
+          # project actually declaring `signature_paths:`: synthesis only matters for the project's own
+          # RBS, and `#synthesized_namespaces` forces the (otherwise-lazy) RBS env to build — doing so when
+          # there is no project sig set would warm `.rigor/cache` on a bare `--no-stats` run.
           @snapshots.synthesized_namespaces =
             project_signature_paths? ? (environment.rbs_loader&.synthesized_namespaces || []) : []
-          # `rigor:v1:conforms-to` lives only in the project's own
-          # `signature_paths:` RBS, so gate the scan the same way and
-          # reuse the already-built env (no extra RBS load).
+          # `rigor:v1:conforms-to` lives only in the project's own `signature_paths:` RBS, so gate the scan
+          # the same way and reuse the already-built env (no extra RBS load).
           @snapshots.conformance_results =
             project_signature_paths? ? RbsExtended::ConformanceChecker.scan(environment.rbs_loader) : []
           result = files.flat_map { |path| @analyze_file.call(path, environment) }
@@ -142,12 +121,10 @@ module Rigor
           result
         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.
+        # 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(source_files: [])
           return build_runner_environment(source_files: source_files) unless @environment_override
 
@@ -158,14 +135,11 @@ module Rigor
           @environment_override
         end
 
-        # ADR-15 Amendment (2026-05-20) — worker-pool backend selector.
-        # `fork` is the active backend: separate processes sidestep both
-        # the Ruby Bug #22075 use-after-free and the worker-side
-        # `Ractor::IsolationError` that make the Ractor pool unusable
-        # (see the ADR-15 Amendment +
-        # docs/notes/20260520-ractor-pool-cruby-uaf.md). The Ractor pool
-        # is preserved but off the default path — `RIGOR_POOL_BACKEND=ractor`
-        # opts back in so it stays testable. Platforms without `fork`
+        # ADR-15 Amendment (2026-05-20) — worker-pool backend selector. `fork` is the active backend:
+        # separate processes sidestep both the Ruby Bug #22075 use-after-free and the worker-side
+        # `Ractor::IsolationError` that make the Ractor pool unusable (see the ADR-15 Amendment +
+        # docs/notes/20260520-ractor-pool-cruby-uaf.md). The Ractor pool is preserved but off the default
+        # path — `RIGOR_POOL_BACKEND=ractor` opts back in so it stays testable. Platforms without `fork`
         # (Windows) fall back to sequential.
         def pool_backend
           return :ractor if ENV["RIGOR_POOL_BACKEND"] == "ractor"
@@ -186,15 +160,12 @@ module Rigor
           end
         end
 
-        # Coordinator-side Environment used by the sequential code
-        # path. Pool mode builds one Environment per worker inside
-        # the worker Ractor's body instead.
+        # Coordinator-side Environment used by the sequential code path. Pool mode builds one Environment
+        # per worker inside the worker Ractor's body instead.
         #
-        # ADR-32 WD4 — `source_files:` is threaded down so that
-        # `Environment.for_project` can invoke each loaded plugin's
-        # `source_rbs_synthesizer` callable per project source file
-        # at env-build time. Defaults to `[]` for callers that don't
-        # have a file list yet (e.g. pre-pass-only build paths); in
+        # ADR-32 WD4 — `source_files:` is threaded down so that `Environment.for_project` can invoke each
+        # loaded plugin's `source_rbs_synthesizer` callable per project source file at env-build time.
+        # Defaults to `[]` for callers that don't have a file list yet (e.g. pre-pass-only build paths); in
         # that case no synthesised RBS is contributed.
         def build_runner_environment(source_files: [])
           Environment.for_project(
@@ -217,62 +188,44 @@ module Rigor
           )
         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:
+        # 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).
+        # - `[: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.
+        # - `[: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.
+        # 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.
+        # 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.
+        # 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,Metrics/PerceivedComplexity
-          # 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.
+          # 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.
+          # 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)"
@@ -284,11 +237,9 @@ module Rigor
           cache_root = @cache_store&.root
           blueprints = plugin_registry.blueprints
           explain = @explain
-          # ADR-32 WD4 — the full project file list travels into
-          # every Ractor worker so each worker's WorkerSession
-          # can invoke loaded plugins' source_rbs_synthesizers at
-          # env-build time. The list is a frozen Array<String>;
-          # cheaply shareable.
+          # ADR-32 WD4 — the full project file list travels into every Ractor worker so each worker's
+          # WorkerSession can invoke loaded plugins' source_rbs_synthesizers at env-build time. The list is
+          # a frozen Array<String>; cheaply shareable.
           shareable_source_files = files.map { |path| path.to_s.dup.freeze }.freeze
 
           pool = Array.new(@workers) do
@@ -340,22 +291,18 @@ module Rigor
           Array(prepare_diagnostics) + files.flat_map { |path| results_by_path.fetch(path, []) }
         end
 
-        # ADR-15 Amendment (2026-05-20) — fork-based worker pool, the
-        # active backend for `workers > 0`. Builds ONE {WorkerSession}
-        # on the parent, then `fork`s N children that copy-on-write
-        # inherit it. Each child analyses a contiguous slice of `files`
-        # and writes a Marshal'd `{results:, reporters:}` payload to a
-        # temp file; the parent `Process.wait`s every child, merges the
-        # payloads, and re-orders diagnostics by original path order.
+        # ADR-15 Amendment (2026-05-20) — fork-based worker pool, the active backend for `workers > 0`.
+        # Builds ONE {WorkerSession} on the parent, then `fork`s N children that copy-on-write inherit it.
+        # Each child analyses a contiguous slice of `files` and writes a Marshal'd `{results:, reporters:}`
+        # payload to a temp file; the parent `Process.wait`s every child, merges the payloads, and re-orders
+        # diagnostics by original path order.
         #
-        # Separate processes have separate GC heaps and `vm->ci_table`
-        # (immune to Ruby Bug #22075) and copy-on-write-inherit every
-        # constant (no `Ractor.shareable?` constraint). See the ADR-15
-        # Amendment + docs/notes/20260520-ractor-pool-cruby-uaf.md.
+        # Separate processes have separate GC heaps and `vm->ci_table` (immune to Ruby Bug #22075) and
+        # copy-on-write-inherit every constant (no `Ractor.shareable?` constraint). See the ADR-15 Amendment
+        # + docs/notes/20260520-ractor-pool-cruby-uaf.md.
         #
-        # A child that exits non-zero (crash / unmarshalable payload) is
-        # degraded: the parent re-analyses that slice in-process and
-        # prepends a `pool-degraded` warning.
+        # A child that exits non-zero (crash / unmarshalable payload) is degraded: the parent re-analyses
+        # that slice in-process and prepends a `pool-degraded` warning.
         def analyze_files_in_fork_pool(files) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
           Environment::ClassRegistry.default
 
@@ -369,9 +316,8 @@ module Rigor
             project_scope_seed: project_scope_seed,
             source_files: files
           )
-          # Force the full RBS load on the parent so children
-          # copy-on-write inherit a warm Environment rather than each
-          # rebuilding it after the fork.
+          # Force the full RBS load on the parent so children copy-on-write inherit a warm Environment
+          # rather than each rebuilding it after the fork.
           session.environment.rbs_loader&.prewarm
           snapshot_fork_pool_stats(session) if @collect_stats
 
@@ -398,10 +344,9 @@ module Rigor
           degraded.empty? ? diagnostics : diagnostics.unshift(fork_degraded_diagnostic(degraded.size))
         end
 
-        # Child-process body for {#analyze_files_in_fork_pool}. Analyses
-        # the slice with the copy-on-write-inherited session and writes
-        # the Marshal'd payload to `out_path`. `exit!` skips `at_exit` /
-        # stdio flush — the payload is already durable on disk by then.
+        # Child-process body for {#analyze_files_in_fork_pool}. Analyses the slice with the
+        # copy-on-write-inherited session and writes the Marshal'd payload to `out_path`. `exit!` skips
+        # `at_exit` / stdio flush — the payload is already durable on disk by then.
         def run_fork_worker(session, slice, out_path)
           results = slice.to_h { |path| [path, session.analyze(path)] }
           payload = { results: results, reporters: session.drain_reporters }
@@ -411,17 +356,16 @@ module Rigor
           exit!(1)
         end
 
-        # Snapshots `class_decl_paths` from the parent session's loader
-        # so end-of-run {RunStats} can attribute the RBS class universe.
+        # Snapshots `class_decl_paths` from the parent session's loader so end-of-run {RunStats} can
+        # attribute the RBS class universe.
         def snapshot_fork_pool_stats(session)
           loader = session.environment.rbs_loader
           @snapshots.class_decl_paths = loader&.class_decl_paths || {}.freeze
           @snapshots.signature_paths = loader&.signature_paths || [].freeze
         end
 
-        # Waits for every forked child, merges each successful payload
-        # into `results_by_path`, and returns the file paths whose
-        # worker exited abnormally (for in-process degrade).
+        # Waits for every forked child, merges each successful payload into `results_by_path`, and returns
+        # the file paths whose worker exited abnormally (for in-process degrade).
         def collect_fork_results(children, results_by_path)
           degraded = []
           children.each do |child|
@@ -437,10 +381,9 @@ module Rigor
           degraded
         end
 
-        # @return [Hash, nil] the child's `{results:, reporters:}`
-        #   payload, or nil when the child exited abnormally or wrote no
-        #   readable payload. `Marshal.load` is safe here: the blob was
-        #   written by our own forked child to a temp file we created.
+        # @return [Hash, nil] the child's `{results:, reporters:}` payload, or nil when the child exited
+        #   abnormally or wrote no readable payload. `Marshal.load` is safe here: the blob was written by
+        #   our own forked child to a temp file we created.
         def fork_worker_payload(status, out_path)
           return nil unless status.success? && File.exist?(out_path)
 
@@ -458,15 +401,11 @@ module Rigor
           )
         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`.
+        # 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,
@@ -481,14 +420,10 @@ module Rigor
           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.
+        # 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.call(path, environment) }
@@ -524,10 +459,8 @@ module Rigor
               rbs_display: entry.rbs_display
             )
           end
-          # ADR-32 WD6 — merge per-worker synthesizer failures
-          # back into the coordinator's reporter. Fetched with a
-          # default empty array so older drains (pre-slice-2)
-          # remain compatible.
+          # ADR-32 WD6 — merge per-worker synthesizer failures back into the coordinator's reporter. Fetched
+          # with a default empty array so older drains (pre-slice-2) remain compatible.
           Array(drained[:source_rbs_synthesis]).each do |entry|
             @source_rbs_synthesis_reporter.record(
               plugin_id: entry.plugin_id, path: entry.path, message: entry.message
@@ -537,8 +470,8 @@ module Rigor
 
         private
 
-        # True when the project declares its own `signature_paths:` (the
-        # only place the qualified-name-without-namespace mistake lives).
+        # True when the project declares its own `signature_paths:` (the only place the
+        # qualified-name-without-namespace mistake lives).
         def project_signature_paths?
           paths = @configuration.signature_paths
           !(paths.nil? || paths.empty?)