rigortype 0.1.5 → 0.1.6

data/lib/rigor/inference/scope_indexer.rb

@@ -177,8 +177,10 @@ module Rigor
         return if def_node.body.nil? || qualified_prefix.empty?
 
         class_name = qualified_prefix.join("::")
+        singleton = def_node.receiver.is_a?(Prism::SelfNode) ||
+                    def_receiver_targets_lexical_self?(def_node.receiver, qualified_prefix)
         self_type =
-          if def_node.receiver.is_a?(Prism::SelfNode)
+          if singleton
             Type::Combinator.singleton_of(class_name)
           else
             Type::Combinator.nominal_of(class_name)
@@ -371,9 +373,12 @@ module Rigor
             return
           end
         when Prism::SingletonClassNode
-          if node.expression.is_a?(Prism::SelfNode) && node.body
-            walk_methods(node.body, qualified_prefix, true, accumulator)
-            return
+          if node.body
+            singleton_prefix = singleton_class_prefix(node, qualified_prefix)
+            if singleton_prefix
+              walk_methods(node.body, singleton_prefix, true, accumulator)
+              return
+            end
           end
         when Prism::ConstantWriteNode
           if meta_new_block_body(node)
@@ -395,6 +400,30 @@ module Rigor
           walk_methods(child, qualified_prefix, in_singleton_class, accumulator)
         end
       end
+
+      # Resolves a `class << X` body's qualified prefix.
+      #   - `class << self` keeps `qualified_prefix` (the enclosing class).
+      #   - `class << Foo` inside `class Foo` collapses to the same prefix
+      #     (semantically `class << self`).
+      #   - `class << Foo` not nested in `class Foo` returns `[Foo]`
+      #     so methods defined inside register on Foo's singleton.
+      #   - Any other expression (variable, method call) returns nil
+      #     so the walker falls through and skips the body.
+      def singleton_class_prefix(node, qualified_prefix)
+        case node.expression
+        when Prism::SelfNode
+          qualified_prefix
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          rendered = qualified_name_for(node.expression)
+          return nil unless rendered
+
+          if !qualified_prefix.empty? && qualified_prefix.last == rendered
+            qualified_prefix
+          else
+            rendered.split("::")
+          end
+        end
+      end
       # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
 
       # v0.1.2 — when a `Const = Data.define(*sym) do ... end`
@@ -418,11 +447,50 @@ module Rigor
         return if qualified_prefix.empty?
 
         class_name = qualified_prefix.join("::")
-        kind = def_node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
+        singleton = def_singleton?(def_node, qualified_prefix, in_singleton_class)
+        kind = singleton ? :singleton : :instance
         accumulator[class_name] ||= {}
         accumulator[class_name][def_node.name] = kind
       end
 
+      # `def Foo.bar` inside `module Foo` (or `def Meta.init` inside
+      # `module Meta`) is semantically equivalent to `def self.bar`:
+      # at the def-site, the runtime value of the constant `Foo` is
+      # the module itself (== `self`). Recognise the form so the
+      # method registers as singleton on the enclosing class.
+      #
+      # The cross-class form `def Bar.baz` inside `module Foo` —
+      # where the receiver names a constant other than the
+      # enclosing class — is not supported at this slice; falls
+      # through to `:instance` (current behaviour) rather than
+      # silently re-routing the registration.
+      def def_singleton?(def_node, qualified_prefix, in_singleton_class)
+        return true if def_node.receiver.is_a?(Prism::SelfNode) || in_singleton_class
+
+        def_receiver_targets_lexical_self?(def_node.receiver, qualified_prefix)
+      end
+
+      # Only `Prism::ConstantReadNode` is observed in real Ruby —
+      # Prism mis-parses `def C::P.method` as `def C.P` (Ruby itself
+      # rejects the form as a SyntaxError). The ConstantPathNode
+      # branch stays defensive in case Prism's grammar widens.
+      def def_receiver_targets_lexical_self?(receiver, qualified_prefix)
+        return false if qualified_prefix.empty?
+
+        case receiver
+        when Prism::ConstantReadNode
+          receiver.name.to_s == qualified_prefix.last
+        when Prism::ConstantPathNode
+          rendered = render_constant_path(receiver)
+          return false unless rendered
+
+          path = rendered.split("::")
+          qualified_prefix.last(path.length) == path
+        else
+          false
+        end
+      end
+
       # v0.0.2 #5 — instance-side def-node recording. Walks
       # class bodies the same way as `build_discovered_methods`
       # but records the actual `Prism::DefNode` for each
