rigortype 0.3.8 → 0.3.9

data/lib/rigor/plugin/bundled_catalog.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# The plugin entry point rather than {Loader} directly: {Registry} closes over constants the package only
+# defines in `plugin.rb`'s order, so requiring a leaf of the package first leaves it half-built.
+require_relative "../plugin"
+require_relative "loader"
+
+module Rigor
+  module Plugin
+    # ADR-96 WD1/WD2 — the gem-to-plugin index behind the plugin-gap advisory: for every plugin the engine
+    # bundles, the gems its manifest declares in `target_gems:`.
+    #
+    # The index is read off the manifests, never listed here. ADR-96's finding was that the same knowledge
+    # sat in four hand-maintained copies (`rigor doctor`, `rigor skill describe`, the project-init prose
+    # table, `plugins/README.md`) and none of them was the plugin; a fifth copy in this file would reproduce
+    # exactly the drift the field exists to end.
+    #
+    # Building it requires each bundled plugin's entry file. That loads plugin *classes* — it never runs
+    # plugin analysis, which is ADR-96 Criterion 2's line: gem presence is evidence for advice, not for
+    # execution. The gem-to-id registrations the requires produce are recorded through
+    # {Rigor::Plugin.record_gem_registration}, so a {Loader} running afterwards in the same process still
+    # resolves a bare-string `plugins:` entry whose `require` now no-ops (ADR-88 WD4b).
+    module BundledCatalog
+      # 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")
+
+      @entries = nil
+      @load_failures = {}
+      @mutex = Mutex.new
+
+      class << self
+        # Every bundled plugin that declares at least one target gem, sorted by gem name. Memoised: the
+        # requires are process-wide and idempotent, and both callers ask once per command.
+        def entries
+          @mutex.synchronize { @entries ||= build_entries }
+        end
+
+        # The bundled plugins modelling `gem_name`, as `Gemfile.lock` spells it.
+        def for_gem(gem_name)
+          name = gem_name.to_s
+          entries.select { |entry| entry.target_gems.include?(name) }
+        end
+
+        # The bundled plugin gems whose entry file did not load this process, as `gem name => message`.
+        # Empty on a healthy process; a non-empty entry is why a bundled plugin is missing from {entries}.
+        def load_failures
+          entries
+          @mutex.synchronize { @load_failures.dup.freeze }
+        end
+
+        # Drops the memo. For specs that stub the engine root only.
+        #
+        # {load_failures} deliberately survives: `require` is idempotent, so a rebuild after a reset no
+        # longer reaches the file that raised and would report a clean process while the entry is still
+        # missing.
+        def reset!
+          @mutex.synchronize { @entries = nil }
+        end
+
+        private
+
+        # Bundledness is decided from the paths this module itself resolved and required, never by asking
+        # {FirstParty}: that predicate memoises a `File.file?` answer for the whole process, so one spec
+        # stubbing the engine root fixes every later answer in the suite — and the catalogue would then
+        # silently drop the plugins the advisory exists to name.
+        def build_entries
+          bundled = require_bundled_plugins
+          loaded_plugin_manifests.filter_map do |manifest|
+            gem_name = bundled[manifest.id]
+            next if gem_name.nil?
+            next if manifest.target_gems.empty?
+
+            Entry.new(gem_name: gem_name, plugin_id: manifest.id, target_gems: manifest.target_gems)
+          end.sort_by(&:gem_name).freeze
+        end
+
+        # The manifests of every plugin class the process has loaded, one per id. Read off the classes
+        # rather than {Rigor::Plugin.registered}: `require` is idempotent, so a plugin required earlier and
+        # then dropped by `Rigor::Plugin.unregister!` (every spec does this) is absent from the registry
+        # while still loaded, and an index built from the registry at that moment silently lacks it — the
+        # advisory then reads the project's own enabled plugin as a gap and fails `rigor doctor`.
+        #
+        # A plugin class whose source file sits under the bundled `plugins/` tree wins its id outright. The
+        # suite defines throwaway `Class.new(Rigor::Plugin::Base)` plugins that reuse a bundled id (a
+        # `stub_const`-ed fake `activerecord`, for one), and those carry no `target_gems:`; picking one of
+        # them for the id erased the real plugin from the index in whatever `ObjectSpace` order that
+        # process happened to have. An anonymous class is still consulted, but only for an id no bundled
+        # class claims.
+        def loaded_plugin_manifests
+          bundled = {}
+          other = {}
+          ObjectSpace.each_object(Class) do |klass|
+            next unless klass < Plugin::Base
+
+            manifest = manifest_of(klass)
+            next if manifest.nil?
+
+            (bundled_source?(klass) ? bundled : other)[manifest.id] ||= manifest
+          end
+          other.merge(bundled).values
+        end
+
+        def manifest_of(klass)
+          klass.manifest
+        rescue ArgumentError
+          nil
+        end
+
+        # Whether `klass` was defined by a file in the engine's own `plugins/` tree. An anonymous class
+        # answers false, and so does one whose constant a spec has since removed — which is exactly the
+        # shadowing case, since `stub_const` restores the name to nil at the end of the example.
+        def bundled_source?(klass)
+          name = klass.name
+          return false if name.nil?
+
+          location = Object.const_source_location(name)
+          return false if location.nil? || location.first.nil?
+
+          location.first.start_with?("#{BUNDLED_PLUGINS_ROOT}#{File::SEPARATOR}")
+        rescue NameError
+          false
+        end
+
+        # @return the gems whose entry file this call resolved, as `plugin id => gem name`.
+        def require_bundled_plugins
+          return {} unless File.directory?(BUNDLED_PLUGINS_ROOT)
+
+          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?
+
+            resolved[gem_name.delete_prefix(FirstParty::GEM_PREFIX)] = gem_name
+            require_and_record(gem_name, path)
+          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
+        # diagnosable instead of silently narrowing the index.
+        def require_and_record(gem_name, path)
+          before = Plugin.registered.keys
+          require path
+          newly_registered = Plugin.registered.keys - before
+          Plugin.record_gem_registration(gem_name, newly_registered) unless newly_registered.empty?
+        rescue ::LoadError, StandardError => e
+          @load_failures[gem_name] = "#{e.class}: #{e.message}"
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/effect_attribution.rb

