rigortype 0.3.0 → 0.3.1

data/lib/rigor/cli/skill_describe.rb

@@ -142,27 +142,43 @@ module Rigor
 
       # @param skills [Array<Hash>] discovered skills, each `{name:, path:}`.
       # @param root [String] project root to probe (defaults to the cwd).
-      def initialize(skills:, root: Dir.pwd)
+      # @param deep [Boolean] opt into `--deep`: run a real `rigor check` and let its result pick the headline. Off by
+      #   default, and off is ADR-73 WD2's contract — see {SkillDeepProbe} for why the whole analysis path lives
+      #   behind this one flag and in its own file.
+      def initialize(skills:, root: Dir.pwd, deep: false)
         @skills = skills
         @root = root
+        @deep = deep
       end
 
       # @return [String] the full describe report.
       def render
         catalog = catalog_skills
         state = ProjectStateProbe.new(@root).to_h
-        recommendation = recommend(state, catalog)
+        deep = deep_report(state)
+        recommendation = recommend(state, catalog, deep)
         [
           title,
           state_section(state),
+          deep_section(deep),
           recommendation_section(recommendation),
           catalog_section(catalog),
-          agent_prompt(recommendation)
-        ].join("\n")
+          agent_prompt(recommendation, deep)
+        ].compact.join("\n")
       end
 
       private
 
+      # The `--deep` analysis, or nil when the flag was not given. `require` sits here rather than at the top of the
+      # file so the default, presence-only path never even loads the check-invocation plumbing — WD2's "runs no
+      # analysis" guarantee is enforced by what gets loaded, not only by what gets called.
+      def deep_report(state)
+        return nil unless @deep
+
+        require_relative "skill_deep_probe"
+        SkillDeepProbe.new(config: state.fetch(:config), root: @root).run
+      end
+
       # The skills offered as "what to do next", in adoption-journey order. The entry-point skill is excluded, and
       # unknown skills sort after the known journey, alphabetically.
       def catalog_skills
@@ -173,8 +189,12 @@ module Rigor
 
       # The decision tree (ADR-73 WD2). Returns `{ skill:, reason: }` for the recommended next step, or nil when no
       # catalogue skill matches.
-      def recommend(state, catalog)
-        name, reason = recommended_name_and_reason(state)
+      #
+      # A `--deep` report overrides the presence-only tree only when it actually routed: a check that was skipped,
+      # could not run, or ran clean leaves the tree's answer standing untouched. So the un-flagged behaviour is
+      # literally the `deep == nil` branch of this one method.
+      def recommend(state, catalog, deep = nil)
+        name, reason = deep&.route ? [deep.route, deep.reason] : recommended_name_and_reason(state)
         skill = catalog.find { |candidate| candidate.fetch(:name) == name }
         skill.nil? ? nil : { skill: skill, reason: reason }
       end
@@ -248,6 +268,18 @@ module Rigor
         STATE
       end
 
+      # Printed only under `--deep`, so the un-flagged report is byte-identical to what it has always been.
+      def deep_section(deep)
+        return nil if deep.nil?
+
+        <<~DEEP
+          ## Deep check (--deep)
+          A real `rigor check` was run for this recommendation — unlike the probe above it
+          is slow and it writes `.rigor/cache`, exactly as `rigor check` does.
+          - Result: #{deep.detail}
+        DEEP
+      end
+
       def recommendation_section(recommendation)
         return "## Recommended next step\n- (no bundled skill matched the current state)\n" if recommendation.nil?
 
@@ -267,7 +299,7 @@ module Rigor
         "## All skills you can run next\n#{lines.join("\n")}\n"
       end
 
-      def agent_prompt(recommendation)
+      def agent_prompt(recommendation, deep = nil)
         opener =
           if recommendation.nil?
             "Ask the user what they would like to do next"
@@ -279,6 +311,33 @@ module Rigor
           #{opener}, then run `rigor skill <name>` for the chosen skill and
           follow its body top to bottom.
 
