rigortype 0.2.9 → 0.3.0

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../diagnostic"
+require_relative "../severity_stamp"
 
 module Rigor
   module Analysis
@@ -31,11 +32,16 @@ module Rigor
         # @param cached_plugin_prepare_diagnostics [#call] reader returning the prepare-diagnostic snapshot.
         # @param pre_eval_diagnostics_from_scanner [#call] reader returning the pre-eval scanner diagnostics.
         # @param synthesized_namespaces_snapshot [#call] reader.
+        # @param quarantined_signatures_snapshot [#call] reader returning the `signature_paths:` files skipped
+        #   because they do not parse (`[path, first_error_line]` pairs).
+        # @param env_build_failure_snapshot [#call] reader returning the total RBS env-build failure tuple
+        #   (`[error_class, first_error_line, conflicting_buffer_names]`) or nil when the env built.
         # @param conformance_results_snapshot [#call] reader.
         def initialize(configuration:, rbs_extended_reporter:, boundary_cross_reporter:, # rubocop:disable Metrics/ParameterLists
                        source_rbs_synthesis_reporter:, plugin_registry:, dependency_source_index:,
                        pool_mode:, cached_plugin_prepare_diagnostics:,
                        pre_eval_diagnostics_from_scanner:, synthesized_namespaces_snapshot:,
+                       quarantined_signatures_snapshot:, env_build_failure_snapshot:,
                        conformance_results_snapshot:)
           @configuration = configuration
           @rbs_extended_reporter = rbs_extended_reporter
@@ -47,6 +53,8 @@ module Rigor
           @cached_plugin_prepare_diagnostics_reader = cached_plugin_prepare_diagnostics
           @pre_eval_diagnostics_from_scanner_reader = pre_eval_diagnostics_from_scanner
           @synthesized_namespaces_snapshot_reader = synthesized_namespaces_snapshot
+          @quarantined_signatures_snapshot_reader = quarantined_signatures_snapshot
+          @env_build_failure_snapshot_reader = env_build_failure_snapshot
           @conformance_results_snapshot_reader = conformance_results_snapshot
         end
 
@@ -73,6 +81,7 @@ module Rigor
             dependency_source_budget_diagnostics +
             dependency_source_config_conflict_diagnostics +
             rbs_coverage_diagnostics +
+            rbs_inline_annotation_hint_diagnostics(expansion) +
             expansion.fetch(:errors)
         end
 
@@ -114,7 +123,7 @@ module Rigor
               path: ".rigor.yml",
               line: 1,
               column: 1,
-              message: error.message,
+              message: plugin_load_error_message(error),
               severity: :error,
               rule: "load-error",
               source_family: :plugin_loader
@@ -122,6 +131,16 @@ module Rigor
           end
         end
 
+        # #194 slice 1 — when the require SUCCEEDED but configuration / instantiation then failed, the loader
+        # stamps the resolved file on the error; naming it here turns an engine↔plugin version skew (a stale
+        # installed `rigortype` gem shadowing a checkout's bundled plugin) into a one-line diagnosis. A
+        # require that failed outright carries no resolved path and keeps its original message.
+        def plugin_load_error_message(error)
+          return error.message if error.resolved_path.nil?
+
+          "#{error.message} (loaded from #{error.resolved_path})"
+        end
+
         # ADR-10 § "Diagnostic prefix family" — surfaces gems listed in `dependencies.source_inference`
         # that RubyGems could not resolve. The run continues; the gem simply contributes nothing this
         # session, mirroring the plugin-load error envelope. Authored `:warning` because an unresolvable
@@ -224,12 +243,114 @@ module Rigor
           [build_rbs_coverage_missing_diagnostic(missing)]
         end
 