@@ -452,9 +520,12 @@ module Rigor
             return
           end
         when Prism::SingletonClassNode
-          if node.expression.is_a?(Prism::SelfNode) && node.body
-            walk_def_nodes(node.body, qualified_prefix, true, accumulator)
-            return
+          if node.body
+            singleton_prefix = singleton_class_prefix(node, qualified_prefix)
+            if singleton_prefix
+              walk_def_nodes(node.body, singleton_prefix, true, accumulator)
+              return
+            end
           end
         when Prism::ConstantWriteNode
           if meta_new_block_body(node)
@@ -481,7 +552,7 @@ module Rigor
       TOP_LEVEL_DEF_KEY = "<toplevel>"
 
       def record_def_node(def_node, qualified_prefix, in_singleton_class, accumulator)
-        return if def_node.receiver.is_a?(Prism::SelfNode) || in_singleton_class
+        return if def_singleton?(def_node, qualified_prefix, in_singleton_class)
 
         class_name = qualified_prefix.empty? ? TOP_LEVEL_DEF_KEY : qualified_prefix.join("::")
         accumulator[class_name] ||= {}
@@ -530,9 +601,12 @@ module Rigor
             return current_visibility
           end
         when Prism::SingletonClassNode
-          if node.expression.is_a?(Prism::SelfNode) && node.body
-            walk_method_visibilities(node.body, qualified_prefix, true, :public, accumulator)
-            return current_visibility
+          if node.body
+            singleton_prefix = singleton_class_prefix(node, qualified_prefix)
+            if singleton_prefix
+              walk_method_visibilities(node.body, singleton_prefix, true, :public, accumulator)
+              return current_visibility
+            end
           end
         when Prism::ConstantWriteNode
           if meta_new_block_body(node)
@@ -703,6 +777,76 @@ module Rigor
         node.unescaped&.to_sym
       end
 
+      # Walks every file in `paths` (each path is parsed once with
+      # `Prism.parse_file`) and returns the unioned project-wide
+      # `discovered_classes` Hash: `{qualified_name => Singleton[…]}`.
+      # Used by `Analysis::Runner` to seed each file's
+      # `default_scope.discovered_classes` so that lexical
+      # constant lookup in one file resolves a `class Foo`
+      # declared in a sibling file. Per-file collisions are
+      # last-write-wins (matches the existing in-file merge
+      # semantics). Parse failures fail-soft to an empty
+      # contribution. The `buffer` argument, when present,
+      # redirects reads for the bound logical path to the
+      # buffer's physical path so editor-mode pre-passes see
+      # the in-flight bytes.
+      #
+      # **Modules are intentionally excluded** from the
+      # project-wide seed: a `module M; module_function; def x; end; end`
+      # body, when surfaced as `singleton(M)` to the dispatcher,
+      # falls through to `Kernel#x` (or any Module ancestor
+      # method) when the project's per-file
+      # `discovered_methods` doesn't know `M.x` — leading to
+      # surprising types like `Kernel.select → Array[String]`.
+      # Until cross-file `discovered_methods` follows the same
+      # project-wide seed, registering modules here would
+      # introduce regressions in modules-with-module_function
+      # idioms that previously resolved to `Dynamic[Top]`.
+      # Class declarations are safe because per-file
+      # `discovered_methods` already tracks `def self.x` /
+      # `def x` instance and singleton methods consistently.
+      #
+      # @param paths  [Array<String>] project file paths.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @return [Hash{String => Rigor::Type::Singleton}]
+      def discovered_classes_for_paths(paths, buffer: nil)
+        accumulator = {}
+        paths.each do |path|
+          physical = buffer ? buffer.resolve(path) : path
+          source = File.read(physical)
+          root = Prism.parse(source, filepath: path).value
+          collect_class_decls(root, [], accumulator)
+        rescue StandardError
+          # Skip files that fail to parse or read; the per-file
+          # analyzer surfaces the parse error separately.
+          next
+        end
+        accumulator.freeze
+      end
+
+      # Class-only variant of `record_declarations` — descends
+      # into nested module bodies (so `module Foo; class Bar`
+      # registers `Foo::Bar`) but never registers the module
+      # itself in `accumulator`.
+      def collect_class_decls(node, qualified_prefix, accumulator)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            full = (qualified_prefix + [name]).join("::")
+            accumulator[full] = Type::Combinator.singleton_of(full)
+            return collect_class_decls(node.body, qualified_prefix + [name], accumulator) if node.body
+          end
+        when Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          return collect_class_decls(node.body, qualified_prefix + [name], accumulator) if name && node.body
+        end
+
+        node.compact_child_nodes.each { |child| collect_class_decls(child, qualified_prefix, accumulator) }
+      end
+
       # Walks the program once for `Prism::ModuleNode` and
       # `Prism::ClassNode`, recording the `Singleton[<qualified>]`
       # type for the outermost `constant_path` node of each

