rigortype 0.3.1 → 0.3.2

data/lib/rigor/inference/statement_evaluator.rb

@@ -247,9 +247,31 @@ module Rigor
 
         bound = bound.without_inferred_param_mark(node.name)
         bound = bound.with_local_origin(node.name, rhs_origin(node.value, post_rhs, rhs_type))
+        bound = bound.with_optimistic_local(node.name, optimistic_rhs_origin(node.value, post_rhs))
         [rhs_type, bound]
       end
 
+      # Issue #286 — the optimistic-nil-free counterpart of {#rhs_origin}, differing in two ways. It does not
+      # gate on `Dynamic`: the values this channel marks are ordinary `Union` / `Constant` / `Nominal`
+      # carriers, which is the whole point. And it resolves a bare local read through its binding, so
+      # `w = v` keeps the mark — the same propagation `OriginLookup` performs for the Dynamic channel.
+      def optimistic_rhs_origin(value_node, scope_after_rhs)
+        optimistic_origin_for(value_node, scope_after_rhs)
+      end
+
+      # The effective optimistic-nil-free cause of an expression: the mark on its own node, else — for a bare
+      # local read or a local write used in value position (`if (x = MAP[k])`, where the write has already
+      # bound the mark) — the one propagated onto the binding.
+      def optimistic_origin_for(node, scope)
+        recorded = scope.optimistic_origins[node]
+        return recorded if recorded
+
+        case node
+        when Prism::LocalVariableReadNode, Prism::LocalVariableWriteNode then scope.optimistic_local(node.name)
+        when Prism::InstanceVariableReadNode, Prism::InstanceVariableWriteNode then scope.optimistic_ivar(node.name)
+        end
+      end
+
       # ADR-82 WD1 — the {Inference::DynamicOrigin} cause to propagate onto a local / ivar being bound to `rhs`.
       # Returns the cause recorded on the assignment's rhs node when the value is `Dynamic` (so a later
       # `x` / `@x` receiver-read resolves to why it is dynamic), else `nil` — `with_local_origin` /
@@ -277,6 +299,7 @@ module Rigor
         rhs_type, post_rhs = sub_eval(node.value, scope)
         bound = post_rhs.with_ivar(node.name, rhs_type)
         bound = bound.with_ivar_origin(node.name, rhs_origin(node.value, post_rhs, rhs_type))
+        bound = bound.with_optimistic_ivar(node.name, optimistic_rhs_origin(node.value, post_rhs))
         [rhs_type, bound]
       end
 
@@ -543,19 +566,34 @@ module Rigor
       # non-falsey carriers like `Nominal[Integer]` (Integer is always truthy in Ruby — including 0) also collapse the
       # dead else.
       def live_branch_for_if(node, pred_type, post_pred)
-        case Narrowing.predicate_certainty(pred_type)
+        verdict = optimistic_carrier?(node.predicate, post_pred) ? nil : Narrowing.predicate_certainty(pred_type)
+        case verdict
         when :truthy then eval_branch_or_nil(node.statements, post_pred)
         when :falsey then eval_branch_or_nil(node.subsequent, post_pred)
         end
       end
 
       def live_branch_for_unless(node, pred_type, post_pred)
-        case Narrowing.predicate_certainty(pred_type)
+        verdict = optimistic_carrier?(node.predicate, post_pred) ? nil : Narrowing.predicate_certainty(pred_type)
+        case verdict
         when :truthy then eval_branch_or_nil(node.else_clause, post_pred)
         when :falsey then eval_branch_or_nil(node.statements, post_pred)
         end
       end
 
+      # ADR-101 — the branch elision MUST NOT conclude truthiness from a carrier whose nil-freeness rests on
+      # the `%a{implicitly-returns-nil}` that `RbsDispatch` reads past. Such a value is optimistic, not proof
+      # (see {Inference::OptimisticOrigin} and docs/internal-spec/inference-engine.md), so eliding an arm on
+      # it deletes a branch the program really takes when the lookup misses.
+      #
+      # The decline lives here and NOT in `Narrowing.falsey_nominal?` / `.narrow_falsey`: `&&=` / `||=` and
+      # the and/or surviving-left edge read those too, and widening the falsey fragment there would re-admit
+      # `nil` into a bound local and buy `possible nil receiver` false positives — a soundness fix paid for
+      # in FPs, which is the wrong trade.
+      def optimistic_carrier?(predicate, scope)
+        !optimistic_origin_for(predicate, scope).nil?
+      end
+
       def eval_else(node)
         return [Type::Combinator.constant_of(nil), scope] if node.statements.nil?
 