+        # ADR-93 WD3 — the standalone residual. A bare `gem install rigortype` has no `rbs-inline` library,
+        # so the spec's "annotations are official type sources whenever present" cannot be satisfied: the
+        # annotated code reads `Dynamic[top]`. When the library is absent AND the project actually carries
+        # annotation-shaped comments, emit one `:info` routing the user to install it. Rigor never bundles it
+        # (ADR-0 zero-dep). Suppressed whenever the library resolves (auto-wire or an explicit `plugins:`
+        # entry then handles it — including the deliberate `enabled: false` opt-out, which resolves and so is
+        # never nagged) or an `rbs-inline` plugin is already active for another reason.
+        def rbs_inline_annotation_hint_diagnostics(expansion)
+          return [] if Configuration.rbs_inline_library_resolvable?
+          return [] if rbs_inline_plugin_active?
+
+          first = expansion.fetch(:files).find { |path| file_carries_inline_annotation?(path) }
+          return [] unless first
+
+          [build_rbs_inline_unsynthesized_diagnostic(first)]
+        end
+
+        def rbs_inline_plugin_active?
+          plugin_registry.plugins.any? { |plugin| plugin.manifest.id == "rbs-inline" }
+        end
+
+        # A deliberately coarse routing scan — NOT the upstream annotation grammar, which is exactly what is
+        # unavailable here (that is the whole condition). It keys on the `# @rbs` block form and on a `#:`
+        # comment immediately followed by the start of an RBS type (`(`, `[`, `{`, `?`, a `Constant`, or an
+        # RBS lowercase base type), and never on an RDoc directive (`#:nodoc:` and friends read as a bare
+        # lowercase word closed by a colon), so a project with no real annotations stays silent. Reads the
+        # file directly (the analysis buffer is not threaded here) and early-exits on the first hit; this runs
+        # at most once per run and only in the library-absent standalone case, so the extra read is bounded.
+        INLINE_ANNOTATION_SHAPE = /
+          (?:^|\s)\#\s*@rbs\b
+          |
+          (?:^|\s)\#:[ \t]*(?:[\[({?A-Z]|(?:bool|void|nil|untyped|top|bot|self|instance|class)\b)
+        /x
+        private_constant :INLINE_ANNOTATION_SHAPE
+
+        def file_carries_inline_annotation?(path)
+          File.foreach(path) do |line|
+            return true if INLINE_ANNOTATION_SHAPE.match?(line)
+          end
+          false
+        rescue StandardError
+          false
+        end
+
+        def build_rbs_inline_unsynthesized_diagnostic(sample_path)
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "Inline rbs-inline annotations (`# @rbs …`, `#: <type>`) are present in your project " \
+                     "(e.g. #{relative_signature_path(sample_path)}), but the `rbs-inline` library is not " \
+                     "installed, so Rigor cannot read them and the annotated code stays `Dynamic[top]` — " \
+                     "this run is quieter than your annotations intend, not cleaner. Install the " \
+                     "`rbs-inline` gem (its dependency closure, `prism` + `rbs`, already ships with Rigor) " \
+                     "and Rigor honours the annotations automatically (ADR-93); it is not bundled, keeping " \
+                     "the core zero-dep (ADR-0).",
+            severity: :info,
+            rule: "rbs.coverage.inline-annotations-unsynthesized",
+            source_family: :builtin
+          )
+        end
+
         # Robustness uplift companion (ADR-5) — when the project's `signature_paths:` RBS declared
         # qualified names without their enclosing namespace, `RbsLoader` synthesizes the missing `module`s
         # so the otherwise-inert signatures resolve. Surface a single `:info` diagnostic naming them so the
         # user knows their sig set is malformed (`rbs validate` rejects it) and can fix it at the source.
         # Authored `:info`: the analysis already succeeded; this is advisory, never a gate. Empty for a
         # well-formed sig set.
