rigortype 0.1.17 → 0.1.19

data/lib/rigor/plugin/base.rb

@@ -74,23 +74,59 @@ module Rigor
         # argument; the same params Hash mixes into the cache
         # key per `Cache::Descriptor#cache_key_for`.
         #
-        # `serialize:` / `deserialize:` are forwarded verbatim to
-        # `Cache::Store#fetch_or_compute`. Default round-trip is
-        # `Marshal.dump` / `Marshal.load` per the v0.0.9 callable
-        # surface; producers whose return values are not Marshal-
-        # clean must supply their own pair.
+        # `serialize:` / `deserialize:` apply to the producer's
+        # return VALUE (the cache layer wraps them around the
+        # record-and-validate entry pair itself). Default
+        # round-trip is `Marshal.dump` / `Marshal.load` per the
+        # v0.0.9 callable surface; producers whose return values
+        # are not Marshal-clean must supply their own pair.
+        #
+        # `watch:` (ADR-60 WD3) declares the glob coverage of a
+        # discovery-style producer — the files whose addition /
+        # removal / edit must invalidate the cached value even
+        # when the producer block never read them individually
+        # (e.g. it globbed a directory itself). It is either
+        #
+        # - a static Array of `[roots, pattern, ...]` tuples
+        #   (`roots` a String or Array of Strings; one or more
+        #   glob-pattern suffixes per tuple — the same shape
+        #   {#glob_descriptor} takes), or
+        # - a Proc, run through `instance_exec` on the plugin
+        #   instance at `cache_for` invocation time (NEVER at
+        #   class-definition time — search roots are typically
+        #   computed in `#init` from config), returning the same
+        #   tuple Array.
+        #
+        # The evaluated tuples become {Cache::Descriptor::GlobEntry}
+        # rows in the dependency descriptor recorded after the
+        # block runs; `Descriptor#fresh?` re-globs + re-digests on
+        # the next run.
         #
         # Producer ids are auto-prefixed `plugin.<manifest.id>.`
         # at the cache layer (slice 6-C) so plugin-side ids cannot
         # collide with built-in producers.
-        def producer(id, serialize: nil, deserialize: nil, &block)
+        def producer(id, watch: nil, serialize: nil, deserialize: nil, &block)
           raise ArgumentError, "Plugin::Base.producer requires a block body" if block.nil?
 
+          validate_producer_watch!(watch)
           @producers ||= {}
-          @producers[id.to_sym] = { block: block, serialize: serialize, deserialize: deserialize }.freeze
+          @producers[id.to_sym] = {
+            block: block, watch: watch, serialize: serialize, deserialize: deserialize
+          }.freeze
           id.to_sym
         end
 
+        # ADR-60 WD3 — `watch:` is nil (no glob coverage), a static
+        # tuple Array, or a Proc evaluated per `cache_for` call.
+        def validate_producer_watch!(watch)
+          return if watch.nil? || watch.is_a?(Array) || watch.respond_to?(:call)
+
+          raise ArgumentError,
+                "Plugin::Base.producer watch: must be nil, an Array of [roots, pattern, ...] tuples, " \
+                "or a Proc returning one, got #{watch.inspect}"
+        end
+        private :validate_producer_watch!
+
         # Frozen snapshot of the producer table. Inherited
         # producers from a superclass are intentionally NOT
         # surfaced — Plugin::Base subclasses do not chain
@@ -190,36 +226,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 +377,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 +475,19 @@ 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 = {}
+        # ADR-60 WD4 — nil-inclusive memo tables for the authoring
+        # helpers ({#read_fact} / {#producer_value} / {#producer_error}).
+        # Allocated here, before any subclass `initialize` self-freeze,
+        # for the same reason: a populate is a Hash-content mutation.
+        @fact_cache = {}
+        @producer_value_cache = {}
+        @producer_errors = {}
       end
 
       # Override in subclasses to wire any state the plugin needs
@@ -287,22 +498,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 +581,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 +597,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 +624,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
@@ -460,6 +668,69 @@ module Rigor
         )
       end
 