data/lib/rigor/language_server/buffer_table.rb

@@ -21,6 +21,7 @@ module Rigor
       def initialize
         @entries = {}
         @desynchronized = {}
+        @dirty = {}
       end
 
       # Records a `textDocument/didOpen` event. Replaces any existing entry (LSP clients may re-open a
@@ -28,6 +29,7 @@ module Rigor
       # payload carries the client's full text, so the two views agree again.
       def open(uri:, bytes:, version:)
         @desynchronized.delete(uri)
+        @dirty.delete(uri)
         @entries[uri] = Entry.new(uri: uri, bytes: bytes, version: version)
       end
 
@@ -36,6 +38,7 @@ module Rigor
       # created — defensive.
       def change(uri:, bytes:, version:)
         @desynchronized.delete(uri)
+        @dirty[uri] = true
         @entries[uri] = Entry.new(uri: uri, bytes: bytes, version: version)
       end
 
@@ -52,6 +55,7 @@ module Rigor
       def apply_changes(uri:, changes:, version:)
         text = IncrementalSync.apply_all(@entries[uri]&.bytes, changes)
         @desynchronized.delete(uri)
+        @dirty[uri] = true
         @entries[uri] = Entry.new(uri: uri, bytes: text, version: version)
         true
       rescue IncrementalSync::UnappliableChange => e
@@ -73,9 +77,27 @@ module Rigor
       # Records a `textDocument/didClose` event. The entry is removed. Subsequent reads via `#[]` return nil.
       def close(uri:)
         @desynchronized.delete(uri)
+        @dirty.delete(uri)
         @entries.delete(uri)
       end
 
+      # Records a `textDocument/didSave`. The client has written the buffer, so the held text and the file on
+      # disk agree again and the URI stops being dirty.
+      #
+      # Dirtiness is the PROTOCOL's notion — "the client told us it changed and has not told us it saved" —
+      # not a byte comparison against disk. A comparison would look stricter and be weaker: it races with the
+      # editor's own write, and the server's truth is what the client notified.
+      def save(uri:)
+        @dirty.delete(uri)
+      end
+
+      # @return [Boolean] true when `uri` has unsaved changes. A buffer that is dirty may only be published
+      #   from an analysis that bound ITS bytes — see the publish-set invariant in
+      #   `docs/design/20260517-language-server.md`.
+      def dirty?(uri)
+        @dirty.key?(uri)
+      end
+
       def [](uri)
         @entries[uri]
       end

data/lib/rigor/language_server/diagnostic_publisher.rb

@@ -3,6 +3,7 @@
 require "tempfile"
 
 require_relative "uri"
+require_relative "publish_batcher"
 require_relative "../analysis/runner"
 require_relative "../analysis/buffer_binding"
 
@@ -14,8 +15,10 @@ module Rigor
     # the Runner, and pushes the resulting LSP `Diagnostic[]` through the writer.
     #
     # Debouncing is wired via an optional `Debouncer` injected at construction (delay defaults to 200ms
-    # quiet-time); without a debouncer each call blocks synchronously (primarily for specs). Ractor-pool
-    # dispatch is queued.
+    # quiet-time); without a debouncer each call blocks synchronously (primarily for specs). When several
+    # buffers' debounce timers elapse around the same moment, the `PublishBatcher` coalesces them into one
+    # `#publish_many` round dispatched across the fork-based worker pool (issue #142) instead of N
+    # independent, GVL-serialized `Runner` calls.
     class DiagnosticPublisher
       # Maps Rigor severity symbols to LSP DiagnosticSeverity
       # integers per spec § "Diagnostic":
@@ -37,6 +40,10 @@ module Rigor
       #   debounced publish fires. 0 with a debouncer means
       #   "schedule on next-tick" (still async); without a
       #   debouncer the value is unused.
+      # The single Debouncer key every save round shares (#246). Per-URI keys would let two saves start two
+      # concurrent rounds; one key means a burst collapses into the last one.
+      PROJECT_ROUND_KEY = :__rigor_project_round__
+
       def initialize(writer:, buffer_table:, project_context:,
                      debouncer: nil, debounce_seconds: 0.2)
         @writer = writer