+        # An unparseable `.rbs` under `signature_paths:` is QUARANTINED so the rest of the env survives
+        # (PR #50), which means the types it declares are silently absent — calls into them read
+        # `Dynamic[top]`, and the run gets *quieter*, not louder. The stderr banner alone never reached CI:
+        # it is not a diagnostic, so it is absent from `--format json` / SARIF / GitHub annotations / the LSP
+        # and cannot move the exit code. This puts it in the diagnostic stream where every channel sees it.
+        #
+        # Authored `:warning`, not `:error`: an existing green build must not turn red on upgrade, and the
+        # `rbs` gem's own parser moves across versions (ADR-79 keeps Rigor faithful to the project's `rbs`,
+        # so a version bump CAN newly reject a file that used to parse). Rejecting a broken sig set outright
+        # is a *new required discipline* — ADR-50 WD3 routes those through the bleeding-edge overlay, where
+        # the `reject-unparseable-signatures` feature promotes this rule to `:error` for anyone who opts in
+        # (and by default at the next major).
+        def rbs_quarantined_signature_diagnostics
+          quarantined = quarantined_signatures_snapshot
+          return [] if quarantined.empty?
+
+          [build_rbs_quarantined_signature_diagnostic(quarantined)]
+        end
+
+        # The twin of {#rbs_quarantined_signature_diagnostics}, one tier louder in consequence. Quarantine
+        # drops ONE unparseable file and keeps the rest of the env; a total build failure — typically a
+        # `signature_paths:` entry redeclaring a constant/class Rigor's bundled RBS already ships, which raises
+        # `RBS::DuplicatedDeclarationError` at resolve — collapses the WHOLE env to nil, so every type-of query
+        # degrades to `Dynamic[top]` and most rules stop firing: the run comes back EMPTY, which reads as clean.
+        # The stderr banner ({RbsLoader#warn_about_env_build_failure_once}) is not a diagnostic, so it never
+        # reached `--format json` / SARIF / CI annotations / the LSP; this puts it in the diagnostic stream so
+        # every channel sees it, and names the conflicting signature files off the raised error's `#decls`.
+        #
+        # Authored `:warning`, not `:error`, for the same reason as its quarantine twin: the conflict is
+        # *typically* between the user's `sig/` and Rigor's OWN bundled RBS, so an `:error` default would let a
+        # Rigor release turn a green build red with zero user change (AGENTS.md § FP discipline). The
+        # `reject-unparseable-signatures` bleeding-edge feature promotes it to `:error` for anyone who opts in
+        # (and by default at the next major).
+        def rbs_environment_build_failed_diagnostics
+          failure = env_build_failure_snapshot
+          return [] if failure.nil?
+
+          [build_rbs_environment_build_failed_diagnostic(failure)]
+        end
+
         def rbs_synthesized_namespace_diagnostics
           synthesized = synthesized_namespaces_snapshot
           return [] if synthesized.nil? || synthesized.empty?
@@ -299,6 +420,54 @@ module Rigor
           methods.size == 1 ? "required method" : "#{methods.size} required methods"
         end
 
+        def build_rbs_quarantined_signature_diagnostic(quarantined)
+          sample_size = 5
+          sample = quarantined.first(sample_size).map { |path, _first_line| relative_signature_path(path) }
+          suffix = quarantined.size > sample_size ? ", and #{quarantined.size - sample_size} more" : ""
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "#{quarantined.size} RBS file(s) under `signature_paths:` do not parse and were " \
+                     "SKIPPED: #{sample.join(', ')}#{suffix}. The rest of your RBS environment still " \
+                     "loaded, but the types those files declare are absent — calls into them read " \
+                     "`Dynamic[top]`, so this run is quieter than it should be, not cleaner. Fix the " \
+                     "parse error(s) (`rbs validate`) to restore that coverage.",
+            severity: :warning,
+            rule: "rbs.coverage.quarantined-signature",
+            source_family: :builtin
+          )
+        end
+
+        def build_rbs_environment_build_failed_diagnostic(failure)
+          error_class, first_line, buffers = failure
+          sample_size = 5
+          files = Array(buffers).map { |name| relative_signature_path(name.to_s) }
+          sample = files.first(sample_size)
+          suffix = files.size > sample_size ? ", and #{files.size - sample_size} more" : ""
+          conflicts = sample.empty? ? "" : " Conflicting signature file(s): #{sample.join(', ')}#{suffix}."
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "The RBS environment failed to build (#{error_class}): #{first_line}.#{conflicts} " \
+                     "A `signature_paths:` entry typically redeclares a constant or class that Rigor's " \
+                     "bundled RBS already ships, which collapses the WHOLE environment to nil — every " \
+                     "type-of query then reads `Dynamic[top]` and most diagnostics stop firing, so this " \
+                     "run is EMPTY rather than clean. Remove the conflicting declaration from your `sig/` " \
+                     "(`rbs validate`) to restore type coverage.",
+            severity: :warning,
+            rule: "rbs.coverage.environment-build-failed",
+            source_family: :builtin
+          )
+        end
+
+        # The absolute path is what the loader records; the user thinks in project-relative terms.
+        def relative_signature_path(path)
+          root = "#{Dir.pwd}#{File::SEPARATOR}"
+          path.start_with?(root) ? path.delete_prefix(root) : path
+        end
+
         def build_rbs_synthesized_namespace_diagnostic(synthesized)
           sample_size = 5
           sample = synthesized.first(sample_size)
