rigortype 0.2.7 → 0.2.8

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

@@ -3,10 +3,9 @@
 module Rigor
   module Plugin
     module Macro
-      # ADR-36 — the nested-class emission tier of the ADR-16
-      # macro substrate. Where Tier C ({HeredocTemplate}) synthesises
-      # *methods* on the calling class, this tier synthesises *nested
-      # subclasses* declared by an enum-shaped block DSL.
+      # ADR-36 — the nested-class emission tier of the ADR-16 macro substrate. Where Tier C ({HeredocTemplate})
+      # synthesises *methods* on the calling class, this tier synthesises *nested subclasses* declared by an
+      # enum-shaped block DSL.
       #
       # Motivating shape — Mangrove's `Enum`:
       #
@@ -18,13 +17,10 @@ module Rigor
       #       end
       #     end
       #
-      # Each `variant <Const>, <Type>` row is meant to mint a nested
-      # subclass `Shape::Circle < Shape` carrying `#inner : <Type>`.
-      # Mangrove builds this at runtime via `const_missing` +
-      # `class_eval`; the substrate replays the same contract
-      # statically so `Shape::Circle.new(1.0).inner` resolves the
-      # payload to `Float` instead of `call.undefined-constant` /
-      # `Dynamic[Top]`.
+      # Each `variant <Const>, <Type>` row is meant to mint a nested subclass `Shape::Circle < Shape` carrying
+      # `#inner : <Type>`. Mangrove builds this at runtime via `const_missing` + `class_eval`; the substrate
+      # replays the same contract statically so `Shape::Circle.new(1.0).inner` resolves the payload to `Float`
+      # instead of `call.undefined-constant` / `Dynamic[Top]`.
       #
       # ## Authoring shape
       #
@@ -41,34 +37,24 @@ module Rigor
       #
       # ## Fields
       #
-      # - `receiver_constraint` — fully-qualified module name (String)
-      #   the enclosing class must `extend` for the block to be
-      #   recognised (e.g. `"Mangrove::Enum"`).
-      # - `block_method` — Symbol naming the enclosing DSL block
-      #   (`:variants`).
-      # - `variant_method` — Symbol naming each declaration call
-      #   inside the block (`:variant`).
-      # - `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
-      #   (`Float`, `String`); non-constant inner shapes (shape
-      #   hashes) degrade to `Dynamic[Top]`.
-      # - `inner_reader` — Symbol (default `:inner`): the payload
-      #   reader synthesised on each variant subclass.
+      # - `receiver_constraint` — fully-qualified module name (String) the enclosing class must `extend` for
+      #   the block to be recognised (e.g. `"Mangrove::Enum"`).
+      # - `block_method` — Symbol naming the enclosing DSL block (`:variants`).
+      # - `variant_method` — Symbol naming each declaration call inside the block (`:variant`).
+      # - `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 (`Float`, `String`);
+      #   non-constant inner shapes (shape hashes) degrade to `Dynamic[Top]`.
+      # - `inner_reader` — Symbol (default `:inner`): the payload reader synthesised on each variant subclass.
       #
       # ## Floor / ceiling per ADR-16 WD13 + ADR-36 WD4
       #
-      # Slice A ships the floor: each variant constant resolves as a
-      # class (so `<Variant>.new(...)` and the constant reference
-      # type), and the `#inner` reader resolves to the declared inner
-      # type. The `sealed`-parent fact + `is_a?` cross-variant
-      # exhaustive narrowing (ADR-36 WD3) is the ceiling, deferred —
-      # it needs the synthetic-class hierarchy threaded into
-      # `Environment#class_ordering`.
+      # Slice A ships the floor: each variant constant resolves as a class (so `<Variant>.new(...)` and the
+      # constant reference type), and the `#inner` reader resolves to the declared inner type. The
+      # `sealed`-parent fact + `is_a?` cross-variant exhaustive narrowing (ADR-36 WD3) is the ceiling,
+      # deferred — it needs the synthetic-class hierarchy threaded into `Environment#class_ordering`.
       class NestedClassTemplate
         attr_reader :receiver_constraint, :block_method, :variant_method,
                     :symbol_arg_position, :inner_arg_position, :inner_reader

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