@@ -77,15 +77,15 @@ module Rigor
       # callable whose body is supplied by the application.
       TAINT_CAUSES = %w[template-not-analysed opaque-callable].freeze
 
-      # @param receiver [String] a class name or a receiver path (see above)
-      # @param method [Symbol, String] the selector this row colours
-      # @param singleton [Boolean] whether the row is `Receiver.method` rather than `Receiver#method`.
+      # @param receiver — a class name or a receiver path (see above)
+      # @param method — the selector this row colours
+      # @param singleton — whether the row is `Receiver.method` rather than `Receiver#method`.
       #   Meaningless — and ignored — for a receiver path, whose head already fixes the receiver object.
-      # @param labels [Array<String>] the effect labels the call contributes
-      # @param narrow [String, nil] a {Rigor::Effects::Narrowing} handler name, when the call's own
+      # @param labels — the effect labels the call contributes
+      # @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 [Boolean] see above; honoured only for a first-party bundled plugin
-      # @param why [String] the audit justification, required exactly as `data/effects/core.yml` requires
+      # @param discharge — see above; honoured only for a first-party bundled plugin
+      # @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)

data/lib/rigor/plugin/effect_entry_points.rb

@@ -21,10 +21,10 @@ module Rigor
     class EffectEntryPoints
       attr_reader :name, :globs, :why
 
-      # @param name [String, Symbol] the token `reach:` adopts. Must satisfy
+      # @param name — the token `reach:` adopts. Must satisfy
       #   {Rigor::Effects::EntryPoints::NAME_PATTERN}, checked at registration.
-      # @param globs [Array<String>] project-relative path globs
-      # @param why [String] what the preset stands for, for the plugin's README and `rigor effects`' help
+      # @param globs — project-relative path globs
+      # @param why — what the preset stands for, for the plugin's README and `rigor effects`' help
       def initialize(name:, globs:, why: "")
         @name = name.to_s.dup.freeze
         @globs = Array(globs).map { |glob| glob.to_s.dup.freeze }.uniq.sort.freeze