+      # ADR-60 WD4 — maps a plugin's own violation objects to
+      # `Rigor::Analysis::Diagnostic`s through {#diagnostic}, absorbing
+      # the `violations.map { |v| diagnostic(node, …) }` block the
+      # node-rule plugins otherwise repeat. Each violation duck-types:
+      # `#message` (required); optional `#node` (the Prism node to
+      # position at — falls back to the `node:` argument, the common
+      # "all violations point at the same call" case), `#location` (a
+      # sub-location such as `node.message_loc`), `#severity` (defaults
+      # `:error`), and `#rule`. Returns an Array suitable for direct
+      # return from `#diagnostics_for_file` / a `node_rule` block.
+      def diagnostics_for(violations, path:, node: nil)
+        Array(violations).map do |violation|
+          target = (violation.node if violation.respond_to?(:node)) || node
+          diagnostic(
+            target,
+            path: path,
+            message: violation.message,
+            severity: (violation.respond_to?(:severity) && violation.severity) || :error,
+            rule: (violation.rule if violation.respond_to?(:rule)),
+            location: (violation.location if violation.respond_to?(:location))
+          )
+        end
+      end
+
+      # ADR-60 WD4 — reads a cross-plugin fact (ADR-9) published by
+      # another plugin's `#prepare` hook, memoised per `(plugin_id,
+      # name)` on this instance INCLUDING a nil result. The nil-inclusive
+      # memo retires the hand-rolled `@x_resolved` flag the discovery
+      # plugins carried to distinguish "fact not published" from "not yet
+      # read". `services.fact_store` is the only sanctioned cross-plugin
+      # channel; a fact no loaded producer published reads as nil.
+      def read_fact(plugin_id:, name:)
+        key = [plugin_id.to_s, name.to_sym].freeze
+        return @fact_cache[key] if @fact_cache.key?(key)
+
+        @fact_cache[key] = services.fact_store.read(plugin_id: plugin_id.to_s, name: name.to_sym)
+      end
+
+      # ADR-60 WD4 — runs a declared {.producer} through {#cache_for}
+      # and returns its value, memoised per `(id, params)` INCLUDING nil.
+      # A `StandardError` the producer raises (a malformed project file,
+      # an I/O failure) is rescued, recorded for {#producer_error}, and
+      # yields nil — so one bad project file degrades a plugin to silence
+      # rather than aborting the whole run. This is the `*_index_or_nil`
+      # shape the discovery plugins hand-rolled, named once.
+      def producer_value(id, params: {})
+        key = [id.to_sym, params].freeze
+        return @producer_value_cache[key] if @producer_value_cache.key?(key)
+
+        @producer_value_cache[key] = cache_for(id, params: params).call
+      rescue StandardError => e
+        @producer_errors[id.to_sym] = e
+        @producer_value_cache[key] = nil
+      end
+
+      # ADR-60 WD4 — the `StandardError` a prior {#producer_value} call
+      # rescued for `id`, or nil when it succeeded or was never called.
+      # Plugins surface it as a load-error diagnostic from
+      # `#diagnostics_for_file`.
+      def producer_error(id)
+        @producer_errors[id.to_sym]
+      end
+
       # Boilerplate-reduction helper (review §1.3): the "did you mean …?"
       # suggestion every diagnostic-emitting plugin otherwise hand-rolls.
       # Returns the closest of `candidates` to `name` via
@@ -530,32 +801,38 @@ module Rigor
         @io_boundary ||= services.io_boundary_for(manifest.id)
       end
 
-      # ADR-7 § "Slice 6-A" — returns a callable that performs
-      # a `Cache::Store#fetch_or_compute` round-trip for the
-      # named producer. The descriptor (per ADR-7 § "Slice
-      # 6-B") is auto-assembled from the plugin's
-      # `PluginEntry` template (id, version, config_hash) and
-      # the {IoBoundary} read history. The producer id is
-      # auto-prefixed `plugin.<manifest.id>.` per ADR-7 §
-      # "Slice 6-C" so plugin caches stay sandboxed from
-      # built-in producers.
+      # ADR-7 § "Slice 6-A" / ADR-60 WD3 — returns a callable that
+      # performs a `Cache::Store#fetch_or_validate` round-trip for
+      # the named producer (the ADR-45 record-and-validate path).
+      # The entry is KEYED on the stable identity inputs — the
+      # plugin's `PluginEntry` template (id, version, config_hash)
+      # composed with the optional `descriptor:` extras — and
+      # stores, beside the value, a DEPENDENCY descriptor recorded
+      # AFTER the producer block ran: the {IoBoundary}'s
+      # post-compute read history plus the evaluated `watch:`
+      # {Cache::Descriptor::GlobEntry} rows. In-block reads are
+      # therefore always captured (the structural stale-cache
+      # hazard `fetch_or_compute`'s call-time snapshot carried);
+      # the next run re-validates the recorded dependencies by
+      # re-digest (`Descriptor#fresh?`) and recomputes when any
+      # changed. The producer id is auto-prefixed
+      # `plugin.<manifest.id>.` per ADR-7 § "Slice 6-C" so plugin
+      # caches stay sandboxed from built-in producers.
       #
       # When `services.cache_store` is `nil` (e.g. CLI
       # `--no-cache`), the callable bypasses the cache and
       # runs the producer block every time — same semantics
       # as the v0.0.9 cache surface for built-in producers.
       #