@@ -44,23 +51,72 @@ module Rigor
         @project_context = project_context
         @debouncer = debouncer
         @debounce_seconds = debounce_seconds
+        @round_lock = Mutex.new
+        @round_running = false
+        @round_pending = false
+        # Issue #142 — coalesces buffers whose OWN debounce timers elapse close together into one
+        # `#publish_many` round instead of N independent GVL-serialized `Runner` calls. Separate from
+        # `@round_lock` above, which single-flights the whole-project SAVE round; this single-flights the
+        # per-buffer DIDCHANGE batch instead. See `PublishBatcher` for the coalescing mechanics.
+        @batcher = PublishBatcher.new(
+          on_batch: ->(uris) { publish_many(uris) },
+          on_error: ->(e) { warn "DiagnosticPublisher batch round: #{e.class}: #{e.message}" }
+        )
       end
 
       # Run analysis for the buffer at `uri` (looked up in the BufferTable) and push a
       # `textDocument/publishDiagnostics` notification. No-op when the URI isn't a `file://` form or the
       # buffer isn't currently open. When a Debouncer is wired, the analysis is scheduled async per the
-      # configured `debounce_seconds`; otherwise it runs inline.
+      # configured `debounce_seconds` and joins the batch coalescing layer (`PublishBatcher`) once its own
+      # quiet-time elapses; otherwise it runs inline (primarily for specs).
       def publish_for(uri)
         path = Uri.to_path(uri)
         return if path.nil?
 
         if @debouncer
-          @debouncer.schedule(uri, delay: @debounce_seconds) { run_and_notify(uri, path) }
+          @debouncer.schedule(uri, delay: @debounce_seconds) { @batcher.enqueue(uri) }
         else
           run_and_notify(uri, path)
         end
       end
 
+      # Issue #142 — publishes N dirty buffers' diagnostics through ONE dispatch across the fork-based
+      # worker pool (`Analysis::Runner::BufferPoolDispatcher`) instead of N independent, GVL-serialized
+      # `Runner` calls. Each URI's OWN `BufferBinding` (its logical path bound to its OWN editor tempfile)
+      # travels with it, so a worker analyses that buffer's in-flight bytes — never the file as it sits on
+      # disk — even when several buffers are dispatched in the same round.
+      #
+      # Degrades to `#run_and_notify`'s existing single-buffer path when only one URI is eligible after
+      # filtering (a buffer closed mid-debounce-window is dropped; a desynchronised one publishes empty
+      # immediately) — a lone edit takes exactly the path it takes today. The dispatcher itself degrades to
+      # sequential in-process execution for any other precondition (see
+      # `BufferPoolDispatcher#dispatchable?`), so a pool that cannot start never fails a publish, only slows
+      # it back down to today's wall time.
+      def publish_many(uris)
+        eligible = uris.uniq.filter_map { |uri| eligible_job(uri) }
+        return if eligible.empty?
+        return run_and_notify(eligible.first.fetch(:uri), eligible.first.fetch(:path)) if eligible.size == 1
+
+        publish_batch(eligible)
+      end
+
+      # Runs one whole-project save round and publishes to the publish set (#246). Called from `didSave`.
+      #
+      # Analysis scope is the whole project; the PUBLISH SET is the open buffers that are not dirty, plus the
+      # buffer that was just saved. A dirty buffer is excluded because only its own `didChange` analysis has
+      # seen its bytes — publishing this round's on-disk answer for it would replace correct markers with
+      # markers for a file the user has already changed.
+      #
+      # Scheduled through the same Debouncer the per-buffer path uses, under one project-wide key, so the
+      # dispatcher never blocks on it.
+      def publish_project(saved_uri)
+        if @debouncer
+          @debouncer.schedule(PROJECT_ROUND_KEY, delay: 0) { run_project_round(saved_uri) }
+        else
+          run_project_round(saved_uri)
+        end
+      end
+
       # Publishes an EMPTY diagnostic array for `uri`. The LSP-spec idiom for "clear inline markers" — called
       # from `didClose` so clients drop stale highlights when the user closes a buffer.
       def publish_empty(uri)
@@ -75,6 +131,73 @@ module Rigor
 
       private
 
