rigortype 0.3.3 → 0.3.4

data/lib/rigor/plugin/effect_attribution.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # One row of a plugin's `effect_attributions:` — "a call to this receiver's method contributes these
+    # effect labels" (ADR-103 WD6 / WD10; design note § 6.6; the contract is
+    # `docs/internal-spec/plugin.md` § Effect contributions).
+    #
+    # A framework method has no body Rigor reads, so someone must colour it. Three channels can, in
+    # descending order of preference:
+    #
+    # 1. a `%a{rigor:v1:effect …}` annotation in the plugin's own `signature_paths:` RBS — tier 1, read
+    #    through {Rigor::Effects::EnvelopeIndex}'s accepted stratum, and the right channel whenever the
+    #    plugin already ships a signature for the method;
+    # 2. this field, for the methods RBS cannot name per app — association readers, `find_by_*`, scopes —
+    #    and for classes the plugin ships no RBS for at all;
+    # 3. the project's own `effects.attribution:` table, which is the user's answer for everything left.
+    #
+    # ## The receiver
+    #
+    # `receiver` is spelled one of two ways, and the spelling picks the matching rule:
+    #
+    # - a **class name** (`"ActiveRecord::Base"`, `"I18n"`) matches the class the call's receiver
+    #   projects to, **through the project's inheritance chain**: an `ActiveRecord::Base` row applies to
+    #   `User.find` because the project declares `User < ApplicationRecord < ActiveRecord::Base`. This is
+    #   the difference from a catalogue row, which matches its exact owner and nothing else — Ruby's core
+    #   classes are leaves in practice and a framework's base class never is.
+    # - a **receiver path** (`"Rails.cache"`, `"Time.zone"`, `"Rails.application.credentials"`) matches
+    #   the receiver *expression* as the syntax spells it. `Rails.cache.read` has no receiver class the
+    #   typer can name — `Rails.cache` is a call, and its return type is adapter-dependent by design —
+    #   so the only honest handle on it is the path that was written.
+    # - a **self path** (`"self.session"`, `"self.flash.now"`, `"self.cookies.encrypted"`) is the same
+    #   thing rooted at implicit self, and is what a Rails controller's accessors actually look like:
+    #   `session[:user_id] = id` is `[]=` on the result of a receiver-less `session`. A self-path row MUST
+    #   name a `within:` class, because a receiver-less `session` in some other project class is a
+    #   different `session` — the row applies only inside a class whose project ancestry reaches `within`.
+    #
+    # `on_result: true` shifts a class-name row one link outwards: it matches a call on **what a call to
+    # that class returned**. `UserMailer.welcome(u).deliver_now` and `WelcomeJob.set(wait: 1.hour)
+    # .perform_later` are the two idioms that need it — the object in the middle is a lazy
+    # `MessageDelivery` / `ConfiguredJob` whose type nothing in the project declares, while the class that
+    # produced it is written right there in the source. Without it the send and the enqueue, the two calls
+    # a reviewer most wants coloured, would go unattributed in the spelling Rails actually uses.
+    #
+    # ## Discharge
+    #
+    # `discharge: true` says the label is derived from the framework's own semantics rather than guessed,
+    # so the site is exhaustive rather than tainted. ADR-103 WD6 grants that only to a **first-party
+    # bundled** plugin ({FirstParty}), gated by `make check-plugins`; a third-party plugin's `true` is
+    # ignored with a load-time warning and the row behaves like the project's `effects.attribution:`
+    # table — declared, and carrying a `plugin-attribution` taint.
+    #
+    # Either way the labels land in the **declared** lane, never the proven one. A discharging row is a
+    # trusted claim, exactly like an accepted signature's `%a{…}`: "this is what it does", not "the
+    # analyzer read the body and saw this".
+    class EffectAttribution
+      # A receiver spelled as a `Constant::Path` — the class-name form. Anything else with a `.` in it is
+      # read as a receiver path.
+      CLASS_NAME = /\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/
+
+      # A receiver path: a constant head followed by one or more sends (`Rails.cache`,
+      # `Rails.application.credentials`).
+      RECEIVER_PATH = /\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*(\.[a-z_][A-Za-z0-9_]*)+\z/
+
+      # A self path: implicit self followed by one or more receiver-less sends (`self.flash.now`).
+      SELF_PATH = /\Aself(\.[a-z_][A-Za-z0-9_]*)+\z/
+
+      # What a self path is rooted at, once the `self.` head is stripped.
+      SELF_HEAD = "self"
+
+      attr_reader :receiver, :method, :singleton, :labels, :narrow, :discharge, :within, :on_result,
+                  :taint, :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
+      # only for the two reasons a framework model can honestly have — a template it does not read, and a
+      # 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`.
+      #   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
+      #   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
+      #   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)
+        @receiver = validate_receiver!(receiver)
+        @method = method.to_sym
+        @singleton = singleton ? true : false
+        @labels = normalize_labels(labels)
+        @narrow = narrow.nil? ? nil : narrow.to_s.dup.freeze
+        @discharge = discharge ? true : false
+        @within = validate_within!(within)
+        @on_result = on_result ? true : false
+        validate_on_result!
+        @taint = validate_taint!(taint)
+        @why = validate_why!(why)
+        freeze
+      end
+
+      # Whether {#receiver} is a receiver path (`Rails.cache`) rather than a class name or a self path.
+      def receiver_path?
+        @receiver.include?(".") && !self_path?
+      end
+
+      # Whether {#receiver} is a self path (`self.flash.now`).
+      def self_path?
+        @receiver.start_with?("#{SELF_HEAD}.")
+      end
+
+      # The key an origin and a report spell this row as.
+      def key
+        return "#{@receiver}.#{@method}" if receiver_path? || self_path?
+        return "#{@receiver}()##{@method}" if @on_result
+
+        "#{@receiver}#{@singleton ? '.' : '#'}#{@method}"
+      end
+
+      def to_h
+        {
+          "receiver" => @receiver, "method" => @method.to_s, "singleton" => @singleton,
+          "labels" => @labels, "narrow" => @narrow, "discharge" => @discharge, "within" => @within,
+          "on_result" => @on_result, "taint" => @taint
+        }
+      end
+
+      def ==(other)
+        other.is_a?(EffectAttribution) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_receiver!(receiver)
+        value = receiver.to_s
+        unless CLASS_NAME.match?(value) || RECEIVER_PATH.match?(value) || SELF_PATH.match?(value)
+          raise ArgumentError,
+                "effect attribution receiver must be a class name, a receiver path or a self path, " \
+                "got #{receiver.inspect}"
+        end
+
+        value.dup.freeze
+      end
+
+      # A self path with no `within:` would colour a receiver-less `session` in any project class at all.
+      def validate_within!(within)
+        if within.nil?
+          raise ArgumentError, "effect attribution #{key} is a self path and must name a `within:` class" if self_path?
+
+          return nil
+        end
+
+        value = within.to_s
+        raise ArgumentError, "effect attribution `within:` must be a class name, got #{within.inspect}" unless
+          CLASS_NAME.match?(value)
+
+        value.dup.freeze
+      end
+
+      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?
+
+        list.uniq.sort.freeze
+      end
+
+      # `on_result:` shifts the match one link outwards, which only a class-name row can do: a receiver
+      # path already names the object, and a self path already names the frame.
+      def validate_on_result!
+        return unless @on_result
+        return unless receiver_path? || self_path?
+
+        raise ArgumentError, "effect attribution #{key} may not combine `on_result:` with a path receiver"
+      end
+
+      # A row may state a bound AND say the bound is not the whole story. `render` is the case that needs
+      # it: what the controller does IS `mutate.self` + `rails.response.write`, and what the TEMPLATE does
+      # is unknown until views become effect units (ADR-103 WD11). Reporting only the first would be a
+      # summary that reads exhaustive and is not.
+      def validate_taint!(taint)
+        return nil if taint.nil?
+
+        value = taint.to_s
+        return value.dup.freeze if TAINT_CAUSES.include?(value)
+
+        raise ArgumentError,
+              "effect attribution #{key} may only taint with one of #{TAINT_CAUSES.inspect}, " \
+              "got #{taint.inspect}"
+      end
+
+      def validate_why!(why)
+        value = why.to_s
+        raise ArgumentError, "effect attribution #{key} needs a `why:` justification" if value.empty?
+
+        value.dup.freeze
+      end
+    end
+  end
+end

