rigortype 0.3.3 → 0.3.5

data/lib/rigor/rbs_extended.rb

@@ -3,6 +3,11 @@
 require_relative "type"
 require_relative "builtins/imported_refinements"
 require_relative "flow_contribution"
+require_relative "effects/envelope"
+require_relative "effects/inline_anchor"
+require_relative "effects/label"
+require_relative "effects/label_set"
+require_relative "effects/signature_sources"
 require_relative "rbs_extended/reporter"
 require_relative "rbs_extended/hkt_directives"
 
@@ -621,6 +626,189 @@ module Rigor
       facts.empty? ? nil : facts
     end
 
+    # ── Effect envelopes (ADR-103 WD1 / WD5 / WD14; #383) ──────────────────────────────────────────
+    #
+    # Two spellings reach the same value. `%a{pure}` is the ecosystem's existing purity annotation
+    # (rbs core and Steep both carry it) and reads as the EMPTY envelope; `%a{rigor:v1:effect …}` is
+    # Rigor's labelled bound. `rigor:v1:pure` is deliberately NOT implemented — WD14 fixed `%a{pure}`
+    # as the only purity spelling.
+
+    # The bare rbs-native purity annotation. Matched whole, with surrounding whitespace tolerated, so
+    # `%a{purely}` and `%a{pure io}` are not it.
+    PURE_ANNOTATION_PATTERN = /\A\s*pure\s*\z/
+    private_constant :PURE_ANNOTATION_PATTERN
+
+    # `%a{rigor:v1:effect io.db, nondet.time}` — a space-separated head (the `assert` / `conforms-to`
+    # family), then a comma-separated list of BARE label tokens. There is no parenthesised comment
+    # form: RBS has real comments. The payload group is optional so that `%a{rigor:v1:effect}` still
+    # MATCHES the directive and is reported as malformed rather than read as "not a directive".
+    EFFECT_DIRECTIVE_PATTERN = /\Arigor:v1:effect(?:\s+(?<labels>.*?))?\s*\z/
+    private_constant :EFFECT_DIRECTIVE_PATTERN
+
+    # The outcome of reading one `%a{rigor:v1:effect …}` payload.
+    #
+    # `bound` is the declared {Rigor::Effects::LabelSet}, or {Effects::LabelSet::TOP} when the tag
+    # could not be given a meaning. `malformed` says the grammar was violated (an empty list, a token
+    # that is not a label); `unknown_labels` says the grammar held but the registry does not
+    # recognise a spelling — a different condition with different handling, and what #384's
+    # `effect.unknown-label` reads. `labels` is the list exactly as written, recognised or not, which
+    # is what lets the diagnostic ask whether some OTHER member of the list was known.
+    EffectAnnotation = Data.define(:bound, :labels, :unknown_labels, :malformed) do
+      def malformed? = malformed
+      def top? = bound.top?
+    end
+
+    NO_EFFECT_LABELS = [].freeze
+    private_constant :NO_EFFECT_LABELS
+
+    # Whether `string` is the bare `%a{pure}` annotation.
+    def pure_annotation?(string)
+      !string.nil? && PURE_ANNOTATION_PATTERN.match?(string)
+    end
+
+    # Reads one annotation string as an effect-envelope payload.
+    #
+    # Returns `nil` when the string is not a `rigor:v1:effect` directive at all (so a caller can walk
+    # an annotation list without pre-filtering). Otherwise an {EffectAnnotation}:
+    #
+    # - well-formed and fully recognised → the declared bound;
+    # - malformed (empty list, a token outside the label grammar) → {Effects::LabelSet::TOP}, and a
+    #   `record_unresolved` event on `reporter`;
+    # - well-formed but carrying a spelling `registry` does not know → {Effects::LabelSet::TOP} and
+    #   the unrecognised spellings, because an unknown label makes the WHOLE tag ⊤ rather than the
+    #   subset that happened to parse. Narrowing to the recognised subset would turn a typo into
+    #   findings on correct code; widening suppresses them, which is the direction the false-positive
+    #   budget runs (ADR-5).
+    def parse_effect_annotation(string, registry: nil, reporter: nil, source_location: nil)
+      match = EFFECT_DIRECTIVE_PATTERN.match(string.to_s)
+      return nil if match.nil?
+
+      tokens = match[:labels].to_s.split(",", -1).map(&:strip)
+      if tokens.empty? || tokens.any? { |token| !Effects::Label.valid?(token) }
+        record_unresolved(reporter, string, source_location)
+        return EffectAnnotation.new(
+          bound: Effects::LabelSet::TOP, labels: NO_EFFECT_LABELS, unknown_labels: NO_EFFECT_LABELS, malformed: true
+        )
+      end
+
+      tokens = tokens.freeze
+      unknown = registry.nil? ? [] : tokens.reject { |token| registry.known?(token) }
+      EffectAnnotation.new(
+        bound: unknown.empty? ? Effects::LabelSet.new(tokens) : Effects::LabelSet::TOP,
+        labels: tokens, unknown_labels: unknown.uniq.sort.freeze, malformed: false
+      )
+    end
+
+    # Reads the effect envelope off an annotation list — `RBS::Definition::Method#annotations`, or the
+    # `#annotations` of an `RBS::AST::Members::MethodDefinition` / class declaration, which carry the
+    # same `(string, location)` shape.
+    #
+    # Precedence, per the spec: `%a{pure}` and `%a{rigor:v1:effect …}` on ONE declaration are
+    # contradictory and `pure` wins; the contradiction is recorded on `reporter` (the existing
+    # `RBS::Extended` conflict channel) rather than silently resolved. Returns `nil` when the list
+    # carries neither spelling.
+    #
+    # @param annotations [Array<#string>] the node's annotations, in source order.
+    # @param owner_key [String] the method key (`Class#m` / `Class.m`) or class name the bound binds.
+    # @param source [Symbol] {Effects::Envelope::SOURCES} member to stamp when the labelled spelling
+    #   matched; `%a{pure}` always stamps `:pure_annotation`, and a class-level read overrides both.
+    def read_effect_envelope(annotations, owner_key:, source: :effect_annotation, registry: nil, reporter: nil)
+      return nil if annotations.nil? || annotations.empty?
+
+      pure = annotations.find { |annotation| pure_annotation?(annotation.string) }
+      labelled = nil
+      parsed = nil
+      annotations.each do |annotation|
+        result = parse_effect_annotation(
+          annotation.string, registry: registry, reporter: reporter, source_location: annotation_location(annotation)
+        )
+        next if result.nil?
+
+        labelled = annotation
+        parsed = result
+        break
+      end
+      return nil if pure.nil? && labelled.nil?
+
+      if pure && labelled
+        record_unresolved(
+          reporter,
+          "`%a{pure}` and `%a{#{labelled.string}}` on one declaration are contradictory; `pure` wins",
+          annotation_location(pure)
+        )
+      end
+      return build_pure_envelope(pure, owner_key: owner_key, source: source) if pure
+
+      build_effect_envelope(labelled, parsed, owner_key: owner_key, source: source)
+    end
+
+    def build_pure_envelope(annotation, owner_key:, source:)
+      Effects::Envelope.build(
+        owner_key: owner_key,
+        bound: Effects::LabelSet::EMPTY,
+        source: source == :class_annotation ? :class_annotation : :pure_annotation,
+        location: render_annotation_location(annotation),
+        spelling: "%a{#{annotation.string}}"
+      )
+    end
+
+    def build_effect_envelope(annotation, parsed, owner_key:, source:)
+      Effects::Envelope.build(
+        owner_key: owner_key,
+        bound: parsed.bound,
+        source: source,
+        location: render_annotation_location(annotation),
+        spelling: "%a{#{annotation.string}}",
+        unknown_labels: parsed.unknown_labels,
+        declared_labels: parsed.labels
+      )
+    end
+
+    def annotation_location(annotation)
+      annotation.respond_to?(:location) ? annotation.location : nil
+    end
+
+    # `path:line` for the annotation, project-relative when it sits under the working directory, so a
+    # diagnostic message names `sig/foo.rbs:12` rather than an absolute path.
+    #
+    # A synthesized buffer is re-anchored here rather than at any of the surfaces that render it
+    # ({Effects::InlineAnchor}; #432). The buffer's own line numbers describe a document the author
+    # never saw, so an envelope carrying one is wrong for every consumer at once — the diagnostic, the
+    # `effect.unknown-label` position, `rigor explain`, the JSON formatter, LSP hover. Correcting it
+    # where the value is *built* is what makes them agree without each learning the mapping.
+    def render_annotation_location(annotation)
+      location = annotation_location(annotation)
+      return nil if location.nil?
+
+      buffer = location.respond_to?(:buffer) ? location.buffer : nil
+      name = buffer.respond_to?(:name) ? buffer.name.to_s : nil
+      return nil if name.nil? || name.empty?
+
+      path = relative_annotation_path(name)
+      "#{path}:#{annotation_line(annotation, location, buffer, path)}"
+    rescue StandardError
+      nil
+    end
+
+    # The line a reader can open. For a real `.rbs` that is the parser's own answer; for the
+    # `virtual:rbs-inline:…rb` buffer the writer produced, the annotation is found again in the Ruby
+    # source by its own spelling.
+    def annotation_line(annotation, location, buffer, path)
+      line = location.respond_to?(:start_line) ? location.start_line : 1
+      content = buffer.respond_to?(:content) ? buffer.content : nil
+      return line if content.nil?
+
+      Effects::InlineAnchor.ruby_line(
+        path: path, buffer: content, buffer_line: line, spelling: "%a{#{annotation.string}}"
+      )
+    end
+
+    # The buffer-name → readable-path rule lives with the walk that produces the buffers
+    # ({Effects::SignatureSources}), so a `virtual:` name is stripped identically wherever it surfaces.
+    def relative_annotation_path(name)
+      Effects::SignatureSources.source_path(name)
+    end
+
     # ADR-13 slice 3b — guards every reporter call so the in-RbsExtended-module call sites can record events
     # uniformly without nil-checking each time. When the reporter is nil (the v0.1.0 → v0.1.3 default for call
     # sites that do not yet thread `environment:`), the call is a no-op and the parser stays fail-soft.

