rigortype 0.2.7 → 0.2.8

data/lib/rigor/plugin/isolation.rb

@@ -4,28 +4,24 @@ require_relative "box"
 
 module Rigor
   module Plugin
-    # ADR-39 slice 5 — the selectable isolation strategy for target-library
-    # invocation. A plugin invokes a pure method on a trusted target
-    # library (e.g. `ActiveSupport::Inflector.pluralize("post")`) through
-    # {.call}; how much the invocation is isolated from Rigor's own process
-    # is a **configurable strategy** (`RIGOR_PLUGIN_ISOLATION` env; the
-    # `exe/rigor` launcher maps `.rigor.yml`'s `plugins_isolation:` onto it
+    # ADR-39 slice 5 — the selectable isolation strategy for target-library invocation. A plugin invokes a
+    # pure method on a trusted target library (e.g. `ActiveSupport::Inflector.pluralize("post")`) through
+    # {.call}; how much the invocation is isolated from Rigor's own process is a **configurable strategy**
+    # (`RIGOR_PLUGIN_ISOLATION` env; the `exe/rigor` launcher maps `.rigor.yml`'s `plugins_isolation:` onto it
     # before re-exec). Three backends behind one interface:
     #
-    # - `none` — load into the main space and call directly.
-    #   Lowest cost; no isolation. Used as the fallback where fork is
-    #   unavailable; fine because the invoked library is trusted + pure.
-    # - `ruby_box` — call inside a {Box} (`Ruby::Box`, `RUBY_BOX=1`). Isolates
-    #   core-class monkey-patches + lets gem versions coexist, but a native
-    #   crash in the boxed work still takes the process down (in-process).
-    # - `process` (**default**) — call in a forked worker ({Process}); returns data over a
-    #   pipe. The strongest: a child crash (even `SIGSEGV`) is contained —
-    #   the parent survives and declines. Higher cost (fork + IPC).
+    # - `none` — load into the main space and call directly. Lowest cost; no isolation. Used as the fallback
+    #   where fork is unavailable; fine because the invoked library is trusted + pure.
+    # - `ruby_box` — call inside a {Box} (`Ruby::Box`, `RUBY_BOX=1`). Isolates core-class monkey-patches +
+    #   lets gem versions coexist, but a native crash in the boxed work still takes the process down
+    #   (in-process).
+    # - `process` (**default**) — call in a forked worker ({Process}); returns data over a pipe. The
+    #   strongest: a child crash (even `SIGSEGV`) is contained — the parent survives and declines. Higher cost
+    #   (fork + IPC).
     #
-    # All three answer with the method's return value, or raise
-    # {Unavailable} (never approximate) when the target library cannot be
-    # reached in the chosen strategy — the caller's per-plugin rescue turns
-    # that into silence, never a wrong fact.
+    # All three answer with the method's return value, or raise {Unavailable} (never approximate) when the
+    # target library cannot be reached in the chosen strategy — the caller's per-plugin rescue turns that into
+    # silence, never a wrong fact.
     module Isolation
       class Unavailable < StandardError
       end
@@ -34,36 +30,31 @@ module Rigor
 
       module_function
 
-      # The default strategy. `process` (a crash-contained forked worker)
-      # is the default: it isolates the target library's monkey-patches +
-      # crashes from Rigor with no in-process contamination, and forks a
-      # single persistent worker (not one per call). It falls back to
-      # `none` where fork is unavailable (see {#backend}).
+      # The default strategy. `process` (a crash-contained forked worker) is the default: it isolates the
+      # target library's monkey-patches + crashes from Rigor with no in-process contamination, and forks a
+      # single persistent worker (not one per call). It falls back to `none` where fork is unavailable (see
+      # {#backend}).
       DEFAULT = "process"
 
-      # The configured strategy name (`RIGOR_PLUGIN_ISOLATION`), defaulting
-      # to {DEFAULT} for any unset / unrecognised value.
+      # The configured strategy name (`RIGOR_PLUGIN_ISOLATION`), defaulting to {DEFAULT} for any unset /
+      # unrecognised value.
       def strategy_name
         name = ENV["RIGOR_PLUGIN_ISOLATION"].to_s
         STRATEGIES.include?(name) ? name : DEFAULT
       end
 