data/lib/rigor/plugin/fact_store.rb

@@ -42,9 +42,9 @@ module Rigor
       # Writes a `(plugin_id, name) -> value` triple. Idempotent if the same value is published twice (`==`);
       # raises {Conflict} if the values differ.
       #
-      # @param plugin_id [String] producing plugin's manifest id.
-      # @param name [Symbol, String] fact name (canonicalised to Symbol for lookup).
-      # @param value [Object] frozen-shape value object the producer chose to publish. The value is stored
+      # @param plugin_id — producing plugin's manifest id.
+      # @param name — fact name (canonicalised to Symbol for lookup).
+      # @param value — frozen-shape value object the producer chose to publish. The value is stored
       #   as-is.
       def publish(plugin_id:, name:, value:)
         plugin_id = plugin_id.to_s
@@ -60,19 +60,19 @@ module Rigor
         nil
       end
 
-      # @return [Object, nil] the published value, or `nil` when no fact is registered. Reads do NOT establish
+      # @return the published value, or `nil` when no fact is registered. Reads do NOT establish
       #   a dependency — `manifest(consumes:)` (slice 4) is the dependency declaration mechanism.
       def read(plugin_id:, name:)
         fact = @mutex.synchronize { @facts[[plugin_id.to_s, name.to_sym]] }
         fact&.value
       end
 
-      # @return [Boolean] whether a fact is registered.
+      # @return whether a fact is registered.
       def published?(plugin_id:, name:)
         @mutex.synchronize { @facts.key?([plugin_id.to_s, name.to_sym]) }
       end
 
-      # @yield [Fact] every published fact in publication order.
+      # @yield every published fact in publication order.
       def each_fact(&)
         snapshot = @mutex.synchronize { @facts.values }
         snapshot.each(&)

data/lib/rigor/plugin/io_boundary.rb

@@ -27,6 +27,12 @@ module Rigor
     #   A plugin that gates its read or its glob on one of these shapes its result on the answer, so the
     #   answer is a dependency; probing through `File` directly leaves that dependency unrecorded and the
     #   warm run serves the pre-appearance result.
+    # - `#list_directory(path)` — the directory-LISTING fingerprint (ADR-45 WD1c, #629): returns the
+    #   directory's entry paths and records ONE {Cache::Descriptor::GlobEntry} for `path/*`, so any file
+    #   added to or removed from the directory (and any content edit under it) invalidates. It is the row
+    #   for a plugin that asks "which of these N candidate files exists here?" — rigor-actionpack tries
+    #   nine template extensions per `render` call — where N per-path probe rows would put thousands of
+    #   validations on every warm run and one listing row puts one per directory.
     # - `#open_url(url)` — fetches the URL when the policy permits it (`network_policy: :allowlist` plus an
     #   `allowed_url_hosts` match) and raises {AccessDeniedError} otherwise. v0.1.2 ships the allowlist
     #   surface; the default project policy still has `network_policy: :disabled` so plugins that want network
@@ -48,8 +54,32 @@ module Rigor
         @plugin_id = plugin_id.to_s.dup.freeze
         @file_entries = {}
         @config_entries = {}
+        @glob_entries = {}
         @http_client = http_client
         @mutex = Mutex.new
+        @refusal_count = 0
+        @first_refused_path = nil
+      end
+
+      # Issue #959 — `TrustPolicy#allow_read?` refuses a path purely by `File.expand_path` comparison
+      # (ADR-2's documented bound; no `File.realpath`), so a project rooted under a symlink (macOS'
+      # `/tmp` → `/private/tmp` alias is the common case) can have every plugin read refused with no
+      # visible cause: the boundary answered "not readable" and the plugin swallowed or surfaced only its
+      # own generic error. `#refusal_summary` is the accumulated record `Analysis::Runner::DiagnosticAggregator`
+      # reads once per run to surface ONE `:info` row per plugin that hit this, naming the count, the first
+      # refused path, and the read root it fell outside (so the message can suggest the fix: `cd "$(pwd -P)"`
+      # on a symlinked project root, or a `trust:` / `plugins_io.allowed_paths:` entry).
+      #
+      # @return `nil` when nothing was refused, else `{count:, first_path:, nearest_root:}` — `nearest_root`
+      #   is the policy's first configured read root (the project root in the common case), named as the
+      #   root a reader should compare the refused path against; it is a hint, not a claim that this
+      #   specific root is the nearest by path distance.
+      def refusal_summary
+        @mutex.synchronize do
+          return nil if @refusal_count.zero?
+
+          { count: @refusal_count, first_path: @first_refused_path, nearest_root: @policy.allowed_read_roots.first }
+        end
       end
 
       # Reads the file at `path` after validating it against the policy. Raises {AccessDeniedError} when the
