rigortype 0.3.1 → 0.3.3

data/lib/rigor/analysis/incremental_session.rb

@@ -62,9 +62,14 @@ module Rigor
       #   pool records each worker's cross-file reads and marshals them back (PoolCoordinator), so the
       #   dependency graph a pooled recheck rebuilds equals the sequential one.
       def initialize(configuration:, paths: nil, environment: nil, cache_store: nil, plugin_requirer: nil,
-                     workers: 0)
+                     workers: 0, buffer: nil)
         @configuration = configuration
         @paths = paths
+        # Editor mode option B (#146) — the in-flight buffer, threaded into every internal Runner so the
+        # pre-passes and the closure re-analysis read the editor's bytes at the logical path. A session
+        # holding one MUST NOT persist its snapshot: its `@digests` and `@cache` describe bytes that exist
+        # only in the editor. {#run_buffer_recheck} is the only entry that honours that.
+        @buffer = buffer
         @environment = environment
         @cache_store = cache_store
         @plugin_requirer = plugin_requirer
@@ -93,6 +98,13 @@ module Rigor
         # ADR-89 WD2 — per-def observed-key return summaries: [path, symbol] => { keys:, returns:, effects: }.
         # Harvested from the ADR-84 return memo after each run; drives the behavioural-stability gate.
         @return_summaries = {}
+        # ADR-67 WD6c lift — the `parameter_inference:` seed table the cached diagnostics were computed
+        # under (`{}` when the gate is off — the gate state is constant across a snapshot's lifetime because
+        # the configuration is part of the global fingerprint). A recheck recomputes the table fresh and
+        # diffs it against this: the pre-pass is whole-project by design, so the fresh table is ground truth
+        # and a missing invalidation edge is impossible by construction — the reason this is a table diff
+        # and not the caller→callee edge recording #204 first sketched.
+        @param_table = {}
         # ADR-88 WD1 — the plugin fact-surface digest computed for THIS invocation (nil until a
         # `#run_incremental` pass runs / a plugin-free project) and the reporting flags a caller (the CLI
         # banner + `--cache-stats`) reads after `#run_incremental`. `@last_runner` is the analysis runner the
@@ -120,6 +132,9 @@ module Rigor
         @seed_bundles = runner.seed_bundles # ADR-85 WD2 — the freshly built bundle set for the next run.
         absorb_dependency_graph(runner)
         @return_summaries = runner.return_summaries # ADR-89 WD2 — the full-run behavioural surface.
+        # ADR-67 WD6c lift — the seed table the runner's own pre-pass computed ({} when the gate is off).
+        # Reading it back, rather than computing it here, keeps the baseline single-collect.
+        @param_table = runner.param_inferred_types
         @cache = per_file(diagnostics)
         @digests = @analyzed.to_h { |path| [path, pack_digest(path)] }
         diagnostics
@@ -134,30 +149,79 @@ module Rigor
         added = current - previous
         removed = previous - current
         changed = changed_paths(current & previous)
-        affected = affected_closure(changed, added, removed)
+        # ADR-67 WD6c lift — recompute the whole-project inferred-param table BEFORE deciding the closure,
+        # and diff it against the snapshot's copy: an entry that moved (because a caller's argument type
+        # changed, a caller appeared, or one vanished) invalidates the CALLEE's file and its symbol
+        # dependents, none of which the file-digest tier can see (the callee's text is unchanged).
+        fresh_params = fresh_param_table(current, changed, added, removed)
+        param_files, param_pairs = param_seed_invalidation(fresh_params)
+        affected = affected_closure(changed, added, removed, param_files, param_pairs)
         analyze_set = affected & current
-        runner = build_runner(analyze_only: analyze_set, record_dependencies: true)
+        # The freshly collected table is handed to the runner so the run seeds from the SAME table the diff
+        # was decided on (and the collector runs once per recheck, not twice).
+        runner = build_runner(analyze_only: analyze_set, record_dependencies: true,
+                              param_inferred_types: fresh_params)
         fresh = run_runner(runner).diagnostics
         @last_runner = runner # ADR-88 WD1 — the post-hoc fact-surface fingerprint reads this prepared registry.
         reused = (current & previous) - affected.to_a
         merged = fresh + reused.flat_map { |path| @cache[path] || [] }
         absorb(runner, fresh, current, analyze_set, removed)