-      # `descriptor:` (optional, ADR-7 § "Slice 6" follow-up)
-      # supplies extra `Cache::Descriptor` rows the plugin
-      # author wants to compose into the auto-built descriptor
-      # — typically gem-version `GemEntry`, configuration-file
-      # `FileEntry` digests, or `ConfigEntry` rows for external
-      # state the {IoBoundary} cannot capture itself. The
-      # passed descriptor composes via `Cache::Descriptor.compose`
-      # with the auto-built one (PluginEntry template + boundary
-      # reads); per-slot conflicts raise
-      # `Cache::Descriptor::Conflict` to make divergent inputs
-      # visible rather than silently shadowing.
+      # `descriptor:` (optional) supplies extra `Cache::Descriptor`
+      # rows for IDENTITY inputs — gem-version `GemEntry` pins,
+      # `ConfigEntry` rows for external state — that compose into
+      # the cache KEY via `Cache::Descriptor.compose`; per-slot
+      # conflicts raise `Cache::Descriptor::Conflict` to make
+      # divergent inputs visible rather than silently shadowing.
+      # A key change is a miss, so the invalidation effect of the
+      # legacy `glob_descriptor`-as-`descriptor:` idiom is
+      # preserved unchanged.
       def cache_for(producer_id, params: {}, descriptor: nil)
         producer = self.class.producers[producer_id.to_sym]
         unless producer
@@ -568,16 +845,18 @@ module Rigor
         return compute unless store
 
         prefixed_id = "plugin.#{manifest.id}.#{producer_id}"
-        composed_descriptor = compose_cache_descriptor(descriptor)
+        key_descriptor = compose_key_descriptor(descriptor)
         lambda do
-          store.fetch_or_compute(
+          store.fetch_or_validate(
             producer_id: prefixed_id,
+            key_descriptor: key_descriptor,
             params: params,
-            descriptor: composed_descriptor,
-            serialize: producer[:serialize],
-            deserialize: producer[:deserialize],
-            &compute
-          )
+            serialize: pair_serializer(producer[:serialize]),
+            deserialize: pair_deserializer(producer[:deserialize])
+          ) do
+            value = compute.call
+            [value, producer_dependency_descriptor(producer)]
+          end
         end
       end
 
@@ -589,31 +868,13 @@ module Rigor
       # descriptor), or any removal (the previously-matched file
       # drops out).
       #
-      # Pass the returned descriptor as `cache_for(..., descriptor: …)`
-      # so the cache key reflects the project files the producer
-      # reads from. Without it, `Plugin::Base#cache_for`'s
-      # auto-built descriptor only includes files the
-      # {Plugin::IoBoundary} has already read in the current
-      # process — empty on the first call of a fresh process — so
-      # the cache key is identical regardless of project state and
-      # warm runs return stale producer output when files have
-      # changed between sessions.
-      #
-      # Discovery-style producers (`actioncable`'s `:channel_index`,
-      # `actionmailer`'s `:mailer_index`, `rails-i18n`'s
-      # `:locale_index`) all follow the same pattern: walk a glob
-      # under one or more search roots, parse / read every match,
-      # build a typed index. They MUST call this helper at the
-      # `cache_for(descriptor: …)` site to be cache-correct under
-      # the persistent `Cache::Store` `rigor check` uses by
-      # default.
-      #
-      # The helper pays one SHA-256 read per matched file at
-      # call time; the producer block typically re-reads through
-      # `io_boundary.read_file` so the cost is doubled. For
-      # discovery globs in the 10-100 file range this is
-      # negligible (~ms) relative to the parse + walk the
-      # producer does on cache miss.
+      # ADR-60 WD3 made this **private**: the declared way for a
+      # discovery-style producer to cover its glob is `producer
+      # watch:` (one {Cache::Descriptor::GlobEntry} per glob in the
+      # record-and-validate dependency descriptor), not a hand-built
+      # descriptor composed into the cache *key*. The method survives
+      # only as the building block for the rare producer that needs
+      # `FileEntry` rows directly; plugin code calls `watch:`.
       #
       # @param roots    [Array<String>] search roots (relative to
       #   the project root, or absolute paths)
@@ -633,6 +894,7 @@ module Rigor
         end
         Cache::Descriptor.new(files: entries)
       end
+      private :glob_descriptor
 
       private
 
@@ -659,6 +921,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
@@ -682,17 +1020,6 @@ module Rigor
         matched.uniq.sort.select { |path| File.file?(path) }
       end
 
-      # ADR-7 § "Slice 6-B" — composes the per-call cache
-      # descriptor from (1) the plugin's PluginEntry template
-      # and (2) the IoBoundary's accumulated FileEntry rows.
-      def build_plugin_cache_descriptor
-        boundary_descriptor = io_boundary.cache_descriptor
-        Cache::Descriptor.new(
-          plugins: [plugin_entry],
-          files: boundary_descriptor.files
-        )
-      end
-
       public
 
       # ADR-32 WD5 — the `Cache::Descriptor::PluginEntry`