@@ -68,6 +98,7 @@ module Rigor
       def read_file(path)
         absolute = File.expand_path(path.to_s)
         unless @policy.allow_read?(absolute)
+          record_refusal(absolute)
           raise AccessDeniedError.new(
             "plugin #{@plugin_id.inspect} cannot read #{absolute.inspect}: " \
             "path is outside the trusted-read scope",
@@ -93,8 +124,8 @@ module Rigor
       # `return nil unless File.file?(config)` gate: the miss shaped the result and left no edge for the
       # file's later appearance.
       #
-      # @param path [String] project path; relative paths expand against the working directory
-      # @return [Boolean] `File.file?`'s answer, unchanged
+      # @param path — project path; relative paths expand against the working directory
+      # @return `File.file?`'s answer, unchanged
       def file?(path)
         probe(path) { |absolute| File.file?(absolute) }
       end
@@ -103,12 +134,42 @@ module Rigor
       # existence row. The discovery shape (`next [] unless directory?(root)` before a `Dir.glob`) depends
       # on the root existing exactly as a config read depends on the config file existing.
       #
-      # @param path [String] project path; relative paths expand against the working directory
-      # @return [Boolean] `File.directory?`'s answer, unchanged
+      # @param path — project path; relative paths expand against the working directory
+      # @return `File.directory?`'s answer, unchanged
       def directory?(path)
         probe(path) { |absolute| File.directory?(absolute) }
       end
 
+      # ADR-45 WD1c (#629) — the directory-listing fingerprint. Returns the paths `path` currently holds
+      # (`[]` when it is not a directory), and records a single {Cache::Descriptor::GlobEntry} over
+      # `path/*` so the recorded dependency is the directory's whole listing rather than one row per
+      # name the caller went on to test. An addition, a removal, or an edit under the directory all move
+      # the glob signature; a caller that answered "no such file" from the listing therefore invalidates
+      # the moment the file appears.
+      #
+      # Why not N {#file?} probes: a caller like rigor-actionpack's template lookup tries an extension
+      # family per candidate, so per-path rows scale with (renders × extensions × view roots) — thousands
+      # of stat validations per warm run on a Rails-scale project — while the listing row scales with the
+      # number of directories actually consulted. The listing row is also the STRICTLY stronger dependency
+      # of the two: it covers names the caller never thought to probe.
+      #
+      # Recording, not the answer, is what the policy gates, exactly as in {#probe}: an out-of-scope
+      # directory is listed truthfully and contributes no row.
+      #
+      # @param path — project directory; relative paths expand against the working directory
+      # @return the absolute paths directly under `path` in `Dir.glob` order; empty when not a directory
+      def list_directory(path)
+        absolute = File.expand_path(path.to_s)
+        entries = Dir.glob(File.join(absolute, "*"))
+        unless @policy.allow_read?(absolute)
+          record_refusal(absolute)
+          return entries
+        end
+
+        record_glob_entry(absolute, "*")
+        entries
+      end
+
       # Fetches the URL when the policy permits it. Returns the response body. Raises {AccessDeniedError} when
       # the policy is `:disabled`, the URL scheme is not `https`, the host is not on the allowlist, the
       # response is non-2xx, the body exceeds {URL_MAX_BYTES}, or the request times out
@@ -131,12 +192,14 @@ module Rigor
         body
       end
 
-      # @return [Rigor::Cache::Descriptor] frozen snapshot of every file / URL the boundary has read so far.
+      # @return frozen snapshot of every file / URL the boundary has read so far.
       #   Calling this multiple times yields equal descriptors; subsequent reads expand the underlying record
       #   tables.
       def cache_descriptor
-        files, configs = @mutex.synchronize { [@file_entries.values.dup, @config_entries.values.dup] }
-        Cache::Descriptor.new(files: files, configs: configs)
+        files, configs, globs = @mutex.synchronize do
+          [@file_entries.values.dup, @config_entries.values.dup, @glob_entries.values.dup]
+        end
+        Cache::Descriptor.new(files: files, configs: configs, globs: globs)
       end
 
       private
@@ -161,7 +224,10 @@ module Rigor
       def probe(path)
         absolute = File.expand_path(path.to_s)
         answer = yield(absolute)
-        return answer unless @policy.allow_read?(absolute)
+        unless @policy.allow_read?(absolute)
+          record_refusal(absolute)
+          return answer
+        end
 
         if answer
           record_presence_entry(absolute)
@@ -209,6 +275,25 @@ module Rigor
         @mutex.synchronize { @file_entries[path] ||= entry }
       end
 
+      # ADR-45 WD1c (#629) — the listing row for {#list_directory}, deduplicated per (root, pattern) slot.
+      # Recomputed on each call rather than `||=`d, so a directory listed again after a mid-run mutation
+      # carries the signature of the state the LAST reader saw.
+      def record_glob_entry(root, pattern)
+        entry = Cache::Descriptor::GlobEntry.compute(root: root, pattern: pattern)
+        @mutex.synchronize { @glob_entries[entry.slot_key] = entry }
+      end
+
+      # Issue #959 — records that `path` fell outside every {TrustPolicy} read root, for {#refusal_summary}.
+      # Only the count and the FIRST path are kept (never the full list): the diagnostic reports one row per
+      # plugin regardless of how many paths it tried, so a plugin that walks a whole out-of-scope subtree
+      # costs one comparison per call here, not an unbounded accumulation.
+      def record_refusal(path)
+        @mutex.synchronize do
+          @refusal_count += 1
+          @first_refused_path ||= path
+        end
+      end
+
       def record_url_entry(url, body)
         digest = Digest::SHA256.hexdigest(body)
         key = "url:#{url}"

data/lib/rigor/plugin/isolation.rb

@@ -7,8 +7,8 @@ module Rigor
     # 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:
+    # (`.rigor.yml`'s `plugins_isolation:` key, or the `RIGOR_PLUGIN_ISOLATION` env, which wins over it —
+    # see {.strategy_name}). Three backends behind one interface:
     #
     # - `none` — load into the main space and call directly. Lowest cost; no isolation. Used as the fallback
     #   where fork is unavailable; fine because the invoked library is trusted + pure.
@@ -98,11 +98,34 @@ module Rigor
       # {#backend}).
       DEFAULT = "process"
 
-      # The configured strategy name (`RIGOR_PLUGIN_ISOLATION`), defaulting to {DEFAULT} for any unset /
-      # unrecognised value.
+      # The strategy the loaded {Rigor::Configuration} named (`plugins_isolation:`), or nil when the
+      # project named none. Handed over as a module ivar for the same reason {target_bundle_root} is: the
+      # invocation happens deep inside a plugin, several layers below anything holding the configuration.
+      def configured_strategy
+        @configured_strategy
+      end
+
+      # Frozen, like {target_bundle_root=}, so a Ractor-pool worker may read it (an unshareable value in a
+      # module ivar is a `Ractor::IsolationError` to read from a non-main Ractor, not only to write).
+      def configured_strategy=(name)
+        @configured_strategy = name.nil? ? nil : name.to_s.dup.freeze
+      end
+
+      # The strategy name in effect, defaulting to {DEFAULT} for any unset / unrecognised value.
+      #
+      # `RIGOR_PLUGIN_ISOLATION` WINS over the configuration (#911). The variable is the operator's
+      # one-invocation override — the thing you reach for when the fork worker misbehaves on this
+      # machine, or when a CI image cannot fork at all — and an override a committed file can veto is not
+      # an override. The config key is the project-wide default the override departs from. It is also the
+      # only ordering under which `ruby_box` works at all: `exe/rigor` re-execs on the variable alone.
       def strategy_name
-        name = ENV["RIGOR_PLUGIN_ISOLATION"].to_s
-        STRATEGIES.include?(name) ? name : DEFAULT
+        from_env = ENV["RIGOR_PLUGIN_ISOLATION"].to_s
+        return from_env if STRATEGIES.include?(from_env)
+
+        from_config = configured_strategy.to_s
+        return from_config if STRATEGIES.include?(from_config)
+
+        DEFAULT
       end
 
       # Invokes `receiver.method(*args)` on a target library, requiring `feature` first, under the configured

data/lib/rigor/plugin/loader.rb

@@ -43,12 +43,11 @@ module Rigor
       # the engine's own bundled plugin copies.
       ENGINE_ROOT = File.expand_path("../../..", __dir__)
 
-      # @param services [Rigor::Plugin::Services]
-      # @param requirer [#call] takes a gem name OR an absolute file path (#194 slice 2 — a bundled plugin is
+      # @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
       #   `Kernel.require` via a lambda, which accepts both forms; the spec injects a fake to avoid touching
       #   the real load path.
-      # @param feature_resolver [#call] takes a gem name and returns the absolute path `require` resolved it
+      # @param feature_resolver — takes a gem name and returns the absolute path `require` resolved it
       #   to (or nil). Defaulted to {FEATURE_RESOLVER}; the spec injects a fake so it never has to mutate the
       #   real `$LOADED_FEATURES` global.
       def initialize(services:, requirer: ->(name) { require name }, feature_resolver: FEATURE_RESOLVER)
@@ -90,8 +89,7 @@ module Rigor
         File.directory?(path) ? path : nil
       end
 
-      # @param entries [Array<String, Hash>] the raw `plugins:` list from the configuration.
-      # @return [Registry]
+      # @param entries — the raw `plugins:` list from the configuration.
       def load(entries)
         plugins = []
         load_errors = []
@@ -266,16 +264,37 @@ module Rigor
         when 1
           Plugin.registered_for(newly_registered.first)
         else
-          raise LoadError.new(
-            "plugin gem #{entry[:gem].inspect} bundles #{newly_registered.size} plugins " \
-            "(#{newly_registered.sort.inspect}) and cannot be activated as a single `plugins:` entry — " \
-            "it is a convenience meta-gem. List the individual plugin gems you want in `plugins:` " \
-            "(e.g. `rigor-#{newly_registered.min}`), or select one with an explicit `id:` field.",
-            plugin_ref: entry[:gem]
-          )
+          own = own_id_among(entry[:gem], newly_registered)
+          raise meta_gem_error(entry, newly_registered) unless own
+
+          Plugin.registered_for(own)
         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`.
+      #
+      # `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)
+        own = gem_name.to_s.delete_prefix(Plugin::FirstParty::GEM_PREFIX)
+        ids.find { |id| id == own }
+      end
+
+      def meta_gem_error(entry, newly_registered)
+        LoadError.new(
+          "plugin gem #{entry[:gem].inspect} bundles #{newly_registered.size} plugins " \
+          "(#{newly_registered.sort.inspect}) and cannot be activated as a single `plugins:` entry — " \
+          "it is a convenience meta-gem. List the individual plugin gems you want in `plugins:` " \
+          "(e.g. `rigor-#{newly_registered.min}`), or select one with an explicit `id:` field.",
+          plugin_ref: entry[:gem]
+        )
+      end
+
       def validate_config!(manifest, config)
         errors = manifest.validate_config(config)
         return if errors.empty?

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

