rigortype 0.1.18 → 0.2.0

data/lib/rigor/plugin/base.rb

@@ -18,10 +18,11 @@ module Rigor
     # overrides {#init} to wire up any state it needs from the
     # injected service container.
     #
-    # Slice 1 ships only the registration / loading plumbing. The
-    # protocol hooks (dynamic-return contributions, type-specifying
-    # contributions, dynamic reflection) land in subsequent v0.1.0
-    # slices and arrive as additional methods on this class.
+    # This class implements all plugin protocol hooks: per-call
+    # return-type contributions (`dynamic_return`), narrowing-fact
+    # contributions (`type_specifier`), AST node rules (`node_rule`),
+    # and producer/cache hooks. Cumulative implementation per the
+    # ADR-37 / ADR-52 slice chain.
     #
     # Example plugin:
     #
@@ -74,23 +75,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
@@ -445,6 +482,13 @@ module Rigor
         # 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
@@ -500,10 +544,11 @@ module Rigor
       #
       # `path` is the analysed file path; `scope` is the entry
       # `Rigor::Scope` after `ScopeIndexer` ran; `root` is the
-      # parsed `Prism::Node` root. Plugin authors traverse `root`
-      # themselves if they need node-scoped rules — the
-      # `Rule<TNode>` API ADR-2 § "Custom rules" mentions stays
-      # deferred to v0.1.x.
+      # parsed `Prism::Node` root. Plugin authors can traverse
+      # `root` themselves or declare rules via the `.node_rule` DSL
+      # (ADR-37, shipped). The PHPStan-style `Rule<TNode>` base
+      # class mentioned in ADR-2 was superseded by the block-based
+      # `.node_rule` DSL.
       #
       # Default returns `[]` so plugins that contribute through
       # other channels (e.g. slice-4 narrowing contributions,
@@ -625,6 +670,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
@@ -695,32 +803,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
@@ -733,16 +847,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
 
@@ -754,31 +870,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)
@@ -798,6 +896,7 @@ module Rigor
         end
         Cache::Descriptor.new(files: entries)
       end
+      private :glob_descriptor
 
       private
 
@@ -923,17 +1022,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`
@@ -962,20 +1050,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))

data/lib/rigor/plugin/macro/block_as_method.rb

@@ -4,9 +4,9 @@ module Rigor
   module Plugin
     module Macro
       # ADR-16 Tier A declaration: "the block passed to a
-      # class-level DSL call of one of `verbs` runs as an instance
-      # method on `receiver_constraint`'s subclass tree, with
-      # `self` typed accordingly."
+      # class-level DSL call of one of `method_names` runs as an
+      # instance method on `receiver_constraint`'s subclass tree,
+      # with `self` typed accordingly."
       #
       # Authored on a plugin manifest:
       #
@@ -16,7 +16,7 @@ module Rigor
       #     block_as_methods: [
       #       Rigor::Plugin::Macro::BlockAsMethod.new(
       #         receiver_constraint: "Sinatra::Base",
-      #         verbs: %i[get post put delete head options patch link unlink]
+      #         method_names: %i[get post put delete head options patch link unlink]
       #       )
       #     ]
       #   )
@@ -29,10 +29,9 @@ module Rigor
       # class-level methods whose block argument runs as if it were
       # an instance method of the receiver.
       #
-      # Slice 1a (this file) is **the contract only**. The engine
-      # hook that consults registered entries and narrows
-      # `Scope#self_type` for a block whose enclosing call matches
-      # arrives in slice 1b.
+      # Engine wiring: `Inference::MacroBlockSelfType.narrow_self_type_for`
+      # (called from expression_typer.rb) consults registered entries
+      # and narrows `Scope#self_type` for matching block call sites.
       #
       # ## Fields
       #
@@ -41,9 +40,10 @@ module Rigor
       #   for the entry to fire. For Sinatra modular-style this is
       #   `"Sinatra::Base"`; the substrate's class-context match
       #   accepts every subclass.
-      # - `verbs` — Array of Symbol method names. A call shape
+      # - `method_names` — Array of Symbol method names. A call shape
       #   `<receiver_subclass>.get('/path') { ... }` matches when