-      # Invokes `receiver.method(*args)` on a target library, requiring
-      # `feature` first, under the configured isolation strategy. `receiver`
-      # is a constant name (String), `method` a Symbol from the caller's
-      # allow-list, and `args` simple, Marshal-able / inspectable values
-      # (Strings) — never free input. Returns the result, or raises
-      # {Unavailable}.
+      # Invokes `receiver.method(*args)` on a target library, requiring `feature` first, under the configured
+      # isolation strategy. `receiver` is a constant name (String), `method` a Symbol from the caller's
+      # allow-list, and `args` simple, Marshal-able / inspectable values (Strings) — never free input. Returns
+      # the result, or raises {Unavailable}.
       def call(feature:, receiver:, method:, args:)
         backend.call(feature: feature, receiver: receiver, method: method, args: args)
       end
 
-      # The backend module for the configured strategy. `process`
-      # (including the default) falls back to `Direct` where `fork` is
-      # unavailable (Windows / JRuby) so inflection still works rather than
-      # silently degrading — the libraries are trusted + pure, so the
-      # main-space fallback is acceptable when no fork-based isolation can
-      # be had.
+      # The backend module for the configured strategy. `process` (including the default) falls back to
+      # `Direct` where `fork` is unavailable (Windows / JRuby) so inflection still works rather than silently
+      # degrading — the libraries are trusted + pure, so the main-space fallback is acceptable when no
+      # fork-based isolation can be had.
       def backend
         case strategy_name
         when "ruby_box" then RubyBox
@@ -72,8 +63,8 @@ module Rigor
         end
       end
 
-      # `none` — load the trusted library into the main space and call it
-      # directly. No isolation; lowest cost; the fork-unavailable fallback.
+      # `none` — load the trusted library into the main space and call it directly. No isolation; lowest
+      # cost; the fork-unavailable fallback.
       module Direct
         module_function
 
@@ -85,9 +76,8 @@ module Rigor
         end
       end
 
-      # `ruby_box` — call inside the shared {Box}. The expression is built
-      # from the fixed `receiver` / allow-listed `method` and `inspect`-ed
-      # args (safe Ruby literals), so the box's `eval` carries no free
+      # `ruby_box` — call inside the shared {Box}. The expression is built from the fixed `receiver` /
+      # allow-listed `method` and `inspect`-ed args (safe Ruby literals), so the box's `eval` carries no free
       # input.
       module RubyBox
         module_function
@@ -96,9 +86,8 @@ module Rigor
           raise Unavailable, "ruby_box isolation requested but Ruby::Box is not active (RUBY_BOX=1)" unless Box.enabled?
           raise Unavailable, "#{feature} could not be loaded into the Ruby::Box" unless Box.require_feature(feature)
 
-          # `receiver` is a fixed constant name and `method` an allow-listed
-          # symbol; args are rendered via `inspect` (safe Ruby literals), so
-          # the expression is e.g. `ActiveSupport::Inflector.pluralize("x")`
+          # `receiver` is a fixed constant name and `method` an allow-listed symbol; args are rendered via
+          # `inspect` (safe Ruby literals), so the expression is e.g. `ActiveSupport::Inflector.pluralize("x")`
           # — no free input reaches the box's eval.
           rendered = args.map(&:inspect).join(", ")
           expression = "#{receiver}.#{method}(#{rendered})"
@@ -106,9 +95,8 @@ module Rigor
         end
       end
 
-      # `process` — run the call in a forked worker so a crash (even a C
-      # extension `SIGSEGV`) is contained: the parent detects the dead
-      # worker (broken pipe / EOF) and declines instead of dying. A single
+      # `process` — run the call in a forked worker so a crash (even a C extension `SIGSEGV`) is contained:
+      # the parent detects the dead worker (broken pipe / EOF) and declines instead of dying. A single
       # persistent worker handles all calls over a Marshal pipe pair.
       module Process
         module_function