+        @param_table = fresh_params
         Recheck.new(diagnostics: merged, changed: changed.to_set, added: added.to_set,
                     removed: removed.to_set, affected: affected, reused: reused.to_set)
       end
 
+      # Editor mode option B (#146) — a whole-project recheck with the editor's buffer substituted for one
+      # file, for the CLI's `--incremental --tmp-file=X --instead-of=Y`. Returns the {Recheck} when the
+      # snapshot could be reused, or nil when it could not — the caller then falls back to option A
+      # (single-file scope) rather than paying a full baseline, because that baseline would repeat on every
+      # keystroke: this session MUST NOT save, so nothing it computes can warm the next invocation.
+      #
+      # Not saving is the whole safety story. `@digests` and `@cache` here describe the buffer's bytes, which
+      # exist only in the editor; persisting them would make the next `rigor check --incremental` believe the
+      # on-disk file was already analysed in a state it was never in.
+      def run_buffer_recheck(snapshot:, fingerprint:)
+        Cache::FileDigest.with_run(strict: @configuration.cache_validation_strict?) do
+          restored = fingerprint && snapshot.load(fingerprint: fingerprint)
+          break nil unless restored
+
+          restore(restored)
+          result = recheck
+          adopt_plugin_fact_fingerprint
+          # The ADR-88 gate applies unchanged: if the plugin fact surface moved, the cache-served files may be
+          # stale. A full baseline is the sound answer for `--incremental`, but in editor mode it is also the
+          # latency this mode exists to avoid, so decline and let the caller drop to single-file scope.
+          break nil unless @plugin_fact_reusable.reusable_against?(restored.plugin_fact_digest)
+
+          result
+        end
+      end
+
       # The frozen set of files a #recheck must re-analyse: the symbol/ancestry-granularity closure of the
       # changed files (slice 4), the added files themselves, the consumers of any symbol / class that
       # *appeared* in a changed OR added file (slice 3 — a now-defined `call.unresolved-toplevel` target or
       # `def.override-*` ancestor), and the consumers of every removed file (which now miss what it
       # provided). An added file has no before-state, so all its symbols / classes appear.
-      def affected_closure(changed, added, removed)
+      #
+      # ADR-67 WD6c lift — `param_files` / `param_pairs` are the callee files (and their `[file, symbol]`
+      # pairs) whose inferred-param seeds moved since the snapshot. Their text is unchanged, so they enter
+      # the closure here: the files themselves re-analyse (their in-body diagnostics were computed under the
+      # old seeds), and their pairs join the SYMBOL fan-out — a seed change shifts the callee's inferred
+      # return exactly the way a body edit does, so it reuses the same audited dependents machinery. The
+      # pairs join AFTER the ADR-89 WD2 behavioural-stability pruning: that gate re-evaluates returns under
+      # the snapshot's OLD seeds, which is the wrong oracle for a pair whose seeds are the thing that moved.
+      def affected_closure(changed, added, removed, param_files = Set.new, param_pairs = Set.new)
         scan = changed + added
         # Parse the changed / added set ONCE for the per-symbol fingerprints, the class declarations, AND the
         # ADR-89 WD1 declaration signatures. They were separate `discovered_def_index_for_paths` passes over
         # the same `scan` set — a duplicate re-parse of every changed file each recheck (recon §2 / the P6
         # recheck-floor audit).
-        summary = scan.empty? ? nil : Inference::ScopeIndexer.scan_summary_for_paths(scan)
+        # `buffer:` is load-bearing for editor mode option B (#146), not an optimisation: this scan decides
+        # the closure, so reading the buffer's logical path from DISK would compare the snapshot's symbol
+        # fingerprints against bytes the user has already edited away — every dependent of the unsaved change
+        # would then be served from cache, which is the stale answer whole-project editor scope exists to
+        # avoid. `ScopeIndexer.scan_summary_for_paths` resolves each path through the binding.
+        summary = scan.empty? ? nil : Inference::ScopeIndexer.scan_summary_for_paths(scan, buffer: @buffer)
         scan_index = summary && summary[:def_index]
         declaration_signatures = (summary && summary[:declaration_signatures]) || {}
         new_fps = symbol_fingerprints_from_index(scan_index)