data/lib/rigor/inference/statement_evaluator.rb

@@ -760,6 +760,19 @@ module Rigor
       # name as a Symbol, so the produced type is `Constant[:name]`.
       def eval_def(node)
         body_scope = build_method_entry_scope(node)
+        # Parameter default value expressions (e.g. `self.x` in
+        # `def copy(x: self.x)`) execute when the method is
+        # *invoked*, not when the `def` is read; their `self` is
+        # the instance receiver, not the surrounding class body.
+        # Walk the parameters subtree under `body_scope` so the
+        # scope-index records the instance `self_type` for every
+        # node inside parameter defaults. `propagate` would
+        # otherwise drop them to the outer class-body scope (where
+        # `self_type` is `singleton(C)`), making `self.foo` look
+        # like a singleton-side call. Observed surfacing 915 false
+        # positives in `prism-1.9.0`'s auto-generated `copy`
+        # methods alone.
+        sub_eval(node.parameters, body_scope, class_context: @class_context) if node.parameters
         sub_eval(node.body, body_scope, class_context: @class_context) if node.body
         [Type::Combinator.constant_of(node.name), scope]
       end
@@ -783,6 +796,21 @@ module Rigor
       def eval_call(node)
         call_type = scope.type_of(node, tracer: tracer)
         evaluate_block_if_present(node)
+        # `ruby2_keywords def foo(...)` (and similar wrappers like
+        # `private def`, `public def`, `module_function def`) parse
+        # the def as the call's positional argument; the
+        # ExpressionTyper#type_of_def handler types it as
+        # `Constant[:foo]` without walking the body. Without
+        # explicitly evaluating the argument-position def, the body's
+        # scope-index entries inherit the outer class-body
+        # `self_type = singleton(C)` from `ScopeIndexer.propagate`,
+        # so `self.helper` inside reports `undefined method 'helper'
+        # for singleton(C)`. Walking each argument-position def under
+        # the current evaluator (not a sub_eval — the def's effects
+        # do not bind into the surrounding scope) populates the
+        # scope index with the correct instance / singleton
+        # `self_type` for the def's body.
+        evaluate_def_arguments(node)
         post_scope = record_closure_escape_if_any(node)
         post_scope = apply_rbs_extended_assertions(node, post_scope)
         post_scope = apply_plugin_assertions(node, post_scope)
@@ -790,6 +818,15 @@ module Rigor
         [call_type, post_scope]
       end
 
+      def evaluate_def_arguments(call_node)
+        args = call_node.arguments
+        return unless args.respond_to?(:arguments)
+
+        args.arguments.each do |arg|
+          eval_def(arg) if arg.is_a?(Prism::DefNode)
+        end
+      end
+
       # v0.0.3 — recognises a small catalogue of RSpec
       # matcher patterns as assert-shaped narrows on the
       # local passed to `expect(...)`. The pattern is
@@ -1399,7 +1436,37 @@ module Rigor
       end
 
       def singleton_def?(def_node)
