rigortype 0.4.5 → 0.4.7

data/lib/rigor/mcp/server.rb

@@ -155,6 +155,10 @@ module Rigor
       ].freeze
       Ractor.make_shareable(TOOLS)
 
+      # The tools that read a configuration — the ones taking a `config` argument — and so report its warnings.
+      CONFIG_TOOLS = TOOLS.filter_map { |tool| tool[:name] if tool.dig(:inputSchema, :properties, :config) }.freeze
+      Ractor.make_shareable(CONFIG_TOOLS)
+
       def initialize(config_path: nil, err: $stderr)
         @config_path = config_path
         @err = err
@@ -165,7 +169,7 @@ module Rigor
         id = request["id"]
         method_name = request["method"]
 
-        # Notifications carry no `id` and require no response.
+        # A notification carries no `id` and requires no response.
         return nil if id.nil?
 
         case method_name
@@ -181,8 +185,38 @@ module Rigor
         end
       end
 
+      # ADR-126 WD4 — `rigor_type_of` and `rigor_explain` print documents whose top-level shape changes in the next
+      # minor, and their CLI says so on stderr, which `tool_result` drops once there is a document. The notice is
+      # carried to the agent as its own `text` content block, the same text the CLI printed, so the document block
+      # stays byte-for-byte what the CLI wrote. When stdout is empty the error text already is stderr.
+      SHAPE_NOTICE_TOOLS = %w[rigor_type_of rigor_explain].freeze
+
       private
 