@@ -457,34 +626,10 @@ module Rigor
         end
 
         # ADR-8 § "Severity profile" — re-stamps each diagnostic's severity from the configured profile +
-        # per-rule overrides. Rules emit with their authored severity; the profile is the final filter.
-        # Diagnostics whose resolved severity is `:off` are dropped from the run result.
+        # per-rule overrides, dropping any that resolve to `:off`. Delegates to the shared {SeverityStamp} so
+        # the ADR-87 WD4 boot-slimming hit path applies the identical final filter.
         def apply_severity_profile(diagnostics)
-          diagnostics.filter_map { |diagnostic| stamp_severity(diagnostic) }
-        end
-
-        def stamp_severity(diagnostic)
-          return diagnostic if diagnostic.rule.nil?
-
-          resolved = Configuration::SeverityProfile.resolve(
-            rule: diagnostic.rule,
-            authored_severity: diagnostic.severity,
-            profile: @configuration.severity_profile,
-            overrides: @configuration.severity_overrides,
-            bleeding_edge_overrides: @configuration.bleeding_edge_severity_overrides
-          )
-          return nil if resolved == :off
-          return diagnostic if resolved == diagnostic.severity
-
-          Diagnostic.new(
-            path: diagnostic.path,
-            line: diagnostic.line,
-            column: diagnostic.column,
-            message: diagnostic.message,
-            severity: resolved,
-            rule: diagnostic.rule,
-            source_family: diagnostic.source_family
-          )
+          SeverityStamp.apply(diagnostics, @configuration)
         end
 
         private
@@ -513,6 +658,14 @@ module Rigor
           @synthesized_namespaces_snapshot_reader.call
         end
 
+        def quarantined_signatures_snapshot
+          @quarantined_signatures_snapshot_reader.call
+        end
+
+        def env_build_failure_snapshot
+          @env_build_failure_snapshot_reader.call
+        end
+
         def conformance_results_snapshot
           @conformance_results_snapshot_reader.call
         end

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

@@ -7,6 +7,7 @@ require_relative "../diagnostic"
 require_relative "../worker_session"
 require_relative "../run_stats"
 require_relative "../../rbs_extended/conformance_checker"
+require_relative "../../runtime/jit"
 
 module Rigor
   module Analysis
@@ -50,11 +51,16 @@ module Rigor
                        boundary_cross_reporter:, source_rbs_synthesis_reporter:,
                        snapshots:, plugin_registry:, dependency_source_index:,
                        synthetic_method_index:, project_patched_methods:,
-                       analyze_file:, project_scope_seed: -> { {} })
+                       analyze_file:, project_scope_seed: -> { {} }, record_dependencies: false)
           @configuration = configuration
           @cache_store = cache_store
           @explain = explain
           @workers = workers
+          # ADR-46 — the `--incremental` pool path. When true, pool-mode analysis is routed to the fork
+          # backend (the Ractor path lacks the cross-file seed and is off-default) and each worker records its
+          # slice's cross-file reads, marshalled back into `#collected_dependencies` for the runner's graph.
+          @record_dependencies = record_dependencies
+          @collected_dependencies = {}
           @collect_stats = collect_stats
           @buffer = buffer
           @environment_override = environment_override
@@ -70,6 +76,11 @@ module Rigor
           @analyze_file = analyze_file
         end
 
+        # ADR-46 — the per-file cross-file read records the fork pool captured this run (empty unless
+        # `record_dependencies:` and a pool run occurred). The runner folds these into its `file_dependencies`
+        # so the incremental session's dependency graph is refreshed whether analysis ran sequential or pooled.
+        attr_reader :collected_dependencies
+
         # 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