@@ -4,16 +4,14 @@ module Rigor
   module Plugin
     module Macro
       # ADR-16 Tier B declaration: "the class-level DSL call
-      # `<receiver_constraint>.<method_name>(:trait_a, :trait_b, ...)`
-      # effectively includes the modules named in
-      # `modules_by_symbol[:trait_a]` + `[:trait_b]` (plus any
-      # `always_included` modules) on the calling class."
+      # `<receiver_constraint>.<method_name>(:trait_a, :trait_b, ...)` effectively includes the modules named
+      # in `modules_by_symbol[:trait_a]` + `[:trait_b]` (plus any `always_included` modules) on the calling
+      # class."
       #
-      # Worked target: Devise's model-side `devise :database_authenticatable,
-      # :recoverable` DSL (per-library survey § Devise). The bundled
-      # registry mirrors `lib/devise/modules.rb`'s symbol → module table;
-      # `always_included` carries the modules Devise always mixes in
-      # regardless of selection (e.g. `Devise::Models::Authenticatable`).
+      # Worked target: Devise's model-side `devise :database_authenticatable, :recoverable` DSL (per-library
+      # survey § Devise). The bundled registry mirrors `lib/devise/modules.rb`'s symbol → module table;
+      # `always_included` carries the modules Devise always mixes in regardless of selection (e.g.
+      # `Devise::Models::Authenticatable`).
       #
       # ## Authoring shape
       #
@@ -37,50 +35,36 @@ module Rigor
       #
       # ## Fields
       #
-      # - `receiver_constraint` — fully-qualified class name (String).
-      #   Synthesis fires when the call's lexical receiver class
-      #   equals or inherits from this constraint.
-      # - `method_name` — Symbol naming the DSL method
-      #   (e.g. `:devise`).
-      # - `symbol_arg_position` — `:rest` (all positional Symbol args
-      #   are traits, slice 3a's only supported form) or a
-      #   non-negative Integer (the index of a single trait symbol —
-      #   reserved for future shapes; not yet honoured by the
-      #   scanner).
-      # - `modules_by_symbol` — Hash<Symbol, String>. Maps each
-      #   recognised trait symbol to a fully-qualified module name.
-      #   Symbols not in the table fall through (silent skip; the
-      #   scanner emits a `macro.tier_b.unknown-trait` `:info`
-      #   provenance marker per WD9 / WD13).
-      # - `always_included` — Array<String>. Fully-qualified module
-      #   names that are added to every call site (even when no
-      #   symbols match). Mirrors Devise's `always_include` modules.
+      # - `receiver_constraint` — fully-qualified class name (String). Synthesis fires when the call's
+      #   lexical receiver class equals or inherits from this constraint.
+      # - `method_name` — Symbol naming the DSL method (e.g. `:devise`).
+      # - `symbol_arg_position` — `:rest` (all positional Symbol args are traits, slice 3a's only supported
+      #   form) or a non-negative Integer (the index of a single trait symbol — reserved for future shapes;
+      #   not yet honoured by the scanner).
+      # - `modules_by_symbol` — Hash<Symbol, String>. Maps each recognised trait symbol to a fully-qualified
+      #   module name. Symbols not in the table fall through (silent skip; the scanner emits a
+      #   `macro.tier_b.unknown-trait` `:info` provenance marker per WD9 / WD13).
+      # - `always_included` — Array<String>. Fully-qualified module names that are added to every call site
+      #   (even when no symbols match). Mirrors Devise's `always_include` modules.
       #
       # ## Floor / ceiling per ADR-16 WD13
       #
-      # Slice 3 ships at the **floor**: the substrate per-method-
-      # explodes each included module's RBS instance methods into
-      # the existing `SyntheticMethodIndex` (slice 2b primitive).
-      # The synthesised methods adopt the module's authored RBS
-      # return types — Tier B is NOT subject to the Tier C
-      # `Dynamic[T]` floor because the source-of-truth (the
-      # module's authored RBS) is not a manifest-declared string.
-      # Per ADR-5 robustness, the substrate does not fabricate
-      # precision; it simply replays the modules's signatures.
+      # Slice 3 ships at the **floor**: the substrate per-method-explodes each included module's RBS instance
+      # methods into the existing `SyntheticMethodIndex` (slice 2b primitive). The synthesised methods adopt
+      # the module's authored RBS return types — Tier B is NOT subject to the Tier C `Dynamic[T]` floor
+      # because the source-of-truth (the module's authored RBS) is not a manifest-declared string. Per ADR-5
+      # robustness, the substrate does not fabricate precision; it simply replays the modules's signatures.
       #
       # **Out of scope for slice 3** (deferred follow-ups):
