rigortype 0.1.8 → 0.1.10

data/lib/rigor/mcp/loop.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  module MCP
+    # Reads newline-delimited JSON-RPC 2.0 messages from `input`,
+    # dispatches each to `server`, and writes responses to `output`.
+    # Runs until input reaches EOF (the client closes the connection).
+    class Loop
+      def initialize(input:, output:, server:)
+        @input = input
+        @output = output
+        @server = server
+      end
+
+      def run
+        @input.each_line do |raw|
+          line = raw.chomp
+          next if line.empty?
+
+          begin
+            request = JSON.parse(line)
+          rescue JSON::ParserError => e
+            write_response({ "jsonrpc" => "2.0", "id" => nil,
+                             "error" => { "code" => -32_700, "message" => "Parse error: #{e.message}" } })
+            next
+          end
+
+          response = @server.handle(request)
+          write_response(response) if response
+        end
+      end
+
+      private
+
+      def write_response(response)
+        @output.puts(JSON.generate(response))
+        @output.flush
+      end
+    end
+  end
+end

data/lib/rigor/mcp/server.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "json"
+require "stringio"
+
+module Rigor
+  module MCP
+    # JSON-RPC 2.0 dispatcher for the MCP server.
+    #
+    # Each public `handle` call takes a parsed request hash and returns
+    # a response hash (or nil for notifications that require no reply).
+    # Tool implementations delegate to `CLI.new(argv, out:, err:).run`
+    # with StringIO capture — every tool stays in sync with its CLI
+    # counterpart automatically (ADR-33 WD4).
+    class Server # rubocop:disable Metrics/ClassLength
+      PROTOCOL_VERSION = "2024-11-05"
+
+      TOOLS = [
+        {
+          name: "rigor_check",
+          description: "Analyze Ruby files for type errors, undefined methods, arity mismatches, " \
+                       "and nil-receiver risks. Returns a JSON diagnostic report.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              paths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Files or directories to analyze (required)"
+              },
+              config: { type: "string", description: "Path to .rigor.yml (optional)" }
+            },
+            required: ["paths"]
+          }
+        },
+        {
+          name: "rigor_type_of",
+          description: "Get the inferred type of the expression at a specific location in a Ruby file.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              file: { type: "string",  description: "Path to the Ruby file" },
+              line: { type: "integer", description: "1-based line number" },
+              col: { type: "integer", description: "1-based column number" },
+              config: { type: "string", description: "Path to .rigor.yml (optional)" }
+            },
+            required: %w[file line col]
+          }
+        },
+        {
+          name: "rigor_triage",
+          description: "Summarize a project's diagnostics: rule distribution, per-file hotspots, " \
+                       "and heuristic hints for the most common error clusters. Returns JSON. " \
+                       "Useful for understanding the shape of a diagnostic set before deciding what to fix.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              paths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Files or directories to analyze (defaults to configured paths)"
+              },
+              top: { type: "integer", description: "Number of hotspot files to include (default: 10)" },
+              config: { type: "string", description: "Path to .rigor.yml (optional)" }
+            }
+          }
+        },
+        {
+          name: "rigor_annotate",
+          description: "Return the given Ruby source file with each line's last-expression type " \
+                       "appended as a comment. Useful for understanding how Rigor infers types " \
+                       "through a file.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              file: { type: "string", description: "Path to the Ruby file to annotate" },
+              config: { type: "string", description: "Path to .rigor.yml (optional)" }
+            },
+            required: ["file"]
+          }
+        },
+        {
+          name: "rigor_sig_gen",
+          description: "Generate RBS skeleton signatures inferred from Ruby source files. " \
+                       "Returns a JSON report of candidates with their classifications " \
+                       "(new-file, new-method, tighter-return, equivalent, skipped).",
+          inputSchema: {
+            type: "object",
+            properties: {
+              paths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Files or directories to generate signatures for (defaults to configured paths)"
+              },
+              params: {
+                type: "string",
+                enum: %w[untyped observed],
+                description: "Parameter policy: untyped (default) or observed " \
+                             "(harvests call-site argument types from spec/)"
+              },
+              config: { type: "string", description: "Path to .rigor.yml (optional)" }
+            }
+          }
+        },
+        {
+          name: "rigor_explain",
+          description: "Look up the description of one or all Rigor diagnostic rules. " \
+                       "Returns JSON. Without a rule argument, returns the full catalog.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              rule: {
+                type: "string",
+                description: "Rule ID, legacy alias, or family prefix (call, flow, assert, dump, def). " \
+                             "Omit to list every rule."
+              }
+            }
+          }
+        },
+        {
+          name: "rigor_coverage",
+          description: "Report type-precision coverage: the ratio of expressions Rigor types as " \
+                       "Constant / Nominal / shaped / refined (precise) vs Dynamic or top (opaque). " \
+                       "Returns JSON. Useful for measuring the impact of adding new fold rules.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              paths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Files or directories to scan (required)"
+              },
+              config: { type: "string", description: "Path to .rigor.yml (optional)" }
+            },
+            required: ["paths"]
+          }
+        }
+      ].freeze
+
+      def initialize(config_path: nil, err: $stderr)
+        @config_path = config_path
+        @err = err
+      end
+
+      # Dispatches a parsed JSON-RPC request hash.
+      # Returns nil for notifications (requests without an `id`).
+      def handle(request)
+        id = request["id"]
+        method_name = request["method"]
+
+        # Notifications carry no `id` and require no response.
+        return nil if id.nil?
+
+        case method_name
+        when "initialize"  then handle_initialize(id)
+        when "ping"        then success(id, {})
+        when "tools/list"  then success(id, { tools: TOOLS })
+        when "tools/call"
+          call_tool(id,
+                    request.dig("params", "name"),
+                    request.dig("params", "arguments") || {})
+        else
+          error(id, -32_601, "Method not found: #{method_name.inspect}")
+        end
+      end
+
+      private
+
+      def handle_initialize(id)
+        require_relative "../version"
+        success(id, {
+                  protocolVersion: PROTOCOL_VERSION,
+                  capabilities: { tools: { listChanged: false } },
+                  serverInfo: { name: "rigor", version: Rigor::VERSION }
+                })
+      end
+
+      def call_tool(id, name, args)
+        argv = build_argv(name, args)
+        return error(id, -32_602, "Unknown tool: #{name.inspect}") unless argv
+
+        out_io = StringIO.new
+        err_io = StringIO.new
+        require_relative "../cli"
+        exit_code = CLI.new(argv, out: out_io, err: err_io).run
+
+        is_error = exit_code == CLI::EXIT_USAGE
+        text = out_io.string
+        text = err_io.string if text.empty? && is_error
+
+        success(id, { content: [{ type: "text", text: text }], isError: is_error })
+      rescue StandardError => e
+        @err.puts("rigor mcp: #{e.class}: #{e.message}")
+        @err.puts(e.backtrace.first(5).join("\n")) if e.backtrace
+        success(id, {
+                  content: [{ type: "text", text: "Internal error: #{e.message}" }],
+                  isError: true
+                })
+      end
+
+      def build_argv(name, args) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/PerceivedComplexity
+        effective_config = args["config"] || @config_path
+
+        case name
+        when "rigor_check"
+          argv = ["check", "--format=json", "--no-stats"]
+          argv << "--config=#{effective_config}" if effective_config
+          argv += Array(args["paths"])
+          argv
+
+        when "rigor_type_of"
+          return nil unless args["file"] && args["line"] && args["col"]
+
+          argv = ["type-of", "--format=json"]
+          argv << "--config=#{effective_config}" if effective_config
+          argv << "#{args['file']}:#{args['line']}:#{args['col']}"
+          argv
+
+        when "rigor_triage"
+          argv = ["triage", "--format=json"]
+          argv << "--config=#{effective_config}" if effective_config
+          argv << "--top=#{args['top']}" if args["top"]
+          argv += Array(args["paths"])
+          argv
+
+        when "rigor_annotate"
+          return nil unless args["file"]
+
+          argv = ["annotate", "--no-color"]
+          argv << "--config=#{effective_config}" if effective_config
+          argv << args["file"]
+          argv
+
+        when "rigor_sig_gen"
+          argv = ["sig-gen", "--print", "--format=json"]
+          argv << "--config=#{effective_config}" if effective_config
+          argv << "--params=#{args['params']}" if args["params"]
+          argv += Array(args["paths"])
+          argv
+
+        when "rigor_explain"
+          argv = ["explain", "--format=json"]
+          argv << args["rule"] if args["rule"]
+          argv
+
+        when "rigor_coverage"
+          argv = ["coverage", "--format=json"]
+          argv << "--config=#{effective_config}" if effective_config
+          argv += Array(args["paths"])
+          argv
+        end
+      end
+
+      def success(id, result)
+        { "jsonrpc" => "2.0", "id" => id, "result" => result }
+      end
+
+      def error(id, code, message)
+        { "jsonrpc" => "2.0", "id" => id, "error" => { "code" => code, "message" => message } }
+      end
+    end
+  end
+end