data/lib/rigor/plugin/effect_edge.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # One entry of a plugin's `effect_edges:` — a call graph edge the *syntax* does not contain but the
+    # framework does (ADR-103 WD10; design note § 11.2 "Framework edges").
+    #
+    # `save` runs the class body's `before_save :normalize` and its validators; `Job.perform_now` runs
+    # `Job#perform`; `UserMailer.welcome(u)` runs `UserMailer#welcome`. None of those is a call the
+    # analyzer can see, and all three are ordinary synchronous in-process control flow — so a plugin that
+    # models the framework contributes **edges**, not only labels.
+    #
+    # What a plugin must NOT contribute is the deferred half: `perform_later` never edges to `perform`,
+    # because the body runs in another process on another stack and the caller's code does not contain it
+    # (ADR-103 WD4, "attribution follows the code, not the clock"). The enum below has no spelling for it,
+    # which is the enforcement.
+    #
+    # ## Why a fixed enum rather than a callback
+    #
+    # A plugin supplies **parameters**; the engine owns the strategy. A block would have to run inside the
+    # per-file effect scan — the one place ADR-103 WD13 forbids anything that resolves, walks or types —
+    # and would not survive the fork-pool / Ractor boundary the collection window crosses. The enum keeps
+    # the plugin's contribution declarative, Marshal-clean and reviewable, and keeps every walk on the
+    # engine's side of the contract.
+    #
+    # ## The strategies
+    #
+    # - `:activerecord_callbacks` — `receiver:` is the ActiveRecord base class. On every project class
+    #   whose ancestry reaches it, the engine reads the class body's callback and validation macros
+    #   (`before_save :sym`, `validate :sym`, `after_commit :sym`, …) and synthesises the persistence
+    #   selectors (`save`, `create!`, `destroy`, `valid?`, …) as effect units edged to those methods.
+    #   `validates … uniqueness: true` additionally contributes an `io.db.read` origin, because the
+    #   uniqueness check IS a query.
+    # - `:perform_now` — `receiver:` is the job base class. `Job.perform_now(…)` on a project subclass
+    #   reaches `Job#perform`.
+    # - `:mailer_body` — `receiver:` is the mailer base class. `UserMailer.welcome(u)` on a project
+    #   subclass reaches `UserMailer#welcome`, the class-method-to-instance mapping ActionMailer performs
+    #   at run time.
+    #
+    # `method:` and `singleton:` are carried for a future strategy that keys on one selector; the three
+    # above read only `receiver:`.
+    class EffectEdge
+      # Every strategy the engine implements. A `target:` outside this set is a manifest error, so a
+      # plugin cannot silently declare an edge nothing honours.
+      TARGETS = %i[activerecord_callbacks perform_now mailer_body].freeze
+
+      attr_reader :receiver, :method, :singleton, :target, :why
+
+      def initialize(receiver:, target:, why:, method: nil, singleton: false)
+        @receiver = validate_receiver!(receiver)
+        @target = validate_target!(target)
+        @method = method&.to_sym
+        @singleton = singleton ? true : false
+        @why = validate_why!(why)
+        freeze
+      end
+
+      def to_h
+        {
+          "receiver" => @receiver, "method" => @method&.to_s, "singleton" => @singleton,
+          "target" => @target.to_s
+        }
+      end
+
+      def ==(other)
+        other.is_a?(EffectEdge) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_receiver!(receiver)
+        value = receiver.to_s
+        unless EffectAttribution::CLASS_NAME.match?(value)
+          raise ArgumentError, "effect edge receiver must be a class name, got #{receiver.inspect}"
+        end
+
+        value.dup.freeze
+      end
+
+      def validate_target!(target)
+        value = target.to_sym
+        return value if TARGETS.include?(value)
+
+        raise ArgumentError,
+              "effect edge target must be one of #{TARGETS.inspect}, got #{target.inspect}"
+      end
+
+      def validate_why!(why)
+        value = why.to_s
+        raise ArgumentError, "effect edge #{@receiver} -> #{@target} needs a `why:` justification" if value.empty?
+
+        value.dup.freeze
+      end
+    end
+  end
+end