+      # Single-flight. The Debouncer only cancels a task that has not started, so without this two rounds
+      # could run concurrently over one session's mutable state. A save that arrives mid-round sets the
+      # pending flag instead of starting a second round, and the running one repeats once when it finishes —
+      # so a burst of saves costs at most one extra round, and the last save is always accounted for.
+      def run_project_round(saved_uri)
+        return unless claim_round
+
+        loop do
+          execute_project_round(saved_uri)
+          break unless consume_pending
+        end
+      end
+
+      # True when this call owns the round. A save arriving while one is in flight records itself as pending
+      # instead — the running round will pick it up.
+      def claim_round
+        @round_lock.synchronize do
+          if @round_running
+            @round_pending = true
+            next false
+          end
+
+          @round_running = true
+          true
+        end
+      end
+
+      # True when a save arrived mid-round and the loop should run once more. Releases ownership otherwise.
+      # `next`, not `break`: inside `Mutex#synchronize`'s block, `break` returns from the SYNCHRONIZE call, so
+      # a `break` written here would leave the caller's `loop` spinning forever — which is exactly what it did
+      # before this was split out.
+      def consume_pending
+        @round_lock.synchronize do
+          next(@round_running = false) unless @round_pending
+
+          @round_pending = false
+          true
+        end
+      end
+
+      # One round: analyse the project as it now stands on disk, then publish each target URI's slice.
+      # The generation captured before the analysis is re-read after it — a `didChangeWatchedFiles` or a
+      # configuration change during a long round invalidates the world these diagnostics describe, and
+      # publishing them would put an answer about a superseded project on the user's screen.
+      def execute_project_round(saved_uri)
+        generation = @project_context.generation
+        diagnostics = @project_context.project_diagnostics
+        return if generation != @project_context.generation
+
+        by_path = diagnostics.group_by(&:path)
+        publish_set(saved_uri).each do |uri|
+          path = Uri.to_path(uri)
+          next if path.nil?
+
+          notify(uri, (by_path[path] || []).filter_map { |diagnostic| to_lsp_diagnostic(diagnostic, path) })
+        end
+      end
+
+      # The URIs this round may speak for: every open buffer whose bytes are the ones on disk. The just-saved
+      # URI qualifies by definition (the client wrote it), and is named explicitly so a client that sends
+      # `didSave` without a preceding applied `didChange` still refreshes it.
+      def publish_set(saved_uri)
+        ([saved_uri] + @buffer_table.uris).uniq.select do |uri|
+          @buffer_table.open?(uri) && !@buffer_table.dirty?(uri) && !@buffer_table.desynchronized?(uri)
+        end
+      end
+
       def run_and_notify(uri, path)
         entry = @buffer_table[uri]
         # The buffer may have been closed during the debounce window — drop the publish; the empty
@@ -89,6 +212,60 @@ module Rigor
         notify(uri, diagnostics)
       end
 
+      # @return [Hash, nil] `{ uri:, path:, bytes: }` when `uri` is eligible for the batch, or nil to
+      #   exclude it. Mirrors `#run_and_notify`'s own guards: a buffer closed during the debounce window is
+      #   dropped silently (its didClose empty publish already cleared the markers); a desynchronised buffer
+      #   publishes an EMPTY set immediately (same as the single-buffer path) rather than joining the batch.
+      def eligible_job(uri)
+        entry = @buffer_table[uri]
+        return nil if entry.nil?
+
+        path = Uri.to_path(uri)
+        return nil if path.nil?
+
+        if @buffer_table.desynchronized?(uri)
+          notify(uri, [])
+          return nil
+        end
+
+        { uri: uri, path: path, bytes: entry.bytes }
+      end
+
+      # Materialises one tempfile + `BufferBinding` per job, dispatches all of them through
+      # `BufferPoolDispatcher#analyze` in ONE call, and publishes each job's own slice. `dispatcher.analyze`
+      # returns diagnostics IN INPUT ORDER, so `jobs`/`bindings`/the result array stay index-aligned — the
+      # parent absorbs worker results in this stable order, so two runs of the same dirty set publish
+      # byte-identical results.
+      def publish_batch(jobs)
+        with_tempfiles(jobs) do |bound_jobs|
+          bindings = bound_jobs.map { |job| job.fetch(:binding) }
+          dispatcher = Analysis::Runner::BufferPoolDispatcher.new(
+            configuration: @project_context.configuration,
+            cache_store: @project_context.cache_store,
+            environment: @project_context.environment,
+            prebuilt: @project_context.project_scan,
+            workers: worker_count
+          )
+          diagnostics_per_binding = dispatcher.analyze(bindings)
+          bound_jobs.each_with_index do |job, index|
+            diagnostics = diagnostics_per_binding.fetch(index, []).filter_map do |diagnostic|
+              to_lsp_diagnostic(diagnostic, job.fetch(:path))
+            end
+            notify(job.fetch(:uri), diagnostics)
+          end
+        end
+      end
+
+      # Worker-pool size, mirroring `rigor check`'s own precedence minus the CLI flag the LSP does not have:
+      # env `RIGOR_RACTOR_WORKERS` (if set and non-empty) wins, else `.rigor.yml` `parallel.workers:` (0 —
+      # sequential — by default). See `docs/design/20260517-language-server.md` § "Concurrency".
+      def worker_count
+        env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
+        return [Integer(env_value), 0].max if env_value && !env_value.empty?
+
+        @project_context.configuration.parallel_workers
+      end
+
       # Runs `Analysis::Runner` with a `BufferBinding` so the buffer bytes (instead of the on-disk file) drive
       # the parse. The `Rigor::Analysis::ProjectScan` cached on the ProjectContext is passed through
       # `prebuilt:` so plugin `#prepare`, the dependency-source walker, and the synthetic-method /