data/lib/rigor/mcp.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Rigor
+  # The MCP (Model Context Protocol) server subsystem.
+  # See `docs/adr/33-mcp-server.md` for the design.
+  #
+  # Entry point: `rigor mcp --transport stdio`.
+  # The server exposes Rigor's analysis tools (check, type-of, triage,
+  # annotate, sig-gen, explain, coverage) as MCP tool calls over a
+  # newline-delimited JSON-RPC 2.0 stdio stream.
+  module MCP
+  end
+end
+
+require_relative "mcp/server"
+require_relative "mcp/loop"

data/lib/rigor/plugin/base.rb

@@ -183,6 +183,45 @@ module Rigor
         self.class.manifest
       end
 
+      # ADR-25 — absolute RBS signature directories this plugin
+      # contributes. Resolves each `manifest.signature_paths` entry
+      # (declared relative to the plugin gem root) against that
+      # root. The gem root is the directory above `lib/` in the
+      # file that defined the plugin class (falling back to that
+      # file's directory for a non-conventional layout). Returns
+      # `[]` when the manifest declares no `signature_paths:` or
+      # the class is anonymous (an anonymous class cannot ship a
+      # gem). `Plugin::Loader` validates the resolved dirs exist at
+      # load time; `Environment.for_project` merges them into the
+      # signature-path set fed to `RbsLoader`.
+      def signature_paths
+        relative = manifest.signature_paths
+        return [] if relative.empty?
+
+        class_name = self.class.name
+        return [] if class_name.nil?
+
+        file, = Object.const_source_location(class_name)
+        return [] if file.nil?
+
+        before, separator, = file.rpartition("/lib/")
+        root = separator.empty? ? File.dirname(file) : before
+        relative.map { |rel| File.expand_path(rel, root) }
+      end
+
+      # ADR-28 — the path-scoped method-protocol contracts this
+      # plugin contributes. Defaults to the manifest-declared
+      # `protocol_contracts:`; the same indirection
+      # `#signature_paths` uses, so a plugin MAY override this to
+      # fold per-project config into the contract set (e.g.
+      # substituting the convention `path_glob` with a user-supplied
+      # one) without the manifest having to be config-aware.
+      # `Plugin::Registry#protocol_contracts` aggregates the result
+      # across loaded plugins.
+      def protocol_contracts
+        manifest.protocol_contracts
+      end
+
       # ADR-7 § "Slice 6-A/6-B" — per-plugin {IoBoundary}.
       # Memoised so the boundary's accumulated `FileEntry`
       # rows persist across producer invocations within the