data/lib/rigor/plugin/effect_entry_points.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # One entry of a plugin's `effect_entry_points:` — a **named** set of globs that
+    # `effects.snapshot.reach:` may adopt by name (ADR-103 WD14).
+    #
+    # `reach:` is "whose transitive footprint does the snapshot record", and the honest answer for a Rails
+    # app — controller actions, `perform`, mailer methods, channel methods — is a fact about the framework
+    # rather than about the project. So the framework's plugin names it and the project adopts it:
+    #
+    #     effects:
+    #       snapshot:
+    #         reach: [rails]
+    #
+    # A preset is a **glob** set, matched against the project-relative file a method is defined in, with
+    # the `rigor unused --entry-point` semantics {Rigor::Effects::EntryPoints} already implements. Globs
+    # rather than a class-ancestry filter, deliberately: `reach:` is resolved from the snapshot's own
+    # method table, which carries a defining path per key and no ancestry — and a Rails app's layout IS
+    # the ancestry, which is why the convention exists at all.
+    class EffectEntryPoints
+      attr_reader :name, :globs, :why
+
+      # @param name [String, Symbol] 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
+      def initialize(name:, globs:, why: "")
+        @name = name.to_s.dup.freeze
+        @globs = Array(globs).map { |glob| glob.to_s.dup.freeze }.uniq.sort.freeze
+        raise ArgumentError, "effect entry-point preset #{@name.inspect} declares no globs" if @globs.empty?
+
+        @why = why.to_s.dup.freeze
+        freeze
+      end
+
+      def to_h
+        { "name" => @name, "globs" => @globs }
+      end
+
+      def ==(other)
+        other.is_a?(EffectEntryPoints) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+  end
+end