@@ -128,9 +116,9 @@ module Rigor
         rescue Unavailable
           raise
         rescue StandardError => e
-          # A dead worker surfaces as EOFError (Marshal.load) or Errno::EPIPE
-          # (Marshal.dump) — both StandardError. The crash is contained: the
-          # parent resets the worker (respawn next call) and declines.
+          # A dead worker surfaces as EOFError (Marshal.load) or Errno::EPIPE (Marshal.dump) — both
+          # StandardError. The crash is contained: the parent resets the worker (respawn next call) and
+          # declines.
           @worker = nil
           raise Unavailable, "process isolation worker failed (#{e.class})"
         end
@@ -164,9 +152,8 @@ module Rigor
           end
         end
 
-        # The child loop: read a `[feature, receiver, method, args]`
-        # request, require + call, and write `[:ok, result]` or
-        # `[:error, message]`. EOF (parent gone) ends the loop.
+        # The child loop: read a `[feature, receiver, method, args]` request, require + call, and write
+        # `[:ok, result]` or `[:error, message]`. EOF (parent gone) ends the loop.
         def run_worker_loop(req_r, res_w)
           loop do
             feature, receiver, method, args = Marshal.load(req_r) # rubocop:disable Security/MarshalLoad -- parent input

data/lib/rigor/plugin/load_error.rb

@@ -2,28 +2,23 @@
 
 module Rigor
   module Plugin
-    # Raised inside the loader (and surfaced as a diagnostic by the
-    # analyzer) when a plugin entry cannot be resolved or
-    # instantiated. Carries the failing plugin reference plus the
-    # underlying cause so the diagnostic message stays precise.
+    # Raised inside the loader (and surfaced as a diagnostic by the analyzer) when a plugin entry cannot be
+    # resolved or instantiated. Carries the failing plugin reference plus the underlying cause so the diagnostic
+    # message stays precise.
     #
-    # ADR-2 § "Plugin Trust and I/O Policy" requires plugin failures
-    # to be isolated at the analyzer boundary; this class is the
-    # carrier for that contract on the loading side.
+    # ADR-2 § "Plugin Trust and I/O Policy" requires plugin failures to be isolated at the analyzer boundary;
+    # this class is the carrier for that contract on the loading side.
     class LoadError < StandardError
       attr_reader :plugin_ref, :cause_class, :reason
 
-      # ADR-9 slice 5 introduces two new reason codes alongside the
-      # implicit "load failure" used for require / configuration /
-      # init failures:
+      # ADR-9 slice 5 introduces two new reason codes alongside the implicit "load failure" used for require /
+      # configuration / init failures:
       #
-      #   - `:missing-producer` — a non-optional `manifest(consumes:)`
-      #     entry names a `(plugin_id, name)` no loaded plugin
-      #     produces.
+      #   - `:missing-producer` — a non-optional `manifest(consumes:)` entry names a `(plugin_id, name)` no
+      #     loaded plugin produces.
       #   - `:dependency-cycle` — the consumes graph forms a cycle.
       #
-      # Older callers omit `reason:` and the field defaults to nil
-      # (the legacy "load failure" envelope).
+      # Older callers omit `reason:` and the field defaults to nil (the legacy "load failure" envelope).
       def initialize(message, plugin_ref:, cause: nil, reason: nil)
         super(message)
         @plugin_ref = plugin_ref

data/lib/rigor/plugin/loader.rb

@@ -6,34 +6,27 @@ require_relative "load_error"
 
 module Rigor
   module Plugin
-    # Resolves the project's `.rigor.yml` `plugins:` entries into
-    # instantiated plugin instances, paired with a service container.
-    # Internal slice-1 implementation; the public surface is
-    # {Loader.load} returning a {Registry}.
+    # Resolves the project's `.rigor.yml` `plugins:` entries into instantiated plugin instances, paired with a
+    # service container. Internal slice-1 implementation; the public surface is {Loader.load} returning a
+    # {Registry}.
     #
     # Steps per entry (in order):
     #
     # 1. Normalise the entry into `{ gem:, id:, config: }`.
     # 2. `require` the gem (failures surface as a {LoadError}).