@@ -312,11 +351,6 @@ module Rigor
       # descriptor from (1) the plugin's PluginEntry template
       # and (2) the IoBoundary's accumulated FileEntry rows.
       def build_plugin_cache_descriptor
-        plugin_entry = Cache::Descriptor::PluginEntry.new(
-          id: manifest.id,
-          version: manifest.version,
-          config_hash: digest_config(config)
-        )
         boundary_descriptor = io_boundary.cache_descriptor
         Cache::Descriptor.new(
           plugins: [plugin_entry],
@@ -324,6 +358,34 @@ module Rigor
         )
       end
 
+      public
+
+      # ADR-32 WD5 — the `Cache::Descriptor::PluginEntry`
+      # template carrying this plugin's id, version, and a
+      # SHA-256 digest of its (canonicalised) config hash.
+      # Callers outside the plugin (e.g. `Environment.for_project`
+      # caching per-file synthesizer output) compose this entry
+      # into their own cache descriptor so a config change to
+      # the plugin (e.g. flipping `require_magic_comment:`)
+      # invalidates the dependent cache.
+      def plugin_entry
+        # Built fresh on each call rather than memoised so a
+        # plugin subclass that freezes itself in `initialize`
+        # (e.g. `Rigor::Plugin::RbsInline` per ADR-32) doesn't
+        # trip a FrozenError on first read. The construction
+        # cost is a single `Data.define`-backed value-object
+        # build; the cache key derivation downstream is the
+        # expensive step, and it's already memoised inside
+        # `Cache::Store`.
+        Cache::Descriptor::PluginEntry.new(
+          id: manifest.id,
+          version: manifest.version,
+          config_hash: digest_config(config)
+        )
+      end
+
+      private
+
       # ADR-7 § "Slice 6" follow-up — composes the auto-built
       # cache descriptor with an optional plugin-author-supplied
       # extension. Extra `GemEntry` / `FileEntry` / `ConfigEntry`

