rigortype 0.3.3 → 0.3.5

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,11 @@
 require_relative "../inference/hkt_registry"
 require_relative "protocol_contract"
 require_relative "additional_initializer"
+require_relative "effect_attribution"
+require_relative "effect_edge"
+require_relative "effect_ancestry"
+require_relative "effect_entry_points"
+require_relative "first_party"
 
 module Rigor
   module Plugin
@@ -33,11 +38,17 @@ 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,
+                  :effect_ancestry
 
       def initialize( # rubocop:disable Metrics/ParameterLists
         id:, version:,
@@ -46,7 +57,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: [], effect_ancestry: []
       )
         validate_id!(id)
         validate_version!(version)
@@ -65,6 +78,8 @@ module Rigor
         validate_protocol_contracts!(protocol_contracts)
         validate_source_rbs_synthesizer!(source_rbs_synthesizer)
         validate_additional_initializers!(additional_initializers)
+        validate_effect_fields!(effect_root, effect_labels, effect_attributions, effect_edges,
+                                effect_entry_points, effect_ancestry)
 
         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 +87,8 @@ 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, effect_ancestry)
         freeze
       end
 
@@ -115,6 +132,31 @@ 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).
+      # The six `effect_*` fields validate together, so {#initialize} carries one call rather than six.
+      def validate_effect_fields!(effect_root, effect_labels, effect_attributions, effect_edges,
+                                  effect_entry_points, effect_ancestry)
+        validate_effect_root!(effect_root)
+        validate_effect_labels!(effect_labels)
+        validate_effect_attributions!(effect_attributions)
+        validate_effect_edges!(effect_edges)
+        validate_effect_entry_points!(effect_entry_points)
+        validate_effect_ancestry!(effect_ancestry)
+      end
+      private :validate_effect_fields!
+
+      def assign_effect_fields(effect_root, effect_labels, effect_attributions, effect_edges,
+                               effect_entry_points, effect_ancestry)
+        @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
+        @effect_ancestry = effect_ancestry.dup.freeze
+      end
+      private :assign_effect_fields
       # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
 
       public
@@ -161,10 +203,39 @@ 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),
+          "effect_ancestry" => effect_ancestry.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 +485,59 @@ 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 WD17 (#465) — `effect_ancestry:` states an ancestry edge the plugin's own gem introduces
+      # and the project's source never writes. Each entry MUST be a {Rigor::Plugin::EffectAncestry}; only
+      # a bundled plugin's survives, which `Effects::PluginFacts` enforces.
+      def validate_effect_ancestry!(entries)
+        validate_array_of!("effect_ancestry", entries, "Rigor::Plugin::EffectAncestry instances") do |e|
+          e.is_a?(EffectAncestry)
+        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,36 @@ 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, :ancestry) do
+        # `ancestry:` defaults so a caller written before #465 — and every spec that constructs one by
+        # hand — keeps working; a plugin that declares none contributes none.
+        def initialize(ancestry: [], **rest)
+          super
+        end
+
+        def empty?
+          labels.empty? && attributions.empty? && edges.empty? && entry_points.empty? && ancestry.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 +409,31 @@ 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,
+          ancestry: plugin.effect_ancestry
+        )
+        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