+          #{check_awareness(deep)}
+
+          Re-run `rigor skill describe` whenever you need the next step — it always
+          reflects the project's current state.
+        PROMPT
+      end
+
+      # The check-aware routing block. Without `--deep` it teaches the agent to make the call itself from a check it
+      # has already run (the 2026-06-20 field-trial fix, unchanged); with `--deep` the headline already made that
+      # call, so the block reports what happened instead of re-teaching it. The routing vocabulary is one taxonomy
+      # shared by both branches and by {SkillDeepProbe}.
+      def check_awareness(deep)
+        return presence_only_check_awareness if deep.nil?
+        return deep_failure_check_awareness if deep.failed?
+
+        <<~DEEP.chomp
+          The recommendation above already factors in the `--deep` check result, using the
+          same routing this command teaches without `--deep`: proven project monkey-patches
+          → rigor-monkeypatch-resolve; `RBS classes available: 0` or a `configuration-error`
+          → rigor-doctor; remaining error diagnostics → rigor-baseline-reduce. It does not
+          route on weaker signals (framework calls typing as Dynamic → rigor-plugin-tune is
+          still yours to judge from the check output).
+        DEEP
+      end
+
+      def presence_only_check_awareness
+        <<~PROMPT.chomp
           The recommendation above is from a presence-only probe — it does not run
           `rigor check`. If you have run (or now run) `rigor check`, let its findings
           refine the choice:
@@ -287,9 +346,16 @@ module Rigor
           - framework calls (ActiveRecord, routes, i18n …) typing as Dynamic with no
             matching plugins enabled → rigor-plugin-tune
           - `RBS classes available: 0` or a `configuration-error` diagnostic → rigor-doctor
+          (`rigor skill describe --deep` runs that check for you and applies this routing
+          to the headline itself — at the cost of a full analysis.)
+        PROMPT
+      end
 
-          Re-run `rigor skill describe` whenever you need the next step — it always
-          reflects the project's current state.
+      def deep_failure_check_awareness
+        <<~PROMPT.chomp
+          The `--deep` check did NOT complete, so the recommendation above is the
+          presence-only one. Do not treat the project as clean: run `rigor doctor`
+          (or `rigor check`) and fix what it reports before trusting any routing.
         PROMPT
       end
 

data/lib/rigor/environment/default_libraries.rb

@@ -6,10 +6,11 @@ module Rigor
     # unless the caller passes an explicit `libraries:` array. Each entry MUST be a stdlib library name
     # accepted by `RBS::EnvironmentLoader#has_library?`; unknown libraries MUST fail-soft
     # (`RbsLoader#build_env` already filters through `has_library?`). The default set covers the common
-    # stdlib surface a Ruby program is likely to import (`pathname`, `optparse`, `json`, `yaml`, `fileutils`,
-    # `tempfile`, `uri`, `logger`, `date`) plus the analyzer-adjacent gems shipping their own RBS in this
-    # bundle (`prism`, `rbs`). On hosts where one of these libraries is not installed, the loader silently
-    # drops it.
+    # stdlib surface a Ruby program is likely to import, plus the analyzer-adjacent gems shipping their own
+    # RBS in this bundle (`prism`, `rbs`). The list below is the enumeration — no prose gloss restates a
+    # subset of it, here or in `docs/internal-spec/inference-engine.md` § Environment Surface, because a
+    # restated subset silently rots as entries are added. On hosts where one of these libraries is not
+    # installed, the loader silently drops it.
     #
     # Callers MAY add to the default by passing `libraries: %w[csv ...]`; the explicit list is appended to
     # `DEFAULT_LIBRARIES` and de-duplicated. Callers that need a strictly RBS-core view MUST construct an

data/lib/rigor/environment.rb

@@ -394,7 +394,8 @@ module Rigor
         cache_store.fetch_or_compute(
           producer_id: SYNTHESIZER_CACHE_PRODUCER_ID,
           params: {},
-          descriptor: descriptor
+          descriptor: descriptor,
+          generation_cap: synthesizer_generation_cap
         ) { invoke_synthesizer_safely(callable, path) || "" }
       end
 
@@ -420,6 +421,14 @@ module Rigor
       SYNTHESIZER_CACHE_PRODUCER_ID = "plugin.source_rbs_synthesizer"
       private_constant :SYNTHESIZER_CACHE_PRODUCER_ID
 