@@ -121,6 +298,28 @@ module Rigor
         tmp&.unlink
       end
 
+      # Plural form of `#with_tempfile` for `#publish_batch` — writes one tempfile per job up front, yields
+      # each job Hash augmented with its own `binding:` (a `BufferBinding` pairing the job's logical path
+      # with ITS OWN physical tempfile), and unlinks every tempfile afterward regardless of how the block
+      # exits.
+      def with_tempfiles(jobs)
+        tempfiles = []
+        bound_jobs = jobs.map do |job|
+          tmp = Tempfile.new(["rigor-lsp-buffer-", ".rb"])
+          tmp.write(job.fetch(:bytes))
+          tmp.flush
+          tempfiles << tmp
+          binding = Analysis::BufferBinding.new(logical_path: job.fetch(:path), physical_path: tmp.path)
+          job.merge(binding: binding)
+        end
+        yield bound_jobs
+      ensure
+        tempfiles.each do |tmp|
+          tmp.close
+          tmp.unlink
+        end
+      end
+
       # @return [Hash, nil] the LSP `Diagnostic` Hash, or nil to
       #   skip diagnostics outside the buffer's own path (e.g.
       #   `.rigor.yml`-anchored info diagnostics get filtered —

data/lib/rigor/language_server/project_context.rb

@@ -3,6 +3,8 @@
 require_relative "../environment"
 require_relative "../cache/store"
 require_relative "../analysis/runner"
+require_relative "../analysis/incremental_session"
+require_relative "../cache/incremental_snapshot"
 
 module Rigor
   module LanguageServer
@@ -34,6 +36,9 @@ module Rigor
     # watch fires → publish) refreshes automatically; the rare in-flight edit to a substrate-DSL file is the
     # documented edge case.
     class ProjectContext
+      # `generation` is the invalidation counter: a long-running save round (#246) captures it on entry and
+      # discards its result if it moved, so diagnostics computed against a world that has since been
+      # invalidated never reach the editor.
       attr_reader :configuration, :generation
 
       def initialize(configuration:)
@@ -42,6 +47,8 @@ module Rigor
         @environment = nil
         @cache_store = nil
         @project_scan = nil
+        @incremental_session = nil
+        @session_primed = false
       end
 
       # Returns the cached `Rigor::Environment` for this session, building it on first access. The build
@@ -90,6 +97,29 @@ module Rigor
         @project_scan ||= build_project_scan
       end
 
+      # Whole-project diagnostics for one save round (#246). The first call primes an in-process
+      # {Analysis::IncrementalSession} — seeded from the on-disk snapshot a terminal
+      # `rigor check --incremental` may have left, and otherwise from a full baseline; every later call is a
+      # recheck against what changed on disk since.
+      #
+      # The session is never persisted. Its state lives as long as this context, which is what a long-running
+      # server needs, and writing it would race exactly the way the read-only {#cache_store} exists to avoid.
+      # Seeding is therefore one-directional: the terminal warms the server, not the reverse.
+      def project_diagnostics
+        session = (@incremental_session ||= build_incremental_session)
+        return session.recheck.diagnostics if @session_primed
+
+        @session_primed = true
+        diagnostics, = session.run_incremental(
+          snapshot: Cache::IncrementalSnapshot.new(root: @configuration.cache_path),
+          fingerprint: Cache::IncrementalSnapshot.fingerprint(
+            configuration: @configuration, roots: @configuration.paths
+          ),
+          persist: false
+        )
+        diagnostics
+      end
+
       # Drops every cached collaborator and bumps the generation. The next reader rebuilds from scratch.
       # Triggered by `workspace/didChangeWatchedFiles` for project source files and by
       # `workspace/didChangeConfiguration`.