-    # 3. Look up the registered plugin class by id (or by gem
-    #    name if the entry omitted an explicit id).
-    # 4. Validate the user's config against the manifest's
-    #    `config_schema`.
+    # 3. Look up the registered plugin class by id (or by gem name if the entry omitted an explicit id).
+    # 4. Validate the user's config against the manifest's `config_schema`.
     # 5. Instantiate the plugin and call `init(services)`.
     #
-    # Loading is deterministic: configuration order, with plugin
-    # id alphabetical as the tie-breaker for entries that resolve
-    # to the same gem. Failures do not abort the run; the loader
-    # collects them on the {Registry} so the runner can convert
-    # each one into a `:plugin_loader` diagnostic.
+    # Loading is deterministic: configuration order, with plugin id alphabetical as the tie-breaker for
+    # entries that resolve to the same gem. Failures do not abort the run; the loader collects them on the
+    # {Registry} so the runner can convert each one into a `:plugin_loader` diagnostic.
     class Loader # rubocop:disable Metrics/ClassLength
       attr_reader :services, :requirer
 
       # @param services [Rigor::Plugin::Services]
-      # @param requirer [#call] takes a gem name and returns truthy
-      #   on successful require. Defaulted to `Kernel.require` via
-      #   a lambda; the spec injects a fake to avoid touching the
-      #   real load path.
+      # @param requirer [#call] takes a gem name and returns truthy on successful require. Defaulted to
+      #   `Kernel.require` via a lambda; the spec injects a fake to avoid touching the real load path.
       def initialize(services:, requirer: ->(name) { require name })
         @services = services
         @requirer = requirer
@@ -43,8 +36,7 @@ module Rigor
         new(services: services, requirer: requirer).load(configuration.plugins)
       end
 
-      # @param entries [Array<String, Hash>] the raw `plugins:`
-      #   list from the configuration.
+      # @param entries [Array<String, Hash>] the raw `plugins:` list from the configuration.
       # @return [Registry]
       def load(entries)
         plugins = []
@@ -64,12 +56,10 @@ module Rigor
           end
         end
 
-        # ADR-9 slice 5 — topological sort by `manifest(consumes:)`
-        # so producers run before consumers, plus early
-        # `missing-producer` validation. Cycles surface as
-        # `dependency-cycle` LoadErrors. When validation fails, the
-        # offending plugin(s) drop from the returned plugins list
-        # and the LoadError surfaces alongside any earlier failure.
+        # ADR-9 slice 5 — topological sort by `manifest(consumes:)` so producers run before consumers, plus
+        # early `missing-producer` validation. Cycles surface as `dependency-cycle` LoadErrors. When
+        # validation fails, the offending plugin(s) drop from the returned plugins list and the LoadError
+        # surfaces alongside any earlier failure.
         plugins, sort_errors = topo_sort_plugins(plugins)
         load_errors.concat(sort_errors)
 
@@ -130,13 +120,11 @@ module Rigor
         plugin
       end
 
-      # ADR-25 — a plugin's manifest-declared `signature_paths:`
-      # are resolved (by `Plugin::Base#signature_paths`) against
-      # the plugin gem root. A declared directory that does not
-      # exist is a load-time failure for that plugin — loud, not
-      # silent, because a missing `sig/` means the bundle gem is
-      # broken. The raised LoadError is collected like any other
-      # load failure and the plugin drops from the registry.
+      # ADR-25 — a plugin's manifest-declared `signature_paths:` are resolved (by
+      # `Plugin::Base#signature_paths`) against the plugin gem root. A declared directory that does not exist
+      # is a load-time failure for that plugin — loud, not silent, because a missing `sig/` means the bundle
+      # gem is broken. The raised LoadError is collected like any other load failure and the plugin drops
+      # from the registry.
       def validate_signature_paths!(plugin)
         plugin.signature_paths.each do |dir|
           next if File.directory?(dir)
