rigortype 0.1.7 → 0.1.9

data/lib/rigor/inference/scope_indexer.rb

@@ -109,12 +109,11 @@ module Rigor
         discovered_methods = build_discovered_methods(root)
         seeded_scope = seeded_scope.with_discovered_methods(discovered_methods)
 
-        # v0.0.2 #5 — also record the def node itself for
-        # instance methods so the engine can re-type the body
-        # when a call site dispatches against a user-defined
-        # method without an RBS sig.
-        discovered_def_nodes = build_discovered_def_nodes(root)
-        seeded_scope = seeded_scope.with_discovered_def_nodes(discovered_def_nodes)
+        # v0.0.2 #5 + ADR-24 slice 2 — record per-instance-method
+        # def nodes, the class -> superclass map, and the
+        # class/module -> included-modules map, each merged under
+        # the cross-file pre-pass seed (see below).
+        seeded_scope = merge_project_method_indexes(seeded_scope, default_scope, root)
 
         # v0.1.2 — per-class table of method visibilities
         # (`:public` / `:private` / `:protected`). The
@@ -134,6 +133,31 @@ module Rigor
         table
       end
 
+      # v0.0.2 #5 + ADR-24 slice 2 — seeds the three
+      # project-method indexes onto `seeded_scope`: the
+      # per-instance-method def-node table, the class ->
+      # superclass map, and the class/module -> included-modules
+      # map. Each per-file table is merged UNDER the cross-file
+      # `discovered_def_index_for_paths` seed carried on
+      # `default_scope` — same-file declarations win per entry,
+      # the cross-file seed supplies sibling-file ancestors.
+      def merge_project_method_indexes(seeded_scope, default_scope, root)
+        def_nodes = default_scope.discovered_def_nodes.merge(
+          build_discovered_def_nodes(root)
+        ) { |_class, cross_file, per_file| cross_file.merge(per_file) }
+        superclasses = default_scope.discovered_superclasses.merge(
+          build_discovered_superclasses(root)
+        )
+        includes = default_scope.discovered_includes.merge(
+          build_discovered_includes(root)
+        ) { |_class, cross_file, per_file| (cross_file + per_file).uniq }
+
+        seeded_scope
+          .with_discovered_def_nodes(def_nodes)
+          .with_discovered_superclasses(superclasses)
+          .with_discovered_includes(includes)
+      end
+
       # Slice 7 phase 2. Builds the class-level ivar accumulator
       # by walking every `Prism::ClassNode` / `Prism::ModuleNode`
       # body, descending into each nested `Prism::DefNode`, and
@@ -580,6 +604,94 @@ module Rigor
         accumulator[class_name][def_node.name] = def_node
       end
 