-        def_node.receiver.is_a?(Prism::SelfNode) || current_frame_singleton?
+        return true if def_node.receiver.is_a?(Prism::SelfNode) || current_frame_singleton?
+
+        def_receiver_targets_lexical_self?(def_node.receiver)
+      end
+
+      # `def Foo.bar` inside `module Foo` (or `def Meta.init` inside
+      # `module Meta`) — explicit-receiver def that semantically
+      # equals `def self.bar` because the receiver constant
+      # resolves to `self` at the def-site. Matched against the
+      # current class context's tail to cover both the
+      # `def OpenURI.x` form (single segment) and the
+      # `def OpenURI::Meta.x` form (qualified path). Cross-class
+      # receivers (`def Bar.baz` inside `module Foo` where the
+      # receiver names a different constant) are not promoted to
+      # singleton at this slice.
+      def def_receiver_targets_lexical_self?(receiver)
+        return false if @class_context.empty?
+
+        prefix = @class_context.map(&:name)
+        case receiver
+        when Prism::ConstantReadNode
+          receiver.name.to_s == prefix.last
+        when Prism::ConstantPathNode
+          rendered = render_constant_path(receiver)
+          return false unless rendered
+
+          path = rendered.split("::")
+          prefix.last(path.length) == path
+        else
+          false
+        end
       end
 
       # Slice A-engine. Inside a class body `class Foo; ...; end`,
@@ -1452,12 +1519,45 @@ module Rigor
       end
 
       def singleton_context_for(node)
-        return @class_context unless node.expression.is_a?(Prism::SelfNode)
-        return @class_context if @class_context.empty?
+        case node.expression
+        when Prism::SelfNode
+          return @class_context if @class_context.empty?
+
+          outer = @class_context[0..-2]
+          last = @class_context.last
+          outer + [ClassFrame.new(name: last.name, singleton: true)]
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          target = singleton_constant_target(node.expression)
+          return @class_context unless target
+
+          # `class << Foo` inside `class Foo` (the canonical
+          # pattern in Ruby's own time.rb) is semantically
+          # `class << self` — replace the enclosing frame with a
+          # singleton frame for the same name so method
+          # registration and `self_type` lookup land on Foo.
+          # When the target names a different constant (rare
+          # cross-class form), append a fresh singleton frame
+          # tagged with the target FQN; the bodies are scoped to
+          # that target rather than to the lexical enclosing
+          # class.
+          if !@class_context.empty? && @class_context.last.name == target
+            outer = @class_context[0..-2]
+            outer + [ClassFrame.new(name: target, singleton: true)]
+          else
+            [ClassFrame.new(name: target, singleton: true)]
+          end
+        else
+          @class_context
+        end
+      end
 
-        outer = @class_context[0..-2]
-        last = @class_context.last
-        outer + [ClassFrame.new(name: last.name, singleton: true)]
+      def singleton_constant_target(expression)
+        case expression
+        when Prism::ConstantReadNode
+          expression.name.to_s
+        when Prism::ConstantPathNode
+          render_constant_path(expression)
+        end
       end
 
       # The qualified name of the immediately-enclosing class (joining

data/lib/rigor/inference/synthetic_method_scanner.rb

@@ -53,24 +53,36 @@ module Rigor
       #   inheritance resolution against RBS-known classes
       #   (ActiveRecord::Base, Dry::Struct, etc.) that aren't
       #   declared in project source.
+      # @param fact_store      [Rigor::Plugin::FactStore, nil]
+      #   the per-run cross-plugin fact store. ADR-18 lookups
+      #   (`Plugin::Macro::HeredocTemplate::Emit#returns_from_arg`)
+      #   consult this at scan time to resolve per-call-site
+      #   return types from published facts; without it, those
+      #   emit rows fall back to their static `returns:` (or
+      #   `"untyped"` → `Dynamic[Top]`).
+      # @param buffer          [Rigor::Analysis::BufferBinding, nil]
+      #   editor-mode buffer binding. When set, reads for the
+      #   logical path resolve to the buffer's physical path so
+      #   the pre-pass sees the in-flight bytes instead of the
+      #   on-disk copy.
       # @return [Rigor::Inference::SyntheticMethodIndex]
-      def scan(plugin_registry:, paths:, environment: nil)
+      def scan(plugin_registry:, paths:, environment: nil, fact_store: nil, buffer: nil)
         templates = collect_templates(plugin_registry)
         registries = collect_trait_registries(plugin_registry)
         return SyntheticMethodIndex::EMPTY if templates.empty? && registries.empty?
 