@@ -221,19 +209,15 @@ module Rigor
         plugin_class.to_s
       end
 
-      # ADR-9 slice 5 — topological sort of plugins by their
-      # `manifest(consumes:)` declarations. Returns `[sorted_plugins,
-      # load_errors]`. Determinism: when no dependency relation
-      # forces an order, plugins are visited alphabetically by
-      # manifest id. A non-optional consume of a `(plugin_id, name)`
-      # whose producer is missing emits a `:missing-producer`
-      # LoadError and drops the consumer; cycles emit a
+      # ADR-9 slice 5 — topological sort of plugins by their `manifest(consumes:)` declarations. Returns
+      # `[sorted_plugins, load_errors]`. Determinism: when no dependency relation forces an order, plugins
+      # are visited alphabetically by manifest id. A non-optional consume of a `(plugin_id, name)` whose
+      # producer is missing emits a `:missing-producer` LoadError and drops the consumer; cycles emit a
       # `:dependency-cycle` LoadError naming the offending chain.
       def topo_sort_plugins(plugins)
-        # If no plugin opts into the cross-plugin API the loader's
-        # legacy configuration-order contract is preserved
-        # unchanged. Topo sort and missing-producer validation only
-        # run when at least one plugin declares `consumes:`.
+        # If no plugin opts into the cross-plugin API the loader's legacy configuration-order contract is
+        # preserved unchanged. Topo sort and missing-producer validation only run when at least one plugin
+        # declares `consumes:`.
         return [plugins, []] unless plugins.any? { |p| p.manifest.consumes.any? }
 
         index = plugins.to_h { |plugin| [plugin.manifest.id, plugin] }
@@ -267,12 +251,9 @@ module Rigor
         producer.manifest.produces.include?(name)
       end
 
-      # Kahn's algorithm with `Configuration#plugins`-order
-      # tie-break. Edges go from producer -> consumer (producer
-      # must visit first). When two plugins are simultaneously
-      # ready, the configuration-order index decides the visit
-      # order — preserves the v0.1.0 legacy contract for plugins
-      # without dependencies.
+      # Kahn's algorithm with `Configuration#plugins`-order tie-break. Edges go from producer -> consumer
+      # (producer must visit first). When two plugins are simultaneously ready, the configuration-order index
+      # decides the visit order — preserves the v0.1.0 legacy contract for plugins without dependencies.
       def sort_in_topo_order(plugins, index, errors, config_order)
         in_degree, forward = build_consumes_graph(plugins, index, errors)
         ordered, cycle_errors = kahn_walk(plugins, in_degree, forward, config_order)

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

@@ -3,10 +3,8 @@
 module Rigor
   module Plugin
     module Macro
-      # ADR-16 Tier A declaration: "the block passed to a
-      # class-level DSL call of one of `method_names` runs as an
-      # instance method on `receiver_constraint`'s subclass tree,
-      # with `self` typed accordingly."
+      # ADR-16 Tier A declaration: "the block passed to a 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:
       #
@@ -21,41 +19,31 @@ module Rigor
       #     ]
       #   )
       #
-      # Sinatra is the canonical worked target (`Sinatra::Base#generate_method`
-      # at `lib/sinatra/base.rb:1788-1793` literally does
-      # `define_method(name, &block); remove_method` — the block IS
-      # the method body, byte-for-byte). The substrate adopts the
-      # same contract: declare the receiver constraint + the
-      # class-level methods whose block argument runs as if it were
-      # an instance method of the receiver.
+      # Sinatra is the canonical worked target (`Sinatra::Base#generate_method` at
+      # `lib/sinatra/base.rb:1788-1793` literally does `define_method(name, &block); remove_method` — the
+      # block IS the method body, byte-for-byte). The substrate adopts the same contract: declare the receiver
+      # constraint + the class-level methods whose block argument runs as if it were an instance method of the
+      # receiver.
       #
-      # 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.
+      # 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
       #