+      # ADR-24 slice 2 — per-class table mapping a fully
+      # qualified user class to its superclass name AS WRITTEN
+      # at the `class Foo < Bar` declaration. Only constant
+      # superclasses are recorded (`class Foo < Struct.new(...)`
+      # and other non-constant superclasses produce no entry).
+      # The as-written name is resolved to a qualified class at
+      # the call site against the subclass's lexical nesting —
+      # see `ExpressionTyper#resolve_ancestor_class_name`.
+      def build_discovered_superclasses(root)
+        accumulator = {}
+        walk_class_superclasses(root, [], accumulator)
+        accumulator.freeze
+      end
+
+      def walk_class_superclasses(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("::")
+            superclass = node.superclass && qualified_name_for(node.superclass)
+            accumulator[full] = superclass if superclass
+            walk_class_superclasses(node.body, qualified_prefix + [name], accumulator) if node.body
+            return
+          end
+        when Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            walk_class_superclasses(node.body, qualified_prefix + [name], accumulator) if node.body
+            return
+          end
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_class_superclasses(child, qualified_prefix, accumulator)
+        end
+      end
+
+      MIXIN_CALL_NAMES = %i[include prepend].freeze
+
+      # ADR-24 slice 2 — per-class/module table mapping a fully
+      # qualified user class or module to the list of module
+      # names it `include`s / `prepend`s, AS WRITTEN at the
+      # mixin call (`include Foo` / `include Foo::Bar`). Only
+      # constant arguments are recorded; dynamic mixins
+      # (`include some_method`) produce no entry. `prepend` is
+      # bucketed with `include` — both contribute instance
+      # methods to the ancestor chain. `extend` is NOT tracked
+      # (it adds singleton methods; ADR-24 slice 2 resolves the
+      # instance-side chain).
+      def build_discovered_includes(root)
+        accumulator = {}
+        walk_class_includes(root, [], nil, accumulator)
+        accumulator.transform_values { |mods| mods.uniq.freeze }.freeze
+      end
+
+      def walk_class_includes(node, qualified_prefix, current_class, accumulator)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            full = (qualified_prefix + [name]).join("::")
+            walk_class_includes(node.body, qualified_prefix + [name], full, accumulator) if node.body
+            return
+          end
+        when Prism::CallNode
+          record_mixin_call(node, current_class, accumulator)
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_class_includes(child, qualified_prefix, current_class, accumulator)
+        end
+      end
+
+      def record_mixin_call(node, current_class, accumulator)
+        return unless current_class && node.receiver.nil?
+        return unless MIXIN_CALL_NAMES.include?(node.name)
+
+        node.arguments&.arguments&.each do |arg|
+          mod = qualified_name_for(arg)
+          (accumulator[current_class] ||= []) << mod if mod
+        end
+      end
+
       VISIBILITY_MODIFIERS = %i[public private protected].freeze
 
       # v0.1.2 — per-class method-visibility table for the
@@ -845,6 +957,44 @@ module Rigor
         accumulator.freeze
       end
 
+      # ADR-24 slice 2 — cross-file companion to
+      # `discovered_classes_for_paths`. Walks every project
+      # file once and returns both the merged
+      # `discovered_def_nodes` table (a class reopened across
+      # files has its method tables merged) and the merged
+      # class -> superclass-name map. The engine consults these
+      # so an implicit-self call inside a subclass resolves
+      # against a superclass `def` declared in a sibling file
+      # (`Mastodon::CLI::Accounts` calling a helper defined in
+      # `Mastodon::CLI::Base`).
+      #
+      # @param paths  [Array<String>] project file paths.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @return [Hash{Symbol => Hash}] `{ def_nodes:, superclasses: }`
+      def discovered_def_index_for_paths(paths, buffer: nil)
+        def_nodes = {}
+        superclasses = {}
+        includes = {}
+        paths.each do |path|
+          physical = buffer ? buffer.resolve(path) : path
+          root = Prism.parse(File.read(physical), filepath: path).value
+          build_discovered_def_nodes(root).each do |class_name, methods|
+            (def_nodes[class_name] ||= {}).merge!(methods)
+          end
+          superclasses.merge!(build_discovered_superclasses(root))
+          build_discovered_includes(root).each do |class_name, mods|
+            includes[class_name] = ((includes[class_name] || []) + mods).uniq
+          end
+        rescue StandardError
+          # Skip files that fail to parse or read; the per-file
+          # analyzer surfaces the parse error separately.
+          next
+        end
+        def_nodes.each_value(&:freeze)
+        includes.each_value(&:freeze)
+        { def_nodes: def_nodes.freeze, superclasses: superclasses.freeze, includes: includes.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

data/lib/rigor/inference/statement_evaluator.rb

@@ -358,9 +358,9 @@ module Rigor
         # is the falsey edge of the predicate (subsequent
         # statements observe the predicate-was-false world).
         return [Type::Combinator.union(then_type, else_type), falsey_scope] \
-          if branch_unconditionally_exits?(node.statements) && node.subsequent.nil?
+          if branch_terminates?(node.statements, then_type) && node.subsequent.nil?
         return [Type::Combinator.union(then_type, else_type), truthy_scope] \
-          if branch_unconditionally_exits?(node.subsequent) && node.statements
+          if branch_terminates?(node.subsequent, else_type) && node.statements
 
         [
           Type::Combinator.union(then_type, else_type),
@@ -385,9 +385,9 @@ module Rigor
         # `if`: when the body unconditionally exits and there
         # is no else, the post-scope is the truthy edge.
         return [Type::Combinator.union(then_type, else_type), truthy_scope] \
-          if branch_unconditionally_exits?(node.statements) && node.else_clause.nil?
+          if branch_terminates?(node.statements, then_type) && node.else_clause.nil?
         return [Type::Combinator.union(then_type, else_type), falsey_scope] \
-          if branch_unconditionally_exits?(node.else_clause) && node.statements
+          if branch_terminates?(node.else_clause, else_type) && node.statements
 
         [
           Type::Combinator.union(then_type, else_type),
@@ -709,24 +709,25 @@ module Rigor
       # `a` when the RHS is skipped, while `a || b` can only produce
       # the truthy fragment of `a` when the RHS is skipped.
       #
-      # When the RHS unconditionally exits (`raise` / `return` /
-      # `throw` / `exit` / `abort` / `fail` / `next` / `break`), the
-      # post-OR / post-AND scope is the LHS-skipped edge alone:
-      # `a or raise` only survives when `a` was truthy, so subsequent
-      # statements observe `a` narrowed to its truthy fragment; the
-      # symmetric `a and raise` survives only when `a` was falsey.
-      # Same shape as the `eval_if` / `eval_unless` early-return
-      # narrowing.
+      # When the RHS is a terminating branch — it `raise`s /
+      # `return`s / `throw`s / `exit`s / `break`s / `next`s, OR its
+      # inferred type is `Bot` (ADR-24 WD6: a divergent helper such
+      # as `a or fail_with_message(...)`, recognised via
+      # `branch_terminates?`) — the post-OR / post-AND scope is the
+      # LHS-skipped edge alone: `a or raise` only survives when `a`
+      # was truthy, so subsequent statements observe `a` narrowed to
+      # its truthy fragment; the symmetric `a and raise` survives
+      # only when `a` was falsey. Same shape as the `eval_if` /
+      # `eval_unless` early-return narrowing.
       def eval_and_or(node)
         left_type, left_scope = sub_eval(node.left, scope)
         truthy_left, falsey_left = Narrowing.predicate_scopes(node.left, left_scope)
         rhs_entry = node.is_a?(Prism::AndNode) ? truthy_left : falsey_left
-        if branch_unconditionally_exits?(node.right)
-          # Walk the RHS for side-effects (on_enter callbacks,
-          # diagnostic dispatch on the raise / return expression
-          # itself) but discard its scope: control never reaches
-          # any statement after `a or raise` via that edge.
-          sub_eval(node.right, rhs_entry)
+        right_type, right_scope = sub_eval(node.right, rhs_entry)
+
+        if branch_terminates?(node.right, right_type)
+          # Control never reaches any statement after `a or raise`
+          # via the RHS edge — the RHS scope is discarded.
           surviving_type =
             if node.is_a?(Prism::AndNode)
               Narrowing.narrow_falsey(left_type)
@@ -737,7 +738,6 @@ module Rigor
           return [surviving_type, surviving_scope]
         end
 
-        right_type, right_scope = sub_eval(node.right, rhs_entry)
         skipped_type =
           if node.is_a?(Prism::AndNode)
             Narrowing.narrow_falsey(left_type)
@@ -1421,7 +1421,8 @@ module Rigor
         binder = MethodParameterBinder.new(
           environment: scope.environment,
           class_path: current_class_path,
-          singleton: singleton
+          singleton: singleton,
+          source_path: scope.source_path
         )
         bindings = binder.bind(def_node)
 
@@ -1484,8 +1485,9 @@ module Rigor
       # ScopeIndexer-populated declaration overrides
       # (`Prism::ConstantReadNode` for `module Foo` headers, etc.)
       # remain reachable from inside nested bodies.
-      def build_fresh_body_scope
+      def build_fresh_body_scope # rubocop:disable Metrics/AbcSize
         Scope.empty(environment: scope.environment)
+             .with_source_path(scope.source_path)
              .with_declared_types(scope.declared_types)
              .with_discovered_classes(scope.discovered_classes)
              .with_in_source_constants(scope.in_source_constants)
@@ -1493,6 +1495,9 @@ module Rigor
              .with_class_cvars(scope.class_cvars)
              .with_program_globals(scope.program_globals)
              .with_discovered_methods(scope.discovered_methods)
+             .with_discovered_def_nodes(scope.discovered_def_nodes)
+             .with_discovered_superclasses(scope.discovered_superclasses)
+             .with_discovered_includes(scope.discovered_includes)
              .with_discovered_method_visibilities(scope.discovered_method_visibilities)
       end
 
@@ -1692,6 +1697,23 @@ module Rigor
         end
       end
 
+      # ADR-24 WD6 / slice 3 — generalised terminating-branch
+      # detection. `branch_unconditionally_exits?` recognises a
+      # branch SYNTACTICALLY (return / next / break / a call
+      # named raise / throw / exit / abort / fail). A branch
+      # whose *inferred type is `Bot`* also terminates — it
+      # cannot produce a value, so control never falls through
+      # it — regardless of how it is spelled. The canonical
+      # case is a resolved guard helper (`fail_with_message(...)`)
+      # whose body always raises: ADR-24 slice 1 types the call
+      # `bot`, and this OR-test makes `helper(...) if x.nil?`
+      # narrow exactly like `raise ... if x.nil?`. The branch
+      # type is already computed by `eval_if` / `eval_unless`.
+      def branch_terminates?(branch_node, branch_type)
+        branch_unconditionally_exits?(branch_node) ||
+          branch_type.is_a?(Type::Bot)
+      end
+
       def eval_branch_or_nil(branch_node, branch_scope)
         return [Type::Combinator.constant_of(nil), branch_scope] if branch_node.nil?
 

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

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,16 @@ 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
 
       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: []
       )
         validate_id!(id)
         validate_version!(version)
@@ -56,6 +58,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 +66,12 @@ 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)
 
         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)
         freeze
       end
 
@@ -74,8 +79,8 @@ 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)
         @id = id.dup.freeze
         @version = version.dup.freeze
         @description = description.nil? ? nil : description.to_s.dup.freeze
@@ -84,6 +89,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 +97,8 @@ 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
       end
       # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
 
@@ -119,7 +127,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 +137,16 @@ 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)
         }
       end
 
@@ -217,6 +228,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 +355,40 @@ 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
+
       def coerce_consumes(consumes)
         unless consumes.is_a?(Array)
           raise ArgumentError, "plugin manifest consumes must be an Array, got #{consumes.inspect}"