rigortype 0.1.4 → 0.1.6

data/lib/rigor/inference/project_patched_scanner.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "project_patched_methods"
+require_relative "../analysis/dependency_source_inference/return_type_heuristic"
+
+module Rigor
+  module Inference
+    # ADR-17 slice 2 — pre-pass scanner. Walks every file the user
+    # listed under `pre_eval:` and harvests every `def` /
+    # `def self.` declaration inside a class / module body into a
+    # {ProjectPatchedMethods} registry the dispatcher consults
+    # below the plugin tier.
+    #
+    # The walker is intentionally a strict subset of
+    # {Rigor::Inference::ScopeIndexer}'s machinery: it only needs
+    # `class C; def m; end; end` shape recognition, not full
+    # inference. Parse errors degrade to a fail-soft `:warning`
+    # `pre-eval.parse-error` diagnostic accumulated alongside
+    # the registry; per ADR-17 § "Failure modes" a parse failure
+    # in a pre-eval file MUST NOT abort the rest of the run.
+    module ProjectPatchedScanner
+      # Frozen scan outcome carrying the populated registry and
+      # the per-file warnings the runner emits at run start.
+      class Result < Data.define(:registry, :diagnostics)
+        def initialize(registry:, diagnostics: [])
+          super(
+            registry: registry,
+            diagnostics: diagnostics.freeze
+          )
+        end
+      end
+
+      module_function
+
+      # @param paths [Array<String>] absolute paths to the
+      #   pre-eval files. The runner has already validated that
+      #   each path exists (slice-1 `pre-eval.file-not-found`
+      #   `:error` covers missing entries); the scanner does NOT
+      #   re-check existence.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      #   editor-mode buffer binding. When set, the scanner reads
+      #   the buffer's physical bytes if a pre-eval entry matches
+      #   the logical path, so users editing a monkey-patch file
+      #   see the in-flight version in their analysis.
+      # @return [Result] the populated registry plus any
+      #   per-file warnings.
+      def scan(paths, buffer: nil)
+        entries = []
+        diagnostics = []
+        paths.each { |path| scan_file(path, entries, diagnostics, buffer) }
+        diagnostics.concat(duplicate_declaration_diagnostics(entries))
+        Result.new(
+          registry: ProjectPatchedMethods.new(entries: entries),
+          diagnostics: diagnostics
+        )
+      end
+
+      # ADR-17 § "Failure modes" — when two pre-eval entries
+      # declare the same `(class_name, method_name, kind)` triple,
+      # emit one `:info` `pre-eval.duplicate-declaration`
+      # diagnostic per collision. The registry's first-write-wins
+      # behaviour is unchanged; the diagnostic just makes the
+      # shadowing visible so users notice when a later patch
+      # is silently masked.
+      def duplicate_declaration_diagnostics(entries)
+        seen = {}
+        entries.each_with_object([]) do |entry, acc|
+          key = [entry.class_name, entry.method_name, entry.kind]
+          if (first = seen[key])
+            acc << build_diagnostic(
+              path: entry.source_path,
+              line: entry.source_line,
+              column: 1,
+              severity: :info,
+              rule: "pre-eval.duplicate-declaration",
+              message: "pre-eval duplicate declaration: " \
+                       "#{entry.class_name}##{entry.method_name} " \
+                       "(#{entry.kind}) is already declared at " \
+                       "#{first.source_path}:#{first.source_line}. " \
+                       "The first declaration wins; this entry is shadowed."
+            )
+          else
+            seen[key] = entry
+          end
+        end
+      end
+      private_class_method :duplicate_declaration_diagnostics
+
+      def scan_file(path, entries, diagnostics, buffer = nil)
+        physical = buffer ? buffer.resolve(path) : path
+        parse_result =
+          if physical == path
+            Prism.parse_file(path)
+          else
+            Prism.parse(File.read(physical), filepath: path)
+          end
+        unless parse_result.errors.empty?
+          diagnostics << parse_error_diagnostic(path, parse_result.errors)
+          return
+        end
+
+        walk_node(parse_result.value, [], false, path, entries)
+      rescue StandardError => e
+        diagnostics << build_diagnostic(
+          path: path, line: 1, column: 1,
+          severity: :warning,
+          rule: "pre-eval.parse-error",
+          message: "rigor: failed to read pre_eval entry #{path.inspect}: " \
+                   "#{e.class}: #{e.message}. Pre-evaluation skipped for this file; " \
+                   "the rest of the run proceeds."
+        )
+      end
+      private_class_method :scan_file
+
+      def parse_error_diagnostic(path, errors)
+        first = errors.first
+        line = first.respond_to?(:location) ? first.location&.start_line || 1 : 1
+        build_diagnostic(
+          path: path, line: line, column: 1,
+          severity: :warning,
+          rule: "pre-eval.parse-error",
+          message: "rigor: pre_eval entry #{path.inspect} has a parse error " \
+                   "(#{first&.message}). Pre-evaluation skipped for this file; " \
+                   "the rest of the run proceeds."
+        )
+      end
+      private_class_method :parse_error_diagnostic
+
+      # Builds a diagnostic Hash-shape the runner translates to a
+      # `Rigor::Analysis::Diagnostic`. The scanner intentionally
+      # does NOT depend on the analysis layer (it's a pre-pass);
+      # the runner adapts at the call site.
+      def build_diagnostic(path:, line:, column:, severity:, rule:, message:)
+        { path: path, line: line, column: column, severity: severity, rule: rule, message: message }
+      end
+      private_class_method :build_diagnostic
+
+      def walk_node(node, qualified_prefix, in_singleton_class, source_path, entries)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          descend_class_or_module(node, qualified_prefix, in_singleton_class, source_path, entries)
+        when Prism::SingletonClassNode
+          descend_singleton_class(node, qualified_prefix, source_path, entries)
+        when Prism::DefNode
+          record_def_node(node, qualified_prefix, in_singleton_class, source_path, entries)
+        else
+          walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
+        end
+      end
+      private_class_method :walk_node
+
+      def walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
+        node.compact_child_nodes.each do |child|
+          walk_node(child, qualified_prefix, in_singleton_class, source_path, entries)
+        end
+      end
+      private_class_method :walk_children
+
+      def descend_class_or_module(node, qualified_prefix, in_singleton_class, source_path, entries)
+        name = qualified_name_for(node.constant_path)
+        if name && node.body
+          walk_node(node.body, qualified_prefix + [name], in_singleton_class, source_path, entries)
+        else
+          walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
+        end
+      end
+      private_class_method :descend_class_or_module
+
+      def descend_singleton_class(node, qualified_prefix, source_path, entries)
+        if node.expression.is_a?(Prism::SelfNode) && node.body
+          walk_node(node.body, qualified_prefix, true, source_path, entries)
+        else
+          walk_children(node, qualified_prefix, false, source_path, entries)
+        end
+      end
+      private_class_method :descend_singleton_class
+
+      def record_def_node(node, qualified_prefix, in_singleton_class, source_path, entries)
+        return if qualified_prefix.empty?
+
+        class_name = qualified_prefix.join("::")
+        kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
+        line = node.location&.start_line || 1
+        return_type = Analysis::DependencySourceInference::ReturnTypeHeuristic.extract(node)
+        entries << ProjectPatchedMethods::Entry.new(
+          class_name: class_name, method_name: node.name, kind: kind,
+          source_path: source_path, source_line: line,
+          return_type: return_type
+        )
+      end
+      private_class_method :record_def_node
+
+      def qualified_name_for(node)
+        case node
+        when Prism::ConstantReadNode then node.name.to_s
+        when Prism::ConstantPathNode
+          parent = node.parent.nil? ? nil : qualified_name_for(node.parent)
+          return nil if !node.parent.nil? && parent.nil?
+
+          parent.nil? ? node.name.to_s : "#{parent}::#{node.name}"
+        end
+      end
+      private_class_method :qualified_name_for
+    end
+  end
+end

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.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-16 Tier C output — one synthetic method declared by a
+    # plugin's `Plugin::Macro::HeredocTemplate` entry, after the
+    # pre-pass has interpolated the call-site literal symbol into
+    # the template name. Stored in {SyntheticMethodIndex} and
+    # consulted by {MethodDispatcher} below the RBS dispatch tier.
+    #
+    # Per ADR-16 § WD13 (cost-bounded best-effort): the v0.1.x
+    # delivery commitment is the floor — method names emit; their
+    # return types degrade to `Dynamic[T]` until slice 6
+    # (precision promotion) routes the recorded `return_type`
+    # string through ADR-13's `Plugin::TypeNodeResolver` chain.
+    # The string is preserved so the ceiling slice can resolve it
+    # without re-walking.
+    #
+    # The `provenance` Hash carries debug / `--explain` metadata:
+    # plugin id, the template's call shape, and the source
+    # location of the originating DSL call. Surfaced through the
+    # dispatcher's `macro.tier_c.*` provenance markers.
+    class SyntheticMethod
+      INSTANCE = :instance
+      SINGLETON = :singleton
+      VALID_KINDS = [INSTANCE, SINGLETON].freeze
+
+      attr_reader :class_name, :method_name, :return_type, :kind, :provenance
+
+      def initialize(class_name:, method_name:, return_type:, kind: INSTANCE, provenance: {})
+        validate!(class_name, method_name, return_type, kind, provenance)
+        @class_name = class_name.dup.freeze
+        @method_name = method_name.to_sym
+        @return_type = return_type.dup.freeze
+        @kind = kind
+        @provenance = provenance.transform_keys(&:to_sym).transform_values do |v|
+          v.is_a?(String) ? v.dup.freeze : v
+        end.freeze
+        freeze
+      end
+
+      def instance? = kind == INSTANCE
+      def singleton? = kind == SINGLETON
+
+      def to_h
+        {
+          "class_name" => class_name,
+          "method_name" => method_name.to_s,
+          "return_type" => return_type,
+          "kind" => kind.to_s,
+          "provenance" => provenance.transform_keys(&:to_s)
+        }
+      end
+
+      def ==(other)
+        other.is_a?(SyntheticMethod) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate!(class_name, method_name, return_type, kind, provenance)
+        unless class_name.is_a?(String) && !class_name.empty?
+          raise ArgumentError, "SyntheticMethod#class_name must be non-empty String, got #{class_name.inspect}"
+        end
+        unless method_name.is_a?(Symbol) || (method_name.is_a?(String) && !method_name.empty?)
+          raise ArgumentError, "SyntheticMethod#method_name must be Symbol/non-empty String, got #{method_name.inspect}"
+        end
+        unless return_type.is_a?(String) && !return_type.empty?
+          raise ArgumentError, "SyntheticMethod#return_type must be non-empty String, got #{return_type.inspect}"
+        end
+        unless VALID_KINDS.include?(kind)
+          raise ArgumentError, "SyntheticMethod#kind must be one of #{VALID_KINDS.inspect}, got #{kind.inspect}"
+        end
+
+        return if provenance.is_a?(Hash)
+
+        raise ArgumentError, "SyntheticMethod#provenance must be a Hash, got #{provenance.inspect}"
+      end
+    end
+  end
+end