+      def finish_tool_result(name, args, out, err, exit_code)
+        result = with_config_warnings(tool_result(out, err, exit_code), name, args, out)
+        result = with_shape_notice(result, name, out, err)
+        with_path_warnings(result, name, out, err)
+      end
+
+      # #2206 — `rigor coverage` writes its path warnings (a missing path skipped beside files it measures) to stderr,
+      # which a successful run drops. The tool carries the CLI's whole stderr (path warnings and any other warnings)
+      # as a second text block, unfiltered, so an agent sees what was skipped.
+      def with_path_warnings(result, name, out, err)
+        return result unless name == "rigor_coverage" && !out.empty? && !err.strip.empty?
+
+        result.merge(content: result.fetch(:content) + [{ type: "text", text: err }])
+      end
+
+      def with_shape_notice(result, name, out, err)
+        return result unless SHAPE_NOTICE_TOOLS.include?(name) && !out.empty?
+
+        notice = err[CLI::JsonDocument::NOTICE_PATTERN]
+        return result unless notice
+
+        result.merge(content: result.fetch(:content) + [{ type: "text", text: notice }])
+      end
+
       def handle_initialize(id)
         require_relative "../version"
         success(id, {
@@ -201,7 +235,7 @@ module Rigor
         require_relative "../cli"
         exit_code = with_captured_streams(out_io, err_io) { CLI.new(argv, out: out_io, err: err_io).run }
 
-        success(id, tool_result(out_io.string, err_io.string, exit_code))
+        success(id, finish_tool_result(name, args, out_io.string, err_io.string, exit_code))
       rescue SystemExit => e
         # Defence against any command that exits: it must not take the server down with it.
         success(id, { content: [{ type: "text", text: "Command exited (status #{e.status})" }], isError: true })
@@ -221,6 +255,43 @@ module Rigor
         { content: [{ type: "text", text: out.empty? ? err : out }], isError: is_error }
       end
 
+      # Issue #2231 — `rigor check` puts {ConfigAudit} warnings in its JSON `config_warnings`; the other tools read the
+      # same configuration and said nothing about it, so an agent saw `call.undefined-method` on a project whose
+      # `.rigor.yml` misspelt the key meant to silence it and got no hint why. Every tool that takes a `config`
+      # argument now carries them: a second `text` content block holding `{"config_warnings": [...]}`, each entry the
+      # shape check's JSON uses. The tool's own document is left byte-for-byte as its CLI printed it, and an output
+      # that already carries the key (check's) gets no second copy. Nothing is added when there is nothing to say,
+      # nor when the configuration does not load — the CLI has already reported that.
+      def with_config_warnings(result, name, args, out)
+        return result unless CONFIG_TOOLS.include?(name)
+
+        warnings = config_warnings(present_config(args["config"]) || @config_path)
+        return result if warnings.empty? || carries_config_warnings?(out)
+
+        block = { type: "text", text: JSON.generate({ "config_warnings" => warnings.map(&:to_h) }) }
+        result.merge(content: result.fetch(:content) + [block])
+      end
+
+      # Only a configuration that does not load is "no warnings to show": the CLI has already reported that error.
+      # A failure in ConfigAudit itself is a bug and surfaces as an internal error rather than reading as clean.
+      def config_warnings(config_path)
+        require_relative "../configuration"
+        require_relative "../config_audit"
+        begin
+          configuration = Configuration.load(config_path)
+        rescue ConfigurationError
+          return []
+        end
+        ConfigAudit.warnings(configuration)
+      end
+
+      def carries_config_warnings?(out)
+        document = JSON.parse(out)
+        document.is_a?(Hash) && document.key?("config_warnings")
+      rescue JSON::ParserError
+        false
+      end
+
       # The JSON-RPC channel is the process's stdout, so nothing a command writes past its `out:` (an option
       # parser's `--help`, a stray `puts`) may reach it while the command runs.
       def with_captured_streams(out_io, err_io)
@@ -235,7 +306,7 @@ module Rigor
       end
 
       def build_argv(name, args) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/PerceivedComplexity
-        effective_config = args["config"] || @config_path
+        effective_config = present_config(args["config"]) || @config_path
 
         case name
         when "rigor_check"
@@ -290,6 +361,14 @@ module Rigor
         end
       end
 
+      # A per-call `config` that is blank names no file, so the session default applies rather than `--config=`
+      # reaching the CLI as an empty path (which the CLI refuses).
+      def present_config(value)
+        return value unless value.is_a?(String) && value.strip.empty?
+
+        nil
+      end
+
       def success(id, result)
         { "jsonrpc" => "2.0", "id" => id, "result" => result }
       end

data/lib/rigor/mcp.rb

@@ -4,7 +4,7 @@ module Rigor
   # The MCP (Model Context Protocol) server subsystem. See `docs/adr/33-mcp-server.md` for the design.
   #
   # Entry point: `rigor mcp --transport stdio`. The server exposes Rigor's analysis tools (check, type-of, triage,
-  # annotate, sig-gen, explain, coverage) as MCP tool calls over a newline-delimited JSON-RPC 2.0 stdio stream.
+  # lens, annotate, sig-gen, explain, coverage) as MCP tool calls over a newline-delimited JSON-RPC 2.0 stdio stream.
   module MCP
   end
 end

data/lib/rigor/plugin/access_denied_error.rb

@@ -6,8 +6,7 @@ module Rigor
     # analyzer can convert the exception into a `:plugin_loader` diagnostic without crashing `rigor check`.
     #
     # The policy is documented in [ADR-2 § "Plugin Trust and I/O Policy"](../../../docs/adr/2-extension-api.md).
-    # Slice 2's surface lists `:read_outside_scope` and `:network_disabled` as the two reason codes; future slices
-    # may extend the set.
+    # `reason:` is one of `:read_outside_scope`, `:network_disabled`, `:url_fetch_failed` or `:url_body_too_large`.
     class AccessDeniedError < StandardError
       attr_reader :reason, :resource
 

data/lib/rigor/plugin/base.rb

@@ -8,6 +8,7 @@ require "prism"
 require_relative "manifest"
 require_relative "node_context"
 require_relative "../analysis/diagnostic"
+require_relative "../analysis/run_disclosure_credit"
 require_relative "../cache/engine_source"
 # `producer generation_cap:` defaults to (and validates against) `Cache::Store::UNBOUNDED_GENERATIONS`, and a
 # plugin class body can be evaluated before anything else pulled the cache layer in.
@@ -780,11 +781,12 @@ module Rigor
       # that differs between workers.
       def disclose_once(key, message:, severity: :info, rule: "load-error")
         id = key.to_s
-        return nil if run_registration_taken?(id, batch: false)
-
-        @run_disclosures[id] = {
-          key: id, message: message.to_s, severity: severity.to_sym, rule: rule.to_s
-        }.freeze
+        unless run_registration_taken?(id, batch: false)
+          @run_disclosures[id] = {
+            key: id, message: message.to_s, severity: severity.to_sym, rule: rule.to_s
+          }.freeze
+        end
+        attribute_run_registration(id)
         nil
       end
 
@@ -816,14 +818,15 @@ module Rigor
       # raises `ArgumentError`, which the engine reports as this plugin's `runtime-error`.
       def emit_once(key, diagnostics)
         id = key.to_s
-        return nil if run_registration_taken?(id, batch: true)
-
-        batch = Array(diagnostics).map do |row|
-          next row.dup.freeze if row.is_a?(Rigor::Analysis::Diagnostic)
+        unless run_registration_taken?(id, batch: true)
+          batch = Array(diagnostics).map do |row|
+            next row.dup.freeze if row.is_a?(Rigor::Analysis::Diagnostic)
 
-          raise ArgumentError, "emit_once expects Rigor::Analysis::Diagnostic rows, got #{row.class}"
+            raise ArgumentError, "emit_once expects Rigor::Analysis::Diagnostic rows, got #{row.class}"
+          end
+          @run_disclosures[id] = { key: id, diagnostics: batch.freeze }.freeze
         end
-        @run_disclosures[id] = { key: id, diagnostics: batch.freeze }.freeze
+        attribute_run_registration(id)
         nil
       end
 
@@ -847,6 +850,18 @@ module Rigor
       end
       private :run_registration_taken?
 
+      # Issue #2020 — hands every call, a repeat of a key already registered included, to the engine's per-file
+      # attribution ({Analysis::RunDisclosureCredit}), so an `--incremental` recheck can replay the row for a file
+      # it serves from cache. A repeat counts because a discloser memoises the input its notice is about and
+      # re-registers the notice from each file's hook. A batch registered empty adds nothing to replay.
+      def attribute_run_registration(id)
+        record = @run_disclosures[id]
+        return if record.nil? || record[:diagnostics]&.empty?
+
+        Analysis::RunDisclosureCredit.attribute(self, record)
+      end
+      private :attribute_run_registration
+
       # 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
       # `DidYouMean::SpellChecker` (the same engine Ruby's own `NoMethodError` hints use), or `nil` when

data/lib/rigor/plugin/bundled_catalog.rb

@@ -127,7 +127,7 @@ module Rigor
         def require_bundled_plugins
           return {} unless File.directory?(BUNDLED_PLUGINS_ROOT)
 
-          add_bundled_lib_dirs
+          Loader.add_bundled_lib_dirs
           Dir.children(BUNDLED_PLUGINS_ROOT).sort.each_with_object({}) do |gem_name, resolved|
             path = Loader.bundled_plugin_path(gem_name)
             next if path.nil?
@@ -137,17 +137,6 @@ module Rigor
           end
         end
 
-        # A bundled plugin's entry file requires its own tree by bare feature name (`require
-        # "rigor/plugin/activestorage"`), which resolves only with that plugin's `lib` on the load path — the
-        # loader gets it from the bundle, and this catalogue has to arrange it itself. Prepending the engine's
-        # own copies matches ADR-93 WD5's anti-skew rule, where the bundled copy always wins.
-        def add_bundled_lib_dirs
-          Dir.children(BUNDLED_PLUGINS_ROOT).sort.each do |gem_name|
-            dir = File.join(BUNDLED_PLUGINS_ROOT, gem_name, "lib")
-            $LOAD_PATH.unshift(dir) if File.directory?(dir) && !$LOAD_PATH.include?(dir)
-          end
-        end
-
         # A plugin gem that fails to load is skipped rather than fatal: the catalogue exists to *advise*, and
         # a broken bundled copy is already reported by `rigor doctor`'s plugin checks for the plugins the
         # project actually enabled. The failure is recorded in {load_failures} so a missing entry stays

data/lib/rigor/plugin/io_boundary.rb

@@ -17,7 +17,7 @@ module Rigor
     # scope and feed the cache descriptor; contributions built on top of out-of-scope reads will not
     # invalidate correctly.
     #
-    # Slice 2 ships a minimal surface:
+    # The surface:
     #
     # - `#read_file(path)` — validates against the policy, returns the file's contents, and adds a
     #   digest-keyed {Cache::Descriptor::FileEntry} to the boundary's accumulated descriptor. A read that

data/lib/rigor/plugin/loader.rb

@@ -90,6 +90,20 @@ module Rigor
         File.directory?(path) ? path : nil
       end
 
+      # Puts every bundled plugin's `lib` on `$LOAD_PATH`, so a bundled plugin that requires another by gem
+      # name (`require "rigor-ffi"` from `rigor-ethon`, `rigor-sassc`, `rigor-ffi-rzmq` and `rigor-rbnacl`)
+      # resolves without a bundle. The engine's own copies go first, which matches ADR-93 WD5's anti-skew
+      # rule: the bundled copy always wins. Idempotent; a trimmed packaging with no `plugins/` tree adds none.
+      def self.add_bundled_lib_dirs
+        root = File.join(ENGINE_ROOT, "plugins")
+        return unless File.directory?(root)
+
+        Dir.children(root).sort.each do |gem_name|
+          dir = File.join(root, gem_name, "lib")
+          $LOAD_PATH.unshift(dir) if File.directory?(dir) && !$LOAD_PATH.include?(dir)
+        end
+      end
+
       # @param entries — the raw `plugins:` list from the configuration.
       def load(entries)
         plugins = []
@@ -233,7 +247,13 @@ module Rigor
       # `feature_resolver` is unaffected: an absolute-path require's `$LOADED_FEATURES` entry still ends in
       # `/<gem>.rb`, the suffix {FEATURE_RESOLVER} matches.
       def require_gem!(entry)
-        @requirer.call(self.class.bundled_plugin_path(entry[:gem]) || entry[:gem])
+        path = self.class.bundled_plugin_path(entry[:gem])
+        if path
+          self.class.add_bundled_lib_dirs
+          @requirer.call(path)
+        else
+          @requirer.call(entry[:gem])
+        end
       rescue ::LoadError => e
         raise LoadError.new(
           "could not load plugin gem #{entry[:gem].inspect}: #{e.message}",
@@ -272,13 +292,10 @@ module Rigor
         end
       end
 
-      # A gem that registers more than one plugin is a meta-gem only when NONE of the ids is its own. The
-      # FFI family (`rigor-sassc`, `rigor-ethon`, `rigor-ffi-rzmq`, `rigor-rbnacl`) each `require "rigor-ffi"`
-      # for the shared binding analyzer, so listing one of them ALONE registered two plugins — its own and
-      # `ffi` — and the meta-gem branch rejected the entry, telling the user to list `rigor-ffi` instead,
-      # which activates the wrong plugin. The failure was load-order dependent (listing `rigor-ffi` first
-      # made the nested require a no-op and the entry loaded), so it never showed up in the suite, where
-      # some earlier example has always loaded `rigor-ffi`.
+      # A gem that registers several plugins is a meta-gem only when NONE of the ids is its own. The FFI family
+      # (`rigor-sassc`, `rigor-ethon`, `rigor-ffi-rzmq`, `rigor-rbnacl`) each `require "rigor-ffi"`, so listing
+      # one alone registered `ffi` too and was wrongly rejected as a meta-gem. The bug was load-order dependent
+      # and hid in the suite, where an earlier example always loaded `rigor-ffi`.
       #
       # `rigor-rails` stays a meta-gem under this rule: it registers eight ids and none of them is `rails`.
       def own_id_among(gem_name, ids)

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

@@ -48,11 +48,11 @@ module Rigor
       #
       # 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.
+      # `symbol_arg_position`). The synthetic method's return type is the `returns_from_arg:` lookup when it
+      # resolves, else a non-empty `returns:` string (`SyntheticMethodScanner#resolve_emit_return_type`); the
+      # dispatcher turns it into a nominal type through `MethodDispatcher#promote_via_return_type` when the
+      # environment knows the class. With neither, an `"untyped"` / `"void"` placeholder, or an unknown class, the
+      # method answers `Dynamic[Top]`. Resolution through ADR-13's `Plugin::TypeNodeResolver` is not wired.
       #
       # Engine wiring: `Inference::SyntheticMethodScanner` (slice 2b, `synthetic_method_scanner.rb`) consumes
       # `manifest.heredoc_templates`. Worked consumers: `plugins/rigor-dry-struct/` and
@@ -98,7 +98,7 @@ module Rigor
         # `\#{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
+        # [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
@@ -147,8 +147,7 @@ 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.
+        # The scanner's `resolve_emit_return_type` does the arg-position extraction and fact-store lookup.
         class ReturnsFromArg
           attr_reader :position, :plugin_id, :fact
 

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

@@ -39,12 +39,10 @@ module Rigor
       #   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
+      #   form) or a non-negative Integer (the index of a single trait symbol).
+      # - `modules_by_symbol` — Maps each recognised trait symbol to a fully-qualified module name. Symbols not
+      #   in the table are silently skipped.
+      # - `always_included` — 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
@@ -53,7 +51,7 @@ module Rigor
       # 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.
+      # robustness, the substrate does not fabricate precision; it simply replays the module'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
@@ -106,8 +104,7 @@ module Rigor
         end
 
         # @return 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).
+        #   registry doesn't know the symbol (the caller skips it).
         def module_for(symbol)
           modules_by_symbol[symbol.to_sym]
         end

data/lib/rigor/plugin/manifest.rb

@@ -56,7 +56,7 @@ module Rigor
                   :hkt_registrations, :hkt_definitions, :signature_paths, :protocol_contracts,
                   :source_rbs_synthesizer, :additional_initializers,
                   :effect_root, :effect_labels, :effect_attributions, :effect_edges, :effect_entry_points,
-                  :effect_ancestry
+                  :effect_ancestry, :per_invocation_classes, :per_invocation_non_action_macros
 
       # #392 — the project-relative globs whose files this plugin compiles into {TemplateUnit}s. Purely a
       # CLAIM: the engine globs these, reads each match's bytes and offers them to
@@ -74,7 +74,8 @@ module Rigor
         hkt_registrations: [], hkt_definitions: [], signature_paths: [], protocol_contracts: [],
         source_rbs_synthesizer: nil, additional_initializers: [],
         effect_root: nil, effect_labels: [], effect_attributions: [], effect_edges: [],
-        effect_entry_points: [], effect_ancestry: [], template_globs: []
+        effect_entry_points: [], effect_ancestry: [], template_globs: [], per_invocation_classes: [],
+        per_invocation_non_action_macros: []
       )
         validate_id!(id)
         validate_version!(version)
@@ -109,6 +110,7 @@ module Rigor
         assign_additional_initializers(additional_initializers)
         assign_effect_fields(effect_root, effect_labels, effect_attributions, effect_edges,
                              effect_entry_points, effect_ancestry, template_globs)
+        assign_per_invocation_classes(per_invocation_classes, per_invocation_non_action_macros)
         freeze
       end
 
@@ -166,9 +168,8 @@ module Rigor
       end
       private :assign_additional_initializers
 
-      # ADR-103 WD2 / WD6 / WD10 / WD14 — the effect contract's five fields, assigned together and outside
-      # `assign_fields` (which already carries the maximum positional arity).
-      # The six `effect_*` fields validate together, so {#initialize} carries one call rather than six.
+      # ADR-103 WD2 / WD6 / WD10 / WD14 — the six `effect_*` fields validate together here, so {#initialize}
+      # carries one call rather than six.
       def validate_effect_fields!(effect_root, effect_labels, effect_attributions, effect_edges,
                                   effect_entry_points, effect_ancestry)
         validate_effect_root!(effect_root)
@@ -202,6 +203,28 @@ module Rigor
         @template_globs = globs.map { |glob| glob.to_s.dup.freeze }.uniq.freeze
       end
       private :assign_template_globs
+
+      # ADR-125 — `per_invocation_classes:` names the framework classes whose every instance serves exactly one
+      # entry point, so ivar writes in two distinct entry points of a descendant are never live together.
+      # `per_invocation_non_action_macros:` names the class-body macros whose Symbol, String or inline-`def`
+      # arguments name a public method that is NOT an entry point (`before_action :load`, `helper_method
+      # :current_user`); they apply to this manifest's own `per_invocation_classes:`, so a list without classes
+      # is refused. Validated and assigned in one call, because `#initialize` is at its line budget.
+      def assign_per_invocation_classes(names, macros)
+        validate_array_of!("per_invocation_classes", names, "non-empty String") do |name|
+          name.is_a?(String) && !name.empty?
+        end
+        validate_array_of!("per_invocation_non_action_macros", macros, "Symbol/non-empty String") do |macro|
+          macro.is_a?(Symbol) || (macro.is_a?(String) && !macro.empty?)
+        end
+        if names.empty? && !macros.empty?
+          raise ArgumentError, "per_invocation_non_action_macros needs per_invocation_classes to apply to"
+        end
+
+        @per_invocation_classes = names.map { |name| name.to_s.delete_prefix("::").dup.freeze }.uniq.freeze
+        @per_invocation_non_action_macros = macros.map(&:to_sym).uniq.freeze
+      end
+      private :assign_per_invocation_classes
       # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
 
       public
@@ -258,7 +281,9 @@ module Rigor
           "effect_edges" => effect_edges.map(&:to_h),
           "effect_entry_points" => effect_entry_points.map(&:to_h),
           "effect_ancestry" => effect_ancestry.map(&:to_h),
-          "template_globs" => template_globs
+          "template_globs" => template_globs,
+          "per_invocation_classes" => per_invocation_classes,
+          "per_invocation_non_action_macros" => per_invocation_non_action_macros.map(&:to_s)
         }
       end
 
@@ -449,10 +474,9 @@ module Rigor
         end
       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 — `type_node_resolvers:` declares the plugin-supplied `TypeNodeResolver` instances the parser
+      # consults when an RBS::Extended payload's named- or generic-type head misses the built-in registry. The
+      # registry exposes them in registration order, and `Environment#build_name_scope` builds the chain.
       def validate_type_node_resolvers!(resolvers)
         validate_array_of!("type_node_resolvers", resolvers, "Rigor::Plugin::TypeNodeResolver instances") do |r|
           r.is_a?(TypeNodeResolver)
@@ -460,8 +484,7 @@ module Rigor
       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.
+      # The engine hook that narrows `Scope#self_type` for matching blocks is `Inference::MacroBlockSelfType`.
       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)