-      # - `class_methods_module:` per-trait (Devise's `ClassMethods`
-      #   extend-pattern); slice 3 covers instance methods only.
-      # - `sort_key:` for controlled include ordering across traits;
-      #   slice 3 uses plugin-registration order then registry
-      #   declaration order.
-      # - `included_do_digest:` — the per-module `included do` block
-      #   facts (attr_reader / after_save / etc.); slice 3 emits
-      #   only the module's plain instance methods.
+      # - `class_methods_module:` per-trait (Devise's `ClassMethods` extend-pattern); slice 3 covers instance
+      #   methods only.
+      # - `sort_key:` for controlled include ordering across traits; slice 3 uses plugin-registration order
+      #   then registry declaration order.
+      # - `included_do_digest:` — the per-module `included do` block facts (attr_reader / after_save / etc.);
+      #   slice 3 emits only the module's plain instance methods.
       #
-      # 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).
+      # 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
 
@@ -121,10 +105,9 @@ module Rigor
           to_h.hash
         end
 
-        # @return [String, nil] fully-qualified module name for the
-        #   given trait symbol, or nil when the registry doesn't
-        #   know the symbol (caller emits a tier_b.unknown-trait
-        #   provenance marker and falls through).
+        # @return [String, nil] fully-qualified module name for the given trait symbol, or nil when the
+        #   registry doesn't know the symbol (caller emits a tier_b.unknown-trait provenance marker and falls
+        #   through).
         def module_for(symbol)
           modules_by_symbol[symbol.to_sym]
         end

data/lib/rigor/plugin/macro.rb

@@ -7,23 +7,18 @@ require_relative "macro/trait_registry"
 
 module Rigor
   module Plugin
-    # Substrate declarations for the macro / DSL expansion tiers
-    # introduced by ADR-16. Plugin authors declare entries under
-    # `Plugin::Manifest` slots (`block_as_methods:`,
-    # `trait_registries:`, `heredoc_templates:`,
-    # `nested_class_templates:`) and the substrate consumes them
-    # to recognise the call shapes a library exposes to its users.
+    # Substrate declarations for the macro / DSL expansion tiers introduced by ADR-16. Plugin authors declare
+    # entries under `Plugin::Manifest` slots (`block_as_methods:`, `trait_registries:`, `heredoc_templates:`,
+    # `nested_class_templates:`) and the substrate consumes them to recognise the call shapes a library exposes
+    # to its users.
     #
-    # Tier A (`BlockAsMethod`), Tier B (`TraitRegistry`), Tier C
-    # (`HeredocTemplate`), and ADR-36 nested-class emission
-    # (`NestedClassTemplate`) value classes are all shipped here.
-    # Engine wiring lives in `lib/rigor/inference/`.
+    # Tier A (`BlockAsMethod`), Tier B (`TraitRegistry`), Tier C (`HeredocTemplate`), and ADR-36 nested-class
+    # emission (`NestedClassTemplate`) value classes are all shipped here. Engine wiring lives in
+    # `lib/rigor/inference/`.
     #
-    # Per ADR-16 § WD13, substrate-produced output ships at a
-    # **floor** in v0.1.x ("substrate-affected code parses cleanly
-    # and has its identifiers resolved"); precise return-type
-    # emission is the ceiling and arrives in a later slice through
-    # the ADR-13 `Plugin::TypeNodeResolver` chain.
+    # Per ADR-16 § WD13, substrate-produced output ships at a **floor** in v0.1.x ("substrate-affected code
+    # parses cleanly and has its identifiers resolved"); precise return-type emission is the ceiling and arrives
+    # in a later slice through the ADR-13 `Plugin::TypeNodeResolver` chain.
     module Macro
     end
   end

data/lib/rigor/plugin/manifest.rb