@@ -101,17 +112,7 @@ 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.
-          @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).
-          @snapshots.conformance_results =
-            project_signature_paths? ? RbsExtended::ConformanceChecker.scan(environment.rbs_loader) : []
+          snapshot_project_signature_state(environment)
           result = files.flat_map { |path| @analyze_file.call(path, environment) }
           if @collect_stats
             loader = environment.rbs_loader
@@ -121,6 +122,31 @@ module Rigor
           result
         end
 
+        # The whole-run findings about the project's OWN `signature_paths:` RBS — the namespaces the loader had
+        # to synthesize, the files it had to quarantine, the total env-build failure (if any), and the
+        # `rigor:v1:conforms-to` results. Snapshotted as small plain data (NOT the env) so `#run` can surface
+        # them as diagnostics without rebuilding it.
+        #
+        # All are gated on the project actually declaring `signature_paths:`, for one reason: each forces the
+        # (otherwise lazy) RBS env to build, and doing that when there is no project sig set would warm
+        # `.rigor/cache` on a bare `--no-stats` run. The loader has already memoised each answer, so reading
+        # them here is free.
+        def snapshot_project_signature_state(environment)
+          unless project_signature_paths?
+            @snapshots.synthesized_namespaces = []
+            @snapshots.quarantined_signatures = []
+            @snapshots.conformance_results = []
+            @snapshots.env_build_failure = nil
+            return
+          end
+
+          loader = environment.rbs_loader
+          @snapshots.synthesized_namespaces = loader&.synthesized_namespaces || []
+          @snapshots.quarantined_signatures = loader&.quarantined_signatures || []
+          @snapshots.env_build_failure = loader&.env_build_failure
+          @snapshots.conformance_results = RbsExtended::ConformanceChecker.scan(loader)
+        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
@@ -148,8 +174,19 @@ module Rigor
           :sequential
         end
 
-        # Routes pool-mode analysis to the selected backend.
+        # Routes pool-mode analysis to the selected backend. A `record_dependencies` (ADR-46 `--incremental`)
+        # run is pinned to the fork backend when `fork` is available: only the fork path marshals the
+        # per-worker dependency records back, and the Ractor path additionally lacks the cross-file
+        # `project_scope_seed` its worker would need to record complete edges. Without `fork` (Windows) a
+        # recording run degrades to sequential, which records correctly through `@analyze_file`.
         def dispatch_pool(files)
+          if @record_dependencies
+            return analyze_files_in_fork_pool(files) if Process.respond_to?(:fork)
+
+            return analyze_files_sequentially_fallback(
+              files, reason: "incremental parallelism requires fork; recording sequentially"
+            )
+          end
           case pool_backend
           when :ractor then analyze_files_in_pool(files)
           when :fork   then analyze_files_in_fork_pool(files)
@@ -314,7 +351,8 @@ module Rigor
             synthetic_method_index: synthetic_method_index,
             project_patched_methods: project_patched_methods,
             project_scope_seed: project_scope_seed,
-            source_files: files
+            source_files: files,
+            record_dependencies: @record_dependencies
           )
           # 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.
@@ -337,6 +375,9 @@ module Rigor
           unless degraded.empty?
             degraded.each { |path| results_by_path[path] = session.analyze(path) }
             merge_worker_reporters(session.drain_reporters)
+            # The degraded slice was re-analysed on the parent session, so its dependency records live there,
+            # not in a child payload — fold them in alongside the successful children's.
+            @collected_dependencies.merge!(session.drain_dependencies) if @record_dependencies
           end
 
           diagnostics = Array(session.prepare_diagnostics) +
@@ -348,8 +389,19 @@ module Rigor
         # 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)
+          # Re-arm deferred YJIT in the child. The parent (`check` / `coverage`) armed `enable_after` on a
+          # background thread, but `fork` copies only the calling thread — the sleeping deadline thread does not
+          # survive into the child, so a worker forked before the deadline fires would otherwise run its whole
+          # (dominant) analysis slice un-JITted no matter how long it takes. If the parent already enabled YJIT
+          # before forking (a slow env build pushed the fork past the deadline), the child inherited the enabled
+          # state and this is a no-op; otherwise the child times its own slice and JITs the tail once it proves
+          # long enough — the same amortization contract, per worker. Parallel mode is opted into for large
+          # projects, so a worker slice reliably outlasts the deadline; a small-project worker finishes first and
+          # stays at no-YJIT parity, exactly as the sequential path would.
+          Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
           results = slice.to_h { |path| [path, session.analyze(path)] }