-        asts = parse_paths(paths)
+        asts = parse_paths(paths, buffer: buffer)
         hierarchy = build_hierarchy(asts)
         concern_index = build_concern_index(asts)
 
         entries = []
         asts.each do |path, ast|
           walk_class_bodies(ast) do |class_name, call_node|
-            collect_entries(entries, templates, class_name, call_node, hierarchy, environment, path)
+            collect_entries(entries, templates, class_name, call_node, hierarchy, environment, path, fact_store)
             collect_trait_entries(entries, registries, class_name, call_node, hierarchy, environment, path)
             collect_concern_re_targeted_entries(
               entries, call_node, class_name, concern_index,
-              templates, registries, hierarchy, environment, path
+              templates, registries, hierarchy, environment, path, fact_store
             )
           end
         end
@@ -107,10 +119,11 @@ module Rigor
         end
       end
 
-      def parse_paths(paths)
+      def parse_paths(paths, buffer: nil)
         paths.to_h do |path|
-          source = File.read(path)
-          [path, Prism.parse(source).value]
+          physical = buffer ? buffer.resolve(path) : path
+          source = File.read(physical)
+          [path, Prism.parse(source, filepath: path).value]
         rescue StandardError
           [path, nil]
         end
@@ -209,7 +222,7 @@ module Rigor
       # `collect_trait_entries` fire just as if the calls had been
       # written directly in X's body.
       def collect_concern_re_targeted_entries(entries, call_node, class_name, concern_index, # rubocop:disable Metrics/ParameterLists
-                                              templates, registries, hierarchy, environment, path)
+                                              templates, registries, hierarchy, environment, path, fact_store = nil)
         return unless call_node.name == :include && call_node.receiver.nil?
         return if concern_index.empty?
 
@@ -220,7 +233,7 @@ module Rigor
           next unless deferred
 
           deferred.each do |inner_call|
-            collect_entries(entries, templates, class_name, inner_call, hierarchy, environment, path)
+            collect_entries(entries, templates, class_name, inner_call, hierarchy, environment, path, fact_store)
             collect_trait_entries(entries, registries, class_name, inner_call, hierarchy, environment, path)
           end
         end
@@ -318,7 +331,7 @@ module Rigor
         parent_str ? "#{parent_str}::#{name}" : name
       end
 
-      def collect_entries(entries, templates, class_name, call_node, hierarchy, environment, path)
+      def collect_entries(entries, templates, class_name, call_node, hierarchy, environment, path, fact_store = nil) # rubocop:disable Metrics/ParameterLists
         templates.each do |(plugin_id, template)|
           next unless call_node.name == template.method_name
           next unless class_inherits_from?(class_name, template.receiver_constraint, hierarchy, environment)
@@ -326,7 +339,7 @@ module Rigor
           symbol_arg = literal_symbol_arg(call_node, template.symbol_arg_position)
           next if symbol_arg.nil?
 
-          emit_entries_for(entries, class_name, symbol_arg, template, plugin_id, path, call_node)
+          emit_entries_for(entries, class_name, symbol_arg, template, plugin_id, path, call_node, fact_store)
         end
       end
 
@@ -439,28 +452,31 @@ module Rigor
         )
       end
 
-      def emit_entries_for(entries, class_name, symbol_arg, template, plugin_id, path, call_node)
+      def emit_entries_for(entries, class_name, symbol_arg, template, plugin_id, path, call_node, fact_store = nil) # rubocop:disable Metrics/ParameterLists
         template.emit.each do |row|
           entries << build_synthetic_method(
             class_name: class_name, name_arg: symbol_arg, row: row,
             template: template, plugin_id: plugin_id, path: path, call_node: call_node,
-            kind: SyntheticMethod::INSTANCE
+            kind: SyntheticMethod::INSTANCE, fact_store: fact_store
           )
         end
         template.class_level_emit.each do |row|
           entries << build_synthetic_method(
             class_name: class_name, name_arg: symbol_arg, row: row,
             template: template, plugin_id: plugin_id, path: path, call_node: call_node,
-            kind: SyntheticMethod::SINGLETON
+            kind: SyntheticMethod::SINGLETON, fact_store: fact_store
           )
         end
       end
 