@@ -6,35 +6,27 @@ require_relative "additional_initializer"
 
 module Rigor
   module Plugin
-    # Value object describing one plugin's identity and metadata.
-    # Constructed once per plugin class through {Rigor::Plugin::Base.manifest};
-    # consumed by {Rigor::Plugin::Loader} when matching project
-    # configuration entries to registered plugins and by
-    # {Rigor::Cache::Descriptor::PluginEntry} when deriving cache keys.
+    # Value object describing one plugin's identity and metadata. Constructed once per plugin class through
+    # {Rigor::Plugin::Base.manifest}; consumed by {Rigor::Plugin::Loader} when matching project configuration
+    # entries to registered plugins and by {Rigor::Cache::Descriptor::PluginEntry} when deriving cache keys.
     #
-    # The fields are pinned by ADR-2 § "Registration, Configuration,
-    # and Caching"; the v0.1.0 plugin contract surface treats this
-    # struct as the public manifest shape.
+    # The fields are pinned by ADR-2 § "Registration, Configuration, and Caching"; the v0.1.0 plugin contract
+    # surface treats this struct as the public manifest shape.
     class Manifest # rubocop:disable Metrics/ClassLength
-      # Same regex {Rigor::Cache::Store::VALID_PRODUCER_ID} uses,
-      # so plugin ids round-trip through cache producer ids and
-      # `plugin.<id>.<rule>` diagnostic identifiers without escape.
+      # Same regex {Rigor::Cache::Store::VALID_PRODUCER_ID} uses, so plugin ids round-trip through cache
+      # producer ids and `plugin.<id>.<rule>` diagnostic identifiers without escape.
       VALID_ID = /\A[a-z][a-z0-9._-]*\z/
 
-      # The first-implementation `config_schema` accepts these value
-      # kinds. Slice 1 only checks key presence and shallow value
-      # kind; richer schemas (nested maps, enums) land later when
-      # the v0.1.0 protocol slices need them.
+      # The first-implementation `config_schema` accepts these value kinds. Slice 1 only checks key presence
+      # and shallow value kind; richer schemas (nested maps, enums) land later when the v0.1.0 protocol slices
+      # need them.
       VALID_VALUE_KINDS = %i[string boolean integer array hash any].freeze
 
-      # ADR-9 slice 4 — declared cross-plugin fact dependencies.
-      # `produces:` lists the names this plugin publishes through
-      # its `#prepare(services)` hook. `consumes:` lists the
-      # `(plugin_id, name)` pairs this plugin reads from
-      # `services.fact_store`. The loader uses both for
-      # topological sort + missing-producer detection; slice 4
-      # added the declarations; slice 5 (`Loader#topo_sort_plugins`)
-      # enforces ordering and missing-producer validation.
+      # ADR-9 slice 4 — declared cross-plugin fact dependencies. `produces:` lists the names this plugin
+      # publishes through its `#prepare(services)` hook. `consumes:` lists the `(plugin_id, name)` pairs this
+      # plugin reads from `services.fact_store`. The loader uses both for topological sort + missing-producer
+      # detection; slice 4 added the declarations; slice 5 (`Loader#topo_sort_plugins`) enforces ordering and
+      # missing-producer validation.
       class Consumption < Data.define(:plugin_id, :name, :optional)
         def initialize(plugin_id:, name:, optional: false)
           super(plugin_id: plugin_id.to_s, name: name.to_sym, optional: optional ? true : false)
@@ -110,17 +102,15 @@ module Rigor
         @source_rbs_synthesizer = source_rbs_synthesizer
       end
 
-      # Assigned outside assign_fields (which already carries the
-      # maximum positional arity) — set in `initialize` before the
-      # final freeze. ADR-36 nested-class emission tier.
+      # Assigned outside assign_fields (which already carries the maximum positional arity) — set in
+      # `initialize` before the final freeze. ADR-36 nested-class emission tier.
       def assign_nested_class_templates(nested_class_templates)
         @nested_class_templates = nested_class_templates.dup.freeze
       end
       private :assign_nested_class_templates
 