data/lib/rigor/rbs_extended/envelope_scanner.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+require_relative "../rbs_extended"
+require_relative "reporter"
+
+module Rigor
+  module RbsExtended
+    # Collects every effect envelope the project's own RBS declares (ADR-103 WD5 / WD14; #383).
+    #
+    # It produces values, never diagnostics — the check that compares a bound against the proven
+    # summaries is {Rigor::Effects::EnvelopeCheck}. Two tables come out, because they are consumed
+    # differently:
+    #
+    # - {Result#method_envelopes} — keyed by method key (`Class#m` / `Class.m`), applied as written.
+    # - {Result#class_envelopes} — keyed by class / module name, DISTRIBUTED by the check to every
+    #   method of that Ruby class discovery knows (reopenings, other files, synthesized `attr_*` and
+    #   `define_method` members), never to subclasses. A per-method envelope wins over a distributed
+    #   one; nearest wins, and no `-except` syntax is needed.
+    #
+    # ## Why it parses rather than reading the built environment
+    #
+    # {ConformanceChecker}, the obvious model, walks `RbsLoader`'s built env. An envelope cannot: the
+    # diagnostic has to name **where the bound was written** (`sig/foo.rbs:12`), and the ADR-54 env
+    # cache dumps every `RBS::Location` to a zero-range `<cached>` sentinel, so a warm run would lose
+    # both the position and the only evidence of which file a declaration came from. Parsing the
+    # project's own signature sources is a few milliseconds over a tree Rigor already globs, it is
+    # identical warm and cold, and it enforces ADR-103 WD6's trust rule structurally: a `%a{pure}` in
+    # rbs core or in a gem's shipped RBS is never read, so it cannot bound a project method that
+    # happens to share its key.
+    #
+    # Malformed payloads and `pure`-versus-`effect` contradictions are recorded on a {Reporter} the
+    # scanner owns and ride out on {Result#unresolved}. They surface no diagnostic in this slice:
+    # `effect.unknown-label` and the annotation-in-a-project-without-`effects:` residual are #384's.
+    module EnvelopeScanner
+      Result = Data.define(:method_envelopes, :class_envelopes, :unresolved) do
+        def empty? = method_envelopes.empty? && class_envelopes.empty?
+      end
+
+      EMPTY = Result.new(method_envelopes: {}.freeze, class_envelopes: {}.freeze, unresolved: [].freeze)
+
+      # RBS's kind for a `def self?.x` member — it declares BOTH sides, so the envelope binds both.
+      SINGLETON_INSTANCE = :singleton_instance
+      private_constant :SINGLETON_INSTANCE
+
+      module_function
+
+      # @param sources [Array<Array(String, String)>] `[buffer name, RBS source]` pairs — the project's
+      #   `.rbs` files, plus the virtual entries rbs-inline and plugin `source_rbs` synthesis contribute.
+      # @param registry [Rigor::Effects::Registry] the vocabulary an unknown label is judged against.
+      # @return [Result]
+      def scan(sources:, registry:)
+        reporter = Reporter.new
+        methods = {}
+        classes = {}
+        sources.each do |name, content|
+          declarations(name, content).each do |decl|
+            walk(decl, [], methods, classes, registry, reporter)
+          end
+        end
+        Result.new(
+          method_envelopes: methods.freeze, class_envelopes: classes.freeze,
+          unresolved: reporter.unresolved_payloads
+        )
+      rescue StandardError
+        EMPTY
+      end
+
+      # The **accepted-signature** reader: every per-method envelope declared anywhere in a BUILT
+      # `RBS::Environment` — a gem's shipped signatures, Rigor's bundled overlays, core RBS
+      # (ADR-103 WD6; #386).
+      #
+      # It exists for one purpose and is usable for exactly one: importing a `≤` bound at a call site
+      # that resolves into un-analysed code ({Rigor::Effects::EnvelopeIndex}). It MUST NOT feed a
+      # contract check. Two facts make that a structural guarantee rather than a convention —
+      # {.scan}, which the check reads, never opens this door, and the values here carry no
+      # `location` at all (the ADR-54 env cache dumps every `RBS::Location` to a `<cached>` sentinel,
+      # so a warm run could not name where the bound was written even if a diagnostic wanted to).
+      # There is also no body to check: a gem method is un-analysed by definition, which is why WD6
+      # trusts the declaration instead, exactly as it already trusts the gem's *types*.
+      #
+      # Class-level annotations are deliberately not read. Distribution needs "every method of the
+      # class discovery knows", which is a project fact; a gem's class-level tag would have to
+      # distribute over a definition set this reader does not have.
+      #
+      # @param loader [Rigor::Environment::RbsLoader] the run's loader; it owns the env walk
+      #   ({Rigor::Environment::RbsLoader#each_annotated_method_member}), so the environment itself never
+      #   leaves it.
+      # @param registry [Rigor::Effects::Registry]
+      # @return [Hash{String => Rigor::Effects::Envelope}] keyed `Class#m` / `Class.m`
+      def from_loader(loader:, registry:)
+        out = {}
+        loader.each_annotated_method_member do |class_name, member|
+          keys_for(class_name, member).each do |key|
+            next if out.key?(key)
+
+            envelope = RbsExtended.read_effect_envelope(
+              member.annotations, owner_key: key, source: :effect_annotation, registry: registry
+            )
+            out[key] = envelope if envelope
+          end
+        end
+        out.freeze
+      rescue StandardError
+        {}.freeze
+      end
+
+      # Fail-soft per file: an unparseable `.rbs` is already quarantined by the loader and reported as
+      # `rbs.coverage.quarantined-signature`; contributing no envelope is the consistent answer here.
+      def declarations(name, content)
+        _, _, decls = ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: name, content: content))
+        decls || []
+      rescue StandardError
+        []
+      end
+
+      # Descends the declaration tree, carrying the lexical prefix so a nested `class Bar` inside
+      # `module Foo` keys as `Foo::Bar` — the same spelling the effects scanner gives its units.
+      def walk(decl, prefix, methods, classes, registry, reporter)
+        return unless decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
+
+        nested = prefix + [decl.name.to_s.sub(/\A::/, "")]
+        class_name = nested.join("::")
+        envelope = RbsExtended.read_effect_envelope(
+          decl.annotations, owner_key: class_name, source: :class_annotation,
+                            registry: registry, reporter: reporter
+        )
+        classes[class_name] = envelope if envelope
+        decl.members.each { |member| absorb_member(member, nested, methods, classes, registry, reporter) }
+      end
+
+      def absorb_member(member, prefix, methods, classes, registry, reporter)
+        return walk(member, prefix, methods, classes, registry, reporter) unless
+          member.is_a?(::RBS::AST::Members::MethodDefinition)
+        return if member.annotations.nil? || member.annotations.empty?
+
+        keys_for(prefix.join("::"), member).each do |key|
+          envelope = RbsExtended.read_effect_envelope(
+            member.annotations, owner_key: key, source: :effect_annotation,
+                                registry: registry, reporter: reporter
+          )
+          methods[key] = envelope if envelope
+        end
+      end
+
+      # The effect-unit keys one RBS member declares. `def self?.x` declares both sides, so its
+      # envelope binds both; every other kind declares one.
+      def keys_for(class_name, member)
+        case member.kind
+        when :singleton then ["#{class_name}.#{member.name}"]
+        when SINGLETON_INSTANCE then ["#{class_name}##{member.name}", "#{class_name}.#{member.name}"]
+        else ["#{class_name}##{member.name}"]
+        end
+      end
+
+      private_class_method :declarations, :walk, :absorb_member, :keys_for
+    end
+  end
+end