rigortype 0.3.9 → 0.4.0

data/lib/rigor/language_server/project_context.rb

@@ -12,12 +12,14 @@ module Rigor
     # Per-session cache of the project-wide analyzer state the LSP reads on every request — chiefly the
     # `Environment` (with its ~100-300ms RBS env build), a read-only `Cache::Store` that lets the runner hit
     # the on-disk RBS cache without writing back, and (since the pre-pass cache slice) a frozen
-    # {Rigor::Analysis::ProjectScan} snapshot covering the plugin registry, dependency-source index, and
-    # pre-pass scanner outputs.
+    # {Rigor::Analysis::ProjectScan} snapshot covering the plugin registry, dependency-source index,
+    # pre-pass scanner outputs and (since #1038) the compiled template-unit index.
     #
     # The pre-pass scan lets `DiagnosticPublisher#run_analysis` build a `Runner` with `prebuilt:` so per-buffer
     # publishes skip plugin `#prepare`, the synthetic-method scanner, the project-patched scanner, and the
-    # dependency-source walker. For projects with substrate plugins / opt-in dependency source / sizeable
+    # dependency-source walker — and, since #1038, the template-unit transform: a publish recompiles only a
+    # template that moved on disk since the scan was built (plus the buffer's own, always), rather than every
+    # view in the project. For projects with substrate plugins / opt-in dependency source / sizeable
     # `pre_eval:` configuration this cuts publish wall time substantially — for the trivial case the savings
     # are small (the per-publish path is already ≈2ms once Environment is warm).
     #

data/lib/rigor/mcp/server.rb

@@ -94,7 +94,7 @@ module Rigor
                 type: "string",
                 enum: %w[untyped observed],
                 description: "Parameter policy: untyped (default) or observed " \
-                             "(harvests call-site argument types from spec/)"
+                             "(harvests call-site argument types from the configured test_paths)"
               },
               config: { type: "string", description: "Path to .rigor.yml (optional)" }
             }
@@ -134,6 +134,7 @@ module Rigor
           }
         }
       ].freeze
+      Ractor.make_shareable(TOOLS)
 
       def initialize(config_path: nil, err: $stderr)
         @config_path = config_path

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 "../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.
 require_relative "../cache/store"
@@ -492,6 +493,10 @@ module Rigor
         @fact_cache = {}
         @producer_value_cache = {}
         @producer_errors = {}
+        # Issue #1051 — the run-scoped disclosure table ({#disclose_once}, and since #1060 {#emit_once}).
+        # Allocated here for the same reason as the three memos above: a registration is a Hash-content
+        # mutation, so it stays sound on a plugin that freezes itself in `initialize`.
+        @run_disclosures = {}
       end
 
       # Override in subclasses to wire any state the plugin needs from the injected service container.
@@ -545,6 +550,38 @@ module Rigor
         []
       end
 
+      # #392 — the **template-unit** transform: compile one non-Ruby project file into the Ruby the engine
+      # analyses (ADR-16 Tier D, revived; design note § 11.3). The engine globs the manifest's
+      # `template_globs:`, reads each match's bytes, and calls this once per match on the PARENT, before any
+      # analysis — so the transform runs exactly once per file per run and its result marshals into every
+      # fork-pool worker.
+      #
+      # Returns an `Array<Rigor::Plugin::TemplateUnit>`; an empty array declines the file, which is the
+      # right answer for a match the plugin's glob caught but its compiler cannot read. The default returns
+      # `[]`, so a plugin that declares no `template_globs:` is never asked and one that does may still
+      # decline per file.
+      #
+      # A raise isolates exactly like `#diagnostics_for_file`: the file contributes no unit and the run
+      # continues. The hook is the one place a template-unit plugin runs code — everything downstream is
+      # the frozen value object — which is what keeps the engine's analysis of a unit identical to its
+      # analysis of a `.rb` file.
+      def template_units_for_file(path:, source:) # rubocop:disable Lint/UnusedMethodArgument
+        []
+      end
+
+      # #1047 — called once at the start of every template-unit COLLECTION PASS over this plugin's claim,
+      # before any `#template_units_for_file` of that pass and whether or not the pass ends up calling it
+      # (a warm pass may carry every unit and compile none). A plugin whose transform reads state gathered
+      # ACROSS its claimed files — rigor-actionpack seeds a partial's locals from the render sites in every
+      # view — memoises that state on its instance, and a long-lived owner keeps the instance across
+      # passes; this is where such a plugin learns that the memo may now be stale. The collector's
+      # per-call order is not a substitute: a warm pass offers only the editor's buffer, so no sequence of
+      # paths can tell one pass from the next.
+      #
+      # The default does nothing. A raise is swallowed: the pass continues, and the plugin's own
+      # revalidation simply does not run for it.
+      def template_units_pass_started; end
+
       # ADR-37 slice 1 — runs the plugin's declared {.node_rule}s over one file and returns their
       # diagnostics. The engine owns the single AST walk here so plugin authors never hand-roll a traversal:
       # every node reachable from `root` is offered to each rule whose `node_type` it satisfies