data/lib/rigor/plugin/first_party.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # Which plugin ids the engine itself ships (ADR-103 WD6).
+    #
+    # WD6's trust ladder grants two things to a **first-party bundled** plugin and to nothing else: it may
+    # open the effect-label root of the framework it models rather than one named after itself
+    # (`rails.*`, not `activerecord.*`), and its `effect_attributions:` may carry `discharge: true`. Both
+    # rest on the same fact — a bundled plugin's framework knowledge is versioned with the engine, reviewed
+    # in this repository, and gated by `make check-plugins`, which is exactly the standing a gem's shipped
+    # RBS has.
+    #
+    # The answer is **derived, never listed**: a plugin is first-party when the engine bundles the gem that
+    # would register it, which is the same question {Loader.bundled_plugin_path} already answers when it
+    # decides whether to require a plugin by its engine-anchored path or by gem name. Every bundled plugin
+    # id equals its gem name minus the `rigor-` prefix (pinned by spec), so the id is enough to ask. A list
+    # would be a second source of truth to keep in sync with `plugins/`, and the first drift would silently
+    # demote a plugin's rows to the tainted lane.
+    #
+    # This is a trust *ladder*, not a sandbox. ADR-2 settles that plugins are trusted gems the user
+    # selected and chooses documentation over forced isolation; a plugin determined to spoof a bundled id
+    # is out of scope there and stays out of scope here. What the predicate buys is that an ordinary
+    # third-party plugin cannot accidentally claim authority it was never granted.
+    module FirstParty
+      # The prefix a bundled plugin's gem name carries over its manifest id.
+      GEM_PREFIX = "rigor-"
+
+      @memo = {}
+
+      class << self
+        # Whether `id` names a plugin the engine bundles.
+        #
+        # Memoised: the answer is a `File.file?` on a path fixed for the process, and the effect surfaces
+        # ask it once per plugin per run — but a plugin's own specs ask it far more often than that.
+        def bundled?(id)
+          key = id.to_s
+          return false if key.empty?
+
+          return @memo[key] if @memo.key?(key)
+
+          # Required here rather than at the top of the file: {Loader} pulls in the plugin {Registry},
+          # which pulls in {Manifest}, which asks this module the question — a `require` cycle that would
+          # leave `Loader` undefined half-way through load. The require is idempotent and this method is
+          # memoised, so it costs one `$LOADED_FEATURES` probe per process.
+          require_relative "loader"
+          @memo[key] = !Loader.bundled_plugin_path("#{GEM_PREFIX}#{key}").nil?
+        end
+
+        # Drops the memo. For specs that stub the engine root only.
+        def reset!
+          @memo = {}
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/isolation.rb