-          payload = { results: results, reporters: session.drain_reporters }
+          payload = { results: results, reporters: session.drain_reporters,
+                      dependencies: session.drain_dependencies }
           File.binwrite(out_path, Marshal.dump(payload))
           exit!(0)
         rescue StandardError
@@ -362,6 +414,12 @@ module Rigor
           loader = session.environment.rbs_loader
           @snapshots.class_decl_paths = loader&.class_decl_paths || {}.freeze
           @snapshots.signature_paths = loader&.signature_paths || [].freeze
+          # The workers each quarantine the same broken file, but they report no diagnostics for it — the row is
+          # a whole-run one. Read it off the parent session's loader so a pooled run says exactly what a
+          # sequential one says. The same reasoning holds for a total env-build failure.
+          @snapshots.quarantined_signatures =
+            project_signature_paths? ? (loader&.quarantined_signatures || []) : []
+          @snapshots.env_build_failure = project_signature_paths? ? loader&.env_build_failure : nil
         end
 
         # Waits for every forked child, merges each successful payload into `results_by_path`, and returns
@@ -374,6 +432,7 @@ module Rigor
             if payload
               results_by_path.merge!(payload.fetch(:results))
               merge_worker_reporters(payload.fetch(:reporters))
+              @collected_dependencies.merge!(payload.fetch(:dependencies, {})) if @record_dependencies
             else
               degraded.concat(child[:slice])
             end
@@ -430,6 +489,9 @@ module Rigor
           loader = environment.rbs_loader
           @snapshots.class_decl_paths = loader&.class_decl_paths || {}.freeze
           @snapshots.signature_paths = loader&.signature_paths || [].freeze