@@ -619,6 +656,27 @@ module Rigor
         []
       end
 
+      # ADR-113 WD4 (#1082) — enumerates the members this plugin synthesizes on `class_name`, for the
+      # `rigor lens` declaration map. A `dynamic_return` rule answers a TYPE for one call site at a time;
+      # nothing on that path can say "`User` has `email`, `name`, …", which is the fact grep can never
+      # find on a DSL-generated member. This hook is that per-class enumeration.
+      #
+      # Returns an `Array` of `{name:, kind:, type:}` Hashes. `name` is the member name as a caller spells
+      # it (String); `kind` is a Symbol grouping same-shaped members (`:column_reader`) — the lens
+      # collapses a group into one line; `type` is the `Rigor::Type` the plugin commits to for the member
+      # itself, or nil where it does not commit to one. It is the member-level answer, not the best a
+      # typed call site can do: a plugin that narrows `user.name` to `String` on a written receiver but
+      # declines to type the bare `name` read reports `Dynamic[top]` here. A member the plugin claims
+      # but deliberately leaves dynamic carries `Rigor::Type::Combinator.untyped` — the explicit
+      # `Dynamic[top]` answer, distinct from nil's "no answer".
+      #
+      # The hook is off the `check` hot path (ADR-52): `rigor lens` invokes it, `check` never does. It may
+      # read state `#prepare` built. The default returns `[]` — a plugin that synthesizes no enumerable
+      # members has nothing to declare.
+      def declared_members(class_name) # rubocop:disable Lint/UnusedMethodArgument
+        []
+      end
+
       # Builds a `Rigor::Analysis::Diagnostic` positioned at a Prism `node` for return from
       # `#diagnostics_for_file`. Internalises the 1-based `line` / `start_column + 1` convention every plugin
       # otherwise re-derives by hand, so authors pass the node and the message/severity/rule rather than
@@ -686,12 +744,108 @@ module Rigor
       end
 
       # ADR-60 WD4 — the `StandardError` a prior {#producer_value} call rescued for `id`, or nil when it
-      # succeeded or was never called. Plugins surface it as a load-error diagnostic from
-      # `#diagnostics_for_file`.
+      # succeeded or was never called. Plugins surface it as a run-scoped `load-error` disclosure through
+      # {#disclose_once} (#1056) — a failed index is a fact about the run's inputs, not about a file.
       def producer_error(id)
         @producer_errors[id.to_sym]
       end
 