@@ -152,7 +152,7 @@ module Rigor
         class ReturnsFromArg
           attr_reader :position, :plugin_id, :fact
 
-          # @return [ReturnsFromArg, nil] coerced value class for a Hash / nil / ReturnsFromArg input. Raises
+          # @return coerced value class for a Hash / nil / ReturnsFromArg input. Raises
           #   on any other shape so manifest authoring failures surface at construction time.
           def self.coerce(value)
             return nil if value.nil?

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

@@ -105,7 +105,7 @@ module Rigor
           to_h.hash
         end
 
-        # @return [String, nil] fully-qualified module name for the given trait symbol, or nil when the
+        # @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).
         def module_for(symbol)

data/lib/rigor/plugin/manifest.rb

@@ -42,6 +42,12 @@ module Rigor
       # {Rigor::Effects::Label} accepts as a root.
       VALID_EFFECT_ROOT = /\A[a-z][a-z0-9_]*\z/
 
+      # ADR-96 WD1 — the gems a plugin models, spelled exactly as `Gemfile.lock` names them. Not derivable
+      # from the plugin id (`rigor-factorybot` models `factory_bot`, `rigor-rspec` models `rspec-core`), which
+      # is what makes it a declared field; an empty list is the meaningful answer for a plugin that models no
+      # gem at all.
+      attr_reader :target_gems
+
       attr_reader :id, :version, :description, :config_schema, :config_defaults, :produces, :consumes,
                   :owns_receivers, :open_receivers, :type_node_resolvers, :block_as_methods,
                   :heredoc_templates, :nested_class_templates, :trait_registries,