@@ -469,8 +492,7 @@ module Rigor
       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.
+      # synthesis on class-level DSL calls). `Inference::SyntheticMethodScanner` emits the synthetic methods.
       def validate_heredoc_templates!(entries)
         validate_array_of!("heredoc_templates", entries, "Rigor::Plugin::Macro::HeredocTemplate instances") do |e|
           e.is_a?(Macro::HeredocTemplate)
@@ -489,8 +511,8 @@ module Rigor
       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.
+      # bundled module registry). `Inference::SyntheticMethodScanner#collect_trait_registries` explodes them
+      # per method through `SyntheticMethodIndex`.
       def validate_trait_registries!(entries)
         validate_array_of!("trait_registries", entries, "Rigor::Plugin::Macro::TraitRegistry instances") do |e|
           e.is_a?(Macro::TraitRegistry)

data/lib/rigor/plugin/registry.rb

@@ -214,7 +214,7 @@ module Rigor
     # tie-breaker.
     #
     # ADR-15 Phase 3 — alongside the instantiated `plugins`, the registry carries `blueprints`: a frozen,
-    # Ractor-shareable `Array<Blueprint>` that records how to re-instantiate the same plugin set in a worker
+    # Ractor-shareable list of {Blueprint} that records how to re-instantiate the same plugin set in a worker
     # Ractor. The eventual Phase 4 pool ships `blueprints` across the boundary and calls {.materialize}
     # per-Ractor; the live `plugins` carriage on the coordinator registry stays unchanged.
     class Registry