+      # Issue #1051 — records a PROJECT-GLOBAL disclosure: a notice about the run's inputs ("the schema file
+      # is not there, so column checks are off") rather than about a line of a file. Registering the same
+      # `key` again — on this instance or on any other instance of this plugin in the same run — is a no-op,
+      # so the run emits the row exactly once however many workers, files or call sites reached it.
+      #
+      #     disclose_once(:missing_schema,
+      #                   message: "rigor-activerecord: schema file `db/schema.rb` not found; …",
+      #                   severity: :info, rule: "load-error")
+      #
+      # Callable from any hook — `#prepare` (the usual place: the disclosure is a fact about the project,
+      # known before a single file is read), `#diagnostics_for_file`, or a `node_rule` block. It returns
+      # `nil` and emits NOTHING itself: the engine harvests the table after analysis, de-duplicates it by
+      # `(plugin id, key)` across the coordinator and every pool worker, and emits one row per surviving
+      # pair at `.rigor.yml:1:1` — the position every other run-level plugin row already uses (plugin load
+      # errors, `#prepare` raises, `plugin_trust.read-refused`).
+      #
+      # That position is the point of the facility. The pre-#1051 idiom was an `@emitted` flag consulted from
+      # `#diagnostics_for_file`, which positions the row at whichever file the plugin instance happened to
+      # see first — per WORKER under `--workers N`, so the row was duplicated, and after #393 the file it
+      # landed on could be a template unit's `.erb` path, reading as a claim about a view. A disclosure has
+      # no source position to be right about; `.rigor.yml` is where the user configured the input it is
+      # about.
+      #
+      # `severity:` defaults to `:info`, the grade plugins use for "here is what I recognised"; pass
+      # `:warning` for "I could not run". `key` is any object with a stable `#to_s` (a Symbol reads best) and
+      # is never shown to the user — it is the de-duplication identity, so it must not interpolate anything
+      # 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
+        nil
+      end
+
+      # Issue #1060 — the POSITIONED sibling of {#disclose_once}: registers a whole batch of fully built
+      # diagnostics under `key`, emitted once per run however many plugin instances (fork-pool workers)
+      # register it. Each row keeps its own `path` / `line` / `column` — use this when a project-wide scan
+      # produces rows that are right about a position (a view template's line) but no single analysed file
+      # owns them, so returning them from `#diagnostics_for_file` would repeat them once per worker.
+      #
+      #     emit_once(:view_diagnostics, scan_view_files(index))
+      #
+      # The question that chooses between the two channels is whether the row has a position it could be
+      # right about: a notice about the run's inputs has none and goes through {#disclose_once}
+      # (`.rigor.yml:1:1`); a row naming a real file and line comes here and keeps it.
+      #
+      # De-duplication is by `key` alone and the first registration wins: a later batch under the same key
+      # is dropped whole, on this instance or on any other instance in the run, never merged row by row.
+      # Every worker scans the same project, so a row-wise union could only add a worker's partial or
+      # divergent view. `key` shares one namespace per plugin with {#disclose_once} — the two channels are
+      # one registration table — but a key keeps the kind it was first registered as: repeating a key on the
+      # same channel is a no-op, and reusing it on the OTHER channel (either order) raises `ArgumentError`
+      # rather than silently dropping a genuine batch or disclosure.
+      #
+      # Callable from `#prepare`, `#diagnostics_for_file`, or a `node_rule` block; returns `nil` and emits
+      # nothing itself. The engine stamps `source_family: "plugin.<id>"` exactly as it does for a per-file
+      # row, so the qualified rule and the position a baseline keys on are the ones `#diagnostics_for_file`
+      # would have produced. Each row is copied and frozen on registration so the batch rides the fork
+      # payload and the Ractor `:done` message unchanged; a non-{Rigor::Analysis::Diagnostic} element
+      # 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)
+
+          raise ArgumentError, "emit_once expects Rigor::Analysis::Diagnostic rows, got #{row.class}"
+        end
+        @run_disclosures[id] = { key: id, diagnostics: batch.freeze }.freeze
+        nil
+      end
+
+      # Engine-facing reader for {#disclose_once} and {#emit_once}: this instance's registrations in
+      # registration order; a positioned batch is the record carrying `:diagnostics`. Plugin authors never
+      # call it — {Rigor::Analysis::Runner} and {Rigor::Analysis::WorkerSession} drain it, and the
+      # de-duplication across instances happens there.
+      def run_disclosure_records
+        @run_disclosures.values
+      end
+
+      # #1060 — true when `id` is already registered on the same channel (the repeat is a no-op); raises when
+      # it is registered on the other one, because either answer there would drop a genuine registration.
+      def run_registration_taken?(id, batch:)
+        existing = @run_disclosures[id]
+        return false if existing.nil?
+        return true if existing.key?(:diagnostics) == batch
+
+        taken = batch ? "a #disclose_once disclosure" : "an #emit_once batch"
+        raise ArgumentError, "run-scoped key #{id.inspect} is already registered as #{taken}; use a distinct key"
+      end
+      private :run_registration_taken?
+
       # 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