data/lib/rigor/reflection.rb

@@ -44,6 +44,10 @@ module Rigor
   # out of scope for the v0.0.7 first pass; v0.1.0's plugin API added it as a separate
   # concern.
   module Reflection
+    # #354 — thread-local slot for the per-run ancestor-scope memo. See {.ancestor_constant_scopes}.
+    ANCESTOR_SCOPES_KEY = :__rigor_ancestor_constant_scopes__
+    private_constant :ANCESTOR_SCOPES_KEY
+
     module_function
 
     # @param class_name [String, Symbol]
@@ -118,42 +122,139 @@ module Rigor
     # reads it to type a constant read, and `Inference::Narrowing` reads it to recognise a
     # value-pinned `Constant[Regexp]` match-predicate operand.
     def resolve_constant_type(name, scope: Scope.empty)
+      prefix = enclosing_class_path(scope)
+
+      # Step 1 — `Module.nesting`, innermost first. Each entry contributes only its OWN constants.
+      walker = prefix
+      while walker && !walker.empty?
+        hit = constant_type_at("#{walker}::#{name}", scope)
+        return hit if hit
+
+        idx = walker.rindex("::")
+        walker = idx ? walker[0, idx] : nil
+      end
+
+      # Step 2 (#354) — the ancestors of the innermost cresting scope, which Ruby consults BEFORE
+      # falling back to the top level. Skipping this step did not merely lose a resolution: when the
+      # same name also exists at top level, step 3 answered a lookup Ruby gives to the ancestor, so
+      # `KEY` inside `class Sub < Base` typed as the top-level constant rather than `Base::KEY` — a
+      # wrong type on correct code, which outranks any worst-case reading (AGENTS.md
+      # § "Implementation Guidelines"). Only project ancestors are walked; an RBS-known superclass
+      # contributes no name here (see {.ancestor_constant_scopes}).
+      if prefix
+        ancestor_constant_scopes(prefix, scope).each do |ancestor|
+          hit = constant_type_at("#{ancestor}::#{name}", scope)
+          return hit if hit
+        end
+      end
+
+      # Step 3 — the bare name (top level).
+      constant_type_at(name, scope)
+    end
+
+    # One candidate name, consulted in source-precedence order: the class registry (yielding a
+    # `Singleton[C]`), source-discovered classes, in-source value constants, then RBS-side
+    # constants. In-source values win over RBS constant decls because the user's source is
+    # authoritative for its own constants. Returns nil when no source knows `candidate`.
+    def constant_type_at(candidate, scope)
       env = scope.environment