-      # ADR-38 — assigned outside assign_fields (which already carries
-      # the maximum positional arity), set in `initialize` before the
-      # final freeze.
+      # ADR-38 — assigned outside assign_fields (which already carries the maximum positional arity), set in
+      # `initialize` before the final freeze.
       def assign_additional_initializers(additional_initializers)
         @additional_initializers = additional_initializers.dup.freeze
       end
@@ -129,11 +119,9 @@ module Rigor
 
       public
 
-      # Validates the user-supplied plugin config block against this
-      # manifest's `config_schema`. Returns an array of human-readable
-      # error strings (empty when the config is valid). Slice 1 checks
-      # only unknown keys and shallow value kind; nested schemas come
-      # with later slices.
+      # Validates the user-supplied plugin config block against this manifest's `config_schema`. Returns an
+      # array of human-readable error strings (empty when the config is valid). Slice 1 checks only unknown
+      # keys and shallow value kind; nested schemas come with later slices.
       def validate_config(config)
         return ["plugin config must be a Hash, got #{config.class}"] unless config.is_a?(Hash)
 
@@ -226,9 +214,8 @@ module Rigor
         end
       end
 
-      # ADR-40 — a `config_schema` value is either a bare kind
-      # (`Symbol`/`String`, the original form) or a `{kind:, default:}`
-      # Hash. These three helpers read whichever shape was given.
+      # ADR-40 — a `config_schema` value is either a bare kind (`Symbol`/`String`, the original form) or a
+      # `{kind:, default:}` Hash. These three helpers read whichever shape was given.
       def schema_kind(value)
         if value.is_a?(Hash)
           kind = value[:kind] || value["kind"]
@@ -277,10 +264,9 @@ module Rigor
         end
       end
 
-      # Shared shape check for the Array-of-X manifest fields. Every entry
-      # must satisfy the block; otherwise raise the uniform "must be an
-      # Array of <label>" message. Centralises the message format the
-      # field validators below share so it cannot drift between them.
+      # Shared shape check for the Array-of-X manifest fields. Every entry must satisfy the block; otherwise
+      # raise the uniform "must be an Array of <label>" message. Centralises the message format the field
+      # validators below share so it cannot drift between them.
       def validate_array_of!(field, value, label, &)
         return if value.is_a?(Array) && value.all?(&)
 
@@ -291,73 +277,56 @@ module Rigor
         validate_array_of!("produces", produces, "Symbol/String") { |p| p.is_a?(Symbol) || p.is_a?(String) }
       end
 
-      # ADR-10 5a — `owns_receivers:` declares the class names
-      # this plugin claims sole ownership of. The dispatcher's
-      # dependency-source-inference tier consults this list
-      # before consulting its own catalog: receivers owned by a
-      # registered plugin (directly or via subclass) decline,
-      # so plugin contributions stay authoritative for those
-      # types.
+      # ADR-10 5a — `owns_receivers:` declares the class names this plugin claims sole ownership of. The
+      # dispatcher's dependency-source-inference tier consults this list before consulting its own catalog:
+      # receivers owned by a registered plugin (directly or via subclass) decline, so plugin contributions
+      # stay authoritative for those types.
       def validate_owns_receivers!(owns_receivers)
         validate_array_of!("owns_receivers", owns_receivers, "non-empty String") { |c| c.is_a?(String) && !c.empty? }
       end
 
-      # ADR-26 — `open_receivers:` declares the class names this
-      # plugin marks as "open": statically known to respond beyond
-      # their RBS-declared method surface (e.g. `ActiveRecord::Relation`,
-      # which delegates an unbounded set of user-defined scopes to
-      # its model). `Analysis::CheckRules` skips the
-      # `call.undefined-method` rule for a receiver whose class any
-      # loaded plugin lists here — flagging a method on a class
-      # with an open dynamic surface is unsound. Distinct from
-      # `owns_receivers:` (which routes dispatch); this one only
-      # suppresses the diagnostic.
+      # ADR-26 — `open_receivers:` declares the class names this plugin marks as "open": statically known to
+      # respond beyond their RBS-declared method surface (e.g. `ActiveRecord::Relation`, which delegates an
+      # unbounded set of user-defined scopes to its model). `Analysis::CheckRules` skips the
+      # `call.undefined-method` rule for a receiver whose class any loaded plugin lists here — flagging a
+      # method on a class with an open dynamic surface is unsound. Distinct from `owns_receivers:` (which
+      # routes dispatch); this one only suppresses the diagnostic.
       def validate_open_receivers!(open_receivers)
         validate_array_of!("open_receivers", open_receivers, "non-empty String") { |c| c.is_a?(String) && !c.empty? }
       end
 