@@ -705,7 +859,6 @@ module Rigor
         DidYouMean::SpellChecker.new(dictionary: dictionary).correct(name.to_s).first
       end
 
-      # Convenience accessor — `manifest` on the instance returns the class-level manifest declaration.
       def manifest
         self.class.manifest
       end
@@ -808,7 +961,12 @@ module Rigor
         return compute unless store
 
         prefixed_id = "plugin.#{manifest.id}.#{producer_id}"
-        key_descriptor = compose_key_descriptor(descriptor)
+        begin
+          key_descriptor = compose_key_descriptor(descriptor)
+        rescue Cache::EngineSource::Unavailable
+          # An unidentifiable engine runs the producer uncached rather than keyed without it (issue #1009).
+          return compute
+        end
         lambda do
           store.fetch_or_validate(
             producer_id: prefixed_id,
@@ -1026,8 +1184,13 @@ module Rigor
       # plugin-author-supplied extension carrying IDENTITY inputs (gem-version pins, `ConfigEntry` rows,
       # configuration-file digests). The IoBoundary read history deliberately does NOT enter the key — it is
       # recorded post-compute into the dependency descriptor instead (see {#producer_dependency_descriptor}).
+      #
+      # Issue #1009 — the engine's source identity rides in the auto-built half. The manifest version is the
+      # plugin author's promise, and a checkout editing a bundled plugin (or the engine API a producer computes
+      # through) keeps it, so without the identity the next session served the previous build's value into a
+      # run the run-result key had correctly re-analysed.
       def compose_key_descriptor(extra)
-        auto_built = Cache::Descriptor.new(plugins: [plugin_entry])
+        auto_built = Cache::Descriptor.new(plugins: [plugin_entry], configs: Cache::EngineSource.key_config_entries)
         return auto_built if extra.nil?
 
         Cache::Descriptor.compose(auto_built, extra)

data/lib/rigor/plugin/box_probe.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Rigor
+  module Plugin
+    # Decides, before `exe/rigor` re-execs itself under `RUBY_BOX=1`, whether the running Ruby can host
+    # Rigor inside `Ruby::Box` at all. A released Ruby up to and including 4.0.7 cannot: `env_copy()` drops
+    # the box a class/module-body proc carries when `Ractor.make_shareable` isolates it, so the first
+    # method call inside such a proc dereferences a NULL box and the VM segfaults (Ruby Bug #22260, fixed on
+    # CRuby master by `a4ad8e461a`). Rigor defines Ractor-shareable lambdas at module scope as a standing
+    # pattern, so on an affected Ruby the `ruby_box` strategy crashes the whole run rather than declining.
+    #
+    # The check is behavioural, not a version comparison: a child Ruby runs the bug's minimal reproducer
+    # under `RUBY_BOX=1` and must print the right answer. That admits a 4.1.0dev build with the fix and a
+    # future 4.0.x that backports it, and refuses a development build cut before the fix — none of which a
+    # `RUBY_VERSION` bound gets right. The probe costs one short-lived `ruby --disable-gems` process, paid
+    # only when a run opts into `ruby_box`.
+    #
+    # Loaded by `exe/rigor` before anything else, so this file requires nothing from Rigor.
+    module BoxProbe
+      # A class-body lambda isolated by `Ractor.make_shareable`, then a method dispatch inside it — the
+      # four ingredients the crash needs. Exits 2 when `Ruby::Box` is not active (a Ruby without the
+      # feature ignores `RUBY_BOX=1`), so a missing feature is told apart from a crash.
+      SCRIPT = <<~PROBE
+        exit 2 unless defined?(Ruby::Box) && Ruby::Box.respond_to?(:enabled?) && Ruby::Box.enabled?
+        module RigorBoxProbe
+          RATIONAL = Ractor.make_shareable(lambda { |*args| Rational(*args) })
+        end
+        print RigorBoxProbe::RATIONAL.call(3, 4).inspect
+      PROBE
+
+      EXPECTED_OUTPUT = "(3/4)"
+
+      # The reproducer answers in well under a second; a child still running after this is killed and
+      # counted as a failure, so a wedged probe cannot hang the launcher (or `rigor lsp` behind it).
+      DEADLINE_SECONDS = 10
+
+      module_function
+
+      # nil when `ruby` can run Rigor under `RUBY_BOX=1`; otherwise a short reason for the launcher's
+      # warning. Only a child killed by a signal is blamed on the bug; any other failure to answer is
+      # reported as the probe failing, never as a pass.
+      def unsupported_reason(ruby = RbConfig.ruby)
+        output, status = run(ruby)
+        return "the Ruby::Box probe could not run #{ruby}" if status.nil?
+        return nil if status.success? && output == EXPECTED_OUTPUT
+        return "Ruby::Box is not available in Ruby #{RUBY_VERSION}" if status.exitstatus == 2
+        return "the Ruby::Box probe failed (#{status})" unless status.signaled?
+
+        "Ruby #{RUBY_VERSION} crashes running Ractor-shareable procs inside Ruby::Box " \
+          "(Ruby Bug #22260; a Ruby carrying its fix is needed)"
+      end
+
+      # `RUBYOPT` is cleared so a `-r` of the caller's (bootsnap, a debugger, a coverage hook) cannot fail
+      # to load under `--disable-gems` and be mistaken for the crash; the probe needs nothing but core.
+      def run(ruby)
+        reader, writer = IO.pipe
+        pid = ::Process.spawn({ "RUBY_BOX" => "1", "RUBYOPT" => nil }, ruby, "--disable-gems", "-e", SCRIPT,
+                              in: File::NULL, out: writer, err: File::NULL)
+        writer.close
+        output = read_until_eof(reader)
+        return [output, ::Process.wait2(pid).last] if output
+
+        ::Process.kill(:KILL, pid)
+        ::Process.wait(pid)
+        [nil, nil]
+      rescue ::SystemCallError
+        [nil, nil]
+      ensure
+        writer&.close unless writer&.closed?
+        reader&.close
+      end
+
+      # The child's whole stdout, or nil when it has not closed it by the deadline.
+      def read_until_eof(reader)
+        deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + DEADLINE_SECONDS
+        output = +""
+        loop do
+          remaining = deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+          return nil unless remaining.positive? && reader.wait_readable(remaining)
+
+          chunk = reader.read_nonblock(4096, exception: false)
+          return output if chunk.nil?
+
+          output << chunk if chunk.is_a?(String)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/bundled_catalog.rb

@@ -24,7 +24,7 @@ module Rigor
       # One bundled plugin: the gem name a `plugins:` entry spells, and the gems it models.
       Entry = Data.define(:gem_name, :plugin_id, :target_gems)
 
-      BUNDLED_PLUGINS_ROOT = File.join(Loader::ENGINE_ROOT, "plugins")
+      BUNDLED_PLUGINS_ROOT = File.join(Loader::ENGINE_ROOT, "plugins").freeze
 
       @entries = nil
       @load_failures = {}

data/lib/rigor/plugin/effect_attribution.rb

@@ -69,7 +69,7 @@ module Rigor
       SELF_HEAD = "self"
 
       attr_reader :receiver, :method, :singleton, :labels, :narrow, :discharge, :within, :on_result,
-                  :taint, :why
+                  :taint, :callee, :callee_fallbacks, :responds, :why
 
       # The taint causes a plugin row may name. A closed subset of
       # {Rigor::Effects::TaintCause::ALL}: a plugin may say "and there is more here I cannot see", but
@@ -85,13 +85,31 @@ module Rigor
       # @param narrow — a {Rigor::Effects::Narrowing} handler name, when the call's own
       #   argument literals settle a question the row cannot (`connection.execute("SELECT …")`)
       # @param discharge — see above; honoured only for a first-party bundled plugin
+      # @param callee — the name of a {Rigor::Effects::CalleeRule} rule, when a call to this
+      #   method is also a call **graph edge** the syntax does not contain: `render :show` runs
+      #   `app/views/users/show.html.erb`, which is an effect unit of its own (#393 / #1048). The rule
+      #   reads the call's own argument literals and names the callee key; the engine owns the strategy,
+      #   exactly as it does for `narrow:`.
+      # @param callee_fallbacks — the framework's lookup ORDER for a callee the rule named, as data (#1065):
+      #   `{ "js" => ["html"] }` says a callee selector of `js` that no unit answers is retried as `html`
+      #   before the row's `taint:` is seeded. Keys and values are selectors; each list is tried in order
+      #   and the first that resolves wins. Meaningless — and refused — without `callee:`. Which rule
+      #   consults it, and for which targets, is the rule's call rather than the row's: a table a plugin
+      #   writes cannot know whether a format was inherited or written by the author.
+      # @param responds — whether a call to this method supplies the unit's answer, so a
+      #   {Rigor::Effects::CalleeRule::UNIT_RULES} rule on the same receiver must not also apply. `render`,
+      #   `redirect_to` and `head` each set it: an action that called one of them did not take Rails'
+      #   implicit render, and edging it to the conventional template would attribute a view the action
+      #   never rendered.
       # @param why — the audit justification, required exactly as `data/effects/core.yml` requires
       #   one of every row: a label with no stated reason is a claim nobody can review.
       def initialize(receiver:, method:, labels:, why:, singleton: false, narrow: nil, discharge: false, # rubocop:disable Metrics/ParameterLists
-                     within: nil, on_result: false, taint: nil)
+                     within: nil, on_result: false, taint: nil, callee: nil, callee_fallbacks: nil, responds: false)
         @receiver = validate_receiver!(receiver)
         @method = method.to_sym
         @singleton = singleton ? true : false
