rigortype 0.1.17 → 0.1.18

data/lib/rigor/plugin/additional_initializer.rb

@@ -3,32 +3,40 @@
 module Rigor
   module Plugin
     # ADR-38 declaration: "on `receiver_constraint` (and its
-    # subclasses), every method named in `methods` also establishes
-    # instance-variable state — treat it like `initialize` for the
-    # read-before-write nil soundness gate."
+    # subclasses), every method named in `methods` (def-form) or
+    # `block_methods` (block-form) also establishes instance-variable
+    # state — treat it like `initialize` for the read-before-write nil
+    # soundness gate."
+    #
+    # **Def-form** (`methods:`) — applies when the ivar write lives in a
+    # named `def` body. Example: Minitest `def setup; @conn = …; end`.
+    #
+    # **Block-form** (`block_methods:`) — applies when the ivar write
+    # lives in a block passed to a method call. Example: RSpec
+    # `before { @user = create(:user) }` / `let(:x) { @y = … }`.
+    # `ScopeIndexer` descends the block body of any `CallNode` whose
+    # method name is in `block_methods`, collecting ivar writes exactly
+    # as it would for a def-form initializer.
+    #
+    # At least one of `methods:` or `block_methods:` must be non-empty.
     #
     # Authored on a plugin manifest:
     #
-    #   manifest(
-    #     id: "minitest",
-    #     version: "0.1.0",
-    #     additional_initializers: [
-    #       Rigor::Plugin::AdditionalInitializer.new(
-    #         receiver_constraint: "Minitest::Test",
-    #         methods: [:setup]
-    #       )
-    #     ]
+    #   # def-form (Minitest):
+    #   AdditionalInitializer.new(
+    #     receiver_constraint: "Minitest::Test",
+    #     methods: [:setup]
+    #   )
+    #
+    #   # block-form (RSpec):
+    #   AdditionalInitializer.new(
+    #     receiver_constraint: "RSpec::ExampleGroup",
+    #     block_methods: [:before, :let, :subject]
     #   )
     #
     # The Ruby analogue of PHPStan's `AdditionalConstructorsExtension`.
     # `Rigor::Inference::ScopeIndexer` consults the aggregated set at
-    # its single read-before-write gate: for a `def` whose name is in
-    # `methods` on a class that equals or inherits from
-    # `receiver_constraint` (matched via `Environment#class_ordering`,
-    # the same mechanism ADR-16 Tier A uses), the method's ivar writes
-    # are folded into the class's `init_writes` set, so a sibling
-    # method reading those ivars no longer gets a `Constant[nil]`
-    # widening.
+    # its read-before-write gate.
     #
     # The contribution can only ever *suppress* a nil widening — it
     # never makes the analyzer stricter — so a missed or over-broad
@@ -39,38 +47,47 @@ module Rigor
     #
     # - `receiver_constraint` — fully-qualified class name (String).
     #   The entry applies to that class and its subclasses.
-    # - `methods` — Array of Symbol method names treated as
-    #   initializers on a matching class.
+    # - `methods` — Array of Symbol `def`-form method names (may be
+    #   empty when only block_methods is used).
+    # - `block_methods` — Array of Symbol call-with-block method names
+    #   (may be empty when only methods is used).
     #
     # ## Ractor-shareability
     #
-    # Both fields are frozen at construction (ADR-15 Phase 1);
-    # `Ractor.shareable?` returns true after `#initialize`, so the
-    # value object survives `Plugin::Registry.materialize` into a
-    # worker Ractor.
+    # All fields are frozen at construction (ADR-15 Phase 1);
+    # `Ractor.shareable?` returns true after `#initialize`.
     class AdditionalInitializer
-      attr_reader :receiver_constraint, :methods
+      attr_reader :receiver_constraint, :methods, :block_methods
 
-      def initialize(receiver_constraint:, methods:)
+      def initialize(receiver_constraint:, methods: [], block_methods: [])
         validate_receiver_constraint!(receiver_constraint)
-        validate_methods!(methods)
+        validate_method_list!(methods, :methods)
+        validate_method_list!(block_methods, :block_methods)
+        validate_at_least_one!(methods, block_methods)
 
         @receiver_constraint = receiver_constraint.dup.freeze
         @methods = methods.map(&:to_sym).freeze
+        @block_methods = block_methods.map(&:to_sym).freeze
         freeze
       end
 