-      # ADR-13 slice 2 — `type_node_resolvers:` declares the
-      # plugin-supplied `TypeNodeResolver` instances the parser
-      # consults (in slice 3) when an RBS::Extended payload's
-      # named- or generic-type head misses the built-in registry.
-      # Slice 2 carries the declarations on the manifest and the
-      # registry exposes them in registration order; the parser
-      # integration that actually drives the chain lands in
-      # slice 3.
+      # ADR-13 slice 2 — `type_node_resolvers:` declares the plugin-supplied `TypeNodeResolver` instances the
+      # parser consults (in slice 3) when an RBS::Extended payload's named- or generic-type head misses the
+      # built-in registry. Slice 2 carries the declarations on the manifest and the registry exposes them in
+      # registration order; the parser integration that actually drives the chain lands in slice 3.
       def validate_type_node_resolvers!(resolvers)
         validate_array_of!("type_node_resolvers", resolvers, "Rigor::Plugin::TypeNodeResolver instances") do |r|
           r.is_a?(TypeNodeResolver)
         end
       end
 
-      # ADR-16 slice 1a — `block_as_methods:` declares the Tier A
-      # substrate entries the plugin contributes. Slice 1a carries
-      # the declarations on the manifest; the engine hook that
-      # actually narrows `Scope#self_type` for matching blocks
-      # arrives in a subsequent slice.
+      # ADR-16 slice 1a — `block_as_methods:` declares the Tier A substrate entries the plugin contributes.
+      # Slice 1a carries the declarations on the manifest; the engine hook that actually narrows
+      # `Scope#self_type` for matching blocks arrives in a subsequent slice.
       def validate_block_as_methods!(entries)
         validate_array_of!("block_as_methods", entries, "Rigor::Plugin::Macro::BlockAsMethod instances") do |e|
           e.is_a?(Macro::BlockAsMethod)
         end
       end
 
-      # ADR-16 slice 2a — `heredoc_templates:` declares the Tier C
-      # substrate entries (heredoc-template synthesis on class-level
-      # DSL calls). Slice 2a carries the declarations on the
-      # manifest; the pre-pass + `SyntheticMethodIndex` that actually
-      # emit synthetic methods arrive in slice 2b.
+      # ADR-16 slice 2a — `heredoc_templates:` declares the Tier C substrate entries (heredoc-template
+      # synthesis on class-level DSL calls). Slice 2a carries the declarations on the manifest; the pre-pass +
+      # `SyntheticMethodIndex` that actually emit synthetic methods arrive in slice 2b.
       def validate_heredoc_templates!(entries)
         validate_array_of!("heredoc_templates", entries, "Rigor::Plugin::Macro::HeredocTemplate instances") do |e|
           e.is_a?(Macro::HeredocTemplate)
         end
       end
 
-      # ADR-36 — `nested_class_templates:` declares the
-      # nested-class emission tier (enum-shaped block DSLs that mint
-      # nested subclasses, e.g. Mangrove's `variants do variant
-      # Const, Type end`). The scanner synthesises the variant
-      # subclasses + their `#inner` reader through the existing
-      # `SyntheticMethodIndex` primitive.
+      # ADR-36 — `nested_class_templates:` declares the nested-class emission tier (enum-shaped block DSLs
+      # that mint nested subclasses, e.g. Mangrove's `variants do variant Const, Type end`). The scanner
+      # synthesises the variant subclasses + their `#inner` reader through the existing `SyntheticMethodIndex`
+      # primitive.
       def validate_nested_class_templates!(entries)
         validate_array_of!("nested_class_templates", entries,
                            "Rigor::Plugin::Macro::NestedClassTemplate instances") do |e|
@@ -365,105 +334,77 @@ module Rigor
         end
       end
 