@@ -397,6 +397,28 @@ module Rigor
         @rbs_complete_extends_set.include?(class_name.to_s)
       end
 
+      # ADR-125 — the aggregate class names declared across loaded plugins as per-invocation (manifest
+      # `per_invocation_classes:`): each instance of a descendant serves exactly one public-method entry point.
+      # `per_invocation_class?` is the exact-name membership predicate; `def.ivar-write-mismatch` walks a
+      # class's ancestry and asks it of each ancestor.
+      attr_reader :per_invocation_classes
+
+      def per_invocation_class?(class_name)
+        return false if class_name.nil?
+
+        @per_invocation_classes_set.include?(class_name.to_s.delete_prefix("::"))
+      end
+
+      # ADR-125 — the macros whose arguments name a non-entry-point method on a descendant of the declared
+      # per-invocation class `class_name`: the union of `per_invocation_non_action_macros:` over the manifests
+      # that declare that class. An empty Set for a class no manifest declares.
+      def per_invocation_non_action_macros(class_name)
+        @per_invocation_macros.fetch(class_name.to_s.delete_prefix("::"), EMPTY_MACROS)
+      end
+
+      EMPTY_MACROS = Set.new.freeze
+      private_constant :EMPTY_MACROS
+
       # ADR-28 — flat, ordered list of every loaded plugin's path-scoped method-protocol contracts, in
       # plugin registration order. Read from each plugin's `#protocol_contracts` (which the manifest backs
       # by default but a plugin MAY override to fold in per-project config). Consumed by