-      # True when `method_name` (a Symbol) is declared an initializer
-      # by this entry. The class-constraint match is the caller's
-      # responsibility (it needs the environment's class graph).
+      # True when `method_name` (a Symbol) is declared a def-form
+      # initializer by this entry.
       def covers_method?(method_name)
         methods.include?(method_name)
       end
 
+      # True when `method_name` (a Symbol) is declared a block-form
+      # initializer by this entry.
+      def covers_block_method?(method_name)
+        block_methods.include?(method_name)
+      end
+
       def to_h
         {
           "receiver_constraint" => receiver_constraint,
-          "methods" => methods.map(&:to_s)
+          "methods" => methods.map(&:to_s),
+          "block_methods" => block_methods.map(&:to_s)
         }
       end
 
@@ -93,16 +110,22 @@ module Rigor
               "got #{value.inspect}"
       end
 
-      def validate_methods!(value)
-        if value.is_a?(Array) && !value.empty? &&
-           value.all? { |m| m.is_a?(Symbol) || (m.is_a?(String) && !m.empty?) }
-          return
-        end
+      def validate_method_list!(value, field)
+        return if value.is_a?(Array) &&
+                  value.all? { |m| m.is_a?(Symbol) || (m.is_a?(String) && !m.empty?) }
 
         raise ArgumentError,
-              "Plugin::AdditionalInitializer#methods must be a non-empty Array of " \
+              "Plugin::AdditionalInitializer##{field} must be an Array of " \
               "Symbol/non-empty String, got #{value.inspect}"
       end
+
+      def validate_at_least_one!(methods, block_methods)
+        return unless methods.empty? && block_methods.empty?
+
+        raise ArgumentError,
+              "Plugin::AdditionalInitializer requires at least one of methods: or block_methods: " \
+              "to be non-empty"
+      end
     end
   end
 end

data/lib/rigor/plugin/base.rb

@@ -190,36 +190,140 @@ module Rigor
           defined?(@node_file_context_block) ? @node_file_context_block : nil
         end
 
-        # ADR-37 slice 2 — declares a per-call-site return-type
-        # contribution, receiver-gated. The narrow successor to the
-        # `return_type` slot of `flow_contribution_for`:
+        # ADR-37 slice 2 / ADR-52 WD2 — declares a per-call-site
+        # return-type contribution, gated by receiver class, method name,
+        # or both. The narrow successor to the `return_type` slot of the
+        # deleted `flow_contribution_for` hook (ADR-52 WD3):
         #
+        #   # receiver-gated only:
         #   dynamic_return receivers: ["ActiveRecord::Base"] do |call_node, scope|
         #     # self = plugin instance; return a Rigor::Type or nil
         #   end
         #
+        #   # receiver + method gated (preferred for focused rules):
+        #   dynamic_return receivers: ["Result"], methods: [:unwrap, :unwrap!] do |call_node, scope|
+        #     # fires only for Result#unwrap / Result#unwrap!
+        #   end
+        #
+        #   # method-gated only (ADR-52 WD2 — receiver-independent rules,
+        #   # e.g. a unit-dimension DSL whose receiver carrier is a
+        #   # refinement, not a nominal class):
+        #   dynamic_return methods: [:kilometers, :per_hour, :in_meters] do |call_node, scope|
+        #     # fires for any receiver when the method name matches;
+        #     # the block reads the receiver's shape itself
+        #   end
+        #
         # `receivers:` is a non-empty Array of class names; the engine
         # calls the block only when the call's receiver type's class
         # equals or inherits from one of them (via