-      def build_synthetic_method(class_name:, name_arg:, row:, template:, plugin_id:, path:, call_node:, kind:) # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Metrics/ParameterLists
+      def build_synthetic_method(class_name:, name_arg:, row:, template:, plugin_id:, path:, call_node:, kind:,
+                                 fact_store: nil)
+        # rubocop:enable Metrics/ParameterLists
         SyntheticMethod.new(
           class_name: class_name,
           method_name: interpolate(row.name, name_arg).to_sym,
-          return_type: row.returns,
+          return_type: resolve_emit_return_type(row, call_node, fact_store),
           kind: kind,
           provenance: {
             plugin_id: plugin_id,
@@ -472,6 +488,68 @@ module Rigor
         )
       end
 
+      # ADR-18 three-tier fallback for the synthetic method's
+      # `return_type` string:
+      #
+      # 1. When `row.returns_from_arg` is present AND the
+      #    call-site argument at the declared position is a
+      #    resolvable constant reference AND the fact_store
+      #    has a matching value, use that as the return type.
+      # 2. Else if `row.returns` is a non-empty String, use it
+      #    (the slice-6b static path).
+      # 3. Else use `"untyped"` so the dispatcher's
+      #    `promote_via_return_type` sentinel chain yields
+      #    `Dynamic[Top]`.
+      def resolve_emit_return_type(row, call_node, fact_store)
+        resolved = resolve_returns_from_arg(row.returns_from_arg, call_node, fact_store)
+        return resolved if resolved
+        return row.returns if row.returns
+
+        "untyped"
+      end
+
+      def resolve_returns_from_arg(returns_from_arg, call_node, fact_store)
+        return nil if returns_from_arg.nil?
+
+        source_rep = argument_source_representation(call_node, returns_from_arg.position)
+        return nil if source_rep.nil?
+        return nil if fact_store.nil?
+
+        fact = fact_store.read(plugin_id: returns_from_arg.plugin_id, name: returns_from_arg.fact)
+        return nil unless fact.is_a?(Hash)
+
+        fact[source_rep]
+      end
+
+      # Extracts the source-text qualified-constant representation
+      # of the call's positional argument (e.g.,
+      # `"Types::String"`). Returns nil for non-constant shapes
+      # (literals, method chains, blocks, …). The floor
+      # intentionally accepts only ConstantReadNode /
+      # ConstantPathNode per ADR-18; chained-call argument
+      # resolution stays deferred.
+      def argument_source_representation(call_node, position)
+        args = call_node.arguments&.arguments
+        return nil if args.nil? || position >= args.size
+
+        node = args[position]
+        case node
+        when Prism::ConstantReadNode then node.name.to_s
+        when Prism::ConstantPathNode then qualified_constant_name(node)
+        end
+      end
+
+      def qualified_constant_name(node)
+        case node
+        when Prism::ConstantReadNode then node.name.to_s
+        when Prism::ConstantPathNode
+          parent_name = node.parent.nil? ? nil : qualified_constant_name(node.parent)
+          return nil if !node.parent.nil? && parent_name.nil?
+
+          parent_name.nil? ? node.name.to_s : "#{parent_name}::#{node.name}"
+        end
+      end
+
       def interpolate(template_name, name_arg)
         template_name.gsub(Rigor::Plugin::Macro::HeredocTemplate::NAME_PLACEHOLDER, name_arg.to_s)
       end

data/lib/rigor/language_server/buffer_table.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+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).
+    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.
+      # @!attribute version  [Integer] the monotonically increasing LSP version number.
+      Entry = Data.define(:uri, :bytes, :version)
+
+      def initialize
+        @entries = {}
+      end
+
+      # Records a `textDocument/didOpen` event. Replaces any
+      # existing entry (LSP clients may re-open a previously closed
+      # URI; the new version is authoritative).
+      def open(uri:, bytes:, version:)
+        @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 created — defensive.
+      def change(uri:, bytes:, version:)
+        @entries[uri] = Entry.new(uri: uri, bytes: bytes, version: version)
+      end
+
+      # Records a `textDocument/didClose` event. The entry is
+      # removed. Subsequent reads via `#[]` return nil.
+      def close(uri:)
+        @entries.delete(uri)
+      end
+
+      def [](uri)
+        @entries[uri]
+      end
+
+      def open?(uri)
+        @entries.key?(uri)
+      end
+
+      def size
+        @entries.size
+      end
+
+      def uris
+        @entries.keys
+      end
+    end
+  end
+end