data/lib/rigor/plugin/loader.rb

@@ -125,7 +125,28 @@ module Rigor
         seen_ids[manifest.id] = entry[:gem]
 
         validate_config!(manifest, entry[:config])
-        instantiate(plugin_class, entry[:config])
+        plugin = instantiate(plugin_class, entry[:config])
+        validate_signature_paths!(plugin)
+        plugin
+      end
+
+      # ADR-25 — a plugin's manifest-declared `signature_paths:`
+      # are resolved (by `Plugin::Base#signature_paths`) against
+      # the plugin gem root. A declared directory that does not
+      # exist is a load-time failure for that plugin — loud, not
+      # silent, because a missing `sig/` means the bundle gem is
+      # broken. The raised LoadError is collected like any other
+      # load failure and the plugin drops from the registry.
+      def validate_signature_paths!(plugin)
+        plugin.signature_paths.each do |dir|
+          next if File.directory?(dir)
+
+          raise LoadError.new(
+            "plugin #{plugin.manifest.id.inspect} declares signature path #{dir.inspect} " \
+            "which is not a directory",
+            plugin_ref: plugin.manifest.id
+          )
+        end
       end
 
       def require_gem!(entry)

data/lib/rigor/plugin/manifest.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../inference/hkt_registry"
+require_relative "protocol_contract"
 
 module Rigor
   module Plugin
@@ -40,15 +41,17 @@ module Rigor
       end
 
       attr_reader :id, :version, :description, :protocols, :config_schema, :produces, :consumes,
-                  :owns_receivers, :type_node_resolvers, :block_as_methods, :heredoc_templates,
-                  :trait_registries, :external_files, :hkt_registrations, :hkt_definitions
+                  :owns_receivers, :open_receivers, :type_node_resolvers, :block_as_methods,
+                  :heredoc_templates, :trait_registries, :external_files, :hkt_registrations,
+                  :hkt_definitions, :signature_paths, :protocol_contracts, :source_rbs_synthesizer
 
       def initialize( # rubocop:disable Metrics/ParameterLists
         id:, version:,
         description: nil, protocols: [], config_schema: {},
-        produces: [], consumes: [], owns_receivers: [], type_node_resolvers: [],
+        produces: [], consumes: [], owns_receivers: [], open_receivers: [], type_node_resolvers: [],
         block_as_methods: [], heredoc_templates: [], trait_registries: [], external_files: [],
-        hkt_registrations: [], hkt_definitions: []
+        hkt_registrations: [], hkt_definitions: [], signature_paths: [], protocol_contracts: [],
+        source_rbs_synthesizer: nil
       )
         validate_id!(id)
         validate_version!(version)
@@ -56,6 +59,7 @@ module Rigor
         validate_config_schema!(config_schema)
         validate_produces!(produces)
         validate_owns_receivers!(owns_receivers)