@@ -176,13 +240,23 @@ module Rigor
         # previously-observed call key + content-mutation effects) is unchanged is behaviourally stable: its
         # symbol dependents' cached diagnostics stay valid, so drop them. `symbol_pairs` is `changed_pairs`
         # minus those stable pairs, and only it (not `changed_pairs`) drives the symbol-dependent fan-out.
-        symbol_pairs = behaviourally_unstable_pairs(changed_pairs, unstable, scan_index)
+        symbol_pairs = behaviourally_unstable_pairs(changed_pairs, unstable, scan_index) | param_pairs
         base = dependents_base(unstable, symbol_pairs)
         closure = base | changed.to_set | added.to_set | negative_affected(scan, new_fps, new_class_decls)
+        closure = param_seed_closure(closure, param_files)
         removed.each { |path| closure |= @dependents[path] || Set.new }
         closure.freeze
       end
 
+      # ADR-67 WD6c lift — the seed-invalidated callees' own contribution to the closure: the files
+      # themselves, plus — on a pre-slice-4 snapshot with no symbol edges, where the pairs' symbol fan-out
+      # found nothing — their file-level dependents (wider, always sound).
+      def param_seed_closure(closure, param_files)
+        closure |= param_files
+        param_files.each { |path| closure |= @dependents[path] || Set.new } if @symbol_sources.empty?
+        closure
+      end
+
       # The dependents contributed by the declaration-unstable changed files and the behaviourally-unstable
       # symbol pairs: the ADR-46 slice-4 symbol-granular fan-out when either is present (ancestry deps of the
       # unstable files + symbol deps of the changed pairs), else the coarse file-level fan-out.
@@ -194,6 +268,47 @@ module Rigor
         end
       end
 
+      # ADR-67 WD6c lift — the fresh whole-project inferred-param table for this recheck ({} when the gate
+      # is off). When NO file moved, the collector's inputs are unchanged — the project files are identical,
+      # and the env-side inputs (configuration, `sig/`, the gem set, the engine version) are constant under
+      # a matched snapshot fingerprint — so the stored table is provably identical and the whole-project
+      # re-collect is skipped (the ADR-87 null-recheck fast path stays collect-free).
+      def fresh_param_table(current, changed, added, removed)
+        return {} unless @configuration.parameter_inference
+        return @param_table if changed.empty? && added.empty? && removed.empty?
+
+        build_runner.collect_param_inference_table(current)
+      end
+
+      # ADR-67 WD6c lift — the `[files, pairs]` the fresh table invalidates. For every `[class, method,
+      # kind]` entry that differs from the snapshot's copy (added, removed, or value-changed — `Type#==`
+      # structural equality, the same comparison the collector's own fixpoint termination uses, already
+      # exercised across Marshal round-trips by its fork workers), every snapshot file defining that symbol
+      # re-analyses and its `[file, symbol]` pair joins the symbol fan-out. An entry attributable to NO
+      # snapshot file is a def that first appeared in this edit: its file is in the changed/added set (so it
+      # re-analyses anyway) and its prior callers are the negative-dependency closure's job — nothing is
+      # lost by skipping it here. The restored types are compared and then DISCARDED (the run seeds from the
+      # fresh table), so a cache-carried stale memo ivar can never poison a live lookup.
+      def param_seed_invalidation(fresh_params)
+        return [Set.new, Set.new] if fresh_params.equal?(@param_table) || @param_table == fresh_params
+
+        files = Set.new
+        pairs = Set.new
+        (@param_table.keys | fresh_params.keys).each do |key|
+          next if @param_table[key] == fresh_params[key]
+
+          class_name, method_name, kind = key
+          symbol = "#{class_name}#{kind == :singleton ? '.' : '#'}#{method_name}"
+          @symbol_fingerprints.each do |path, symbols|
+            next unless symbols.key?(symbol)
+
+            files << path
+            pairs << [path, symbol]
+          end
+        end
+        [files, pairs]
+      end
+
       # ADR-89 WD2 — `changed_pairs` minus the behaviourally-STABLE pairs whose symbol dependents may be
       # skipped. A pair `[path, "Class#method"]` is a candidate when its file is declaration-stable (WD1), it
       # carries a persisted return summary, and the (edited) def is GATE-ELIGIBLE — its only cross-file body