@@ -97,6 +127,10 @@ module Rigor
         @generation += 1
         @environment = nil
         @project_scan = nil
+        # The session's per-file cache was computed against the old environment / project scan, so it cannot
+        # outlive them. The next save round primes a fresh one.
+        @incremental_session = nil
+        @session_primed = false
         # Cache store stays — it's content-addressed; a stale env build won't be served because the file
         # digest mixed into the cache key has changed.
         nil
@@ -104,6 +138,17 @@ module Rigor
 
       private
 
+      # The session shares this context's warm Environment, so a round does not rebuild the RBS universe. It
+      # deliberately does NOT share the prebuilt ProjectScan: a round runs after a save, i.e. after the file
+      # on disk moved, and the scan is what a changed file invalidates.
+      def build_incremental_session
+        Analysis::IncrementalSession.new(
+          configuration: @configuration,
+          environment: environment,
+          cache_store: cache_store
+        )
+      end
+
       def build_project_scan
         runner = Analysis::Runner.new(
           configuration: @configuration,

data/lib/rigor/language_server/publish_batcher.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Rigor
+  module LanguageServer
+    # Issue #142 — coalesces keys that become "ready" close together in wall-clock time into ONE batched
+    # round instead of firing one round per key. `DiagnosticPublisher` uses this to fold a burst of buffers
+    # whose OWN per-URI debounce timers elapse around the same moment (a workspace-wide rename, a git branch
+    # switch that touches many open files) into one `#publish_many` dispatch across the fork-based worker
+    # pool — but the mechanism itself carries no LSP- or URI-specific knowledge, so it stays a small,
+    # independently testable collaborator rather than inline state on `DiagnosticPublisher`.
+    #
+    # Single-flight: the first `#enqueue` call to arrive owns the round and runs `on_batch` with every key
+    # currently pending (deduplicated); a call that arrives while a round is running just adds its key and
+    # returns — the running round loops once more before releasing ownership, so nothing queued mid-round is
+    # dropped. The same claim/consume shape `DiagnosticPublisher#run_project_round` already uses for the
+    # whole-project save round (#246), generalised to an arbitrary key type and an arbitrary batch action.
+    class PublishBatcher
+      # @param on_batch [#call] `(keys) -> void`, called with the deduplicated Array of keys pending at the
+      #   start of one round. May be called more than once in a row when keys keep arriving while a round
+      #   runs.
+      # @param on_error [#call, nil] `(exception) -> void`, called when `on_batch` raises. A round must
+      #   never wedge the coalescing lock for every future `#enqueue` call — ownership is always released
+      #   before this fires. Whatever was mid-flight when the round raised is lost; anything enqueued by a
+      #   concurrent `#enqueue` call after this round's drain but before the rescue stays pending and rides
+      #   the NEXT round instead. Defaults to a no-op (the exception is swallowed silently).
+      def initialize(on_batch:, on_error: nil)
+        @on_batch = on_batch
+        @on_error = on_error
+        @lock = Mutex.new
+        @pending = []
+        @running = false
+      end
+
+      # Adds `key` to the pending set and, if no round is currently running, becomes the round and drains
+      # every key pending (looping until none remain) before returning. A call that arrives while another is
+      # already running the round returns immediately having only enqueued its key.
+      def enqueue(key)
+        start = false
+        @lock.synchronize do
+          @pending << key
+          unless @running
+            @running = true
+            start = true
+          end
+        end
+        return unless start
+
+        run_owned_round
+      end
+
+      private
+
+      def run_owned_round
+        loop do
+          run_batch
+          break unless more_pending?
+        end
+      rescue StandardError => e
+        @lock.synchronize { @running = false }
+        @on_error&.call(e)
+      end
+
+      # True when another key joined `@pending` while this round was running — the caller's loop should run
+      # once more rather than release ownership. Releases ownership (resets `@running`) otherwise.
+      def more_pending?
+        @lock.synchronize do
+          if @pending.empty?
+            @running = false
+            false
+          else
+            true
+          end
+        end
+      end
+
+      def run_batch
+        keys = @lock.synchronize { @pending.uniq.tap { @pending.clear } }
+        @on_batch.call(keys)
+      end
+    end
+  end
+end

data/lib/rigor/language_server/server.rb

@@ -95,6 +95,7 @@ module Rigor
         when "exit"                   then handle_exit
         when "textDocument/didOpen"   then handle_did_open(params)
         when "textDocument/didChange" then handle_did_change(params)
+        when "textDocument/didSave"   then handle_did_save(params)
         when "textDocument/didClose"  then handle_did_close(params)
         when "textDocument/hover"               then handle_hover(params)
         when "textDocument/documentSymbol"      then handle_document_symbol(params)
@@ -161,7 +162,10 @@ module Rigor
           positionEncoding: POSITION_ENCODING_UTF16,
           textDocumentSync: {
             openClose: true,
-            change: TEXT_DOCUMENT_SYNC_INCREMENTAL
+            change: TEXT_DOCUMENT_SYNC_INCREMENTAL,
+            # `includeText: false` — the round reads the file the client just wrote, so the payload's copy
+            # would be redundant. See `handle_did_save`.
+            save: { includeText: false }
           }
         }
         caps[:hoverProvider] = true if @hover_provider