+        @callee = callee.nil? ? nil : callee.to_s.dup.freeze
+        @responds = responds ? true : false
         @labels = normalize_labels(labels)
         @narrow = narrow.nil? ? nil : narrow.to_s.dup.freeze
         @discharge = discharge ? true : false
@@ -99,6 +117,7 @@ module Rigor
         @on_result = on_result ? true : false
         validate_on_result!
         @taint = validate_taint!(taint)
+        @callee_fallbacks = validate_callee_fallbacks!(callee_fallbacks)
         @why = validate_why!(why)
         freeze
       end
@@ -125,7 +144,8 @@ module Rigor
         {
           "receiver" => @receiver, "method" => @method.to_s, "singleton" => @singleton,
           "labels" => @labels, "narrow" => @narrow, "discharge" => @discharge, "within" => @within,
-          "on_result" => @on_result, "taint" => @taint
+          "on_result" => @on_result, "taint" => @taint, "callee" => @callee,
+          "callee_fallbacks" => @callee_fallbacks, "responds" => @responds
         }
       end
 
@@ -166,9 +186,16 @@ module Rigor
         value.dup.freeze
       end
 
+      # A row normally has to say something. The one exception is a row whose whole contribution is a
+      # `callee:` EDGE — Rails' implicit render is a fact about an action that made no call at all, so
+      # there is no site to colour and no label to state; what the row buys is the edge to the template.
+      # Reading the edge and inventing a label beside it would put `rails.response.write` on every private
+      # helper a controller happens to define.
       def normalize_labels(labels)
         list = Array(labels).map { |label| label.to_s.dup.freeze }