-        # `Environment#class_ordering`). Method-name and type-shape
-        # refinement stays in the block, which returns a `Rigor::Type`
-        # (or `nil` to decline). The block runs through `instance_exec`,
-        # so `config` / `services` are in scope. This is the
-        # {.producer}-style class DSL (it carries logic needing the
-        # instance, not pure data).
-        def dynamic_return(receivers:, &block)
+        # `Environment#class_ordering`). It MAY be omitted — then the rule
+        # is receiver-independent and fires on `methods:` alone.
+        #
+        # `methods:` is an Array of Symbol method names. When provided, the
+        # block is skipped unless `call_node.name` is in the list —
+        # declarative and cheaper than an in-block guard (the engine
+        # compiles it into the registry's contribution table, ADR-52 WD1).
+        # It is REQUIRED when `receivers:` is omitted: a rule gated on
+        # neither would fire on every dispatch, which is exactly the
+        # ungated cost the `flow_contribution_for` escape valve carries —
+        # `dynamic_return` declines to reintroduce it.
+        #
+        # Method-name and type-shape refinement can still be done inside
+        # the block. The block runs through `instance_exec`, so `config`
+        # / `services` are in scope.
+        # ADR-52 slice 3 — `receivers:` may also be a **callable**
+        # (a `-> { ... }` resolved once per run, lazily, the first time
+        # the rule is consulted — always after `#prepare`) for a receiver
+        # set the plugin only knows at run time:
+        #
+        #   dynamic_return receivers: -> { attachment_index.model_names } do |call_node, scope|
+        #     # fires when the receiver class is one a `prepare`-time scan
+        #     # found; the block does the precise per-call lookup
+        #   end
+        #
+        # The callable runs through `instance_exec`, so it reads the
+        # plugin's own `#prepare`-built indexes. It MUST be idempotent and
+        # post-`#prepare`-safe — reference a lazily-built / memoised index
+        # (as activestorage's `attachment_index` and activerecord's
+        # `model_index` are), never a value captured at class-definition
+        # time. The resolved set is a safe over-approximation of the
+        # block's own filter (it admits subclasses too), so the block
+        # stays the precise gate and diagnostics are unchanged.
+        #
+        # ADR-52 slice 4 — `methods:` may ALSO be a callable, for a
+        # method-name set the plugin only knows at run time (a Sorbet
+        # catalog's keys, a config-derived DSL method name):
+        #
+        #   dynamic_return methods: -> { catalog.method_names } do |call_node, scope|
+        #     ...
+        #   end
+        #
+        # Same contract as a callable `receivers:` — `instance_exec`'d,
+        # resolved lazily after `#prepare`, memoised, idempotent. A
+        # callable method set cannot be compiled into the registry's
+        # name gate (it is unknown at registry-build time), so the
+        # plugin is consulted on every dispatch and the name filter runs
+        # in this instance path instead — the block still only fires for
+        # a listed name, so diagnostics are unchanged.
+        # ADR-52 slice 5a — `file_methods:` is the per-file
+        # specialisation of the run-time `methods:` callable, for a name
+        # set that varies per analysed file (rigor-rspec's `let` names —
+        # the names depend on each file's `describe`/`let` structure, so
+        # one run-wide set cannot exist). The callable receives the file
+        # path, runs through `instance_exec`, and is memoised per
+        # `(rule, path)`:
+        #
+        #   dynamic_return file_methods: ->(path) { let_names_for(path) } do |call_node, scope|
+        #     ...
+        #   end
+        #
+        # Same idempotence contract as the other callables, plus: it MUST
+        # tolerate any path the engine analyses (return `[]` / nil for a
+        # file it has no names for — never raise). Like a callable
+        # `methods:`, it cannot compile into the registry name gate, so
+        # the plugin is consulted on every dispatch and filtered here.
+        # `file_methods:` replaces `methods:` (declaring both is
+        # rejected — they are the same gate at two scopes); it MAY
+        # combine with `receivers:`.
+        def dynamic_return(receivers: nil, methods: nil, file_methods: nil, &block)
           raise ArgumentError, "Plugin::Base.dynamic_return requires a block body" if block.nil?
-          unless receivers.is_a?(Array) && !receivers.empty? && receivers.all? { |r| r.is_a?(String) && !r.empty? }
-            raise ArgumentError,
-                  "Plugin::Base.dynamic_return receivers: must be a non-empty Array of class-name Strings, " \
-                  "got #{receivers.inspect}"
-          end
+
+          validate_dynamic_return_gate!(receivers, methods, file_methods)
+          validate_dynamic_return_receivers!(receivers) unless receivers.nil?
+          validate_dynamic_return_methods!(methods)
+          validate_dynamic_return_file_methods!(file_methods, methods)
 
           @dynamic_returns ||= []
-          @dynamic_returns << { receivers: receivers.map { |r| r.dup.freeze }.freeze, block: block }.freeze
+          @dynamic_returns << {
+            receivers: normalize_dynamic_return_receivers(receivers),
+            methods: normalize_dynamic_return_methods(methods),
+            file_methods: file_methods,
+            block: block
+          }.freeze
           nil
         end
 
