rigortype 0.1.14 → 0.1.16

data/lib/rigor/plugin/isolation.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+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
+    # before re-exec). Three backends behind one interface:
+    #
+    # - `none` (**default**) — load into the main space and call directly.
+    #   Lowest cost; no isolation. Fine for the common case 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` — 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.
+    module Isolation
+      class Unavailable < StandardError
+      end
+
+      STRATEGIES = %w[none ruby_box process].freeze
+
+      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}).
+      DEFAULT = "process"
+
+      # 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}.
+      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.
+      def backend
+        case strategy_name
+        when "ruby_box" then RubyBox
+        when "none" then Direct
+        else Process.available? ? Process : Direct
+        end
+      end
+
+      # `none` — load the trusted library into the main space and call it
+      # directly. No isolation; lowest cost; the current default behaviour.
+      module Direct
+        module_function
+
+        def call(feature:, receiver:, method:, args:)
+          require feature
+          Object.const_get(receiver).public_send(method, *args)
+        rescue LoadError, NameError => e
+          raise Unavailable, "#{receiver} could not be loaded (#{e.class}: #{e.message})"
+        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
+      # input.
+      module RubyBox
+        module_function
+
+        def call(feature:, receiver:, method:, args:)
+          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")`
+          # — no free input reaches the box's eval.
+          rendered = args.map(&:inspect).join(", ")
+          expression = "#{receiver}.#{method}(#{rendered})"
+          Box.eval(expression)
+        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
+      # persistent worker handles all calls over a Marshal pipe pair.
+      module Process
+        module_function
+
+        # Whether fork-based isolation can run on this platform.
+        def available?
+          ::Process.respond_to?(:fork)
+        end
+
+        def call(feature:, receiver:, method:, args:)
+          raise Unavailable, "process isolation unavailable: fork is not supported" unless available?
+
+          status, value = exchange([feature, receiver, method, args])
+          raise Unavailable, "process isolation worker error: #{value}" if status == :error
+
+          value
+        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.
+          @worker = nil
+          raise Unavailable, "process isolation worker failed (#{e.class})"
+        end
+
+        # Sends one request to the persistent worker and reads its reply.
+        def exchange(request)
+          w = worker
+          Marshal.dump(request, w[:req])
+          w[:req].flush
+          Marshal.load(w[:res]) # rubocop:disable Security/MarshalLoad -- worker output, not untrusted input
+        end
+
+        def worker
+          @worker ||= spawn_worker
+        end
+
+        def spawn_worker
+          req_r, req_w = IO.pipe
+          res_r, res_w = IO.pipe
+          pid = fork_worker(req_r, req_w, res_r, res_w)
+          req_r.close
+          res_w.close
+          { pid: pid, req: req_w, res: res_r }
+        end
+
+        def fork_worker(req_r, req_w, res_r, res_w)
+          ::Process.fork do
+            req_w.close
+            res_r.close
+            run_worker_loop(req_r, res_w)
+          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.
+        def run_worker_loop(req_r, res_w)
+          loop do
+            feature, receiver, method, args = Marshal.load(req_r) # rubocop:disable Security/MarshalLoad -- parent input
+            reply =
+              begin
+                require feature
+                [:ok, Object.const_get(receiver).public_send(method, *args)]
+              rescue StandardError, LoadError => e
+                [:error, "#{e.class}: #{e.message}"]
+              end
+            Marshal.dump(reply, res_w)
+            res_w.flush
+          end
+        rescue EOFError
+          # parent closed the request pipe — exit quietly
+        ensure
+          exit!(0)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # Motivating shape — Mangrove's `Enum`:
+      #
+      #     class Shape
+      #       extend Mangrove::Enum
+      #       variants do
+      #         variant Circle, Float
+      #         variant Rectangle, Float
+      #       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]`.
+      #
+      # ## Authoring shape
+      #
+      #     nested_class_templates: [
+      #       Rigor::Plugin::Macro::NestedClassTemplate.new(
+      #         receiver_constraint: "Mangrove::Enum", # `extend`-ed marker module
+      #         block_method: :variants,               # the enclosing DSL block
+      #         variant_method: :variant,              # each declaration call
+      #         name_arg_position: 0,                  # constant arg → nested class
+      #         inner_arg_position: 1,                 # type arg → `#inner` return
+      #         inner_reader: :inner                   # the payload reader name
+      #       )
+      #     ]
+      #
+      # ## 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`).
+      # - `name_arg_position` — Integer (default 0): the argument
+      #   index whose literal **constant** names the nested subclass.
+      # - `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`.
+      class NestedClassTemplate
+        attr_reader :receiver_constraint, :block_method, :variant_method,
+                    :name_arg_position, :inner_arg_position, :inner_reader
+
+        def initialize(receiver_constraint:, block_method: :variants, variant_method: :variant,
+                       name_arg_position: 0, inner_arg_position: 1, inner_reader: :inner)
+          validate_constraint!(receiver_constraint)
+          validate_method!(block_method, "block_method")
+          validate_method!(variant_method, "variant_method")
+          validate_position!(name_arg_position, "name_arg_position")
+          validate_position!(inner_arg_position, "inner_arg_position")
+          validate_method!(inner_reader, "inner_reader")
+
+          @receiver_constraint = receiver_constraint.dup.freeze
+          @block_method = block_method.to_sym
+          @variant_method = variant_method.to_sym
+          @name_arg_position = name_arg_position
+          @inner_arg_position = inner_arg_position
+          @inner_reader = inner_reader.to_sym
+          freeze
+        end
+
+        def to_h
+          {
+            "receiver_constraint" => receiver_constraint,
+            "block_method" => block_method.to_s,
+            "variant_method" => variant_method.to_s,
+            "name_arg_position" => name_arg_position,
+            "inner_arg_position" => inner_arg_position,
+            "inner_reader" => inner_reader.to_s
+          }
+        end
+
+        def ==(other)
+          other.is_a?(NestedClassTemplate) && to_h == other.to_h
+        end
+        alias eql? ==
+
+        def hash
+          to_h.hash
+        end
+
+        private
+
+        def validate_constraint!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::NestedClassTemplate#receiver_constraint must be a non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_method!(value, label)
+          return if value.is_a?(Symbol) || (value.is_a?(String) && !value.empty?)
+
+          raise ArgumentError,
+                "Plugin::Macro::NestedClassTemplate##{label} must be a Symbol or non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_position!(value, label)
+          return if value.is_a?(Integer) && value >= 0
+
+          raise ArgumentError,
+                "Plugin::Macro::NestedClassTemplate##{label} must be a non-negative Integer, " \
+                "got #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/macro.rb