-        raise ArgumentError, "effect attribution for #{@receiver} must declare at least one label" if list.empty?
+        if list.empty? && @callee.nil?
+          raise ArgumentError, "effect attribution for #{@receiver} must declare at least one label"
+        end
 
         list.uniq.sort.freeze
       end
@@ -197,6 +224,33 @@ module Rigor
               "got #{taint.inspect}"
       end
 
+      # A selector is one dot-free, space-free segment — the half of a callee key after the receiver
+      # (`html` in `view:users/show.html`). Anything else could never be spliced into a key a unit answers,
+      # and a fallback that silently resolved nothing would read to its author as the feature being broken.
+      FALLBACK_SELECTOR = /\A[a-z0-9_]+\z/
+      private_constant :FALLBACK_SELECTOR
+
+      def validate_callee_fallbacks!(fallbacks)
+        return nil if fallbacks.nil?
+        raise ArgumentError, "effect attribution #{key} names `callee_fallbacks:` without a `callee:`" if @callee.nil?
+        raise ArgumentError, "effect attribution #{key} `callee_fallbacks:` must be a Hash" unless fallbacks.is_a?(Hash)
+
+        fallbacks.to_h do |from, to|
+          list = Array(to).map { |selector| fallback_selector!(selector) }.uniq
+          selector = fallback_selector!(from)
+          list.delete(selector)
+          [selector, list.freeze]
+        end.sort.to_h.freeze
+      end
+
+      def fallback_selector!(selector)
+        value = selector.to_s
+        return value.dup.freeze if FALLBACK_SELECTOR.match?(value)
+
+        raise ArgumentError, "effect attribution #{key} `callee_fallbacks:` selector must be one lowercase " \
+                             "segment, got #{selector.inspect}"
+      end
+
       def validate_why!(why)
         value = why.to_s
         raise ArgumentError, "effect attribution #{key} needs a `why:` justification" if value.empty?