+        validate_open_receivers!(open_receivers)
         validate_type_node_resolvers!(type_node_resolvers)
         validate_block_as_methods!(block_as_methods)
         validate_heredoc_templates!(heredoc_templates)
@@ -63,10 +67,14 @@ module Rigor
         validate_external_files!(external_files)
         validate_hkt_registrations!(hkt_registrations)
         validate_hkt_definitions!(hkt_definitions)
+        validate_signature_paths!(signature_paths)
+        validate_protocol_contracts!(protocol_contracts)
+        validate_source_rbs_synthesizer!(source_rbs_synthesizer)
 
         assign_fields(id, version, description, protocols, config_schema, produces, consumes, owns_receivers,
-                      type_node_resolvers, block_as_methods, heredoc_templates, trait_registries, external_files,
-                      hkt_registrations, hkt_definitions)
+                      open_receivers, type_node_resolvers, block_as_methods, heredoc_templates, trait_registries,
+                      external_files, hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
+                      source_rbs_synthesizer)
         freeze
       end
 
@@ -74,8 +82,9 @@ module Rigor
 
       # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize
       def assign_fields(id, version, description, protocols, config_schema, produces, consumes, owns_receivers,
-                        type_node_resolvers, block_as_methods, heredoc_templates, trait_registries, external_files,
-                        hkt_registrations, hkt_definitions)
+                        open_receivers, type_node_resolvers, block_as_methods, heredoc_templates, trait_registries,
+                        external_files, hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
+                        source_rbs_synthesizer)
         @id = id.dup.freeze
         @version = version.dup.freeze
         @description = description.nil? ? nil : description.to_s.dup.freeze
@@ -84,6 +93,7 @@ module Rigor
         @produces = produces.map(&:to_sym).freeze
         @consumes = coerce_consumes(consumes)
         @owns_receivers = owns_receivers.map { |c| c.to_s.dup.freeze }.freeze
+        @open_receivers = open_receivers.map { |c| c.to_s.dup.freeze }.freeze
         @type_node_resolvers = type_node_resolvers.dup.freeze
         @block_as_methods = block_as_methods.dup.freeze
         @heredoc_templates = heredoc_templates.dup.freeze
@@ -91,6 +101,9 @@ module Rigor
         @external_files = external_files.dup.freeze
         @hkt_registrations = hkt_registrations.dup.freeze
         @hkt_definitions = hkt_definitions.dup.freeze
+        @signature_paths = signature_paths.map { |p| p.to_s.dup.freeze }.freeze
+        @protocol_contracts = protocol_contracts.dup.freeze
+        @source_rbs_synthesizer = source_rbs_synthesizer
       end
       # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
 
@@ -119,7 +132,7 @@ module Rigor
         errors
       end
 
-      def to_h # rubocop:disable Metrics/AbcSize
+      def to_h # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         {
           "id" => id,
           "version" => version,
@@ -129,13 +142,17 @@ module Rigor
           "produces" => produces.map(&:to_s),
           "consumes" => consumes.map { |c| consumption_hash(c) },
           "owns_receivers" => owns_receivers,
+          "open_receivers" => open_receivers,
           "type_node_resolvers" => type_node_resolvers.map { |r| r.class.name },
           "block_as_methods" => block_as_methods.map(&:to_h),
           "heredoc_templates" => heredoc_templates.map(&:to_h),
           "trait_registries" => trait_registries.map(&:to_h),
           "external_files" => external_files.map(&:to_h),
           "hkt_registrations" => hkt_registrations.map(&:to_h),
-          "hkt_definitions" => hkt_definitions.map { |d| { "uri" => d.uri, "params" => d.params } }
+          "hkt_definitions" => hkt_definitions.map { |d| { "uri" => d.uri, "params" => d.params } },
+          "signature_paths" => signature_paths,
+          "protocol_contracts" => protocol_contracts.map(&:to_h),
+          "source_rbs_synthesizer" => source_rbs_synthesizer&.class&.name
         }
       end
 
@@ -217,6 +234,24 @@ module Rigor
               "got #{owns_receivers.inspect}"
       end
 