+        # A class-name Array is frozen element-wise; a run-time callable
+        # (ADR-52 slice 3) is stored verbatim and resolved per instance.
+        def normalize_dynamic_return_receivers(receivers)
+          return nil if receivers.nil?
+          return receivers if receivers.respond_to?(:call)
+
+          receivers.map { |r| r.dup.freeze }.freeze
+        end
+        private :normalize_dynamic_return_receivers
+
+        # A method-name Array is symbol-normalised + frozen; a run-time
+        # callable (ADR-52 slice 4) is stored verbatim and resolved per
+        # instance.
+        def normalize_dynamic_return_methods(methods)
+          return nil if methods.nil?
+          return methods if methods.respond_to?(:call)
+
+          methods.map(&:to_sym).freeze
+        end
+        private :normalize_dynamic_return_methods
+
         # Frozen snapshot of the declared dynamic-return rules. Memoised:
         # `@dynamic_returns` is built once at class-definition time (via
         # `dynamic_return`) and never mutated during analysis, and every
@@ -237,9 +341,67 @@ module Rigor
         end
         # rubocop:enable Naming/MemoizedInstanceVariableName
 
+        # ADR-52 WD2 — a rule must gate on something. `receivers:` alone,
+        # `methods:` alone, or both are valid; neither is not (it would
+        # fire on every dispatch).
+        def validate_dynamic_return_gate!(receivers, methods, file_methods)
+          return unless receivers.nil? && file_methods.nil?
+          return if (methods.is_a?(Array) && !methods.empty?) || methods.respond_to?(:call)
+
+          raise ArgumentError,
+                "Plugin::Base.dynamic_return requires receivers:, methods:, or file_methods: — a rule " \
+                "gated on none would fire on every dispatch (that is what flow_contribution_for is for)"
+        end
+
+        # ADR-52 slice 5a — `file_methods:` must be a callable, and is
+        # mutually exclusive with `methods:` (one name gate, two scopes —
+        # declaring both is a contradiction, not a composition).
+        def validate_dynamic_return_file_methods!(file_methods, methods)
+          return if file_methods.nil?
+
+          unless file_methods.respond_to?(:call)
+            raise ArgumentError,
+                  "Plugin::Base.dynamic_return file_methods: must be a callable receiving the file path, " \
+                  "got #{file_methods.inspect}"
+          end
+          return if methods.nil?
+
+          raise ArgumentError,
+                "Plugin::Base.dynamic_return file_methods: replaces methods: — declare one name gate, " \
+                "not both"
+        end
+
+        def validate_dynamic_return_receivers!(receivers)
+          # ADR-52 slice 3 — a run-time callable is resolved per instance
+          # after `#prepare`; its shape is checked at resolution time.
+          return if receivers.respond_to?(:call)
+          return if receivers.is_a?(Array) && !receivers.empty? && receivers.all? { |r| r.is_a?(String) && !r.empty? }
+
+          raise ArgumentError,
+                "Plugin::Base.dynamic_return receivers: must be a non-empty Array of class-name Strings " \
+                "or a callable, got #{receivers.inspect}"
+        end
+
+        def validate_dynamic_return_methods!(methods)
+          return if methods.nil?
+          # ADR-52 slice 4 — a run-time callable resolves to the name set
+          # per instance after `#prepare`; its shape is checked then.
+          return if methods.respond_to?(:call)
+          return if methods.is_a?(Array) && !methods.empty? &&
+                    methods.all? { |m| m.is_a?(Symbol) || (m.is_a?(String) && !m.empty?) }
+
+          raise ArgumentError,
+                "Plugin::Base.dynamic_return methods: must be a non-empty Array of Symbol/String, a callable, " \
+                "or nil, got #{methods.inspect}"
+        end
+
+        private :validate_dynamic_return_gate!, :validate_dynamic_return_receivers!,
+                :validate_dynamic_return_methods!, :validate_dynamic_return_file_methods!
+
         # ADR-37 slice 2 — declares a predicate/assertion narrowing
         # contribution, method-gated. The narrow successor to the
-        # `post_return_facts` slot of `flow_contribution_for`:
+        # `post_return_facts` slot of the deleted `flow_contribution_for`
+        # hook (ADR-52 WD3):
         #
         #   type_specifier methods: [:assert_kind_of] do |call_node, scope|
         #     # return an Array of post-return facts, or nil
@@ -277,6 +439,12 @@ module Rigor
       def initialize(services:, config: {})
         @services = services
         @config = merge_config_defaults(config).freeze