@@ -3,6 +3,7 @@
 require_relative "macro/block_as_method"
 require_relative "macro/external_file"
 require_relative "macro/heredoc_template"
+require_relative "macro/nested_class_template"
 require_relative "macro/trait_registry"
 
 module Rigor

data/lib/rigor/plugin/manifest.rb

@@ -2,6 +2,7 @@
 
 require_relative "../inference/hkt_registry"
 require_relative "protocol_contract"
+require_relative "additional_initializer"
 
 module Rigor
   module Plugin
@@ -40,22 +41,23 @@ module Rigor
         end
       end
 
-      attr_reader :id, :version, :description, :protocols, :config_schema, :produces, :consumes,
+      attr_reader :id, :version, :description, :config_schema, :config_defaults, :produces, :consumes,
                   :owns_receivers, :open_receivers, :type_node_resolvers, :block_as_methods,
-                  :heredoc_templates, :trait_registries, :external_files, :hkt_registrations,
-                  :hkt_definitions, :signature_paths, :protocol_contracts, :source_rbs_synthesizer
+                  :heredoc_templates, :nested_class_templates, :trait_registries, :external_files,
+                  :hkt_registrations, :hkt_definitions, :signature_paths, :protocol_contracts,
+                  :source_rbs_synthesizer, :additional_initializers
 
       def initialize( # rubocop:disable Metrics/ParameterLists
         id:, version:,
-        description: nil, protocols: [], config_schema: {},
+        description: nil, config_schema: {},
         produces: [], consumes: [], owns_receivers: [], open_receivers: [], type_node_resolvers: [],
-        block_as_methods: [], heredoc_templates: [], trait_registries: [], external_files: [],
+        block_as_methods: [], heredoc_templates: [], nested_class_templates: [],
+        trait_registries: [], external_files: [],
         hkt_registrations: [], hkt_definitions: [], signature_paths: [], protocol_contracts: [],
-        source_rbs_synthesizer: nil
+        source_rbs_synthesizer: nil, additional_initializers: []
       )
         validate_id!(id)
         validate_version!(version)