+      # One entry per (plugin, source file), all of them live for as long as the file is in the project — a
+      # generation count says nothing about staleness here, so this producer declares itself out of
+      # `Cache::Store#evict!`'s compaction pass and is bounded only by the size-based LRU pass. A method
+      # rather than a constant: `Cache::Store` is not loaded yet when this class body runs.
+      def synthesizer_generation_cap
+        Cache::Store::UNBOUNDED_GENERATIONS
+      end
+
       def build_synthesizer_cache_descriptor(plugin, path)
         Cache::Descriptor.new(
           files: [Cache::Descriptor::FileEntry.new(

data/lib/rigor/inference/method_dispatcher/overload_selector.rb

@@ -55,7 +55,12 @@ module Rigor
           "::io" => ["IO"],
           "::encoding" => %w[Encoding String],
           "::path" => ["String"],
-          "::boolean" => %w[TrueClass FalseClass]
+          "::boolean" => %w[TrueClass FalseClass],
+          # `range[T] = Range[T] | _Range[T]`. Generic, unlike the others, but the strict arm is still a
+          # single nominal and the args are irrelevant to this pass. rbs 4.1 rewrote `Array#[]`'s slicing
+          # overload from `(::Range[::Integer?])` to `(range[int])`; without the entry both it and the
+          # `(int) -> E` overload look alias-typed, so `a[1..2]` resolved to the element type.
+          "::range" => ["Range"]
         }.freeze
         private_constant :ALIAS_STRICT_NOMINALS
 

data/lib/rigor/language_server/buffer_resolution.rb

@@ -13,12 +13,15 @@ module Rigor
     module BufferResolution
       private
 
-      # Resolves `[path, entry]` for the document `uri`, or nil when the uri has no file path or no open
-      # buffer. A caller that destructures `path, entry = buffer_for(uri)` can guard on `entry.nil?` to cover
-      # both misses (a nil return leaves both locals nil).
+      # Resolves `[path, entry]` for the document `uri`, or nil when the uri has no file path, no open buffer,
+      # or a buffer the server could not keep in sync with the editor (see `BufferTable#apply_changes`) — a
+      # position answered from text that has drifted from the editor's is worse than no answer. A caller that
+      # destructures `path, entry = buffer_for(uri)` can guard on `entry.nil?` to cover every miss (a nil
+      # return leaves both locals nil).
       def buffer_for(uri)
         path = Uri.to_path(uri)
         return nil if path.nil?
+        return nil if @buffer_table.desynchronized?(uri)
 
         entry = @buffer_table[uri]
         return nil if entry.nil?

data/lib/rigor/language_server/buffer_table.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "incremental_sync"
+
 module Rigor
   module LanguageServer
     # Per-session virtual file table. The LSP server maintains the canonical view of every open buffer here;
     # analysis (slice 4+) reads from this table instead of disk so in-flight edits are reflected immediately.
     #
-    # Keyed by `DocumentUri` (LSP `file://...` URIs). v1 ships FULL text sync (LSP
-    # `TextDocumentSyncKind::Full = 1`) so each `didChange` carries the entire buffer text — there's no
-    # incremental edit application yet. Incremental sync is slice 10 (deferred per the design doc).
+    # Keyed by `DocumentUri` (LSP `file://...` URIs). Sync is INCREMENTAL (LSP
+    # `TextDocumentSyncKind::Incremental = 2`): a `didChange` carries range edits which {#apply_changes} splices
+    # into the held text through {IncrementalSync}. The full-text form ({#change}, and a `contentChanges` entry
+    # with no `range`) stays supported — it is still legal under incremental sync and is what `didOpen` and a
+    # client-side resync send.
     class BufferTable
       # @!attribute uri      [String]  the LSP DocumentUri (e.g. `file:///abs/path/lib/foo.rb`).
       # @!attribute bytes    [String]  the current full text of the buffer.
@@ -16,23 +20,59 @@ module Rigor
 
       def initialize
         @entries = {}
+        @desynchronized = {}
       end
 
       # Records a `textDocument/didOpen` event. Replaces any existing entry (LSP clients may re-open a
-      # previously closed URI; the new version is authoritative).
+      # previously closed URI; the new version is authoritative) and clears any desynchronised mark — the
+      # payload carries the client's full text, so the two views agree again.
       def open(uri:, bytes:, version:)
+        @desynchronized.delete(uri)
         @entries[uri] = Entry.new(uri: uri, bytes: bytes, version: version)
       end
 
-      # Records a `textDocument/didChange` event under FULL sync. The full new buffer text replaces the entry.
-      # If the client sends a `didChange` for a URI that was never opened (spec violation), the entry is still
+      # Records a full-text `textDocument/didChange`. The full new buffer text replaces the entry. If the
+      # client sends a `didChange` for a URI that was never opened (spec violation), the entry is still
       # created — defensive.
       def change(uri:, bytes:, version:)
+        @desynchronized.delete(uri)
         @entries[uri] = Entry.new(uri: uri, bytes: bytes, version: version)
       end
 
+      # Applies a `textDocument/didChange` payload under INCREMENTAL sync. Each entry of `changes` is applied
+      # in order against the result of the previous one, per the LSP contract.
+      #
+      # On success the entry is replaced with the spliced text at the new version. On failure — a malformed
+      # change, or a range edit for a URI with no held buffer — the held text is left EXACTLY as it was and the
+      # URI is marked desynchronised: the server's view and the editor's view have diverged, and every position
+      # computed from the stale text would be wrong. Consumers check {#desynchronized?} and decline to answer
+      # rather than answering wrongly; the mark clears on the next `didOpen` or full-text change.
+      #
+      # @return [Boolean] true when the changes were applied.
+      def apply_changes(uri:, changes:, version:)
+        text = IncrementalSync.apply_all(@entries[uri]&.bytes, changes)
+        @desynchronized.delete(uri)
+        @entries[uri] = Entry.new(uri: uri, bytes: text, version: version)
+        true
+      rescue IncrementalSync::UnappliableChange => e
+        @desynchronized[uri] = e.message
+        false
+      end
+
+      # @return [Boolean] true when the last `didChange` for `uri` could not be applied, so the held text no
+      #   longer matches the editor's.
+      def desynchronized?(uri)
+        @desynchronized.key?(uri)
+      end
+
+      # @return [String, nil] why `uri` is desynchronised, for the log line; nil when it is in sync.
+      def desynchronization_reason(uri)
+        @desynchronized[uri]
+      end
+
       # Records a `textDocument/didClose` event. The entry is removed. Subsequent reads via `#[]` return nil.
       def close(uri:)
+        @desynchronized.delete(uri)
         @entries.delete(uri)
       end
 

data/lib/rigor/language_server/diagnostic_publisher.rb

@@ -80,6 +80,10 @@ module Rigor
         # The buffer may have been closed during the debounce window — drop the publish; the empty
         # notification from didClose already cleared the markers.
         return if entry.nil?
+        # An incremental change the table could not apply: the held text no longer matches the editor's, so
+        # every span we could compute from it would be misplaced. Clear the markers and stay silent until a
+        # full-text change or a re-open re-establishes the buffer.
+        return notify(uri, []) if @buffer_table.desynchronized?(uri)
 
         diagnostics = run_analysis(path: path, bytes: entry.bytes)
         notify(uri, diagnostics)

data/lib/rigor/language_server/incremental_sync.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Rigor
+  module LanguageServer
+    # Applies LSP `TextDocumentContentChangeEvent`s to a held buffer under `TextDocumentSyncKind::Incremental`.
+    #
+    # ## Why the offsets need care
+    #
+    # An LSP `Position#character` counts **UTF-16 code units** (`positionEncoding: "utf-16"`, the protocol
+    # default and the only encoding every client supports), while a Ruby String indexes by **codepoint**. The
+    # two agree for every character in the Basic Multilingual Plane — all of ASCII, Latin-1, Greek, Cyrillic,
+    # kana and common kanji — and disagree above U+FFFF, where an emoji or a CJK-extension ideograph is ONE
+    # Ruby character and TWO UTF-16 code units. Reading one as the other shifts every subsequent edit on the
+    # line, and a shifted edit desynchronises the server's text from what the editor shows for the rest of the
+    # session: every diagnostic after that point lands on the wrong span, silently.
+    #
+    # So the conversion is explicit. {.utf16_offset_to_index} walks the line one character at a time, charging
+    # 2 code units for a codepoint above U+FFFF and 1 for everything else, and stops when the requested count
+    # is spent. An all-ASCII line short-circuits the walk, since there the offset IS the index — that is the
+    # keystroke path, and `String#ascii_only?` answers it from the cached coderange.
+    #
+    # ## Failure is a resync, never a guess
+    #
+    # A change whose shape cannot be applied confidently raises {UnappliableChange} rather than producing a
+    # best-effort buffer: {BufferTable#apply_changes} then keeps the last known-good text and marks the URI
+    # desynchronised, which suppresses diagnostics until a full-text change or a re-open re-establishes the
+    # buffer. A stale-but-flagged buffer is recoverable; a silently wrong one is not.
+    module IncrementalSync
+      # Raised when a `contentChanges` entry cannot be applied to the held text: a malformed payload, a
+      # position that is not a non-negative Integer pair, or a range edit against a buffer the server never
+      # received a `didOpen` / full-text change for.
+      class UnappliableChange < StandardError; end
+
+      # LSP considers a line delimited by `\n`, `\r\n`, or a lone `\r`. Ruby's own line splitting only knows
+      # `\n`, so the scan is explicit.
+      LINE_TERMINATOR = /\r\n|\n|\r/
+
+      # UTF-8 encodes exactly the codepoints above the BMP — the ones UTF-16 must encode as a surrogate pair —
+      # in four bytes. So a character's UTF-8 byte length answers "one code unit or two?" without decoding it.
+      SURROGATE_PAIR_BYTES = 4
+
+      module_function
+
+      # Applies every change in order, each against the result of the previous — the LSP contract for a
+      # multi-change `didChange` notification.
+      #
+      # @param text [String, nil] the held buffer text; nil when no buffer is open for the URI.
+      # @param changes [Array<Hash>] the `contentChanges` array.
+      # @return [String] the new buffer text.
+      # @raise [UnappliableChange] if any change cannot be applied.
+      def apply_all(text, changes)
+        raise UnappliableChange, "contentChanges must be an Array, got #{changes.class}" unless changes.is_a?(Array)
+
+        changes.reduce(text) { |acc, change| apply(acc, change) }
+      end
+
+      # Applies one `TextDocumentContentChangeEvent`.
+      #
+      # Two shapes are legal under incremental sync. Without `range` the entry is the full new document text
+      # (clients fall back to it for a paste, an undo, or a file reload, and it stays legal under
+      # `Incremental`); with `range` it replaces the spanned text. `rangeLength` is the deprecated pre-3.16
+      # companion to `range` and is accepted-but-ignored: it is redundant with `range`, historically ambiguous
+      # about its units, and `range` is the authoritative field.
+      #
+      # @raise [UnappliableChange]
+      def apply(text, change)
+        raise UnappliableChange, "contentChanges entry must be a Hash, got #{change.class}" unless change.is_a?(Hash)
+
+        replacement = change[:text]
+        raise UnappliableChange, "contentChanges entry has no `text`" unless replacement.is_a?(String)
+
+        range = change[:range]
+        return replacement.dup if range.nil?
+        raise UnappliableChange, "`range` must be a Hash, got #{range.class}" unless range.is_a?(Hash)
+        raise UnappliableChange, "range edit for a URI with no open buffer" if text.nil?
+
+        splice(text, range, replacement)
+      end
+
+      # Replaces the `range` span of `text` with `replacement`.
+      #
+      # Text that is not valid UTF-8 makes the line scan itself raise. That is not a buffer JSON transport can
+      # deliver, but if one appears there is no offset arithmetic to be confident about, so it becomes a
+      # resync like any other unappliable shape.
+      def splice(text, range, replacement)
+        spans = line_spans(text)
+        from = char_offset(text, spans, range[:start])
+        # A client that inverts the range — or an `end` rounded below `start` off a mid-surrogate
+        # position — would otherwise slice backwards; collapse to an insertion at `from` instead.
+        to = char_offset(text, spans, range[:end]).clamp(from, text.length)
+        "#{text[0, from]}#{replacement}#{text[to..]}"
+      rescue ArgumentError, Encoding::CompatibilityError => e
+        raise UnappliableChange, "held text is not valid UTF-8: #{e.message}"
+      end
+
+      # @return [Array<Array(Integer, Integer)>] one `[content_start, content_end]` pair per line, in Ruby
+      #   character indices. `content_end` excludes the line terminator, so it doubles as the clamp target for
+      #   an over-long `character`. A trailing terminator yields a final empty span — the virtual last line an
+      #   editor puts the cursor on, and the anchor for an end-of-document insert.
+      def line_spans(text)
+        spans = []
+        scanner = StringScanner.new(text)
+        start = 0
+        while scanner.skip_until(LINE_TERMINATOR)
+          stop = scanner.charpos
+          spans << [start, stop - scanner.matched.length]
+          start = stop
+        end
+        spans << [start, text.length]
+        spans
+      end
+
+      # Converts an LSP `Position` into a Ruby character index into `text`.
+      #
+      # A `line` past the last line clamps to the end of the document rather than raising: clients do address
+      # the position one past the final line, and the clamp is what the protocol's own end-of-document
+      # convention implies.
+      def char_offset(text, spans, position)
+        line = position_field(position, :line)
+        character = position_field(position, :character)
+        return text.length if line >= spans.length
+
+        start, stop = spans[line]
+        start + utf16_offset_to_index(text[start...stop], character)
+      end
+
+      # Converts a UTF-16 code-unit offset into `line` to a Ruby character index into the same line.
+      #
+      # Clamps an offset past the end of the line to the line length, per LSP's rule that a `character`
+      # greater than the line length defaults back to the line length.
+      def utf16_offset_to_index(line, units)
+        # Fast path: on an all-ASCII line one UTF-16 code unit is one Ruby character, so the offset is the
+        # index. This is the keystroke case, and `ascii_only?` reads the string's cached coderange.
+        return units.clamp(0, line.length) if line.ascii_only?
+
+        index = 0
+        remaining = units
+        line.each_char do |char|
+          break if remaining <= 0
+
+          remaining -= char.bytesize == SURROGATE_PAIR_BYTES ? 2 : 1
+          index += 1
+        end
+        # `remaining` below zero means the offset addressed the low half of a surrogate pair — a position no
+        # conforming client sends. Round DOWN to the character boundary; splitting the pair is not an option.
+        remaining.negative? ? index - 1 : index
+      end
+
+      def position_field(position, key)
+        value = position.is_a?(Hash) ? position[key] : nil
+        return value if value.is_a?(Integer) && !value.negative?
+
+        raise UnappliableChange, "position `#{key}` must be a non-negative Integer, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/rigor/language_server/server.rb

@@ -21,8 +21,15 @@ module Rigor
       ERROR_SERVER_NOT_INITIALIZED = -32_002
       ERROR_INVALID_REQUEST_AFTER_SHUTDOWN = -32_600
 
-      # `TextDocumentSyncKind::Full = 1`. Slice 10 (deferred) promotes to `Incremental = 2`.
-      TEXT_DOCUMENT_SYNC_FULL = 1
+      # `TextDocumentSyncKind::Incremental = 2`: `didChange` carries range edits, which `IncrementalSync`
+      # splices into the buffer the table already holds instead of re-sending — and re-parsing — the whole
+      # document on every keystroke. The full-text entry form (a `contentChanges` entry with no `range`) stays
+      # legal under this mode and is still handled.
+      TEXT_DOCUMENT_SYNC_INCREMENTAL = 2
+
+      # LSP `PositionEncodingKind`. UTF-16 is the protocol default and the encoding `IncrementalSync` does its
+      # offset arithmetic in; advertising it explicitly states the contract rather than leaving it implied.
+      POSITION_ENCODING_UTF16 = "utf-16"
 
       # Methods callable BEFORE `initialize`. Per LSP spec § 3 only `initialize` and `exit` are allowed
       # pre-initialization; every other request returns `ServerNotInitialized`. We also accept `shutdown` so a
@@ -151,9 +158,10 @@ module Rigor
 
       def advertised_capabilities
         caps = {
+          positionEncoding: POSITION_ENCODING_UTF16,
           textDocumentSync: {
             openClose: true,
-            change: TEXT_DOCUMENT_SYNC_FULL
+            change: TEXT_DOCUMENT_SYNC_INCREMENTAL
           }
         }
         caps[:hoverProvider] = true if @hover_provider
@@ -213,19 +221,21 @@ module Rigor
         nil
       end
 
-      # textDocument/didChange under FULL sync. Each `contentChanges` entry carries only `{ text: }`; the LAST
-      # entry is the new full document text. Per LSP spec § "FULL sync" the array MUST be exactly one entry in
-      # practice — we still take `.last` defensively for clients that pad. Triggers `publishDiagnostics`
-      # afterwards.
+      # textDocument/didChange under INCREMENTAL sync. Every `contentChanges` entry is applied in order, each
+      # against the result of the previous — an entry with a `range` splices that span, an entry without one is
+      # the full new document text. The application (and its UTF-16 offset arithmetic) lives in
+      # `IncrementalSync`; the table keeps the last known-good text and flags the URI when a change cannot be
+      # applied. Triggers `publishDiagnostics` either way: a desynchronised buffer publishes an EMPTY set,
+      # which clears the markers instead of leaving stale ones on screen.
       def handle_did_change(params)
         doc = params.fetch(:textDocument)
         changes = params.fetch(:contentChanges)
         return nil if changes.empty?
 
         uri = doc.fetch(:uri)
-        @buffer_table.change(
+        @buffer_table.apply_changes(
           uri: uri,
-          bytes: changes.last.fetch(:text),
+          changes: changes,
           version: doc.fetch(:version)
         )
         @publisher&.publish_for(uri)

data/lib/rigor/language_server.rb

@@ -9,6 +9,7 @@ module Rigor
   end
 end
 
+require_relative "language_server/incremental_sync"
 require_relative "language_server/buffer_table"
 require_relative "language_server/uri"
 require_relative "language_server/project_context"

data/lib/rigor/plugin/base.rb

@@ -8,6 +8,9 @@ require "prism"
 require_relative "manifest"
 require_relative "node_context"
 require_relative "../analysis/diagnostic"
+# `producer generation_cap:` defaults to (and validates against) `Cache::Store::UNBOUNDED_GENERATIONS`, and a
+# plugin class body can be evaluated before anything else pulled the cache layer in.
+require_relative "../cache/store"
 require_relative "../source/node_walker"
 
 module Rigor
@@ -86,17 +89,40 @@ module Rigor
         #
         # Producer ids are auto-prefixed `plugin.<manifest.id>.` at the cache layer (slice 6-C) so plugin-side
         # ids cannot collide with built-in producers.
-        def producer(id, watch: nil, serialize: nil, deserialize: nil, &block)
+        #
+        # `generation_cap:` declares how many generations of this producer's entries survive
+        # `Cache::Store#evict!`'s compaction pass. The default —
+        # `Cache::Store::UNBOUNDED_GENERATIONS` — suits the usual plugin producer, which keys per file or per
+        # discovered unit and keeps many entries live at once; only the size-based LRU pass bounds it. A
+        # producer whose entries are WHOLE-PROJECT and content-keyed (each run's inputs produce a fresh key
+        # and orphan the previous one) should declare a small positive Integer instead, so the orphans are
+        # reclaimed rather than accumulating under the global byte cap.
+        def producer(id, watch: nil, serialize: nil, deserialize: nil,
+                     generation_cap: Cache::Store::UNBOUNDED_GENERATIONS, &block)
           raise ArgumentError, "Plugin::Base.producer requires a block body" if block.nil?
 
           validate_producer_watch!(watch)
+          validate_producer_generation_cap!(id, generation_cap)
           @producers ||= {}
           @producers[id.to_sym] = {
-            block: block, watch: watch, serialize: serialize, deserialize: deserialize
+            block: block, watch: watch, serialize: serialize, deserialize: deserialize,
+            generation_cap: generation_cap
           }.freeze
           id.to_sym
         end
 
+        # A bad `generation_cap:` is caught at class-definition time (plugin load) rather than at the first
+        # `cache_for` round-trip, so the plugin author sees it before any caching happens.
+        def validate_producer_generation_cap!(id, generation_cap)
+          return if generation_cap == Cache::Store::UNBOUNDED_GENERATIONS
+          return if generation_cap.is_a?(Integer) && generation_cap.positive?
+
+          raise ArgumentError,
+                "Plugin::Base.producer #{id.inspect} generation_cap: must be a positive Integer or " \
+                "#{Cache::Store::UNBOUNDED_GENERATIONS.inspect}, got #{generation_cap.inspect}"
+        end
+        private :validate_producer_generation_cap!
+
         # ADR-60 WD3 — `watch:` is nil (no glob coverage), a static tuple Array, or a Proc evaluated per
         # `cache_for` call.
         def validate_producer_watch!(watch)
@@ -728,6 +754,7 @@ module Rigor
           store.fetch_or_validate(
             producer_id: prefixed_id,
             key_descriptor: key_descriptor,
+            generation_cap: producer[:generation_cap],
             params: params,
             serialize: pair_serializer(producer[:serialize]),
             deserialize: pair_deserializer(producer[:deserialize])