-      # ADR-16 slice 3a — `trait_registries:` declares the Tier B
-      # substrate entries (trait-inlining via bundled module
-      # registry). Slice 3a carries the declarations on the
-      # manifest; the scanner + per-method explosion through
-      # `SyntheticMethodIndex` (slice 2b primitive) arrives in
-      # slice 3b.
+      # ADR-16 slice 3a — `trait_registries:` declares the Tier B substrate entries (trait-inlining via
+      # bundled module registry). Slice 3a carries the declarations on the manifest; the scanner + per-method
+      # explosion through `SyntheticMethodIndex` (slice 2b primitive) arrives in slice 3b.
       def validate_trait_registries!(entries)
         validate_array_of!("trait_registries", entries, "Rigor::Plugin::Macro::TraitRegistry instances") do |e|
           e.is_a?(Macro::TraitRegistry)
         end
       end
 
-      # ADR-20 slice 6 — `hkt_registrations:` declares the
-      # Lightweight HKT URI registrations this plugin ships
-      # (analogous to `%a{rigor:v1:hkt_register: ...}` directives
-      # but published via the manifest contract instead of a
-      # shipped `.rbs` file). Each entry MUST be an
-      # `Rigor::Inference::HktRegistry::Registration`. The
-      # registry aggregator on `Plugin::Registry` flattens
-      # entries from every loaded plugin and merges them into
-      # `env.hkt_registry` on top of `Builtins::HktBuiltins.registry`;
-      # user `.rbs` overlays merge on top of plugin entries
-      # last-write-wins.
+      # ADR-20 slice 6 — `hkt_registrations:` declares the Lightweight HKT URI registrations this plugin
+      # ships (analogous to `%a{rigor:v1:hkt_register: ...}` directives but published via the manifest
+      # contract instead of a shipped `.rbs` file). Each entry MUST be an
+      # `Rigor::Inference::HktRegistry::Registration`. The registry aggregator on `Plugin::Registry` flattens
+      # entries from every loaded plugin and merges them into `env.hkt_registry` on top of
+      # `Builtins::HktBuiltins.registry`; user `.rbs` overlays merge on top of plugin entries last-write-wins.
       def validate_hkt_registrations!(entries)
         validate_array_of!("hkt_registrations", entries, "Rigor::Inference::HktRegistry::Registration instances") do |e|
           e.is_a?(Inference::HktRegistry::Registration)
         end
       end
 
-      # ADR-20 slice 6 — `hkt_definitions:` declares the
-      # plugin's HKT type-function bodies (analogous to
-      # `%a{rigor:v1:hkt_define: ...}` directives). Each entry
-      # MUST be an `Rigor::Inference::HktRegistry::Definition`
-      # — typically built via
-      # `Rigor::Inference::HktRegistry.definition_with_body_tree(...)`
-      # so plugin authors can build the body programmatically
-      # via {Rigor::Inference::HktBody}'s node-constructor API
-      # without parsing a string.
+      # ADR-20 slice 6 — `hkt_definitions:` declares the plugin's HKT type-function bodies (analogous to
+      # `%a{rigor:v1:hkt_define: ...}` directives). Each entry MUST be an
+      # `Rigor::Inference::HktRegistry::Definition` — typically built via
+      # `Rigor::Inference::HktRegistry.definition_with_body_tree(...)` so plugin authors can build the body
+      # programmatically via {Rigor::Inference::HktBody}'s node-constructor API without parsing a string.
       def validate_hkt_definitions!(entries)
         validate_array_of!("hkt_definitions", entries, "Rigor::Inference::HktRegistry::Definition instances") do |e|
           e.is_a?(Inference::HktRegistry::Definition)
         end
       end
 
-      # ADR-25 — `signature_paths:` declares the RBS signature
-      # directories this plugin gem ships, as paths relative to the
-      # plugin's own gem root (e.g. `["sig"]`). `Plugin::Base#signature_paths`
-      # resolves them to absolute dirs against the gem root; the
-      # loader validates each exists and `Environment.for_project`
+      # ADR-25 — `signature_paths:` declares the RBS signature directories this plugin gem ships, as paths
+      # relative to the plugin's own gem root (e.g. `["sig"]`). `Plugin::Base#signature_paths` resolves them
+      # to absolute dirs against the gem root; the loader validates each exists and `Environment.for_project`
       # merges the resolved set into the RBS environment.
       def validate_signature_paths!(paths)
         validate_array_of!("signature_paths", paths, "non-empty String") { |p| p.is_a?(String) && !p.empty? }
       end
 