@@ -266,7 +381,9 @@ module Rigor
       # mutating session state. Returns the merged diagnostics.
       def reanalyze_subset(subset)
         affected = subset.to_set
-        runner = build_runner(analyze_only: affected)
+        # ADR-67 WD6c lift — seed the subset run from the baseline's own table so the verification engine
+        # exercises the exact seeds the served cache entries were computed under (and skips a re-collect).
+        runner = build_runner(analyze_only: affected, param_inferred_types: @param_table)
         fresh = run_runner(runner).diagnostics
         reused = @analyzed - affected.to_a
         fresh + reused.flat_map { |path| @cache[path] || [] }
@@ -278,7 +395,12 @@ module Rigor
       # persist the updated snapshot for the next process. Returns `[diagnostics, warm]` — `warm` is true
       # when a snapshot was restored. A nil `fingerprint` (uncomputable inputs) disables persistence: a
       # plain full run.
-      def run_incremental(snapshot:, fingerprint:)
+      # `persist: false` runs the same restore / recheck / baseline decision without writing the snapshot
+      # back. The language server (#246) needs exactly that: it keeps its session in memory for the life of
+      # the process, and writing shared state would race the way its read-only cache store already declines
+      # to. Every soundness gate below — the fingerprint, the ADR-88 fact surface — is unchanged, so the
+      # decision to reuse is made identically whether or not the result is saved.
+      def run_incremental(snapshot:, fingerprint:, persist: true)
         # ADR-87 WD1 — install the per-run digest table + recording instant + strict flag for the whole
         # invocation so change-detection's stat-then-digest freshness (`#pack_digest` / `#stat_fresh?`) honours
         # `cache.validation: digest` (and `RIGOR_STRICT_VALIDATION`, which the env-only path already sees) and
@@ -320,7 +442,7 @@ module Rigor
             warm = false
             skip_save = false
           end
-          snapshot.save(fingerprint: fingerprint, payload: to_payload) if fingerprint && !skip_save
+          snapshot.save(fingerprint: fingerprint, payload: to_payload) if persist && fingerprint && !skip_save
           [diagnostics, warm]
         end
       end
@@ -386,6 +508,7 @@ module Rigor
         @missing           = payload.missing || {}
         @class_decls       = payload.class_decls || {}
         @return_summaries  = payload.return_summaries || {}
+        @param_table       = payload.param_table || {} # ADR-67 WD6c lift — the seeds the cache was built under.
         @symbol_dependents = Incremental.invert_symbols(@symbol_sources)
         @ancestry_dependents = Incremental.invert(@ancestry_sources)
         @negative_dependents = Incremental.invert(@missing)
@@ -398,7 +521,8 @@ module Rigor
           symbol_fingerprints: @symbol_fingerprints, missing: @missing,
           class_decls: @class_decls, seed_bundles: @seed_bundles,
           plugin_fact_digest: @plugin_fact_digest,
-          return_summaries: marshal_safe_return_summaries
+          return_summaries: marshal_safe_return_summaries,
+          param_table: marshal_safe_param_table
         )
       end
 
@@ -416,6 +540,18 @@ module Rigor
         end
       end
 
+      # ADR-67 WD6c lift — the param table filtered to Marshal-clean entries, the same guard (and reason) as
+      # {#marshal_safe_return_summaries} above. A dropped entry re-appears as "added" in the next recheck's
+      # diff, so its callee re-checks — the conservative direction.
+      def marshal_safe_param_table
+        @param_table.each_with_object({}) do |(key, params), safe|
+          Marshal.dump(params)
+          safe[key] = params
+        rescue StandardError
+          next
+        end
+      end
+
       # Fold a #recheck's fresh results back into the cache + graph so the session is correct across
       # multiple edits: the analyzed set gets fresh diagnostics + digests + dependency edges, removed files
       # are evicted from every map, and the analyzed-file list advances to `current`.
@@ -669,7 +805,7 @@ module Rigor
         Runner.new(
           configuration: @configuration, cache_store: @cache_store, environment: @environment,
           plugin_requirer: @plugin_requirer, seed_bundles: @seed_bundles, collect_seed_bundles: true,
-          workers: @workers, **
+          workers: @workers, buffer: @buffer, **
         )
       end
 
@@ -696,10 +832,19 @@ module Rigor
         candidates.reject { |path| stat_fresh?(path) }
       end
 