-      # - `receiver_constraint` — fully-qualified class name (String)
-      #   that the call's lexical receiver MUST be (or inherit from)
-      #   for the entry to fire. For Sinatra modular-style this is
-      #   `"Sinatra::Base"`; the substrate's class-context match
-      #   accepts every subclass.
-      # - `method_names` — Array of Symbol method names. A call shape
-      #   `<receiver_subclass>.get('/path') { ... }` matches when
-      #   `: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
-      #   method of the receiver class). Other kinds (`:receiver_singleton`,
-      #   `:dsl_recorder`) are reserved for later slices.
+      # - `receiver_constraint` — fully-qualified class name (String) that the call's lexical receiver MUST be
+      #   (or inherit from) for the entry to fire. For Sinatra modular-style this is `"Sinatra::Base"`; the
+      #   substrate's class-context match accepts every subclass.
+      # - `method_names` — Array of Symbol method names. A call shape `<receiver_subclass>.get('/path') { ... }`
+      #   matches when `: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 method of the receiver
+      #   class). Other kinds (`:receiver_singleton`, `:dsl_recorder`) are reserved for later slices.
       #
       # ## Ractor-shareability
       #
-      # All fields are frozen at construction (ADR-15 Phase 1).
-      # `method_names` is dup-frozen so the caller's mutable array
-      # does not leak into the value. `Ractor.shareable?` returns
-      # true after `#initialize`.
+      # All fields are frozen at construction (ADR-15 Phase 1). `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

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

@@ -3,17 +3,13 @@
 module Rigor
   module Plugin
     module Macro
-      # ADR-16 Tier C declaration: "the class-level DSL call
-      # `<receiver_constraint>.<method_name>(name_arg, ...)` emits
-      # synthetic methods on the calling class, with names
-      # interpolating the source-visible literal argument at
-      # `symbol_arg_position`."
+      # ADR-16 Tier C declaration: "the class-level DSL call `<receiver_constraint>.<method_name>(name_arg,
+      # ...)` emits synthetic methods on the calling class, with names interpolating the source-visible
+      # literal argument at `symbol_arg_position`."
       #
-      # Textbook target — dry-struct's `attribute :name, T` and
-      # ActiveStorage's `has_one_attached :avatar` both have this
-      # shape: a class-level call enumerates a literal Symbol
-      # argument; the framework `class_eval`s a heredoc
-      # interpolating that Symbol; the emit table is fixed.
+      # Textbook target — dry-struct's `attribute :name, T` and ActiveStorage's `has_one_attached :avatar`
+      # both have this shape: a class-level call enumerates a literal Symbol argument; the framework
+      # `class_eval`s a heredoc interpolating that Symbol; the emit table is fixed.
       #
       # ## Authoring shape
       #
@@ -39,38 +35,27 @@ 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.
-      #   `:has_one_attached`, `:attribute`).
-      # - `symbol_arg_position` — Integer (default 0) — the
-      #   argument index whose literal Symbol value becomes the
-      #   `name` interpolated into each emit row's `name:`
-      #   template. Slice 2a accepts non-negative integers only.
-      # - `emit` — Array of `Emit` (or coerced Hash) — instance
-      #   methods to synthesise on the calling class.
-      # - `class_level_emit` — same shape, but the synthesised
-      #   methods are singleton (class-level) methods.
+      # - `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. `:has_one_attached`, `:attribute`).
+      # - `symbol_arg_position` — Integer (default 0) — the argument index whose literal Symbol value becomes
+      #   the `name` interpolated into each emit row's `name:` template. Slice 2a accepts non-negative
+      #   integers only.
+      # - `emit` — Array of `Emit` (or coerced Hash) — instance methods to synthesise on the calling class.
+      # - `class_level_emit` — same shape, but the synthesised methods are singleton (class-level) methods.
       #
       # ## Floor / ceiling per ADR-16 WD13
       #