-        validate_protocols!(protocols)
         validate_config_schema!(config_schema)
         validate_produces!(produces)
         validate_owns_receivers!(owns_receivers)
@@ -63,6 +65,7 @@ module Rigor
         validate_type_node_resolvers!(type_node_resolvers)
         validate_block_as_methods!(block_as_methods)
         validate_heredoc_templates!(heredoc_templates)
+        validate_nested_class_templates!(nested_class_templates)
         validate_trait_registries!(trait_registries)
         validate_external_files!(external_files)
         validate_hkt_registrations!(hkt_registrations)
@@ -70,26 +73,29 @@ module Rigor
         validate_signature_paths!(signature_paths)
         validate_protocol_contracts!(protocol_contracts)
         validate_source_rbs_synthesizer!(source_rbs_synthesizer)
+        validate_additional_initializers!(additional_initializers)
 
-        assign_fields(id, version, description, protocols, config_schema, produces, consumes, owns_receivers,
+        assign_fields(id, version, description, config_schema, produces, consumes, owns_receivers,
                       open_receivers, type_node_resolvers, block_as_methods, heredoc_templates, trait_registries,
                       external_files, hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
                       source_rbs_synthesizer)
+        assign_nested_class_templates(nested_class_templates)
+        assign_additional_initializers(additional_initializers)
         freeze
       end
 
       private
 
       # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize
-      def assign_fields(id, version, description, protocols, config_schema, produces, consumes, owns_receivers,
+      def assign_fields(id, version, description, config_schema, produces, consumes, owns_receivers,
                         open_receivers, type_node_resolvers, block_as_methods, heredoc_templates, trait_registries,
                         external_files, hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
                         source_rbs_synthesizer)
         @id = id.dup.freeze
         @version = version.dup.freeze
         @description = description.nil? ? nil : description.to_s.dup.freeze
-        @protocols = protocols.map(&:to_sym).freeze
-        @config_schema = config_schema.to_h { |k, v| [k.to_s.dup.freeze, v.to_sym] }.freeze
+        @config_schema = config_schema.to_h { |k, v| [k.to_s.dup.freeze, schema_kind(v)] }.freeze
+        @config_defaults = extract_config_defaults(config_schema)
         @produces = produces.map(&:to_sym).freeze
         @consumes = coerce_consumes(consumes)
         @owns_receivers = owns_receivers.map { |c| c.to_s.dup.freeze }.freeze
@@ -105,6 +111,22 @@ module Rigor
         @protocol_contracts = protocol_contracts.dup.freeze
         @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.
+      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.
+      def assign_additional_initializers(additional_initializers)
+        @additional_initializers = additional_initializers.dup.freeze
+      end
+      private :assign_additional_initializers
       # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
 
       public
@@ -137,8 +159,8 @@ module Rigor
           "id" => id,
           "version" => version,
           "description" => description,
-          "protocols" => protocols.map(&:to_s),
           "config_schema" => config_schema.to_h { |k, v| [k, v.to_s] },
+          "config_defaults" => config_defaults,
           "produces" => produces.map(&:to_s),
           "consumes" => consumes.map { |c| consumption_hash(c) },
           "owns_receivers" => owns_receivers,
@@ -146,13 +168,15 @@ module Rigor
           "type_node_resolvers" => type_node_resolvers.map { |r| r.class.name },
           "block_as_methods" => block_as_methods.map(&:to_h),
           "heredoc_templates" => heredoc_templates.map(&:to_h),
+          "nested_class_templates" => nested_class_templates.map(&:to_h),
           "trait_registries" => trait_registries.map(&:to_h),
           "external_files" => external_files.map(&:to_h),
           "hkt_registrations" => hkt_registrations.map(&:to_h),
           "hkt_definitions" => hkt_definitions.map { |d| { "uri" => d.uri, "params" => d.params } },
           "signature_paths" => signature_paths,
           "protocol_contracts" => protocol_contracts.map(&:to_h),
-          "source_rbs_synthesizer" => source_rbs_synthesizer&.class&.name
+          "source_rbs_synthesizer" => source_rbs_synthesizer&.class&.name,
+          "additional_initializers" => additional_initializers.map(&:to_h)
         }
       end
 
@@ -180,27 +204,70 @@ module Rigor
         raise ArgumentError, "plugin manifest version must be a non-empty String, got #{version.inspect}"
       end
 
-      def validate_protocols!(protocols)
-        return if protocols.is_a?(Array) && protocols.all? { |p| p.is_a?(Symbol) || p.is_a?(String) }
-
-        raise ArgumentError, "plugin manifest protocols must be an Array of Symbol/String, got #{protocols.inspect}"
-      end
-
       def validate_config_schema!(schema)
         unless schema.is_a?(Hash)
           raise ArgumentError,
                 "plugin manifest config_schema must be a Hash, got #{schema.inspect}"
         end
 
-        schema.each_value do |kind|
-          next if VALID_VALUE_KINDS.include?(kind.to_sym)
+        schema.each do |key, value|
+          kind = schema_kind(value)
+          unless VALID_VALUE_KINDS.include?(kind)
+            raise ArgumentError,
+                  "plugin manifest config_schema value kind must be one of " \
+                  "#{VALID_VALUE_KINDS.inspect}, got #{value.inspect}"
+          end
+
+          next unless schema_default?(value)
+
+          default = schema_default(value)
+          next if value_matches?(default, kind)
+
+          raise ArgumentError,
+                "plugin manifest config_schema default for #{key.to_s.inspect} expected " \
+                "#{kind}, got #{default.class}"
+        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.
+      def schema_kind(value)
+        if value.is_a?(Hash)
+          kind = value[:kind] || value["kind"]
+          if kind.nil?
+            raise ArgumentError,
+                  "plugin manifest config_schema entry Hash must declare :kind, got #{value.inspect}"
+          end
 
+          kind.to_sym
+        elsif value.is_a?(Symbol) || value.is_a?(String)
+          value.to_sym
+        else
           raise ArgumentError,
-                "plugin manifest config_schema value kind must be one of " \
-                "#{VALID_VALUE_KINDS.inspect}, got #{kind.inspect}"
+                "plugin manifest config_schema value must be a kind Symbol/String or a " \
+                "{kind:, default:} Hash, got #{value.inspect}"
         end
       end
 
+      def schema_default?(value)
+        value.is_a?(Hash) && (value.key?(:default) || value.key?("default"))
+      end
+
+      def schema_default(value)
+        value.key?(:default) ? value[:default] : value["default"]
+      end
+
+      def extract_config_defaults(schema)
+        schema.each_with_object({}) do |(key, value), acc|
+          acc[key.to_s.dup.freeze] = value_default_frozen(schema_default(value)) if schema_default?(value)
+        end.freeze
+      end
+
+      def value_default_frozen(default)
+        default.frozen? ? default : default.dup.freeze
+      end
+
       def value_matches?(value, kind)
         case kind
         when :string then value.is_a?(String)
@@ -294,6 +361,20 @@ module Rigor
               "Rigor::Plugin::Macro::HeredocTemplate instances, got #{entries.inspect}"
       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.
+      def validate_nested_class_templates!(entries)
+        return if entries.is_a?(Array) && entries.all?(Macro::NestedClassTemplate)
+
+        raise ArgumentError,
+              "plugin manifest nested_class_templates must be an Array of " \
+              "Rigor::Plugin::Macro::NestedClassTemplate instances, got #{entries.inspect}"
+      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
@@ -395,6 +476,22 @@ module Rigor
               "Rigor::Plugin::ProtocolContract instances, got #{entries.inspect}"
       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.
+      def validate_additional_initializers!(entries)
+        return if entries.is_a?(Array) && entries.all?(AdditionalInitializer)
+
+        raise ArgumentError,
+              "plugin manifest additional_initializers must be an Array of " \
+              "Rigor::Plugin::AdditionalInitializer instances, got #{entries.inspect}"
+      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

data/lib/rigor/plugin/node_context.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Plugin
+    # ADR-37 slice 1d — the lexical context of a node, handed to a
+    # {Base.node_rule} block as its fifth argument. Realises the
+    # `ContextInfo` ADR-2 § "Scope Object" promised: the enclosing
+    # class / module, method, and block-DSL nesting that a per-node rule
+    # needs but that `Scope` (value/type facts) does not carry.
+    #
+    # The engine builds one per matching node from the descent stack
+    # (snapshotted, so it is safe to retain). Rules read the bits they
+    # need:
+    #
+    #   node_rule Prism::CallNode do |node, _scope, path, _fc, context|
+    #     action = context.enclosing_def&.name           # rails-i18n
+    #     model  = context.enclosing_block(:describe)     # shoulda
+    #     …
+    #   end
+    #
+    # `ancestors` is the full chain, outermost first, EXCLUDING the node
+    # itself — the general primitive; the accessors below are
+    # conveniences derived from it.
+    class NodeContext
+      EMPTY = nil # sentinel documented for readers; rules get a real instance
+
+      attr_reader :ancestors
+
+      def initialize(ancestors)
+        @ancestors = ancestors.dup.freeze
+        freeze
+      end
+
+      # The innermost enclosing `Prism::DefNode`, or nil. Its `#name`
+      # is the method the node sits in (rails-i18n uses it to expand a
+      # lazy `t('.key')` against the controller action).
+      def enclosing_def
+        ancestors.rfind { |n| n.is_a?(Prism::DefNode) }
+      end
+
+      # The innermost enclosing `Prism::ClassNode` / `Prism::ModuleNode`,
+      # or nil (actionpack uses it to resolve the controller a
+      # `before_action` / `render` sits in).
+      def enclosing_module
+        ancestors.rfind { |n| n.is_a?(Prism::ClassNode) || n.is_a?(Prism::ModuleNode) }
+      end
+
+      # The innermost enclosing `Prism::CallNode` that carries a block
+      # and whose method name is `method_name` — e.g. the
+      # `RSpec.describe(Model) do … end` a shoulda matcher sits in.
+      # Returns the CallNode (so the caller can read its arguments /
+      # receiver), or nil.
+      def enclosing_block(method_name)
+        ancestors.rfind do |n|
+          n.is_a?(Prism::CallNode) && n.block && n.name == method_name
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/registry.rb

@@ -143,6 +143,16 @@ module Rigor
         plugins.flat_map(&:protocol_contracts)
       end
 
+      # ADR-38 — flat, ordered list of every loaded plugin's
+      # manifest-declared `Rigor::Plugin::AdditionalInitializer`
+      # entries. `Inference::ScopeIndexer` consults the set at its
+      # read-before-write nil soundness gate: a `def` whose name an
+      # entry covers, on a class that equals or inherits from the
+      # entry's `receiver_constraint`, is treated like `initialize`.
+      def additional_initializers
+        plugins.flat_map { |plugin| plugin.manifest.additional_initializers }
+      end
+
       # ADR-28 — the subset of `protocol_contracts` whose
       # `path_glob` matches `path`. Contract globs are authored
       # project-root-relative (`lib/controller/**/*.rb`); the

data/lib/rigor/plugin.rb

@@ -11,6 +11,9 @@ require_relative "plugin/services"
 require_relative "plugin/base"
 require_relative "plugin/registry"
 require_relative "plugin/load_error"
+require_relative "plugin/box"
+require_relative "plugin/isolation"
+require_relative "plugin/inflector"
 
 module Rigor
   module Plugin