@@ -465,12 +487,28 @@ module Rigor
         @rbs_complete_ancestors_set = @rbs_complete_ancestors.to_set.freeze
         @rbs_complete_extends = aggregate_class_names(manifests, :rbs_complete_extends)
         @rbs_complete_extends_set = @rbs_complete_extends.to_set.freeze
+        @per_invocation_classes = aggregate_class_names(manifests, :per_invocation_classes)
+        @per_invocation_classes_set = @per_invocation_classes.to_set.freeze
+        @per_invocation_macros = compile_per_invocation_macros(manifests)
         @type_node_resolvers = manifests.flat_map { |m| m&.type_node_resolvers || [] }.freeze
         @protocol_contracts = @plugins.flat_map { |p| safe_protocol_contracts(p) }.freeze
         @contracts_by_path = {}
         @effect_memo = {}
       end
 
+      # ADR-125 — declared class name => frozen Set of the non-action macros its declaring manifests list.
+      def compile_per_invocation_macros(manifests)
+        table = Hash.new { |hash, key| hash[key] = Set.new }
+        manifests.each do |manifest|
+          next if manifest.nil?
+
+          manifest.per_invocation_classes.each do |name|
+            table[name].merge(manifest.per_invocation_non_action_macros)
+          end
+        end
+        table.to_h { |name, macros| [name, macros.freeze] }.freeze
+      end
+
       # The shared shape of `open_receivers:` / `rbs_complete_ancestors:` — a flat uniq'd class-name list
       # aggregated across manifests, each entry normalised to String.
       def aggregate_class_names(manifests, field)