@@ -242,6 +246,21 @@ module Rigor
         nil
       end
 
+      # textDocument/didSave notification. Marks the buffer clean — the client has written it, so the held
+      # text and the file on disk agree — and starts a whole-project publish round (#246).
+      #
+      # This is where whole-project scope lives, rather than on `didChange`: a round costs ~0.6s on a
+      # mid-sized project against a 250ms `didChange` p50 budget, and "the rest of the project catches up"
+      # is what saving means to the user. Because the saved bytes are the bytes on disk, the round needs no
+      # buffer binding at all. Design: `docs/design/20260517-language-server.md` § "Whole-project publishes
+      # on save".
+      def handle_did_save(params)
+        uri = params.fetch(:textDocument).fetch(:uri)
+        @buffer_table.save(uri: uri)
+        @publisher&.publish_project(uri)
+        nil
+      end
+
       # textDocument/hover REQUEST. Slice 5 returns either a `Hover` payload (markdown contents wrapping type
       # + erased-RBS info) or nil when no expression is at the queried position. Nil maps to `result: null`
       # per LSP spec; clients suppress the popup. Returns `MethodNotFound` when no hover_provider is wired

data/lib/rigor/language_server.rb

@@ -14,6 +14,7 @@ require_relative "language_server/buffer_table"
 require_relative "language_server/uri"
 require_relative "language_server/project_context"
 require_relative "language_server/debouncer"
+require_relative "language_server/publish_batcher"
 require_relative "language_server/synchronized_writer"
 require_relative "language_server/diagnostic_publisher"
 require_relative "language_server/hover_renderer"

data/lib/rigor/plugin/source_rbs_synthesis_reporter.rb

@@ -16,17 +16,23 @@ module Rigor
     # single reporter across the run; entries are appended one at a time during env build (before any per-file
     # analysis runs), so no locking is needed.
     class SourceRbsSynthesisReporter
-      Entry = Data.define(:plugin_id, :path, :message)
+      # `kind` separates the two outcomes the Runner reports differently (ADR-32 WD12): `:failed` is a
+      # synthesis that raised or could not parse, `:not_honoured` a synthesis that SUCCEEDED while silently
+      # dropping an annotation it parsed. They are not the same news — the first says the file contributed
+      # nothing, the second that it contributed all but one thing — so they carry distinct diagnostic ids.
+      # Defaults to `:failed`, the pre-WD12 meaning, so an older caller records what it always did.
+      Entry = Data.define(:plugin_id, :path, :message, :kind)
 
       def initialize
         @entries = []
       end
 
-      def record(plugin_id:, path:, message:)
+      def record(plugin_id:, path:, message:, kind: :failed)
         @entries << Entry.new(
           plugin_id: plugin_id.to_s.dup.freeze,
           path: path.to_s.dup.freeze,
-          message: message.to_s.dup.freeze
+          message: message.to_s.dup.freeze,
+          kind: kind
         )
         nil
       end