-      discovered = scope.discovered_classes
-      in_source = scope.in_source_constants
-      lexical_constant_candidates(name, scope: scope).each do |candidate|
-        singleton = env.singleton_for_name(candidate)
-        return singleton if singleton
-
-        in_source_class = discovered[candidate]
-        return in_source_class if in_source_class
-
-        # In-source value-bearing constants take precedence over RBS constant decls because
-        # user code is the authoritative source for its own constants.
-        in_source_value = in_source[candidate]
-        return in_source_value if in_source_value
-
-        value = env.constant_for_name(candidate)
-        return value if value
+
+      singleton = env.singleton_for_name(candidate)
+      return singleton if singleton
+
+      in_source_class = scope.discovered_classes[candidate]
+      return in_source_class if in_source_class
+
+      in_source_value = scope.in_source_constants[candidate]
+      return in_source_value if in_source_value
+
+      env.constant_for_name(candidate)
+    end
+    private_class_method :constant_type_at
+
+    # #354 — the project classes and modules whose own constants `class_name` inherits, in Ruby's
+    # ancestor order: included / prepended modules before the superclass (Ruby places mixins nearer),
+    # transitively, breadth-first. `class_name` itself is excluded — step 1 already covered it.
+    #
+    # Only PROJECT ancestors appear. `Scope#superclass_of` / `#includes_of` carry as-written names
+    # from the discovery pre-pass, and an as-written name that resolves to no discovered class or
+    # module is dropped — so a `class Foo < ActiveRecord::Base` contributes nothing and a constant
+    # owned by an RBS-known ancestor still resolves only if the bare name reaches it at step 3. That
+    # gap is deliberate for this slice: widening to the RBS ancestor graph is a separate question
+    # with its own FP surface.
+    #
+    # Memoised per run because step 2 runs on every constant reference whose lexical candidates all
+    # miss — which is the common case for a core-class reference (`String` inside `class Foo`). The
+    # bucket keys on the identity of the runner-seeded run-generation token (ADR-84 WD2), falling
+    # back to the per-file discovery table for runner-less scopes, so a re-run in one process (LSP,
+    # ADR-62 warm loop) cannot hit stale entries.
+    def ancestor_constant_scopes(class_name, scope)
+      # ADR-46: `superclass_of` / `includes_of` record a cross-file class dependency per consumer
+      # file, and the memo is run-scoped rather than file-scoped — a hit would skip the recording and
+      # under-record the edge for every later file. Recording runs are rare (incremental only), so
+      # they simply bypass the memo rather than complicate its key.
+      return compute_ancestor_constant_scopes(class_name, scope) if Analysis::DependencyRecorder.active?
+
+      generation = scope.run_generation || scope.discovered_superclasses
+      slot = Thread.current[ANCESTOR_SCOPES_KEY]
+      unless slot && slot[0].equal?(generation)
+        slot = [generation, {}]
+        Thread.current[ANCESTOR_SCOPES_KEY] = slot
       end