@@ -518,8 +556,8 @@ module Rigor
       # Issue #806 — {#safe_manifest} with a receipt. The construction-time aggregates degraded silently
       # when a manifest read raised, so a plugin that contributed nothing looked identical to a plugin that
       # was never asked; the load-error channel is where "a plugin could not be loaded" already lives, and
-      # `Analysis::Runner` turns each entry into one `plugin_loader.load-error` row naming the plugin. The
-      # plugin ref is the CLASS, not `manifest.id`: the manifest is the surface that just failed.
+      # `Analysis::Runner` turns each entry into one `load-error` row (source family `plugin_loader`) naming
+      # the plugin. The plugin ref is the CLASS, not `manifest.id`: the manifest is the surface that just failed.
       def guarded_manifest(plugin, errors)
         plugin.manifest
       rescue StandardError => e

data/lib/rigor/plugin/services.rb

@@ -25,9 +25,8 @@ module Rigor
     # documents the trust model the boundary enforces.
     #
     # ADR-9 slice 2 adds `fact_store`: the per-run cross-plugin `Plugin::FactStore`. Producer plugins publish
-    # their facts in `#prepare(services)` (slice 3); consumer plugins read in `#diagnostics_for_file` via
-    # `services.fact_store.read(...)`. A fresh `FactStore` instance is constructed per Services when none is
-    # supplied — the runner threads its own instance in once slice 3 wires `#prepare` invocation.
+    # their facts in `#prepare(services)`; consumer plugins read in `#diagnostics_for_file` via
+    # `services.fact_store.read(...)`. A fresh `FactStore` is constructed when none is supplied.
     class Services
       attr_reader :reflection, :type, :configuration, :cache_store, :trust_policy, :fact_store
 