+        # ADR-52 slice 3 — per-rule cache of resolved run-time
+        # `dynamic_return receivers:` callables. Created here (before any
+        # subclass `initialize` freezes the instance) so the lazy
+        # memo-on-first-dispatch is a Hash-content mutation, sound even on
+        # a self-freezing plugin.
+        @dynamic_return_runtime_cache = {}
       end
 
       # Override in subclasses to wire any state the plugin needs
@@ -287,22 +455,13 @@ module Rigor
         nil
       end
 
-      # ADR-2 § "Flow Contribution Bundle" / v0.1.1 Track 2
-      # slice 7 — per-call return-type contribution hook. When
-      # the inference engine dispatches a `Prism::CallNode` and
-      # neither the precision tiers nor RBS resolve a result,
-      # `MethodDispatcher` consults each loaded plugin via this
-      # hook ahead of `RbsDispatch`. Plugins that override the
-      # default return a {Rigor::FlowContribution} bundle whose
-      # `return_type` slot pins the call site's result type.
-      #
-      # Default returns nil — plugins that don't refine return
-      # types skip the override. Failures are isolated: a hook
-      # that raises gets its contribution dropped silently for
-      # this call so the rest of the dispatch chain continues.
-      def flow_contribution_for(call_node:, scope:) # rubocop:disable Lint/UnusedMethodArgument
-        nil
-      end
+      # NOTE: (ADR-52 WD3): the legacy ungated per-call hook
+      # `flow_contribution_for` was DELETED here pre-1.0 after its five
+      # production users migrated. Per-call return types are declared via
+      # the gated {.dynamic_return} DSL (static / run-time / per-file
+      # name sets, static / run-time receiver sets); post-return
+      # narrowing facts via {.type_specifier}. See the CHANGELOG
+      # migration note for the idiom-by-idiom mapping.
 
       # ADR-9 slice 3 — per-run preparation hook. The runner
       # invokes `#prepare(services)` on every loaded plugin once
@@ -379,10 +538,14 @@ module Rigor
 
         diagnostics = []
         Source::NodeWalker.each_with_ancestors(root) do |node, ancestors|
+          # One frozen NodeContext per node, shared across the rules
+          # that match it (ADR-52 WD1) — built lazily so non-matching
+          # nodes (the vast majority) allocate nothing.
+          context = nil
           rules.each do |rule|
             next unless node.is_a?(rule[:node_type])
 
-            context = NodeContext.new(ancestors)
+            context ||= NodeContext.new(ancestors)
             diagnostics.concat(Array(instance_exec(node, scope, path, file_context, context, &rule[:block])))
           end
         end
@@ -391,20 +554,22 @@ module Rigor
 
       # ADR-37 slice 2 — the return type contributed by this plugin's
       # {.dynamic_return} rules for a call, or nil. The engine calls this
-      # from `MethodDispatcher` alongside (and ahead of) the legacy
-      # `flow_contribution_for`; a rule fires only when `receiver_type`'s
+      # from `MethodDispatcher`; a rule fires only when `receiver_type`'s
       # class equals or inherits from one of its declared `receivers:`.
       # First non-nil wins (declaration order). Failures isolate to nil.
       def dynamic_return_type(call_node:, scope:, receiver_type:)
         rules = self.class.dynamic_returns
         return nil if rules.empty? || receiver_type.nil?
 
+        # `class_name` is nil for a receiver carrier with no nominal
+        # class (a refinement dimension, an inferred shape) — fine for a
+        # receiver-less (methods-only) rule (ADR-52 WD2), which gates on
+        # the method name alone and reads the receiver shape inside its
+        # own block.
         class_name = dynamic_return_receiver_class_name(receiver_type)
-        return nil if class_name.nil?
-
         environment = scope&.environment
         rules.each do |rule|
-          next unless rule[:receivers].any? { |c| class_matches_receiver?(class_name, c, environment) }
+          next unless dynamic_return_rule_applies?(rule, call_node, class_name, environment, scope)
 
           result = instance_exec(call_node, scope, &rule[:block])
           return result if result
@@ -416,8 +581,8 @@ module Rigor
 
       # ADR-37 slice 2 — the post-return narrowing facts contributed by
       # this plugin's {.type_specifier} rules for a call. The engine
-      # calls this from `StatementEvaluator` alongside the legacy
-      # `flow_contribution_for`; a rule fires only when `call_node.name`
+      # calls this from `StatementEvaluator`; a rule fires only when
+      # `call_node.name`
       # is one of its declared `methods:`. Failures isolate to [].
       def type_specifier_facts(call_node:, scope:)
         rules = self.class.type_specifiers