@@ -43,8 +43,11 @@ module Rigor
         @target_bundle_root
       end
 
+      # Frozen so the value stays `Ractor.shareable?`: a Ractor-pool worker READS this (its Environment
+      # build resolves the same root and skips the write — #414), and reading an unshareable value out of
+      # a module ivar from a non-main Ractor is the same `Ractor::IsolationError` as writing one.
       def target_bundle_root=(root)
-        @target_bundle_root = root.nil? ? nil : File.expand_path(root.to_s)
+        @target_bundle_root = root.nil? ? nil : File.expand_path(root.to_s).freeze
       end
 
       # Requires `feature`, falling back to the analyzed project's bundler install tree. The fallback

data/lib/rigor/plugin/manifest.rb

@@ -3,6 +3,10 @@
 require_relative "../inference/hkt_registry"
 require_relative "protocol_contract"
 require_relative "additional_initializer"
+require_relative "effect_attribution"
+require_relative "effect_edge"
+require_relative "effect_entry_points"
+require_relative "first_party"
 
 module Rigor
   module Plugin
@@ -33,11 +37,16 @@ module Rigor
         end
       end
 
+      # ADR-103 WD2 — what a plugin's `effect_root:` may be spelled as: one label segment, the shape
+      # {Rigor::Effects::Label} accepts as a root.
+      VALID_EFFECT_ROOT = /\A[a-z][a-z0-9_]*\z/
+
       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,
                   :hkt_registrations, :hkt_definitions, :signature_paths, :protocol_contracts,
-                  :source_rbs_synthesizer, :additional_initializers
+                  :source_rbs_synthesizer, :additional_initializers,
+                  :effect_root, :effect_labels, :effect_attributions, :effect_edges, :effect_entry_points
 
       def initialize( # rubocop:disable Metrics/ParameterLists
         id:, version:,
@@ -46,7 +55,9 @@ module Rigor
         block_as_methods: [], heredoc_templates: [], nested_class_templates: [],
         trait_registries: [],
         hkt_registrations: [], hkt_definitions: [], signature_paths: [], protocol_contracts: [],
-        source_rbs_synthesizer: nil, additional_initializers: []
+        source_rbs_synthesizer: nil, additional_initializers: [],
+        effect_root: nil, effect_labels: [], effect_attributions: [], effect_edges: [],
+        effect_entry_points: []
       )
         validate_id!(id)
         validate_version!(version)
@@ -65,6 +76,11 @@ module Rigor
         validate_protocol_contracts!(protocol_contracts)
         validate_source_rbs_synthesizer!(source_rbs_synthesizer)
         validate_additional_initializers!(additional_initializers)
+        validate_effect_root!(effect_root)
+        validate_effect_labels!(effect_labels)
+        validate_effect_attributions!(effect_attributions)
+        validate_effect_edges!(effect_edges)
+        validate_effect_entry_points!(effect_entry_points)
 
         assign_fields(id, version, description, config_schema, produces, consumes, owns_receivers,
                       open_receivers, type_node_resolvers, block_as_methods, heredoc_templates, trait_registries,
@@ -72,6 +88,7 @@ module Rigor
                       source_rbs_synthesizer)
         assign_nested_class_templates(nested_class_templates)
         assign_additional_initializers(additional_initializers)
+        assign_effect_fields(effect_root, effect_labels, effect_attributions, effect_edges, effect_entry_points)
         freeze
       end
 
@@ -115,6 +132,17 @@ module Rigor
         @additional_initializers = additional_initializers.dup.freeze
       end
       private :assign_additional_initializers
+
+      # ADR-103 WD2 / WD6 / WD10 / WD14 — the effect contract's five fields, assigned together and outside
+      # `assign_fields` (which already carries the maximum positional arity).
+      def assign_effect_fields(effect_root, effect_labels, effect_attributions, effect_edges, effect_entry_points)
+        @effect_root = effect_root.nil? ? nil : effect_root.to_s.dup.freeze
+        @effect_labels = effect_labels.map { |label| label.to_s.dup.freeze }.uniq.sort.freeze
+        @effect_attributions = effect_attributions.dup.freeze
+        @effect_edges = effect_edges.dup.freeze
+        @effect_entry_points = effect_entry_points.dup.freeze
+      end
+      private :assign_effect_fields
       # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
 
       public