@@ -52,7 +58,7 @@ module Rigor
 
       def initialize( # rubocop:disable Metrics/ParameterLists
         id:, version:,
-        description: nil, config_schema: {},
+        description: nil, config_schema: {}, target_gems: [],
         produces: [], consumes: [], owns_receivers: [], open_receivers: [], type_node_resolvers: [],
         block_as_methods: [], heredoc_templates: [], nested_class_templates: [],
         trait_registries: [],
@@ -65,6 +71,7 @@ module Rigor
         validate_version!(version)
         validate_config_schema!(config_schema)
         validate_produces!(produces)
+        validate_target_gems!(target_gems)
         validate_owns_receivers!(owns_receivers)
         validate_open_receivers!(open_receivers)
         validate_type_node_resolvers!(type_node_resolvers)
@@ -85,6 +92,7 @@ module Rigor
                       open_receivers, type_node_resolvers, block_as_methods, heredoc_templates, trait_registries,
                       hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
                       source_rbs_synthesizer)
+        assign_target_gems(target_gems)
         assign_nested_class_templates(nested_class_templates)
         assign_additional_initializers(additional_initializers)
         assign_effect_fields(effect_root, effect_labels, effect_attributions, effect_edges,
@@ -119,6 +127,12 @@ module Rigor
         @source_rbs_synthesizer = source_rbs_synthesizer
       end
 
+      # ADR-96 WD1 — assigned outside assign_fields, which already carries the maximum positional arity.
+      def assign_target_gems(target_gems)
+        @target_gems = target_gems.map { |g| g.to_s.dup.freeze }.uniq.freeze
+      end
+      private :assign_target_gems
+
       # 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)
@@ -189,6 +203,7 @@ module Rigor
           "description" => description,
           "config_schema" => config_schema.to_h { |k, v| [k, v.to_s] },
           "config_defaults" => config_defaults,
+          "target_gems" => target_gems,
           "produces" => produces.map(&:to_s),
           "consumes" => consumes.map { |c| consumption_hash(c) },
           "owns_receivers" => owns_receivers,
@@ -344,6 +359,13 @@ module Rigor
         raise ArgumentError, "plugin manifest #{field} must be an Array of #{label}, got #{value.inspect}"
       end
 
+      # ADR-96 WD1 — every entry is a gem name as `Gemfile.lock` spells it. The uniform Array-of-String check
+      # is all the manifest can do: whether the named gem exists is a fact about RubyGems, not about the
+      # manifest, and a typo surfaces as an advisory that never fires rather than as a load failure.
+      def validate_target_gems!(target_gems)
+        validate_array_of!("target_gems", target_gems, "non-empty String") { |g| g.is_a?(String) && !g.empty? }
+      end
+
       def validate_produces!(produces)
         validate_array_of!("produces", produces, "Symbol/String") { |p| p.is_a?(Symbol) || p.is_a?(String) }
       end