+      # A bound buffer's logical path is never fresh: the bytes to analyse live in the editor's temp file, and
+      # the recorded entry describes the file on disk. Re-analysing it when the two happen to agree costs one
+      # file; trusting the stat tuple would serve the editor its own stale diagnostics.
+      def buffer_path?(path)
+        !@buffer.nil? && path == @buffer.logical_path
+      end
+
       # True when `path`'s recorded stat entry proves it unchanged since the last analysis. Any stat / parse
       # failure (missing entry, unreadable / vanished file) reads as NOT fresh (→ re-analyse), preserving the
       # prior `digest(path) != recorded` "changed" semantics for a file that cannot be validated.
       def stat_fresh?(path)
+        return false if buffer_path?(path)
+
         entry = @digests[path]
         return false if entry.nil?
 

data/lib/rigor/analysis/plugin_fact_fingerprint.rb

@@ -71,6 +71,20 @@ module Rigor
         new.digest_registry(registry)
       end
 
+      # The fact surface reduced to the one String a cache KEY can carry, or nil when the surface cannot be
+      # seen at all (an opaque plugin — one that contributes call-site types while declaring none of the three
+      # fingerprint channels). A nil obliges the caller to decline caching entirely, which is the same
+      # conservative direction {Result#reusable_against?} takes for the incremental snapshot: a key that
+      # silently omitted an invisible input would serve a stale value rather than miss.
+      #
+      # Keeping the opaque decision here, rather than at each cache's call site, means a new consumer cannot
+      # key on `digest` while forgetting that an opaque surface makes it meaningless.
+      # @return [String, nil]
+      def self.key_digest(registry)
+        result = from_registry(registry)
+        result.opaque? ? nil : result.digest.to_s
+      end
+
       # Loads the plugins and runs every `#prepare` hook sequentially, returning the prepared registry (nil on
       # any failure → the caller treats it as "no fact surface").
       def self.prepared_registry(configuration:, cache_store:, plugin_requirer:)

data/lib/rigor/analysis/rule_catalog.rb

@@ -660,6 +660,8 @@ module Rigor
             "The token resolves (canonical id, legacy alias, `all`, family wildcard, known engine id).",
             "The token starts with `plugin.` — plugins load dynamically, so their rule vocabulary cannot " \
             "be enumerated statically and under-warning is the FP-safe direction.",
+            "The marker does not open the comment (documentation prose quoting the syntax, a doubled " \
+            "`##` comment, or an `=begin` block) — that is not parsed as a suppression either.",
             "The comment merely mentions the marker followed by non-token text (documentation prose " \
             "like \"`# rigor:disable <rule>` comments\") — that is not parsed as a suppression either."
           ],
@@ -684,6 +686,7 @@ module Rigor
           does_not_fire_when: [
             "At least one token follows the marker (each token is then checked by " \
             "`suppression.unknown-rule` instead).",
+            "The marker does not open the comment (documentation prose quoting the syntax).",
             "Non-token text follows the marker (documentation prose mentioning the syntax)."
           ],
           suppression: "Complete the marker (`# rigor:disable <rule>` / `all`) or delete it; " \
@@ -730,7 +733,7 @@ module Rigor
           summary: "A comment uses a suppression marker Rigor does not recognise " \
                    "(`rigor:disable-next-line`, `rigor:enable`, ...).",
           fires_when: [
-            "A comment carries `rigor:disable-<suffix>` with a suffix other than `file`, or " \
+            "A comment OPENS with `rigor:disable-<suffix>` for a suffix other than `file`, or with " \
             "`rigor:enable[-<suffix>]` — typically the RuboCop reflex `# rigor:disable-next-line " \
             "<rule>` — followed by nothing or a rule-list-shaped remainder.",
             "Such a marker is invisible to the whole suppression grammar, so it silently suppresses " \
@@ -740,6 +743,7 @@ module Rigor
           does_not_fire_when: [
             "The marker is one of the two recognised forms (their tokens are then checked by " \
             "`suppression.unknown-rule` / `suppression.empty` instead).",
+            "The marker does not open the comment (documentation prose quoting the spelling).",
             "Non-token text follows the marker (documentation prose mentioning the spelling)."
           ],
           suppression: "Rewrite as `# rigor:disable <rules>` on the offending line (Rigor has no " \

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