rigortype 0.3.1 → 0.3.2

data/lib/rigor/analysis/run_cache_key.rb

@@ -13,6 +13,7 @@ end
 
 require_relative "../version"
 require_relative "../cache/descriptor"
+require_relative "../cache/engine_source"
 require_relative "../cache/rbs_descriptor"
 require_relative "../environment/default_libraries"
 
@@ -51,7 +52,7 @@ module Rigor
       def descriptor(configuration:, files:, explain:, rbs_config_entries:)
         Cache::Descriptor.new(
           gems: [Cache::RbsDescriptor.rbs_gem_entry],
-          configs: rbs_config_entries + [
+          configs: rbs_config_entries + engine_source_entries + [
             config_entry("configuration", Marshal.dump(configuration.to_h)),
             config_entry("engine",
                          "#{Rigor::VERSION}:#{Cache::Descriptor::SCHEMA_VERSION}:#{explain}"),
@@ -62,6 +63,21 @@ module Rigor
         nil
       end
 
+      # Issue #285 — the `engine` slot above pins the engine by VERSION, which identifies the source only
+      # for a released gem. A checkout (a contributor's, or a `bundle add rigor, github:` clone) gets one
+      # extra slot carrying a digest of the engine's own source, so editing `lib/rigor/inference/*.rb` no
+      # longer replays the pre-edit diagnostics out of a warm cache. A released install adds NO entry, so
+      # its key — and its hit rate — are exactly what they were.
+      #
+      # {Cache::EngineSource::Unavailable} is left to propagate into `descriptor`'s rescue, which disables
+      # the cache for the run: an engine we cannot identify must not be keyed by its version alone.
+      def engine_source_entries
+        identity = Cache::EngineSource.process_identity
+        return [] if identity.nil?
+
+        [config_entry("engine-source", identity)]
+      end
+
       def config_entry(key, payload)
         Cache::Descriptor::ConfigEntry.new(key: key, value_hash: Digest::SHA256.hexdigest(payload))
       end

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

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+require_relative "../../environment"
+require_relative "../../runtime/jit"
+
+module Rigor
+  module Analysis
+    class Runner
+      # Issue #142 — LSP multi-buffer dispatch. Runs one independent single-buffer `Runner#run` call per
+      # dirty buffer due to publish, distributed across a fork-based worker pool, reusing the SAME warm
+      # `Environment` + `ProjectScan` a sequential per-buffer publish already shares via
+      # `Rigor::LanguageServer::ProjectContext` — so a batch pays zero extra RBS-env-build or plugin
+      # `#prepare` cost over today's sequential path; only the per-file inference itself moves off the main
+      # process.
+      #
+      # Deliberately a SIBLING of {PoolCoordinator}, not a method on it. PoolCoordinator's unit of dispatch is
+      # "one shared {WorkerSession}, a project's files split across it" — that shape needs cross-worker
+      # reporter merge because ONE session's reporters accumulate per file. This dispatcher's unit of
+      # dispatch is "one COMPLETE `Runner#run` call per job", and each job is already fully self-contained
+      # (its own fresh reporters, its own severity-profile stamp, its own diagnostic aggregation) by
+      # construction — there is nothing to merge back except the diagnostics array itself. Forcing this
+      # through PoolCoordinator's constructor (which exists to wire ONE Runner's own mutable ivar surface
+      # through reader procs) would buy nothing.
+      #
+      # Sequential-equivalence contract: each job's diagnostics are EXACTLY what
+      #   `Runner.new(buffer:, prebuilt:, environment:, configuration:, cache_store:, collect_stats: false)
+      #     .run([binding.logical_path]).diagnostics`
+      # returns today — the same call `LanguageServer::DiagnosticPublisher#run_analysis` already makes
+      # inline for a single buffer. This dispatcher only changes WHERE that call executes (a forked child vs.
+      # the parent), never what it computes — so two runs of the same dirty set publish byte-identical
+      # results, and a run that cannot use the pool falls back to running every job in-process rather than
+      # failing.
+      #
+      # Buffer-substitution correctness (the highest-risk part of #142): EVERY job carries its OWN
+      # `BufferBinding` — a fork worker never shares one session-wide binding the way `PoolCoordinator`'s
+      # editor-mode single-buffer contract does. A binding not threaded all the way into the child's `Runner`
+      # would make that worker parse the file as it sits on disk and publish plausible-looking, stale
+      # diagnostics; every code path below carries `binding` explicitly rather than defaulting to nil.
+      class BufferPoolDispatcher
+        # Below this many bindings, `#analyze` takes the sequential in-process path even when the pool is
+        # otherwise available (workers positive, `fork` available, `cache_store` present). Reviewed and
+        # required for #142 to merge: a throwaway measurement against this repo's own `lib/rigor` (46-353
+        # files, ~1-2ms/file analysis once `Environment` + `ProjectScan` are warm — the exact steady state
+        # this dispatcher runs in) showed the FORK + `Marshal` + `Process.waitpid2` overhead exceeding the
+        # parallelism win below roughly N=12, and only paying off cleanly from N=16 up (interleaved,
+        # median-of-5, `workers: 8`):
+        #
+        #   N=8   sequential=0.018s  pooled=0.027s  speedup=0.66x  (pool SLOWER)
+        #   N=12  sequential=0.021s  pooled=0.021s  speedup=1.00x  (break-even, noisy)
+        #   N=16  sequential=0.028s  pooled=0.025s  speedup=1.09x
+        #   N=24  sequential=0.038s  pooled=0.026s  speedup=1.47x
+        #   N=32  sequential=0.050s  pooled=0.029s  speedup=1.73x
+        #
+        # 16 sits with margin ABOVE the noisy break-even (12), not at it — full method + table in #142's PR
+        # description.
+        #
+        # This is deliberately a FIXED default, not a per-project auto-calibrated one. Per-file analysis cost
+        # varies enormously by project — this repo's own `lib/rigor` is ~1-2ms/file warm; a large Rails
+        # controller or model file can cost far more, which would make pooling profitable at a MUCH smaller N
+        # there. A cost-aware gate — deciding from the publisher's own observed per-publish duration instead
+        # of a bare file count — would adapt automatically, but needs plumbing that does not exist today (the
+        # publisher tracks no timing history) and is disproportionate to what closing #142 calls for; it is a
+        # reasonable follow-up, not attempted here. A project whose crossover sits at a different N overrides
+        # via `RIGOR_LSP_POOL_MIN_BATCH` (mirrors `RIGOR_RACTOR_WORKERS`'s override shape).
+        DEFAULT_MIN_BATCH_SIZE = 16
+
+        # @return [Integer] `RIGOR_LSP_POOL_MIN_BATCH` when set to a non-empty value, else
+        #   {DEFAULT_MIN_BATCH_SIZE}.
+        def self.resolve_min_batch_size
+          env_value = ENV.fetch("RIGOR_LSP_POOL_MIN_BATCH", nil)
+          return DEFAULT_MIN_BATCH_SIZE if env_value.nil? || env_value.empty?
+
+          Integer(env_value)
+        end
+
+        # @param configuration [Rigor::Configuration]
+        # @param cache_store [Rigor::Cache::Store, nil]
+        # @param environment [Rigor::Environment] the warm, shared per-session Environment
+        #   (`ProjectContext#environment`) every job's Runner reuses instead of rebuilding.
+        # @param prebuilt [Rigor::Analysis::ProjectScan] the warm, shared pre-pass snapshot
+        #   (`ProjectContext#project_scan`) every job's Runner adopts instead of re-scanning.
+        # @param workers [Integer] pool size. `#analyze` degrades to sequential in-process execution — one
+        #   job at a time, no `fork` — when fewer than 2 bindings are submitted, fewer than `min_batch_size`
+        #   bindings are submitted, `workers` is not positive, `fork` is unavailable on this platform, or
+        #   `cache_store` is nil. The middle two are the fork-pool-is-not-worth-it-yet gate documented on
+        #   {DEFAULT_MIN_BATCH_SIZE}; the last two mirror
+        #   {PoolCoordinator#analyze_files_in_pool}'s own fork-pool preconditions.
+        # @param min_batch_size [Integer] see {DEFAULT_MIN_BATCH_SIZE}. Exposed as a constructor param
+        #   (rather than read from the env internally) purely for spec control; production callers get the
+        #   resolved default.
+        def initialize(configuration:, cache_store:, environment:, prebuilt:, workers:,
+                       min_batch_size: self.class.resolve_min_batch_size)
+          @configuration = configuration
+          @cache_store = cache_store
+          @environment = environment
+          @prebuilt = prebuilt
+          @workers = workers
+          @min_batch_size = min_batch_size
+        end
+
+        # Runs one `Runner#run([binding.logical_path])` per binding and returns `Array<Array<Diagnostic>>` —
+        # one diagnostics array per input binding, IN INPUT ORDER. The parent always absorbs worker results
+        # re-indexed by POSITION, never keyed on path, so two bindings that happen to share a logical path
+        # (should not occur — one dirty buffer per URI — but is not assumed away) can never collide or
+        # silently overwrite one another.
+        def analyze(bindings)
+          return [] if bindings.empty?
+          return bindings.map { |binding| run_one(binding) } unless dispatchable?(bindings)
+
+          dispatch_in_fork_pool(bindings)
+        end
+
+        private
+
+        def dispatchable?(bindings)
+          bindings.size > 1 && bindings.size >= @min_batch_size &&
+            @workers.is_a?(Integer) && @workers.positive? &&
+            Process.respond_to?(:fork) && !@cache_store.nil?
+        end
+
+        # One job, run exactly as `DiagnosticPublisher#run_analysis` runs it today — the equivalence contract
+        # this whole class exists to preserve.
+        def run_one(binding)
+          Runner.new(
+            configuration: @configuration, cache_store: @cache_store, collect_stats: false,
+            buffer: binding, prebuilt: @prebuilt, environment: @environment
+          ).run([binding.logical_path]).diagnostics
+        end
+
+        def dispatch_in_fork_pool(bindings)
+          # Pre-warm the memoized class registry on the parent so every forked child inherits it via
+          # copy-on-write instead of each re-computing it — mirrors `PoolCoordinator`'s own pool entry points.
+          Environment::ClassRegistry.default
+
+          worker_count = [@workers, bindings.size].min
+          indexed = bindings.each_with_index.to_a
+          slices = indexed.each_slice((indexed.size.to_f / worker_count).ceil).to_a
+          results_by_index = {}
+
+          degraded = Dir.mktmpdir("rigor-lsp-buffer-pool") do |tmpdir|
+            children = slices.each_with_index.map do |slice, worker_index|
+              out_path = File.join(tmpdir, "worker-#{worker_index}")
+              { pid: fork { run_fork_worker(slice, out_path) }, slice: slice, out_path: out_path }
+            end
+            collect_fork_results(children, results_by_index)
+          end
+
+          degraded.each do |slice|
+            slice.each { |binding, index| results_by_index[index] = run_one(binding) }
+          end
+
+          indexed.map { |_binding, index| results_by_index.fetch(index, []) }
+        end
+
+        # Child-process body. `fork` copies only the calling thread, so any deferred-YJIT deadline the parent
+        # armed does not survive into this child — re-arm it first, mirroring
+        # `PoolCoordinator#run_fork_worker`. In practice the LSP process enables YJIT immediately at boot
+        # (`Runtime::Jit.enable_now` in `LspCommand`, never the deferred-deadline path), so this is a cheap
+        # no-op today — kept for parity with every other fork site and in case that boot-time choice changes.
+        # `exit!` skips `at_exit` / stdio flush; the payload is already durable on disk by then.
+        def run_fork_worker(slice, out_path)
+          Runtime::Jit.rearm_after_fork
+          results = slice.to_h { |binding, index| [index, run_one(binding)] }
+          File.binwrite(out_path, Marshal.dump(results))
+          exit!(0)
+        rescue StandardError
+          exit!(1)
+        end
+
+        # Waits for every forked child, merges each successful payload into `results_by_index`, and returns
+        # the (binding, index) slices whose worker exited abnormally, for in-process degrade.
+        def collect_fork_results(children, results_by_index)
+          degraded = []
+          children.each do |child|
+            _, status = Process.waitpid2(child[:pid])
+            payload = fork_worker_payload(status, child[:out_path])
+            if payload
+              results_by_index.merge!(payload)
+            else
+              degraded << child[:slice]
+            end
+          end
+          degraded
+        end
+
+        # @return [Hash, nil] the child's `{index => diagnostics}` 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)
+
+          Marshal.load(File.binread(out_path)) # rubocop:disable Security/MarshalLoad
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -557,19 +557,37 @@ module Rigor
           return [] if @source_rbs_synthesis_reporter.empty?
 
           @source_rbs_synthesis_reporter.entries.map do |entry|
-            Diagnostic.new(
-              path: entry.path, line: 1, column: 1,
-              message: "plugin `#{entry.plugin_id}` failed to synthesise RBS from this file: " \
-                       "#{entry.message}. The file's analysis falls back to no inline-RBS " \
-                       "contribution. Fix the inline-RBS comment grammar or remove the " \
-                       "annotation to silence this diagnostic.",
-              severity: :info,
-              rule: "source-rbs-synthesis-failed",
-              source_family: :builtin
-            )
+            entry.kind == :not_honoured ? not_honoured_diagnostic(entry) : synthesis_failed_diagnostic(entry)
           end
         end
 
+        def synthesis_failed_diagnostic(entry)
+          Diagnostic.new(
+            path: entry.path, line: 1, column: 1,
+            message: "plugin `#{entry.plugin_id}` failed to synthesise RBS from this file: " \
+                     "#{entry.message}. The file's analysis falls back to no inline-RBS " \
+                     "contribution. Fix the inline-RBS comment grammar or remove the " \
+                     "annotation to silence this diagnostic.",
+            severity: :info,
+            rule: "source-rbs-synthesis-failed",
+            source_family: :builtin
+          )
+        end
+
+        # ADR-32 WD12 — the synthesis SUCCEEDED; one annotation inside it was parsed and then contributed
+        # nothing. Distinct from the failure above in the only way that matters to the reader: the rest of
+        # the file's annotations ARE in effect, so the advice is to fix one comment, not to distrust the file.
+        def not_honoured_diagnostic(entry)
+          Diagnostic.new(
+            path: entry.path, line: 1, column: 1,
+            message: "plugin `#{entry.plugin_id}` parsed an inline-RBS annotation in this file but did " \
+                     "not honour it: #{entry.message} The file's other annotations are unaffected.",
+            severity: :info,
+            rule: "source-rbs-annotation-not-honoured",
+            source_family: :builtin
+          )
+        end
+
         # ADR-10 slice 5c — drains the per-run {DependencySourceInference::BoundaryCrossReporter} into
         # `dynamic.dependency-source.boundary-cross` `:info` diagnostics. Each event flags a call site
         # where RBS dispatch produced a concrete answer AND a `mode: :full` opt-in gem's source catalog

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

@@ -389,16 +389,13 @@ 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)
+          # Re-arm deferred YJIT in the child: the parent's deadline thread does not survive `fork`, so a worker
+          # forked before the deadline fires would otherwise run its whole (dominant) analysis slice un-JITted
+          # no matter how long it takes. {Runtime::Jit.rearm_after_fork} carries what is *left* of the parent's
+          # window, so the run's amortization deadline stays one deadline rather than one per worker. Parallel
+          # mode is opted into for large projects, so a slice reliably outlasts the remainder; a small-project
+          # worker finishes first and stays at no-YJIT parity, exactly as the sequential path would.
+          Runtime::Jit.rearm_after_fork
           results = slice.to_h { |path| [path, session.analyze(path)] }
           payload = { results: results, reporters: session.drain_reporters,
                       dependencies: session.drain_dependencies }

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

@@ -186,7 +186,9 @@ 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), and `Runner#ensure_project_discovery`
-        # is a no-op under `prebuilt`, so they stay at their frozen-empty constructor defaults.
+        # is a no-op under `prebuilt`, so they stay at their frozen-empty constructor defaults — unless the
+        # caller opted into `Runner.new(discovery_seed:)` (issue #260), which seeds the per-file scopes
+        # directly and leaves these ivars alone.
         def adopt_prebuilt(scan)
           Result.new(
             plugin_registry: scan.plugin_registry,

data/lib/rigor/analysis/runner.rb

@@ -40,6 +40,7 @@ require_relative "runner/run_snapshots"
 require_relative "runner/project_pre_passes"
 require_relative "runner/pool_coordinator"
 require_relative "runner/diagnostic_aggregator"
+require_relative "runner/buffer_pool_dispatcher"
 
 module Rigor
   module Analysis
@@ -95,12 +96,19 @@ module Rigor
       #   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.
+      # @param discovery_seed [Hash, nil] issue #260 — opt-in cross-file discovery tables, keyed by
+      #   {Scope::DiscoveryIndex} slot name, seeded onto every per-file scope through
+      #   `project_scope_seed_tables`. The ONE deliberate exception to "a `prebuilt:` runner carries no
+      #   discovery tables": {Protection::DiagnosticOracle} threads the table set Tier 2's site filter already
+      #   judges anchors against, so a site admitted because a sibling-file class resolved is also a site the
+      #   oracle can kill at. nil (the default) leaves the prebuilt/LSP contract byte-identical.
       def initialize(configuration:, explain: false, # rubocop:disable Metrics/ParameterLists,Metrics/AbcSize,Metrics/MethodLength
                      cache_store: Cache::Store.new(root: DEFAULT_CACHE_ROOT),
                      plugin_requirer: nil, workers: 0, collect_stats: true,
                      buffer: nil, prebuilt: nil, environment: nil,
                      record_dependencies: false, record_self_calls: false, analyze_only: nil,
-                     seed_bundles: nil, collect_seed_bundles: false)
+                     seed_bundles: nil, collect_seed_bundles: false, param_inferred_types: nil,
+                     discovery_seed: nil)
         @configuration = configuration
         @explain = explain
         @cache_store = enforce_read_only_cache(cache_store, buffer)
@@ -140,6 +148,16 @@ module Rigor
         @collect_seed_bundles = collect_seed_bundles
         @restored_seed_bundles = seed_bundles || {}
         @seed_bundles = {}.freeze
+        # ADR-67 WD6c lift — a precomputed inferred-param table. When the incremental session already ran the
+        # collector (it must, to diff the table against its snapshot BEFORE deciding the re-analyse closure),
+        # it hands the result here so `seed_parameter_inference` seeds without a second whole-project collect
+        # — and so the table the diff was decided on and the table this run seeds from are the SAME object,
+        # not merely an equal recomputation. nil (the default) keeps the runner self-sufficient.
+        @param_inferred_types_override = param_inferred_types
+        # Issue #260 — the opt-in cross-file discovery seed (see the `discovery_seed:` doc above). Frozen and
+        # never mutated; `project_scope_seed_tables` starts from a copy of it and lets any table this run
+        # actually computed win.
+        @discovery_seed = discovery_seed&.freeze
         @file_dependencies = {}
         @plugin_registry = Plugin::Registry::EMPTY
         @dependency_source_index = DependencySourceInference::Index::EMPTY
@@ -324,6 +342,32 @@ module Rigor
         result.transform_values(&:freeze).freeze
       end
 
+      # ADR-67 WD6c lift — the inferred-param table this run seeded from (frozen; empty when
+      # `parameter_inference:` is off or the pre-pass failed soft). The incremental session reads it back
+      # after a baseline so the snapshot records the seeds the cached diagnostics were computed under.
+      def param_inferred_types
+        @project_param_inferred_types
+      end
+
+      # ADR-67 WD6c lift — computes the whole-project inferred-param table without running an analysis.
+      # The incremental session calls this BEFORE deciding its re-analyse closure: the table's diff against
+      # the snapshot's stored table is what invalidates a callee whose seeds moved because a *caller* file
+      # changed. Same collector invocation as {#seed_parameter_inference} (one round, same workers), so the
+      # session-computed table and an in-run collect are byte-identical by construction. Fails soft to the
+      # empty table — which the caller's diff then treats as "every stored entry removed", the conservative
+      # direction (those callees re-check).
+      def collect_param_inference_table(files)
+        return {}.freeze unless @configuration.parameter_inference
+
+        environment = @pool_coordinator.resolve_sequential_environment(source_files: files)
+        Inference::ParameterInferenceCollector.collect(
+          files: files, environment: environment,
+          target_ruby: @configuration.target_ruby, max_rounds: 1, workers: @workers
+        )
+      rescue StandardError
+        {}.freeze
+      end
+
       # ADR-89 WD2 — the per-method observed-key return summaries the run's ADR-84 return memo just captured.
       # For each project method with live memo entries, a bounded `{ keys:, returns:, effects: }` summary the
       # incremental session persists: `keys` the observed `[receiver, arg_types]` type tuples, `returns` their
@@ -511,6 +555,11 @@ module Rigor
       def seed_parameter_inference(expansion, environment)
         return environment unless @configuration.parameter_inference
 
+        if @param_inferred_types_override
+          @project_param_inferred_types = @param_inferred_types_override
+          return environment
+        end
+
         files = expansion.fetch(:files)
         environment ||= @pool_coordinator.resolve_sequential_environment(source_files: files)
         @project_param_inferred_types = Inference::ParameterInferenceCollector.collect(
@@ -638,7 +687,9 @@ module Rigor
       # surface. The cross-file discovery tables are NOT carried here — `#run` (prebuilt-less) and
       # `adopt_prebuilt` both leave them at their frozen-empty constructor defaults, and the analysis path
       # fills them lazily via {#ensure_project_discovery}. The prebuilt (LSP) path never fills them, matching
-      # the original adopt behaviour that seeded an empty project scope.
+      # the original adopt behaviour that seeded an empty project scope — with ONE deliberate exception, the
+      # opt-in `discovery_seed:` constructor seam (issue #260), which bypasses the ivars entirely and rides
+      # `project_scope_seed_tables`. A prebuilt runner constructed without it is unchanged.
       def apply_pre_passes_result(result)
         @plugin_registry = result.plugin_registry
         @dependency_source_index = result.dependency_source_index
@@ -669,7 +720,9 @@ module Rigor
       # Internal: builds the deferred cross-file discovery tables at most once per run and adopts them.
       # Memoised on `@project_discovery_done` (reset at the start of `#run`). No-op under `@prebuilt` — the
       # LSP path deliberately seeds an empty project scope from a snapshot that carries no discovery tables,
-      # so forcing a build there would change that contract. Called eagerly from `#run` for the recording /
+      # so forcing a build there would change that contract. A caller that DOES want cross-file knowledge under
+      # `prebuilt:` supplies it explicitly through `discovery_seed:` (issue #260) rather than by re-walking the
+      # project here. Called eagerly from `#run` for the recording /
       # subset (ADR-46) modes and lazily from `#assemble_run_diagnostics` on the analysis path, so a warm
       # cache HIT (which never assembles) never pays the double parse.
       def ensure_project_discovery(expansion)
@@ -757,11 +810,18 @@ module Rigor
       def target_files(expansion)
         files = expansion.fetch(:files)
         # ADR-46 slice 2 — restrict the analyzed set to the affected closure while the pre-pass (run
-        # separately over `expansion`'s full file list) keeps the cross-file index complete. Buffer mode
-        # takes precedence — its single logical path is the analyzed set.
-        files = files.select { |path| @analyze_only.include?(path) } if @analyze_only
+        # separately over `expansion`'s full file list) keeps the cross-file index complete.
+        if @analyze_only
+          # Editor mode option B (#146) — with BOTH set, the closure wins and the buffer is one member of it.
+          # The logical path joins even when it is not on disk under `paths:` (design § "Failure envelope"),
+          # the same allowance option A makes below.
+          files = files.select { |path| @analyze_only.include?(path) }
+          files |= [@buffer.logical_path] if @buffer && @analyze_only.include?(@buffer.logical_path)
+          return files
+        end
         return files if @buffer.nil?
 
+        # Editor mode option A — no closure, so the buffer's single logical path IS the analyzed set.
         [@buffer.logical_path]
       end
 
@@ -1023,8 +1083,12 @@ module Rigor
       # The cross-file pre-pass tables {#seed_project_scope} applies, as a plain Hash so the fork-pool path
       # can hand the same seed to its {WorkerSession} (whose per-file scopes would otherwise miss every
       # cross-file def — ADR-15 sequential-equivalence contract).
+      #
+      # Issue #260 — an opt-in `discovery_seed:` is the BASE of the result, so every table this run computed
+      # for itself still wins. Under `prebuilt:` (the only caller that passes one today) the run computes
+      # none, so the seed applies wholesale.
       def project_scope_seed_tables
-        tables = {}
+        tables = discovery_seed_base
         # ADR-84 WD2 — the run-scope token rides the same seed so the fork/Ractor `WorkerSession` scopes
         # bucket identically to the sequential path.
         tables[:run_generation] = @run_generation if @run_generation
@@ -1055,6 +1119,13 @@ module Rigor
         tables
       end
 
+      # Issue #260 — the mutable starting point {#project_scope_seed_tables} fills in: a copy of the opt-in
+      # `discovery_seed:` when one was supplied, otherwise the empty Hash every other run has always started
+      # from. Extracted so the seed costs {#project_scope_seed_tables} no branch of its complexity budget.
+      def discovery_seed_base
+        @discovery_seed ? @discovery_seed.dup : {}
+      end
+
       # ADR-46 — seed the instance + singleton `"path:line"` def-source tables (each only when non-empty).
       # Extracted to keep {#project_scope_seed_tables} under the complexity budget. The singleton table (slice 4
       # extension) rides the same seed so a pooled `WorkerSession` records singleton symbol edges identically.