-      # Slice 2 ships at the **floor**: each emit row's `name:`
-      # is the source of truth for the synthetic method's name
-      # (a single `"\#{name}"` placeholder gets interpolated with
-      # the literal symbol argument at `symbol_arg_position`).
-      # The `returns:` strings are **recorded in the manifest but
-      # not resolved**; the engine emits synthetic methods with
-      # `Dynamic[T]` returns plus a
-      # `macro.tier_c.unresolved-return` provenance marker.
-      # Precise return-type resolution via ADR-13's
-      # `Plugin::TypeNodeResolver` is the **ceiling**, deferred
-      # to a later slice — the `returns:` declarations cost
-      # nothing to write today and unlock precision then.
+      # Slice 2 ships at the **floor**: each emit row's `name:` is the source of truth for the synthetic
+      # method's name (a single `"\#{name}"` placeholder gets interpolated with the literal symbol argument at
+      # `symbol_arg_position`). The `returns:` strings are **recorded in the manifest but not resolved**; the
+      # engine emits synthetic methods with `Dynamic[T]` returns plus a `macro.tier_c.unresolved-return`
+      # provenance marker. Precise return-type resolution via ADR-13's `Plugin::TypeNodeResolver` is the
+      # **ceiling**, deferred to a later slice — the `returns:` declarations cost nothing to write today and
+      # unlock precision then.
       #
-      # Engine wiring: `Inference::SyntheticMethodScanner` (slice 2b,
-      # `synthetic_method_scanner.rb`) consumes `manifest.heredoc_templates`.
-      # Worked consumers: `plugins/rigor-dry-struct/` and
+      # 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}"
@@ -109,15 +94,12 @@ module Rigor
           to_h.hash
         end
 
-        # One row of an emit table: the synthetic method's
-        # name-template (the analyzer interpolates `\#{name}` with
-        # the call-site literal symbol) and its declared return
-        # type. The return type can be a static String (resolved
-        # via `Environment#nominal_for_name` per ADR-16 slice 6b)
-        # or a per-call-site lookup ({ReturnsFromArg}) — see
-        # [ADR-18](../../../../../docs/adr/18-substrate-per-call-site-return-type.md).
-        # When both are nil, the synthesised method's return type
-        # falls back to `Dynamic[Top]`.
+        # One row of an emit table: the synthetic method's name-template (the analyzer interpolates
+        # `\#{name}` with the call-site literal symbol) and its declared return type. The return type can be
+        # a static String (resolved via `Environment#nominal_for_name` per ADR-16 slice 6b) or a
+        # per-call-site lookup ({ReturnsFromArg}) — see
+        # [ADR-18](../../../../../docs/adr/18-substrate-per-call-site-return-type.md). When both are nil, the
+        # synthesised method's return type falls back to `Dynamic[Top]`.
         class Emit
           attr_reader :name, :returns, :returns_from_arg
 
@@ -155,10 +137,8 @@ module Rigor
           end
         end
 
-        # ADR-18 — per-call-site return-type DSL. Declares which
-        # call-site argument's source representation to look up
-        # in a cross-plugin fact channel for the synthesised
-        # method's return type.
+        # ADR-18 — per-call-site return-type DSL. Declares which call-site argument's source representation
+        # to look up in a cross-plugin fact channel for the synthesised method's return type.
         #
         # Authoring shape:
         #
@@ -167,16 +147,13 @@ module Rigor
         #       lookup_via: { plugin_id: "dry-types", fact: :dry_type_aliases }
         #     }
         #
-        # Slice 1 (this file) ships the value class + validation
-        # only. The scanner-side arg-position extraction +
-        # fact-store lookup land in slice 2 / 3.
+        # Slice 1 (this file) ships the value class + validation only. The scanner-side arg-position
+        # extraction + fact-store lookup land in slice 2 / 3.
         class ReturnsFromArg
           attr_reader :position, :plugin_id, :fact
 
-          # @return [ReturnsFromArg, nil] coerced value class
-          #   for a Hash / nil / ReturnsFromArg input. Raises on
-          #   any other shape so manifest authoring failures
-          #   surface at construction time.
+          # @return [ReturnsFromArg, nil] coerced value class for a Hash / nil / ReturnsFromArg input. Raises
+          #   on any other shape so manifest authoring failures surface at construction time.
           def self.coerce(value)
             return nil if value.nil?
             return value if value.is_a?(ReturnsFromArg)