+          @snapshots.quarantined_signatures =
+            project_signature_paths? ? (loader&.quarantined_signatures || []) : []
+          @snapshots.env_build_failure = project_signature_paths? ? loader&.env_build_failure : nil
           diagnostics.unshift(
             Diagnostic.new(
               path: ".rigor.yml", line: 1, column: 1,

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

@@ -22,27 +22,17 @@ module Rigor
       # predicate is injected (it keys on `@workers` / `@buffer`, owned by the Runner) so this collaborator
       # never calls back into it.
       class ProjectPrePasses
-        # Frozen bundle of the project-wide state the pre-passes produce. Mirrors the ivars
-        # `run_project_pre_passes` / `adopt_prebuilt` set on the {Runner}, in the same order they were
-        # assigned.
+        # Frozen bundle of the EAGER (env-input) project-wide state the pre-passes produce — the slots whose
+        # products feed the RBS environment build. Mirrors the env-input ivars `apply_pre_passes_result`
+        # sets on the {Runner}. The cross-file discovery tables live in the separate {Discovery} bundle
+        # ({#discover}), deferred to the analysis path.
         Result = Data.define(
           :plugin_registry,
           :dependency_source_index,
           :cached_plugin_prepare_diagnostics,
           :synthetic_method_index,
           :project_patched_methods,
-          :pre_eval_diagnostics_from_scanner,
-          :discovered_classes,
-          :discovered_def_nodes,
-          :discovered_singleton_def_nodes,
-          :discovered_def_sources,
-          :discovered_superclasses,
-          :discovered_includes,
-          :discovered_class_sources,
-          :discovered_method_visibilities,
-          :discovered_methods,
-          :data_member_layouts,
-          :struct_member_layouts
+          :pre_eval_diagnostics_from_scanner
         )
 
         # @param configuration [Rigor::Configuration]
@@ -58,10 +48,41 @@ module Rigor
           @pool_mode_reader = pool_mode
         end
 
-        # Internal: drives every project-wide pre-pass and returns the results bundled in {Result} in the
-        # order the downstream `#run` body expects. Extracted so `#prepare_project_scan` and the
-        # prebuilt-less `#run` path share one implementation.
-        def run(expansion:) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        # Frozen bundle of the cross-file discovery tables the two whole-project parse passes produce. Split
+        # out of {Result} so the {Runner} can defer these to the analysis (miss) path — a warm cache HIT never
+        # consumes them and so never pays the double parse (see {#discover} + `Runner#ensure_project_discovery`).
+        # The slot names mirror the discovery half of {Result} exactly.
+        Discovery = Data.define(
+          :discovered_classes,
+          :discovered_def_nodes,
+          :discovered_singleton_def_nodes,
+          :discovered_def_sources,
+          :discovered_singleton_def_sources,
+          :discovered_superclasses,
+          :discovered_includes,
+          :discovered_class_sources,
+          :discovered_method_visibilities,
+          :discovered_methods,
+          :data_member_layouts,
+          :struct_member_layouts
+        )
+
+        # Internal: drives every EAGER project-wide pre-pass — the ones whose products feed the RBS
+        # environment build (and therefore the cache key): plugin load + `#prepare`, the ADR-10
+        # dependency-source index, the ADR-16 synthetic-method scanner, and the ADR-17 project-patched
+        # scanner. The cross-file discovery tables are NOT built here (they are consumed only on the analysis
+        # path, so they defer to {#discover}); the {Result} carries `nil` for them, matching {#adopt_prebuilt}.
+        # Extracted so `#prepare_project_scan` and the prebuilt-less `#run` path share one implementation.
+        def run(expansion:)
+          # ADR-90 — resolve the target project's bundle for the plugin isolation layer BEFORE any plugin
+          # code runs: `#prepare` hooks (the rails-routes parse, the activerecord model index) already
+          # invoke `Plugin::Inflector`, and the `Environment.for_project` assignment of the same value
+          # happens only after the pre-passes. Without this, a standalone install degrades inflection for
+          # exactly the prepare-time checks even though the analyzed project's bundle carries activesupport.
+          Plugin::Isolation.target_bundle_root ||= Environment::BundleSigDiscovery.resolve_bundle_path(
+            bundle_path: @configuration.bundler_bundle_path,
+            auto_detect: @configuration.bundler_auto_detect
+          )&.to_s
           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
@@ -91,31 +112,53 @@ module Rigor
           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.
-          discovered_classes =
-            Inference::ScopeIndexer.discovered_classes_for_paths(expansion.fetch(:files), buffer: @buffer)
-          # ADR-24 slice 2 — cross-file def-node + class->superclass index so an implicit-self call inside a
-          # subclass resolves a superclass `def` declared in a sibling file. One extra parse pass over the
-          # project; shares the cost profile of the class-discovery pass above.
-          def_index =
-            Inference::ScopeIndexer.discovered_def_index_for_paths(expansion.fetch(:files), buffer: @buffer)
           Result.new(
             plugin_registry: plugin_registry,
             dependency_source_index: dependency_source_index,
             cached_plugin_prepare_diagnostics: cached_plugin_prepare_diagnostics,
             synthetic_method_index: synthetic_method_index,
             project_patched_methods: project_patched_methods,
-            pre_eval_diagnostics_from_scanner: pre_eval_diagnostics_from_scanner,
-            discovered_classes: discovered_classes,
+            pre_eval_diagnostics_from_scanner: pre_eval_diagnostics_from_scanner
+          )
+        end
+
+        # Internal: the DEFERRED cross-file discovery pre-pass, run lazily on the analysis (miss) path only —
+        # a warm cache HIT skips it entirely. Builds two whole-project tables in ONE walk:
+        # - Class discovery: every project file's `class Foo` / `module Bar` so a `Foo.method_call` receiver
+        #   in one file resolves a `class Foo` declared in a sibling file (without it, lexical lookup fell
+        #   back to stdlib `::Foo` for any user class shadowing a stdlib name).
+        # - ADR-24 slice 2 def-node / superclass / include index so an implicit-self call inside a subclass
+        #   resolves a superclass `def` declared in a sibling file.
+        # Returns a frozen {Discovery} bundle; the {Runner} adopts it onto its discovery ivars. Both tables
+        # share ONE parse per file via `discovered_project_index_for_paths` — the file is parsed, both
+        # collectors walk the tree, and the AST is dropped before the next file (peak RSS stays flat).
+        def discover(expansion:)
+          build_discovery(
+            Inference::ScopeIndexer.discovered_project_index_for_paths(expansion.fetch(:files), buffer: @buffer)
+          )
+        end
+
+        # ADR-85 WD2 — the seed-bundle twin of {#discover}. Rebuilds the discovery tables by folding the prior
+        # run's per-file bundles (re-walking only changed files) and returns `[Discovery, refreshed_bundles]`;
+        # the runner adopts the Discovery and exposes the bundles for the session to persist. On a cold run
+        # (`seed_bundles` empty) this is `#discover` plus a fresh bundle set — the discovery index is identical.
+        def discover_from_bundles(expansion:, seed_bundles:)
+          index = Inference::ScopeIndexer.discovered_project_index_incremental(
+            expansion.fetch(:files), seed_bundles: seed_bundles, buffer: @buffer
+          )
+          [build_discovery(index), index.fetch(:bundles)]
+        end
+
+        # Builds the {Discovery} bundle from a `{ classes:, def_index: }` index hash (shared by the plain and
+        # seed-bundle discovery paths).
+        def build_discovery(index)
+          def_index = index.fetch(:def_index)
+          Discovery.new(
+            discovered_classes: index.fetch(:classes),
             discovered_def_nodes: def_index.fetch(:def_nodes),
             discovered_singleton_def_nodes: def_index.fetch(:singleton_def_nodes),
             discovered_def_sources: def_index.fetch(:def_sources),
+            discovered_singleton_def_sources: def_index.fetch(:singleton_def_sources),
             discovered_superclasses: def_index.fetch(:superclasses),
             discovered_includes: def_index.fetch(:includes),
             discovered_class_sources: def_index.fetch(:class_sources),
@@ -142,8 +185,8 @@ module Rigor
 
         # Translates a prebuilt {ProjectScan} snapshot supplied to `Runner.new(prebuilt: ...)` into a
         # {Result} the runner adopts the same way it adopts a fresh pre-pass run. The discovery tables are
-        # not part of the snapshot (the LSP path seeds an empty project scope), so they stay at their
-        # frozen-empty constructor defaults.
+        # not part of the snapshot (the LSP path seeds an empty project scope), and `Runner#ensure_project_discovery`
+        # is a no-op under `prebuilt`, so they stay at their frozen-empty constructor defaults.
         def adopt_prebuilt(scan)
           Result.new(
             plugin_registry: scan.plugin_registry,
@@ -151,21 +194,24 @@ module Rigor
             cached_plugin_prepare_diagnostics: scan.plugin_prepare_diagnostics,
             synthetic_method_index: scan.synthetic_method_index,
             project_patched_methods: scan.project_patched_methods,
-            pre_eval_diagnostics_from_scanner: scan.pre_eval_diagnostics,
-            discovered_classes: nil,
-            discovered_def_nodes: nil,
-            discovered_singleton_def_nodes: nil,
-            discovered_def_sources: nil,
-            discovered_superclasses: nil,
-            discovered_includes: nil,
-            discovered_class_sources: nil,
-            discovered_method_visibilities: nil,
-            discovered_methods: nil,
-            data_member_layouts: nil,
-            struct_member_layouts: nil
+            pre_eval_diagnostics_from_scanner: scan.pre_eval_diagnostics
           )
         end
 
+        # ADR-88 WD1 — load the project's plugins and run every `#prepare` hook, returning the prepared
+        # {Rigor::Plugin::Registry} WITHOUT the synthetic-method / dependency-source / pre-eval scanners. The
+        # incremental fact-surface fingerprint probe ({Analysis::PluginFactFingerprint}) uses this to read the
+        # ADR-9 fact store + drive the ADR-60 producers without paying for the full pre-pass or building the RBS
+        # environment. `prepare` runs unconditionally here — the probe is always sequential (its `pool_mode?`
+        # reader returns false), so the pool-mode skip in {#run} does not apply. Prepare diagnostics are
+        # discarded: a plugin that raises in `#prepare` publishes no facts, so its surface is simply absent from
+        # the fingerprint, exactly as it would be absent from analysis.
+        def prepared_registry
+          registry = load_plugins
+          plugin_prepare_diagnostics(registry) unless registry.empty?
+          registry
+        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.