@@ -161,10 +189,38 @@ module Rigor
           "signature_paths" => signature_paths,
           "protocol_contracts" => protocol_contracts.map(&:to_h),
           "source_rbs_synthesizer" => source_rbs_synthesizer&.class&.name,
-          "additional_initializers" => additional_initializers.map(&:to_h)
+          "additional_initializers" => additional_initializers.map(&:to_h),
+          "effect_root" => effect_root,
+          "effect_labels" => effect_labels,
+          "effect_attributions" => effect_attributions.map(&:to_h),
+          "effect_edges" => effect_edges.map(&:to_h),
+          "effect_entry_points" => effect_entry_points.map(&:to_h)
         }
       end
 
+      # ADR-103 WD2 — the identity opening a root when this plugin's labels join the run's vocabulary: the
+      # framework root it models for a first-party bundled plugin that declares one, and the plugin id
+      # otherwise. A third-party plugin's `effect_root:` is ignored here (and warned about by the registry),
+      # so it opens only the root named after itself.
+      def effect_owner
+        return id if effect_root.nil?
+        return id unless FirstParty.bundled?(id)
+
+        effect_root
+      end
+
+      # Whether this plugin's `effect_attributions:` may carry `discharge: true` (ADR-103 WD6).
+      def effect_discharge_allowed?
+        FirstParty.bundled?(id)
+      end
+
+      # Whether the plugin contributes anything to the effect surfaces at all. The compiled per-run tables
+      # skip a plugin that answers false, so a project whose plugins predate this contract pays nothing.
+      def effects?
+        !effect_labels.empty? || !effect_attributions.empty? || !effect_edges.empty? ||
+          !effect_entry_points.empty?
+      end
+
       def ==(other)
         other.is_a?(Manifest) && to_h == other.to_h
       end
@@ -414,6 +470,50 @@ module Rigor
               "got #{synthesizer.inspect}"
       end
 
+      # ADR-103 WD2 — `effect_root:` names the effect-label root this plugin opens when it is one the
+      # engine bundles: rigor-activejob models ActiveJob and therefore opens `rails.*`, not `activejob.*`.
+      # Declaring one is only ever a *request*; {#effect_owner} grants it to a first-party plugin and
+      # ignores it otherwise, so the field is safe to accept from anyone.
+      def validate_effect_root!(root)
+        return if root.nil?
+        return if root.is_a?(String) && root.match?(VALID_EFFECT_ROOT)
+
+        raise ArgumentError,
+              "plugin manifest effect_root must match #{VALID_EFFECT_ROOT.inspect}, got #{root.inspect}"
+      end
+
+      # ADR-103 WD2 — `effect_labels:` lists the vocabulary this plugin registers. The engine folds them
+      # into the run's {Rigor::Effects::Registry} through `#with(labels:, owner: manifest.effect_owner)`,
+      # which is where root ownership is enforced; a label outside the plugin's root is a load-time plugin
+      # error, reported like any other. Only the spelling is checked here.
+      def validate_effect_labels!(labels)
+        validate_array_of!("effect_labels", labels, "non-empty String") { |l| l.is_a?(String) && !l.empty? }
+      end
+
+      # ADR-103 WD6 / WD10 — `effect_attributions:` colours calls into the framework this plugin models.
+      # Each entry MUST be a {Rigor::Plugin::EffectAttribution}.
+      def validate_effect_attributions!(entries)
+        validate_array_of!("effect_attributions", entries, "Rigor::Plugin::EffectAttribution instances") do |e|
+          e.is_a?(EffectAttribution)
+        end
+      end
+
+      # ADR-103 WD10 — `effect_edges:` declares the framework edges the syntax lacks. Each entry MUST be a
+      # {Rigor::Plugin::EffectEdge}, whose `target:` is one of a fixed engine-side strategy enum.
+      def validate_effect_edges!(entries)
+        validate_array_of!("effect_edges", entries, "Rigor::Plugin::EffectEdge instances") do |e|
+          e.is_a?(EffectEdge)
+        end
+      end
+
+      # ADR-103 WD14 — `effect_entry_points:` names the `effects.snapshot.reach:` presets this plugin
+      # supplies. Each entry MUST be a {Rigor::Plugin::EffectEntryPoints}.
+      def validate_effect_entry_points!(entries)
+        validate_array_of!("effect_entry_points", entries, "Rigor::Plugin::EffectEntryPoints instances") do |e|
+          e.is_a?(EffectEntryPoints)
+        end
+      end
+
       def coerce_consumes(consumes)
         unless consumes.is_a?(Array)
           raise ArgumentError, "plugin manifest consumes must be an Array, got #{consumes.inspect}"