-      # ADR-28 — `protocol_contracts:` declares the path-scoped
-      # method-protocol contracts the plugin contributes. Each
-      # entry MUST be a `Rigor::Plugin::ProtocolContract`. The
-      # registry aggregator on `Plugin::Registry` flattens
-      # contracts across loaded plugins; the engine consults them
-      # in two places — `MethodParameterBinder` provides the
-      # declared parameter types into matching method bodies, and
-      # the contributing plugin's `#diagnostics_for_file` checks
-      # method presence + return-type conformance. The manifest
-      # field carries the plugin's *default* contracts; a plugin
-      # MAY override `Plugin::Base#protocol_contracts` to fold in
-      # per-project config (e.g. a custom convention path).
+      # ADR-28 — `protocol_contracts:` declares the path-scoped method-protocol contracts the plugin
+      # contributes. Each entry MUST be a `Rigor::Plugin::ProtocolContract`. The registry aggregator on
+      # `Plugin::Registry` flattens contracts across loaded plugins; the engine consults them in two places —
+      # `MethodParameterBinder` provides the declared parameter types into matching method bodies, and the
+      # contributing plugin's `#diagnostics_for_file` checks method presence + return-type conformance. The
+      # manifest field carries the plugin's *default* contracts; a plugin MAY override
+      # `Plugin::Base#protocol_contracts` to fold in per-project config (e.g. a custom convention path).
       def validate_protocol_contracts!(entries)
         validate_array_of!("protocol_contracts", entries, "Rigor::Plugin::ProtocolContract instances") do |e|
           e.is_a?(ProtocolContract)
         end
       end
 
-      # ADR-38 — `additional_initializers:` declares the
-      # (receiver_constraint, methods) pairs whose `def`-form methods
-      # the engine treats like `initialize` for the read-before-write
-      # nil soundness gate. Each entry MUST be a
-      # `Rigor::Plugin::AdditionalInitializer`. The registry
-      # aggregator on `Plugin::Registry` flattens entries across
-      # loaded plugins; `Inference::ScopeIndexer` consults the set at
-      # its single gate.
+      # ADR-38 — `additional_initializers:` declares the (receiver_constraint, methods) pairs whose `def`-form
+      # methods the engine treats like `initialize` for the read-before-write nil soundness gate. Each entry
+      # MUST be a `Rigor::Plugin::AdditionalInitializer`. The registry aggregator on `Plugin::Registry`
+      # flattens entries across loaded plugins; `Inference::ScopeIndexer` consults the set at its single gate.
       def validate_additional_initializers!(entries)
         validate_array_of!("additional_initializers", entries, "Rigor::Plugin::AdditionalInitializer instances") do |e|
           e.is_a?(AdditionalInitializer)
         end
       end
 
-      # ADR-32 WD4 — `source_rbs_synthesizer:` declares a callable
-      # the engine invokes once per analysed Ruby source file at
-      # env-build time. The callable receives a source file path
-      # (String) and returns either an RBS source String to merge
-      # into the analysis environment or `nil` (no contribution
-      # for this file). Distinct from `signature_paths:` (static,
-      # bundled RBS): the synthesizer derives RBS from project
+      # ADR-32 WD4 — `source_rbs_synthesizer:` declares a callable the engine invokes once per analysed Ruby
+      # source file at env-build time. The callable receives a source file path (String) and returns either
+      # an RBS source String to merge into the analysis environment or `nil` (no contribution for this file).
+      # Distinct from `signature_paths:` (static, bundled RBS): the synthesizer derives RBS from project
       # source on each run.
       #
-      # The value is held as-given (no dup / freeze) because a
-      # callable instance is opaque to the manifest; the plugin
-      # author is responsible for thread-/Ractor-safety of any
-      # captured state (per ADR-15).
+      # The value is held as-given (no dup / freeze) because a callable instance is opaque to the manifest;
+      # the plugin author is responsible for thread-/Ractor-safety of any captured state (per ADR-15).
       def validate_source_rbs_synthesizer!(synthesizer)
         return if synthesizer.nil?
         return if synthesizer.respond_to?(:call)