-      nil
+      bucket = slot[1]
+      bucket.fetch(class_name) { bucket[class_name] = compute_ancestor_constant_scopes(class_name, scope) }
     end
+    private_class_method :ancestor_constant_scopes
 
-    # The candidate qualified names to try, in Ruby's lexical order: most-qualified first (the
-    # enclosing class path joined to `name`), then progressively less-qualified, then the bare
-    # `name`. A top-level scope (no `self_type`) yields only `[name]`.
-    def lexical_constant_candidates(name, scope: Scope.empty)
-      prefix = enclosing_class_path(scope)
-      candidates = []
-      while prefix && !prefix.empty?
-        candidates << "#{prefix}::#{name}"
-        idx = prefix.rindex("::")
-        prefix = idx ? prefix[0, idx] : nil
+    def compute_ancestor_constant_scopes(class_name, scope)
+      queue = [class_name]
+      seen = { class_name => true }
+      out = []
+      until queue.empty?
+        current = queue.shift
+        # Mixins first, then the superclass — Ruby's ancestor order.
+        scope.includes_of(current).each do |raw|
+          resolved = resolve_ancestor_name(current, raw, scope)
+          next if resolved.nil? || seen[resolved]
+
+          seen[resolved] = true
+          out << resolved
+          queue << resolved
+        end
+        raw_super = scope.superclass_of(current)
+        next if raw_super.nil?
+
+        resolved_super = resolve_ancestor_name(current, raw_super, scope)
+        next if resolved_super.nil? || seen[resolved_super]
+
+        seen[resolved_super] = true
+        out << resolved_super
+        queue << resolved_super
+      end
+      out.freeze
+    end
+    private_class_method :compute_ancestor_constant_scopes
+
+    # Resolves an ancestor name AS WRITTEN (`"Base"`, or a qualified `"A::B"`) against the
+    # subclass's lexical nesting, innermost first — the same walk
+    # `ExpressionTyper#compute_ancestor_class_name` performs for method lookup. Returns nil when no
+    # candidate names a discovered project class or module.
+    def resolve_ancestor_name(subclass_qualified, raw, scope)
+      segments = subclass_qualified.split("::")
+      (segments.length - 1).downto(0) do |i|
+        candidate = (segments[0, i] + [raw]).join("::")
+        return candidate if known_project_namespace?(candidate, scope)
       end