data/lib/rigor/plugin/registry.rb

@@ -244,6 +244,30 @@ module Rigor
       # ADR-52 WD4 — the per-run node-rule walk (see {NodeRuleWalk}).
       attr_reader :node_rule_walk
 
+      # ADR-103 WD2 / WD6 / WD10 / WD14 (#387) — every loaded plugin's effect contribution, in
+      # registration order, as {Contribution} rows.
+      #
+      # **Lazy, unlike the other aggregates.** A plugin MAY compute its `effect_attributions:` from project
+      # facts — rigor-activejob reads `config.active_job.queue_adapter` to decide whether an enqueue is a
+      # database write or a Redis one — and that is an I/O-boundary read a `rigor check` with no `effects:`
+      # block must never pay. Nothing asks for this until {Rigor::Effects::PluginFacts.build} does, and
+      # nothing calls that unless collection is on. Memoised into the frozen registry the same way
+      # `contracts_for_path` memoises, and for the same reason: the answer is fixed for the run.
+      def effect_contributions
+        @effect_memo[:contributions] ||= compile_effect_contributions
+      end
+
+      # One plugin's effect contribution, flattened off whichever surface answered it (the manifest, or the
+      # plugin's own override). Carries the two authority answers with it — `owner`, the label root this
+      # plugin may open, and `discharge_allowed`, whether its attributions may discharge — so nothing
+      # downstream has to re-derive who is first-party.
+      Contribution = Data.define(:id, :owner, :requested_root, :discharge_allowed, :labels, :attributions,
+                                 :edges, :entry_points) do
+        def empty?
+          labels.empty? && attributions.empty? && edges.empty? && entry_points.empty?
+        end
+      end
+
       # ADR-15 Phase 3 — build a fresh Registry from the supplied blueprint set by replaying
       # {Blueprint#materialize} per entry against `services`. The returned registry carries NEW plugin
       # instances (mutable per-Ractor accumulators included) and the same blueprint set, so a worker can hand
@@ -379,6 +403,30 @@ module Rigor
         @open_receivers_set = @open_receivers.to_set.freeze
         @protocol_contracts = @plugins.flat_map { |p| safe_protocol_contracts(p) }.freeze
         @contracts_by_path = {}
+        @effect_memo = {}
+      end
+
+      # Fail-soft per plugin: a plugin whose `effect_attributions:` override raises (a missing
+      # `config/application.rb`, an unreadable path) contributes nothing rather than taking the run down.
+      # An effect contribution is an enrichment; ADR-2 isolates plugin failures at the analyzer boundary
+      # and this is that boundary.
+      def compile_effect_contributions
+        @plugins.filter_map { |plugin| effect_contribution_for(plugin) }.freeze
+      end
+
+      def effect_contribution_for(plugin)
+        manifest = safe_manifest(plugin)
+        return nil if manifest.nil?
+
+        contribution = Contribution.new(
+          id: manifest.id, owner: manifest.effect_owner, requested_root: manifest.effect_root,
+          discharge_allowed: manifest.effect_discharge_allowed?,
+          labels: plugin.effect_labels, attributions: plugin.effect_attributions,
+          edges: plugin.effect_edges, entry_points: plugin.effect_entry_points
+        )
+        contribution.empty? ? nil : contribution
+      rescue StandardError
+        nil
       end
 
       def path_matches_glob?(glob, path)

data/lib/rigor/plugin.rb

@@ -15,6 +15,7 @@ require_relative "plugin/load_error"
 require_relative "plugin/box"
 require_relative "plugin/isolation"
 require_relative "plugin/inflector"
+require_relative "plugin/first_party"
 
 module Rigor
   module Plugin