@@ -721,20 +1048,90 @@ module Rigor
 
       private
 
-      # ADR-7 § "Slice 6" follow-up — composes the auto-built
-      # cache descriptor with an optional plugin-author-supplied
-      # extension. Extra `GemEntry` / `FileEntry` / `ConfigEntry`
-      # rows the plugin needs (gem-version pins, external
-      # configuration files, sibling-plugin state) flow through
-      # `Cache::Descriptor.compose`; the union behaviour matches
-      # built-in producers (`RbsConstantTable`, `RbsEnvironment`).
-      def compose_cache_descriptor(extra)
-        auto_built = build_plugin_cache_descriptor
+      # ADR-60 WD3 — the cache KEY descriptor: the plugin's
+      # PluginEntry template composed with an optional
+      # plugin-author-supplied extension carrying IDENTITY inputs
+      # (gem-version pins, `ConfigEntry` rows, configuration-file
+      # digests). The IoBoundary read history deliberately does NOT
+      # enter the key — it is recorded post-compute into the
+      # dependency descriptor instead (see
+      # {#producer_dependency_descriptor}).
+      def compose_key_descriptor(extra)
+        auto_built = Cache::Descriptor.new(plugins: [plugin_entry])
         return auto_built if extra.nil?
 
         Cache::Descriptor.compose(auto_built, extra)
       end
 
+      # ADR-60 WD3 — the dependency descriptor stored beside the
+      # producer's value, built AFTER the block ran so every
+      # in-block `io_boundary` read is captured, plus the evaluated
+      # `watch:` glob rows.
+      #
+      # The boundary snapshot may carry `ConfigEntry` rows (URL
+      # fetches, see {IoBoundary#open_url}). `Descriptor#fresh?`
+      # refuses any non-file/glob slot, so including them makes the
+      # entry permanently stale → the producer recomputes EVERY run.
+      # That is deliberate: it is sound (never stale) and
+      # URL-reading producers are rare; a remote document has no
+      # cheap local re-validation anyway.
+      def producer_dependency_descriptor(producer)
+        boundary = io_boundary.cache_descriptor
+        Cache::Descriptor.new(
+          files: boundary.files,
+          configs: boundary.configs,
+          globs: watch_glob_entries(producer[:watch])
+        )
+      end
+
+      # ADR-60 WD3 — evaluates a producer's `watch:` declaration
+      # into {Cache::Descriptor::GlobEntry} rows. A Proc is
+      # `instance_exec`'d on this plugin instance (so `#init`-built
+      # search roots are in scope); the result — like the static
+      # form — is an Array of `[roots, pattern, ...]` tuples, one
+      # GlobEntry per (root, pattern) pair. Roots are expanded to
+      # absolute paths (matching {#glob_descriptor}) so freshness
+      # re-validation does not depend on the validating process's
+      # working directory.
+      def watch_glob_entries(watch)
+        return [] if watch.nil?
+
+        tuples = watch.respond_to?(:call) ? instance_exec(&watch) : watch
+        Array(tuples).flat_map do |tuple|
+          roots, *patterns = Array(tuple)
+          Array(roots).flat_map do |root|
+            absolute = File.expand_path(root.to_s)
+            patterns.map { |pattern| Cache::Descriptor::GlobEntry.compute(root: absolute, pattern: pattern.to_s) }
+          end
+        end.uniq
+      end
+
+      # ADR-60 WD3 — `fetch_or_validate` stores a
+      # `[value, dependency_descriptor]` pair, but the producer's
+      # declared `serialize:`/`deserialize:` contract covers the
+      # VALUE alone. These wrappers apply the custom callable to the
+      # value half and Marshal the descriptor half, so a producer
+      # with a non-Marshal-clean value keeps working unchanged. A
+      # nil callable returns nil — the store's default whole-pair
+      # Marshal round-trip applies.
+      def pair_serializer(serialize)
+        return nil if serialize.nil?
+
+        lambda do |pair|
+          value, dependency_descriptor = pair
+          Marshal.dump([serialize.call(value).b, Marshal.dump(dependency_descriptor)]).b
+        end
+      end
+
+      def pair_deserializer(deserialize)
+        return nil if deserialize.nil?
+
+        lambda do |bytes|
+          value_bytes, descriptor_bytes = Marshal.load(bytes) # rubocop:disable Security/MarshalLoad
+          [deserialize.call(value_bytes), Marshal.load(descriptor_bytes)] # rubocop:disable Security/MarshalLoad
+        end
+      end
+
       def digest_config(config)
         canonical = Cache::Descriptor.canonicalize_value(config || {})
         Digest::SHA256.hexdigest(JSON.generate(canonical))