-      candidates << name
-      candidates
+      nil
+    end
+    private_class_method :resolve_ancestor_name
+
+    def known_project_namespace?(name, scope)
+      scope.discovered_superclasses.key?(name) ||
+        scope.discovered_includes.key?(name) ||
+        scope.discovered_classes.key?(name)
     end
-    private_class_method :lexical_constant_candidates
+    private_class_method :known_project_namespace?
 
     # Pulls the enclosing qualified class name out of `scope.self_type` when one is set.
     # `Nominal[T]` and `Singleton[T]` both expose `class_name`. Returns nil at the top level.

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.3.3"
+  VERSION = "0.3.5"
 end

data/lib/rigor.rb

@@ -32,6 +32,7 @@ require_relative "rigor/cache/rbs_class_ancestor_table"
 require_relative "rigor/cache/rbs_class_type_param_names"
 require_relative "rigor/cache/rbs_environment"
 require_relative "rigor/type_node"
+require_relative "rigor/effects"
 require_relative "rigor/flow_contribution"
 require_relative "rigor/flow_contribution/fact"
 require_relative "rigor/flow_contribution/conflict"

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable/effects.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    class Actioncable < Rigor::Plugin::Base
+      # rigor-actioncable's effect contract (ADR-103 WD10; design note § 11.2; issue #387).
+      #
+      # A broadcast leaves the process — through Redis, through the async in-memory adapter, or through
+      # Solid Cable's database table, depending on `config/cable.yml`. Bare `io` is the only sound
+      # transport, and `rails.actioncable.broadcast` is what a reviewer means when they say "this model
+      # callback pushes to every connected browser".
+      #
+      # Turbo Streams' `broadcast_*` family rides the same rows: it is ActionCable underneath, and a
+      # `broadcast_replace_later_to` in a model callback is exactly the effect a policy on `app/models/**`
+      # exists to surface.
+      module Effects
+        CHANNEL = "ActionCable::Channel::Base"
+        SERVER = "ActionCable.server"
+        BROADCASTING = ["io", "rails.actioncable.broadcast"].freeze
+
+        # `Turbo::Broadcastable`'s class-body-declared broadcasts, called on a model instance.
+        TURBO_SELECTORS = %w[
+          broadcast_append_to broadcast_prepend_to broadcast_replace_to broadcast_update_to
+          broadcast_remove_to broadcast_before_to broadcast_after_to broadcast_action_to
+          broadcast_render_to broadcast_refresh_to
+        ].freeze
+
+        # The `_later` twins enqueue an ActiveJob that broadcasts, so they carry the enqueue meaning too.
+        TURBO_LATER_SELECTORS = TURBO_SELECTORS.map { |name| "#{name.delete_suffix('_to')}_later_to" }.freeze
+
+        LATER = (BROADCASTING + ["rails.activejob.enqueue", "job.enqueue"]).freeze
+
+        module_function
+
+        def attributions
+          channel_rows + server_rows + turbo_rows
+        end
+
+        def channel_rows
+          [
+            row(CHANNEL, :broadcast_to, BROADCASTING, singleton: true,
+                                                      why: "publishes to the channel's stream — out of this process, through whatever " \
+                                                           "`config/cable.yml` names"),
+            row(CHANNEL, :transmit, BROADCASTING,
+                why: "sends a message down this subscriber's own connection"),
+            row(CHANNEL, :stream_from, BROADCASTING,
+                why: "subscribes the connection to a stream, which registers with the pubsub adapter"),
+            row(CHANNEL, :stream_for, BROADCASTING, why: "the model-keyed `stream_from`")
+          ]
+        end
+
+        def server_rows
+          [
+            row(SERVER, :broadcast, BROADCASTING, why: "the bare pubsub publish"),
+            row("ActionCable.server.pubsub", :broadcast, BROADCASTING, why: "the adapter-level publish")
+          ]
+        end
+
+        def turbo_rows
+          TURBO_SELECTORS.map do |selector|
+            row("ActiveRecord::Base", selector, BROADCASTING,
+                why: "Turbo Streams broadcasts over ActionCable — a model callback that pushes HTML to " \
+                     "every connected browser is exactly the effect an `app/models/**` policy names")
+          end +
+            TURBO_LATER_SELECTORS.map do |selector|
+              row("ActiveRecord::Base", selector, LATER,
+                  why: "the `_later` twin enqueues a job that broadcasts, so it carries the enqueue " \
+                       "meaning as well as the broadcast one")
+            end
+        end
+
+        def row(receiver, selector, labels, why:, singleton: false)
+          EffectAttribution.new(receiver: receiver, method: selector, labels: labels,
+                                singleton: singleton, discharge: true, why: why)
+        end
+
+        def entry_points
+          [
+            EffectEntryPoints.new(
+              name: "rails-channels", globs: ["app/channels/**/*.rb"],
+              why: "channel callbacks — `subscribed`, `receive` and friends are invoked by the framework"
+            )
+          ]
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable.rb