@@ -659,6 +824,82 @@ module Rigor
         end
       end
 
+      # The gate for one `dynamic_return` rule. Method-name gate first —
+      # a Symbol-array probe vs the receiver ancestry resolution below
+      # (ADR-52 WD1); both are pure predicates, so order only affects
+      # cost. A receiver-less rule (ADR-52 WD2) skips the ancestry check
+      # entirely and fires on the method name alone.
+      def dynamic_return_rule_applies?(rule, call_node, class_name, environment, scope)
+        return false if rule[:methods] && !resolved_dynamic_return_methods(rule).include?(call_node.name)
+
+        if rule[:file_methods]
+          # The path is read here, not in `dynamic_return_type`, so a
+          # spec-double scope without `source_path` only affects
+          # `file_methods:` rules (other gate forms never touch it).
+          path = scope.respond_to?(:source_path) ? scope.source_path : nil
+          return false unless resolved_dynamic_return_file_methods(rule, path).include?(call_node.name)
+        end
+
+        receivers = resolved_dynamic_return_receivers(rule)
+        return true if receivers.nil?
+        return false if class_name.nil?
+
+        receivers.any? { |c| class_matches_receiver?(class_name, c, environment) }
+      end
+
+      # ADR-52 slice 4 — the rule's method-name set. A static Array is
+      # returned as-is (`#include?` over Symbols); a run-time callable is
+      # `instance_exec`'d against this plugin and memoised as a Symbol Set,
+      # same lazy/idempotent contract as a callable `receivers:`. The
+      # cache key is namespaced so a rule that makes both `methods:` and
+      # `receivers:` callable keeps two distinct memo slots.
+      def resolved_dynamic_return_methods(rule)
+        methods = rule[:methods]
+        return methods unless methods.respond_to?(:call)
+
+        (@dynamic_return_runtime_cache ||= {})[[:methods, rule]] ||=
+          Array(instance_exec(&methods)).to_set(&:to_sym).freeze
+      end
+
+      # ADR-52 slice 5a — the rule's per-file method-name set. The
+      # `file_methods:` callable is `instance_exec`'d with the file path
+      # and memoised per `(rule, path)` — one resolution per analysed
+      # file, the per-file analogue of the run-wide `methods:` memo. A
+      # nil path (synthetic call sites with no file context) resolves to
+      # the empty set: the gate has nothing to key on, so the rule
+      # declines — fail-closed, consistent with the gate's purpose. A
+      # raising callable degrades to "declines this dispatch" via
+      # `dynamic_return_type`'s surrounding rescue.
+      EMPTY_NAME_SET = Set.new.freeze
+      private_constant :EMPTY_NAME_SET
+
+      def resolved_dynamic_return_file_methods(rule, path)
+        return EMPTY_NAME_SET if path.nil?
+
+        (@dynamic_return_runtime_cache ||= {})[[:file_methods, rule, path]] ||=
+          Array(instance_exec(path, &rule[:file_methods])).to_set(&:to_sym).freeze
+      end
+
+      # ADR-52 slice 3 — the rule's receiver class-name Array. A static
+      # Array is returned as-is; a run-time callable is `instance_exec`'d
+      # against this plugin (so it reads the `#prepare`-built indexes) and
+      # memoised per rule for the run. Resolution is lazy — first reached
+      # during file analysis, always after `#prepare` — and the callable
+      # is required to be idempotent, so the memoised set is stable. A
+      # callable that raises degrades to "no receivers match" (the rule
+      # declines), never a crash, consistent with the surrounding rescue.
+      def resolved_dynamic_return_receivers(rule)
+        receivers = rule[:receivers]
+        return receivers unless receivers.respond_to?(:call)
+
+        # `||= {}` keeps the path correct even when a caller bypassed
+        # `initialize` (`allocate` in unit specs that inject a fake
+        # index); a self-freezing plugin already has the Hash from
+        # `initialize`, so the `||=` is a no-op there (never a FrozenError).
+        (@dynamic_return_runtime_cache ||= {})[rule] ||=
+          Array(instance_exec(&receivers)).map { |c| c.to_s.dup.freeze }.freeze
+      end
+
       # True when `class_name` equals or inherits from `constraint`,
       # matched through `Environment#class_ordering` (the mechanism
       # `MacroBlockSelfType` / `additional_initializers` use). Degrades to