-      #   `:get` is in this list.
+      #   `:get` is in this list. (Named `verbs:` before ADR-60 WD2
+      #   normalised the macro value-object vocabulary.)
       # - `self_type` — Symbol selecting the kind of `self`-binding
       #   the substrate applies inside the block. Slice 1a accepts
       #   only `:receiver_instance` (the block runs as an instance
@@ -53,22 +53,22 @@ module Rigor
       # ## Ractor-shareability
       #
       # All fields are frozen at construction (ADR-15 Phase 1).
-      # `verbs` is dup-frozen so the caller's mutable array does
-      # not leak into the value. `Ractor.shareable?` returns true
-      # after `#initialize`.
+      # `method_names` is dup-frozen so the caller's mutable array
+      # does not leak into the value. `Ractor.shareable?` returns
+      # true after `#initialize`.
       class BlockAsMethod
         SELF_TYPE_RECEIVER_INSTANCE = :receiver_instance
         VALID_SELF_TYPES = [SELF_TYPE_RECEIVER_INSTANCE].freeze
 
-        attr_reader :receiver_constraint, :verbs, :self_type
+        attr_reader :receiver_constraint, :method_names, :self_type
 
-        def initialize(receiver_constraint:, verbs:, self_type: SELF_TYPE_RECEIVER_INSTANCE)
+        def initialize(receiver_constraint:, method_names:, self_type: SELF_TYPE_RECEIVER_INSTANCE)
           validate_receiver_constraint!(receiver_constraint)
-          validate_verbs!(verbs)
+          validate_method_names!(method_names)
           validate_self_type!(self_type)
 
           @receiver_constraint = receiver_constraint.dup.freeze
-          @verbs = verbs.map(&:to_sym).freeze
+          @method_names = method_names.map(&:to_sym).freeze
           @self_type = self_type
           freeze
         end
@@ -76,7 +76,7 @@ module Rigor
         def to_h
           {
             "receiver_constraint" => receiver_constraint,
-            "verbs" => verbs.map(&:to_s),
+            "method_names" => method_names.map(&:to_s),
             "self_type" => self_type.to_s
           }
         end
@@ -84,13 +84,13 @@ module Rigor
         def ==(other)
           other.is_a?(BlockAsMethod) &&
             receiver_constraint == other.receiver_constraint &&
-            verbs == other.verbs &&
+            method_names == other.method_names &&
             self_type == other.self_type
         end
         alias eql? ==
 
         def hash
-          [receiver_constraint, verbs, self_type].hash
+          [receiver_constraint, method_names, self_type].hash
         end
 
         private
@@ -103,17 +103,17 @@ module Rigor
                 "got #{value.inspect}"
         end
 
-        def validate_verbs!(verbs)
-          unless verbs.is_a?(Array) && !verbs.empty?
+        def validate_method_names!(method_names)
+          unless method_names.is_a?(Array) && !method_names.empty?
             raise ArgumentError,
-                  "Plugin::Macro::BlockAsMethod#verbs must be a non-empty Array, got #{verbs.inspect}"
+                  "Plugin::Macro::BlockAsMethod#method_names must be a non-empty Array, got #{method_names.inspect}"
           end
 
-          verbs.each do |v|
+          method_names.each do |v|
             next if v.is_a?(Symbol) || (v.is_a?(String) && !v.empty?)
 
             raise ArgumentError,
-                  "Plugin::Macro::BlockAsMethod#verbs entries must be Symbol/non-empty String, " \
+                  "Plugin::Macro::BlockAsMethod#method_names entries must be Symbol/non-empty String, " \
                   "got #{v.inspect}"
           end
         end

data/lib/rigor/plugin/macro/heredoc_template.rb

@@ -68,13 +68,10 @@ module Rigor
       # to a later slice — the `returns:` declarations cost
       # nothing to write today and unlock precision then.
       #