data/lib/rigor/plugin/source_rbs_synthesis_reporter.rb

@@ -61,6 +61,17 @@ module Rigor
       def empty?
         @entries.empty?
       end
+
+      # The pool drain ({Rigor::Analysis::WorkerSession#drain_reporters}): the frozen entries.
+      def snapshot
+        entries
+      end
+
+      # Replays one worker's {#snapshot}, `kind:` (#824) and `line:` (#1075) included; the dedup above
+      # collapses every worker's copy. Nil records nothing.
+      def absorb(snapshot)
+        Array(snapshot).each { |entry| record(**entry.to_h) }
+      end
     end
   end
 end

data/lib/rigor/plugin/trust_policy.rb

@@ -19,8 +19,8 @@ module Rigor
     # - `trusted_gems`: gem names the user has authorised. Derived from the `plugins:` section of `.rigor.yml`
     #   plus any gems they reach transitively. Used today for documentation and future trust diagnostics.
     # - `allowed_read_roots`: absolute paths plugin code may read from through the {IoBoundary}. The default
-    #   set covers the project root, the project's `signature_paths`, the active `Gemfile.lock`, and each
-    #   trusted gem's `Gem::Specification#full_gem_path`. The user extends this with `.rigor.yml`'s
+    #   set covers the project root, the project's `signature_paths`, and each trusted
+    #   gem's `Gem::Specification#full_gem_path`. The user extends this with `.rigor.yml`'s
     #   `plugins_io.allowed_paths:`.
     # - `network_policy`: one of {VALID_NETWORK_POLICIES}. `:disabled` (default) makes
     #   {IoBoundary#open_url} always raise. `:allowlist` (v0.1.2) consults `allowed_url_hosts` on every fetch —