data/lib/rigor/plugin/loader.rb

@@ -35,13 +35,14 @@ module Rigor
         suffix = "/#{gem_name}.rb"
         $LOADED_FEATURES.rfind { |feature| feature.end_with?(suffix) }
       end
+      Ractor.make_shareable(FEATURE_RESOLVER)
 
       # #194 slice 2 (ADR-93 WD5) — the engine's own root, anchored from THIS file's location: the loader
       # lives at `<root>/lib/rigor/plugin/loader.rb`, so three levels up is the engine root. It resolves
       # identically in a git checkout and inside an installed `rigortype` gem, because the gem packages the
       # `plugins/` tree at the same relative path — which is exactly what makes it a trustworthy anchor for
       # the engine's own bundled plugin copies.
-      ENGINE_ROOT = File.expand_path("../../..", __dir__)
+      ENGINE_ROOT = File.expand_path("../../..", __dir__).freeze
 
       # @param requirer — takes a gem name OR an absolute file path (#194 slice 2 — a bundled plugin is
       #   required by its {.bundled_plugin_path}) and returns truthy on successful require. Defaulted to

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

@@ -36,9 +36,14 @@ module Rigor
       # - `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.
+      # - `self_type` — the `self`-binding the substrate applies inside the block. `:receiver_instance`
+      #   (the default) types `self` as an instance of the receiver class — the Sinatra contract. A String
+      #   binds `self` to a *named* class instead of the receiver: `"Grape::Endpoint"` binds
+      #   `Nominal[Grape::Endpoint]` (the block is `instance_eval`'d on an instance of that class, e.g. a
+      #   route body on `Grape::Endpoint`), and `"singleton(Grape::API::Instance)"` binds
+      #   `Singleton[Grape::API::Instance]` (the block is `instance_eval`'d on that *class object*, e.g.
+      #   a `namespace` body on `Grape::API::Instance`). Reserved Symbol names (`:receiver_singleton`,
+      #   `:dsl_recorder`) remain unaccepted.
       #
       # ## Ractor-shareability
       #