+      # ADR-26 — `open_receivers:` declares the class names this
+      # plugin marks as "open": statically known to respond beyond
+      # their RBS-declared method surface (e.g. `ActiveRecord::Relation`,
+      # which delegates an unbounded set of user-defined scopes to
+      # its model). `Analysis::CheckRules` skips the
+      # `call.undefined-method` rule for a receiver whose class any
+      # loaded plugin lists here — flagging a method on a class
+      # with an open dynamic surface is unsound. Distinct from
+      # `owns_receivers:` (which routes dispatch); this one only
+      # suppresses the diagnostic.
+      def validate_open_receivers!(open_receivers)
+        return if open_receivers.is_a?(Array) && open_receivers.all? { |c| c.is_a?(String) && !c.empty? }
+
+        raise ArgumentError,
+              "plugin manifest open_receivers must be an Array of non-empty String, " \
+              "got #{open_receivers.inspect}"
+      end
+
       # ADR-13 slice 2 — `type_node_resolvers:` declares the
       # plugin-supplied `TypeNodeResolver` instances the parser
       # consults (in slice 3) when an RBS::Extended payload's
@@ -326,6 +361,62 @@ module Rigor
               "Rigor::Inference::HktRegistry::Definition instances, got #{entries.inspect}"
       end
 
+      # ADR-25 — `signature_paths:` declares the RBS signature
+      # directories this plugin gem ships, as paths relative to the
+      # plugin's own gem root (e.g. `["sig"]`). `Plugin::Base#signature_paths`
+      # resolves them to absolute dirs against the gem root; the
+      # loader validates each exists and `Environment.for_project`
+      # merges the resolved set into the RBS environment.
+      def validate_signature_paths!(paths)
+        return if paths.is_a?(Array) && paths.all? { |p| p.is_a?(String) && !p.empty? }
+
+        raise ArgumentError,
+              "plugin manifest signature_paths must be an Array of non-empty String, " \
+              "got #{paths.inspect}"
+      end
+
+      # ADR-28 — `protocol_contracts:` declares the path-scoped
+      # method-protocol contracts the plugin contributes. Each
+      # entry MUST be a `Rigor::Plugin::ProtocolContract`. The
+      # registry aggregator on `Plugin::Registry` flattens
+      # contracts across loaded plugins; the engine consults them
+      # in two places — `MethodParameterBinder` provides the
+      # declared parameter types into matching method bodies, and
+      # the contributing plugin's `#diagnostics_for_file` checks
+      # method presence + return-type conformance. The manifest
+      # field carries the plugin's *default* contracts; a plugin
+      # MAY override `Plugin::Base#protocol_contracts` to fold in
+      # per-project config (e.g. a custom convention path).
+      def validate_protocol_contracts!(entries)
+        return if entries.is_a?(Array) && entries.all?(ProtocolContract)
+
+        raise ArgumentError,
+              "plugin manifest protocol_contracts must be an Array of " \
+              "Rigor::Plugin::ProtocolContract instances, got #{entries.inspect}"
+      end
+
+      # ADR-32 WD4 — `source_rbs_synthesizer:` declares a callable
+      # the engine invokes once per analysed Ruby source file at
+      # env-build time. The callable receives a source file path
+      # (String) and returns either an RBS source String to merge
+      # into the analysis environment or `nil` (no contribution
+      # for this file). Distinct from `signature_paths:` (static,
+      # bundled RBS): the synthesizer derives RBS from project
+      # source on each run.
+      #
+      # The value is held as-given (no dup / freeze) because a
+      # callable instance is opaque to the manifest; the plugin
+      # author is responsible for thread-/Ractor-safety of any
+      # captured state (per ADR-15).
+      def validate_source_rbs_synthesizer!(synthesizer)
+        return if synthesizer.nil?
+        return if synthesizer.respond_to?(:call)
+
+        raise ArgumentError,
+              "plugin manifest source_rbs_synthesizer must respond to :call, " \
+              "got #{synthesizer.inspect}"
+      end
+
       def coerce_consumes(consumes)
         unless consumes.is_a?(Array)
           raise ArgumentError, "plugin manifest consumes must be an Array, got #{consumes.inspect}"