-      # ## Slice 2a scope
-      #
-      # This file ships the value class only. Slice 2b wires the
-      # pre-pass that scans Tier C call sites + the
-      # `SyntheticMethodIndex` the dispatcher consults; slice 2c
-      # authors `plugins/rigor-dry-struct/` and
-      # `plugins/rigor-dry-types/` as the worked consumers.
+      # Engine wiring: `Inference::SyntheticMethodScanner` (slice 2b,
+      # `synthetic_method_scanner.rb`) consumes `manifest.heredoc_templates`.
+      # Worked consumers: `plugins/rigor-dry-struct/` and
+      # `plugins/rigor-dry-types/` (slice 2c).
       class HeredocTemplate
         NAME_PLACEHOLDER = "\#{name}"
 

data/lib/rigor/plugin/macro/nested_class_template.rb

@@ -33,7 +33,7 @@ module Rigor
       #         receiver_constraint: "Mangrove::Enum", # `extend`-ed marker module
       #         block_method: :variants,               # the enclosing DSL block
       #         variant_method: :variant,              # each declaration call
-      #         name_arg_position: 0,                  # constant arg → nested class
+      #         symbol_arg_position: 0,                  # constant arg → nested class
       #         inner_arg_position: 1,                 # type arg → `#inner` return
       #         inner_reader: :inner                   # the payload reader name
       #       )
@@ -48,8 +48,10 @@ module Rigor
       #   (`:variants`).
       # - `variant_method` — Symbol naming each declaration call
       #   inside the block (`:variant`).
-      # - `name_arg_position` — Integer (default 0): the argument
+      # - `symbol_arg_position` — Integer (default 0): the argument
       #   index whose literal **constant** names the nested subclass.
+      #   (Named `name_arg_position:` before ADR-60 WD2 normalised
+      #   the macro value-object vocabulary.)
       # - `inner_arg_position` — Integer (default 1): the argument
       #   index whose type expression becomes the `#inner` reader's
       #   return type. Slice A resolves a constant type argument
@@ -69,21 +71,21 @@ module Rigor
       # `Environment#class_ordering`.
       class NestedClassTemplate
         attr_reader :receiver_constraint, :block_method, :variant_method,
-                    :name_arg_position, :inner_arg_position, :inner_reader
+                    :symbol_arg_position, :inner_arg_position, :inner_reader
 
         def initialize(receiver_constraint:, block_method: :variants, variant_method: :variant,
-                       name_arg_position: 0, inner_arg_position: 1, inner_reader: :inner)
+                       symbol_arg_position: 0, inner_arg_position: 1, inner_reader: :inner)
           validate_constraint!(receiver_constraint)
           validate_method!(block_method, "block_method")
           validate_method!(variant_method, "variant_method")
-          validate_position!(name_arg_position, "name_arg_position")
+          validate_position!(symbol_arg_position, "symbol_arg_position")
           validate_position!(inner_arg_position, "inner_arg_position")
           validate_method!(inner_reader, "inner_reader")
 
           @receiver_constraint = receiver_constraint.dup.freeze
           @block_method = block_method.to_sym
           @variant_method = variant_method.to_sym
-          @name_arg_position = name_arg_position
+          @symbol_arg_position = symbol_arg_position
           @inner_arg_position = inner_arg_position
           @inner_reader = inner_reader.to_sym
           freeze
@@ -94,7 +96,7 @@ module Rigor
             "receiver_constraint" => receiver_constraint,
             "block_method" => block_method.to_s,
             "variant_method" => variant_method.to_s,
-            "name_arg_position" => name_arg_position,
+            "symbol_arg_position" => symbol_arg_position,
             "inner_arg_position" => inner_arg_position,
             "inner_reader" => inner_reader.to_s
           }

data/lib/rigor/plugin/macro/trait_registry.rb

@@ -78,12 +78,9 @@ module Rigor
       #   facts (attr_reader / after_save / etc.); slice 3 emits
       #   only the module's plain instance methods.
       #
-      # ## Slice 3a scope
-      #
-      # This file ships the value class only. Slice 3b wires the
-      # scanner that walks Tier B call sites + the per-method
-      # explosion via `SyntheticMethodIndex`; slice 3c authors
-      # `plugins/rigor-devise/` model side as the worked consumer.
+      # Engine wiring: `Inference::SyntheticMethodScanner#collect_trait_registries`
+      # (slice 3b) walks Tier B call sites and explodes per-method
+      # entries. Worked consumer: `plugins/rigor-devise/` (slice 3c).
       class TraitRegistry
         REST_POSITION = :rest