@@ -48,6 +53,13 @@ module Rigor
         SELF_TYPE_RECEIVER_INSTANCE = :receiver_instance
         VALID_SELF_TYPES = [SELF_TYPE_RECEIVER_INSTANCE].freeze
 
+        CLASS_NAME_PATTERN = /[A-Z]\w*(?:::[A-Z]\w*)*/
+        # `self_type: "Foo::Bar"` — the block is `instance_eval`'d on an instance of `Foo::Bar`.
+        NAMED_SELF_TYPE_PATTERN = /\A#{CLASS_NAME_PATTERN}\z/
+        # `self_type: "singleton(Foo::Bar)"` — the block is `instance_eval`'d on the `Foo::Bar` class
+        # object itself (Grape's `namespace`/`route_param` bodies run on `Grape::API::Instance`).
+        SINGLETON_SELF_TYPE_PATTERN = /\Asingleton\((#{CLASS_NAME_PATTERN})\)\z/
+
         attr_reader :receiver_constraint, :method_names, :self_type
 
         def initialize(receiver_constraint:, method_names:, self_type: SELF_TYPE_RECEIVER_INSTANCE)
@@ -57,7 +69,7 @@ module Rigor
 
           @receiver_constraint = receiver_constraint.dup.freeze
           @method_names = method_names.map(&:to_sym).freeze
-          @self_type = self_type
+          @self_type = self_type.is_a?(String) ? self_type.dup.freeze : self_type
           freeze
         end
 
@@ -81,6 +93,31 @@ module Rigor
           [receiver_constraint, method_names, self_type].hash
         end
 
+        # The class name a String `self_type` binds `self` to — `"Foo::Bar"` for both the plain and the
+        # `singleton(Foo::Bar)` form — or `nil` for `:receiver_instance`.
+        def self_type_name
+          return nil unless self_type.is_a?(String)
+
+          self_type[SINGLETON_SELF_TYPE_PATTERN, 1] || self_type
+        end
+
+        # Whether a String `self_type` binds the *class object* (`"singleton(Foo::Bar)"`) rather than an
+        # instance (`"Foo::Bar"`). Nominal-receiver call sites only match instance-binding entries —
+        # a `singleton(...)` binding exists solely for `instance_eval`-on-class contracts, which always
+        # surface as `Singleton[X]` receivers.
+        def singleton_binding?
+          self_type.is_a?(String) && self_type.match?(SINGLETON_SELF_TYPE_PATTERN)
+        end
+
+        # Whether `self_type` names a class whose *instance* the block is `instance_eval`'d on
+        # (`"Foo::Bar"`). These entries are the only ones that also match `Nominal[Y]` receivers: inside
+        # an already-narrowed `instance_eval` body (`self : Nominal[ParamsScope]`), a nested call on
+        # `self` re-enters the same context. `:receiver_instance` keeps its original Singleton-only
+        # contract — a nominal receiver calling a class-level verb is a different (unmodelled) shape.
+        def named_instance_binding?
+          self_type.is_a?(String) && !singleton_binding?
+        end
+
         private
 
         def validate_receiver_constraint!(value)
@@ -108,10 +145,12 @@ module Rigor
 
         def validate_self_type!(self_type)
           return if VALID_SELF_TYPES.include?(self_type)
+          return if self_type.is_a?(String) &&
+                    (self_type.match?(NAMED_SELF_TYPE_PATTERN) || self_type.match?(SINGLETON_SELF_TYPE_PATTERN))
 
           raise ArgumentError,
-                "Plugin::Macro::BlockAsMethod#self_type must be one of #{VALID_SELF_TYPES.inspect}, " \
-                "got #{self_type.inspect}"
+                "Plugin::Macro::BlockAsMethod#self_type must be one of #{VALID_SELF_TYPES.inspect} " \
+                "or a class-name String ('Foo::Bar' / 'singleton(Foo::Bar)'), got #{self_type.inspect}"
         end
       end
     end