@@ -5,6 +5,7 @@ require "rigor/plugin"
 require_relative "actioncable/channel_index"
 require_relative "actioncable/channel_discoverer"
 require_relative "actioncable/analyzer"
+require_relative "actioncable/effects"
 
 module Rigor
   module Plugin
@@ -80,7 +81,12 @@ module Rigor
             param_types: [{ index: 0, type_name: "Hash" }]
             # return_type_name: nil — receive's return value is discarded by the framework dispatcher.
           )
-        ]
+        ],
+        # ADR-103 WD10 (#387) — see {Effects} for what each row is and why.
+        effect_root: "rails",
+        effect_labels: ["rails.actioncable.broadcast"],
+        effect_attributions: Effects.attributions,
+        effect_entry_points: Effects.entry_points
       )
 
       # `watch:` covers every `.rb` file under the channel search paths so the cache invalidates when

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer/effects.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    class Actionmailer < Rigor::Plugin::Base
+      # rigor-actionmailer's effect contract (ADR-103 WD10; design note § 11.2; issue #387).
+      #
+      # ActionMailer is the clearest case in Rails of a lazy builder followed by a transport, and the
+      # design note's deferred-execution rule reads it straight off the syntax:
+      #
+      #     UserMailer.welcome(user).deliver_now
+      #     └──────── builder ─────┘└─ the effect ┘
+      #
+      # `UserMailer.welcome(u)` runs the mailer method and returns a `MessageDelivery` that has sent
+      # nothing. So it is an **edge** into `UserMailer#welcome` (whose own body may well read the
+      # database) and contributes no transport of its own. `deliver_now` is the send. `deliver_later`
+      # enqueues, which is ActiveJob's row plus the mail meaning — `email.send` still belongs there,
+      # because the mail WILL go out and a policy that forbids sending mail from a presenter means to
+      # forbid both spellings.
+      #
+      # The `on_result:` rows are what make this work on the idiom people actually write: the
+      # `MessageDelivery` in the middle has no type the project declares, but the class that produced it
+      # is written right there.
+      module Effects
+        BASE = "ActionMailer::Base"
+        DELIVERY = "ActionMailer::MessageDelivery"
+
+        NOW = ["io", "email.send", "rails.actionmailer.deliver"].freeze
+        LATER = ["io", "email.send", "rails.actionmailer.deliver", "rails.activejob.enqueue",
+                 "job.enqueue"].freeze
+
+        module_function
+
+        def attributions
+          rows(:deliver_now, NOW,
+               why: "the SMTP / API round trip itself — `io` because the delivery method is configured " \
+                    "per environment and is statically unknowable, `email.send` because that is what a " \
+                    "policy names") +
+            rows(:deliver_now!, NOW, why: "`deliver_now!` is `deliver_now` ignoring the perform-deliveries " \
+                                          "setting; the same send") +
+            rows(:deliver_later, LATER,
+                 why: "enqueues a delivery job: the enqueue rows, plus `email.send` — the mail goes out, " \
+                      "and a policy forbidding mail from this layer means both spellings") +
+            rows(:deliver_later!, LATER, why: "`deliver_later!` raises rather than serialising a missing " \
+                                              "record; the same enqueue")
+        end
+
+        # Each selector twice: once on a `MessageDelivery` receiver the typer managed to name, and once on
+        # the RESULT of a call to the mailer class, which is the spelling in every Rails codebase.
+        def rows(selector, labels, why:)
+          [
+            EffectAttribution.new(receiver: DELIVERY, method: selector, labels: labels, discharge: true,
+                                  why: why),
+            EffectAttribution.new(receiver: BASE, method: selector, labels: labels, on_result: true,
+                                  discharge: true,
+                                  why: "#{why} Matched on the result of `UserMailer.welcome(u)`, whose " \
+                                       "MessageDelivery has no type the project declares.")
+          ]
+        end
+
+        def edges
+          [
+            EffectEdge.new(
+              receiver: BASE, target: :mailer_body,
+              why: "`UserMailer.welcome(u)` instantiates the mailer and runs `#welcome` — synchronously, " \
+                   "in this process, before any delivery is attempted. The mailer body's own effects " \
+                   "(the records it reads to build the mail) belong to the caller"
+            )
+          ]
+        end
+
+        def entry_points
+          [
+            EffectEntryPoints.new(
+              name: "rails-mailers", globs: ["app/mailers/**/*.rb"],
+              why: "mailer actions — invoked by the framework through the class-method mapping"
+            )
+          ]
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer.rb

@@ -5,6 +5,7 @@ require "rigor/plugin"
 require_relative "actionmailer/mailer_index"
 require_relative "actionmailer/mailer_discoverer"
 require_relative "actionmailer/analyzer"
+require_relative "actionmailer/effects"
 
 module Rigor
   module Plugin
@@ -52,7 +53,13 @@ module Rigor
           "mailer_search_paths" => { kind: :array, default: ["app/mailers"] },
           "mailer_base_classes" => { kind: :array, default: %w[ApplicationMailer ActionMailer::Base] },
           "views_root" => { kind: :string, default: "app/views" }
-        }
+        },
+        # ADR-103 WD10 (#387) — see {Effects} for what each row is and why.
+        effect_root: "rails",
+        effect_labels: ["rails.actionmailer.deliver"],
+        effect_attributions: Effects.attributions,
+        effect_edges: Effects.edges,
+        effect_entry_points: Effects.entry_points
       )
 
       # `watch:` covers every mailer class under `mailer_search_paths` AND every view template under