rigortype 0.3.3 → 0.3.5

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    class Activerecord < Rigor::Plugin::Base
+      # rigor-activerecord's effect contract (ADR-103 WD10; design note § 11.2; issue #387).
+      #
+      # ## The two channels, and which row goes where
+      #
+      # The plugin already ships `sig/active_record/relation.rbs`, so **every `ActiveRecord::Relation`
+      # method it declares carries its own `%a{…}` annotation there** — the tier-1 channel, read as an
+      # accepted signature and therefore discharging (ADR-103 WD6). That file is also where the builder /
+      # materializer split lives, because it is the file that already draws it.
+      #
+      # What is left over lands here, and each item is left over for a reason RBS cannot fix:
+      #
+      # - **`ActiveRecord::Base`'s own surface.** The plugin ships no `ActiveRecord::Base` signature and
+      #   should not: an app's models are typed from `db/schema.rb`, per project, and a generic base-class
+      #   RBS would fight whatever the project's own `rbs collection` supplies.
+      # - **The `Enumerable` delegations on a Relation.** `map`, `filter_map`, `each_with_object` and the
+      #   rest materialise by delegating to `each`, and declaring them in the bundled RBS would change how
+      #   they *type* (`Enumerable#map`'s block-return element type is the whole point of the include).
+      # - **The connection adapter and the migration DSL**, neither of which the plugin types at all.
+      #
+      # ## Why the reads and writes are worth spelling out at all
+      #
+      # An `ActiveRecord::Base` row reaches `User.find` through the project's own
+      # `User < ApplicationRecord < ActiveRecord::Base` lines, so one row covers every model in the app.
+      # That is the whole economy of the framework layer: thirty-odd rows here colour the several thousand
+      # database touches a Rails app performs, and none of them needed a line of application code.
+      module Effects
+        BASE = "ActiveRecord::Base"
+        RELATION = "ActiveRecord::Relation"
+        ADAPTER = "ActiveRecord::ConnectionAdapters::AbstractAdapter"
+        MIGRATION = "ActiveRecord::Migration"
+
+        READ = ["io.db.read"].freeze
+        WRITE = ["io.db.write"].freeze
+        TRANSACTION = ["io.db.transaction"].freeze
+        SCHEMA_WRITE = ["io.db.write", "rails.schema.write"].freeze
+
+        # Class-side finders. Every one issues a `SELECT` the moment it is called — that is what separates
+        # them from `where`, which returns a relation and issues nothing.
+        SINGLETON_READS = %w[
+          find find_by find_by! first first! last last! take take! sole find_sole_by
+          second third fourth fifth forty_two second_to_last third_to_last
+          exists? any? none? one? many? empty? count sum average minimum maximum calculate
+          pluck pick ids find_each find_in_batches in_batches find_by_sql count_by_sql
+          find_or_initialize_by
+        ].freeze
+
+        # Class-side writers.
+        SINGLETON_WRITES = %w[
+          create create! insert insert! insert_all insert_all! upsert upsert_all
+          update update! update_all delete delete_all delete_by destroy destroy_all destroy_by
+          find_or_create_by find_or_create_by! create_or_find_by create_or_find_by! touch_all
+        ].freeze
+
+        # Instance-side readers. `reload` re-issues the `SELECT` and replaces the record's attributes,
+        # which is a receiver mutation as well as a read.
+        INSTANCE_READS = %w[valid? invalid? reload].freeze
+
+        # Instance-side writers. Each is a statement issued now; `save`'s callbacks and validators are the
+        # `effect_edges:` half, and arrive as edges rather than labels.
+        INSTANCE_WRITES = %w[
+          save save! update update! update_attribute update_attributes update_attributes!
+          update_column update_columns destroy destroy! delete touch increment! decrement!
+          toggle! becomes! insert
+        ].freeze
+
+        # The `Enumerable` surface a Relation inherits. Every one of these runs the query, because every
+        # one of them calls `each`.
+        RELATION_MATERIALIZERS = %w[
+          map flat_map filter_map collect collect_concat select filter reject find detect find_all
+          each_with_object each_with_index each_entry each_slice each_cons reduce inject
+          group_by partition sort sort_by min min_by max max_by minmax tally zip
+          take_while drop_while chunk_while slice_when lazy to_set to_h
+          all? any? none? one? include? member? first count sum
+        ].freeze
+
+        # Raw SQL, narrowed by the statement's own leading verb ({Rigor::Effects::Narrowing} `sql_verb`).
+        ADAPTER_SQL = %w[execute exec_query exec_insert exec_update exec_delete select_all select_one
+                         select_value select_values select_rows query query_value query_values].freeze
+
+        # The migration DSL. `rails.schema.write` is the meaning a reviewer names ("this changes the
+        # schema"); `io.db.write` is the transport that makes the summary honest.
+        MIGRATION_DSL = %w[
+          create_table drop_table rename_table change_table create_join_table drop_join_table
+          add_column remove_column rename_column change_column change_column_null
+          change_column_default change_column_comment
+          add_index remove_index rename_index add_reference remove_reference
+          add_foreign_key remove_foreign_key add_check_constraint remove_check_constraint
+          add_timestamps remove_timestamps enable_extension disable_extension
+          execute add_belongs_to remove_belongs_to
+        ].freeze
+
+        ADAPTER_WHY = "raw SQL; the statement's own leading verb narrows the direction, so a literal " \
+                      "`execute(\"UPDATE …\")` reads as a write and a computed string keeps the honest " \
+                      "`io.db`."
+
+        # Ambient AR calls that are neither a read nor a write of rows.
+        TRANSACTIONAL = %w[transaction with_lock lock!].freeze
+
+        module_function
+
+        def attributions
+          singleton_rows + instance_rows + relation_rows + adapter_rows + migration_rows
+        end
+
+        def singleton_rows
+          rows(BASE, SINGLETON_READS, READ, singleton: true,
+                                            why: "issues the SELECT at the call — this is the materializing " \
+                                                 "half of the builder/materializer split") +
+            rows(BASE, SINGLETON_WRITES, WRITE, singleton: true,
+                                                why: "issues an INSERT / UPDATE / DELETE at the call") +
+            rows(BASE, TRANSACTIONAL, TRANSACTION, singleton: true,
+                                                   why: "opens a transaction; the block's own origins join " \
+                                                        "by containment, so the row states only the BEGIN")
+        end
+
+        def instance_rows
+          rows(BASE, INSTANCE_READS, READ,
+               why: "re-reads the row (`reload`) or runs the validators, whose uniqueness checks query") +
+            rows(BASE, INSTANCE_WRITES, WRITE,
+                 why: "persists the record — the write a `db: none` envelope is written to catch") +
+            rows(BASE, TRANSACTIONAL, TRANSACTION,
+                 why: "opens a transaction / takes a row lock around the block")
+        end
+
+        def relation_rows
+          rows(RELATION, RELATION_MATERIALIZERS, READ,
+               why: "an Enumerable delegation on a Relation: it calls `each`, which runs the query. Not " \
+                    "declared in the bundled RBS because declaring it would change how it types")
+        end
+
+        # Two rows per selector, because raw SQL is written two ways and only one of them names a type.
+        # `adapter.execute(sql)` on a receiver the typer managed to name is the first; the second matches
+        # `ActiveRecord::Base.connection.execute(sql)` and `User.connection.exec_query(sql)`, where the
+        # connection object has no declared type but the class that handed it over is written in the source.
+        def adapter_rows
+          ADAPTER_SQL.flat_map do |selector|
+            [
+              EffectAttribution.new(
+                receiver: ADAPTER, method: selector, labels: ["io.db"], narrow: "sql_verb", discharge: true,
+                why: ADAPTER_WHY
+              ),
+              EffectAttribution.new(
+                receiver: BASE, method: selector, labels: ["io.db"], narrow: "sql_verb", on_result: true,
+                discharge: true,
+                why: "#{ADAPTER_WHY} Matched on the result of `Model.connection`, which is how raw SQL is " \
+                     "actually spelled in a Rails app."
+              )
+            ]
+          end
+        end
+
+        def migration_rows
+          rows(MIGRATION, MIGRATION_DSL, SCHEMA_WRITE,
+               why: "the migration DSL issues DDL: `io.db.write` is the transport, `rails.schema.write` " \
+                    "the meaning a `db/migrate/**` envelope names")
+        end
+
+        def rows(receiver, selectors, labels, why:, singleton: false)
+          selectors.map do |selector|
+            EffectAttribution.new(receiver: receiver, method: selector, labels: labels,
+                                  singleton: singleton, discharge: true, why: why)
+          end
+        end
+
+        # ADR-103 WD10 — the one edge ActiveRecord contributes: `save` runs the class body's callbacks and
+        # validators. The engine owns the walk; this names the base class whose descendants it applies to.
+        def edges
+          [
+            EffectEdge.new(
+              receiver: BASE, target: :activerecord_callbacks,
+              why: "`before_save :normalize` / `validate :check` / `after_commit :notify` are real, " \
+                   "synchronous, in-process calls that no syntax at the call site contains"
+            )
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,7 @@ require_relative "activerecord/structure_sql_parser"
 require_relative "activerecord/model_index"
 require_relative "activerecord/model_discoverer"
 require_relative "activerecord/analyzer"
+require_relative "activerecord/effects"
 
 module Rigor
   module Plugin
@@ -72,7 +73,17 @@ module Rigor
         # ADR-26 — `ActiveRecord::Relation` is an "open" receiver: it delegates an unbounded set of
         # user-defined scopes / class methods to its model, so `call.undefined-method` must not fire for
         # it. `CheckRules` reads this manifest field and skips the rule for the class.
-        open_receivers: ["ActiveRecord::Relation"]
+        open_receivers: ["ActiveRecord::Relation"],
+        # ADR-103 WD2 / WD10 (#387) — the effect layer. rigor-activerecord models ActiveRecord, which is
+        # part of Rails, so it opens the framework's own `rails.*` root rather than one named after the
+        # plugin; `effect_root:` is granted only because the engine bundles this plugin
+        # ({Rigor::Plugin::FirstParty}). Every row's justification is in {Effects}, and the
+        # `ActiveRecord::Relation` half is in the bundled `sig/active_record/relation.rbs` instead —
+        # tier 1, because the plugin already ships that signature.
+        effect_root: "rails",
+        effect_labels: ["rails.schema.write"],
+        effect_attributions: Effects.attributions,
+        effect_edges: Effects.edges
       )
 
       # The class the bundled `sig/active_record/relation.rbs` describes; `dynamic_return` contributes

data/plugins/rigor-activerecord/sig/active_record/relation.rbs

@@ -26,6 +26,26 @@
 # `rbs collection`), that definition conflicts with this one and
 # the conflict degrades through Rigor's plugin-RBS failure memo
 # (ADR-25 WD4) — the richer upstream definition simply wins.
+#
+# ## Effect annotations (ADR-103 WD10, issue #387)
+#
+# Every method carries an effect annotation, and the split down
+# the middle of this file is the whole point of the Rails effect
+# layer: a **builder** is `%a{pure}` because it issues nothing —
+# `where` composes an Arel tree and returns a relation — while a
+# **materializer** is `%a{rigor:v1:effect io.db.read}` because it
+# is the call that finally runs the query. A presenter that builds
+# and returns a scope has pure code; the caller that materialises
+# it gets the read. That is the truthful reading of what the code
+# does, not of how Rails developers narrate it.
+#
+# This is the plugin's tier-1 channel: these are *accepted
+# signatures*, so a call site importing one of these bounds is
+# exhaustive rather than tainted (ADR-103 WD6). The methods this
+# file does not declare — `map`, `filter_map` and the rest of the
+# `Enumerable` surface, which materialise by delegating to `each`
+# — are covered by the plugin's `effect_attributions:` instead,
+# because declaring them here would change how they TYPE.
 
 module ActiveRecord
   class Relation[Elem]
@@ -34,149 +54,274 @@ module ActiveRecord
     # `Enumerable` only *requires* `each` (the includer supplies
     # it); it is declared here so `relation.each { |m| ... }`
     # resolves and the block parameter carries the element type.
+    %a{rigor:v1:effect io.db.read}
     def each: () { (Elem) -> void } -> self
             | () -> Enumerator[Elem, self]
 
     # --- query builders (return another relation) ---
+    %a{pure}
     def where: (*untyped) ?{ () -> untyped } -> self
+    %a{pure}
     def rewhere: (*untyped) -> self
+    %a{pure}
     def not: (*untyped) -> self
+    %a{pure}
     def or: (untyped) -> self
+    %a{pure}
     def and: (untyped) -> self
+    %a{pure}
     def order: (*untyped) -> self
+    %a{pure}
     def reorder: (*untyped) -> self
+    %a{pure}
     def in_order_of: (*untyped) -> self
+    %a{pure}
     def limit: (untyped) -> self
+    %a{pure}
     def offset: (untyped) -> self
+    %a{pure}
     def distinct: (?untyped) -> self
+    %a{pure}
     def group: (*untyped) -> self
+    %a{pure}
     def regroup: (*untyped) -> self
+    %a{pure}
     def having: (*untyped) -> self
+    %a{pure}
     def includes: (*untyped) -> self
+    %a{pure}
     def preload: (*untyped) -> self
+    %a{pure}
     def eager_load: (*untyped) -> self
+    %a{pure}
     def joins: (*untyped) -> self
+    %a{pure}
     def left_joins: (*untyped) -> self
+    %a{pure}
     def left_outer_joins: (*untyped) -> self
+    %a{pure}
     def references: (*untyped) -> self
+    %a{pure}
     def select: (*untyped) -> self
+    %a{pure}
     def reselect: (*untyped) -> self
+    %a{pure}
     def unscope: (*untyped) -> self
+    %a{pure}
     def merge: (untyped) -> self
+    %a{pure}
     def except: (*untyped) -> self
+    %a{pure}
     def only: (*untyped) -> self
+    %a{pure}
     def extending: (*untyped) -> self
+    %a{pure}
     def from: (untyped, ?untyped) -> self
+    %a{pure}
     def lock: (?untyped) -> self
+    %a{pure}
     def readonly: (?untyped) -> self
+    %a{pure}
     def strict_loading: (?untyped) -> self
+    %a{pure}
     def create_with: (untyped) -> self
+    %a{pure}
     def none: () -> self
+    %a{pure}
     def all: () -> self
+    %a{pure}
     def unscoped: () -> self
+    %a{pure}
     def default_scoped: () -> self
+    %a{pure}
     def annotate: (*untyped) -> self
+    %a{pure}
     def optimizer_hints: (*untyped) -> self
+    %a{pure}
     def excluding: (*untyped) -> self
+    %a{pure}
     def without: (*untyped) -> self
+    %a{pure}
     def with: (*untyped) -> self
     def scoping: () { () -> untyped } -> untyped
 
     # --- finders (return an element) ---
+    %a{rigor:v1:effect io.db.read}
     def find: (*untyped) -> Elem
+    %a{rigor:v1:effect io.db.read}
     def find_by: (*untyped) -> Elem?
+    %a{rigor:v1:effect io.db.read}
     def find_by!: (*untyped) -> Elem
+    %a{rigor:v1:effect io.db.read}
     def find_sole_by: (*untyped) -> Elem
+    %a{rigor:v1:effect io.db.read}
     def sole: () -> Elem
+    %a{rigor:v1:effect io.db.read}
     def first: () -> Elem?
             | (Integer limit) -> Array[Elem]
+    %a{rigor:v1:effect io.db.read}
     def first!: () -> Elem
+    %a{rigor:v1:effect io.db.read}
     def last: () -> Elem?
            | (Integer limit) -> Array[Elem]
+    %a{rigor:v1:effect io.db.read}
     def last!: () -> Elem
+    %a{rigor:v1:effect io.db.read}
     def take: () -> Elem?
            | (Integer limit) -> Array[Elem]
+    %a{rigor:v1:effect io.db.read}
     def take!: () -> Elem
+    %a{rigor:v1:effect io.db.read}
     def second: () -> Elem?
+    %a{rigor:v1:effect io.db.read}
     def third: () -> Elem?
+    %a{rigor:v1:effect io.db.read}
     def fourth: () -> Elem?
+    %a{rigor:v1:effect io.db.read}
     def fifth: () -> Elem?
+    %a{rigor:v1:effect io.db.read}
     def forty_two: () -> Elem?
+    %a{rigor:v1:effect io.db.read}
     def second_to_last: () -> Elem?
+    %a{rigor:v1:effect io.db.read}
     def third_to_last: () -> Elem?
 
     # --- batched enumeration ---
+    %a{rigor:v1:effect io.db.read}
     def find_each: (**untyped) ?{ (Elem) -> void } -> untyped
+    %a{rigor:v1:effect io.db.read}
     def find_in_batches: (**untyped) ?{ (Array[Elem]) -> void } -> untyped
+    %a{rigor:v1:effect io.db.read}
     def in_batches: (**untyped) ?{ (ActiveRecord::Relation[Elem]) -> void } -> untyped
 
     # --- scalars / aggregates ---
+    %a{rigor:v1:effect io.db.read}
     def count: (*untyped) ?{ (Elem) -> untyped } -> untyped
+    %a{rigor:v1:effect io.db.read}
     def sum: (*untyped) ?{ (Elem) -> untyped } -> untyped
+    %a{rigor:v1:effect io.db.read}
     def average: (untyped) -> untyped
+    %a{rigor:v1:effect io.db.read}
     def minimum: (untyped) -> untyped
+    %a{rigor:v1:effect io.db.read}
     def maximum: (untyped) -> untyped
+    %a{rigor:v1:effect io.db.read}
     def calculate: (*untyped) -> untyped
+    %a{rigor:v1:effect io.db.read}
     def pluck: (*untyped) -> Array[untyped]
+    %a{rigor:v1:effect io.db.read}
     def pick: (*untyped) -> untyped
+    %a{rigor:v1:effect io.db.read}
     def ids: () -> Array[untyped]
+    %a{rigor:v1:effect io.db.read}
     def size: () -> Integer
+    %a{rigor:v1:effect io.db.read}
     def length: () -> Integer
+    %a{rigor:v1:effect io.db.read}
     def empty?: () -> bool
+    %a{rigor:v1:effect io.db.read}
     def any?: (*untyped) ?{ (Elem) -> boolish } -> bool
+    %a{rigor:v1:effect io.db.read}
     def none?: (*untyped) ?{ (Elem) -> boolish } -> bool
+    %a{rigor:v1:effect io.db.read}
     def one?: (*untyped) ?{ (Elem) -> boolish } -> bool
+    %a{rigor:v1:effect io.db.read}
     def many?: () ?{ (Elem) -> boolish } -> bool
+    %a{rigor:v1:effect io.db.read}
     def exists?: (*untyped) -> bool
+    %a{rigor:v1:effect io.db.read}
     def include?: (untyped) -> bool
+    %a{rigor:v1:effect io.db.read}
     def member?: (untyped) -> bool
 
     # --- conversion / state ---
+    %a{rigor:v1:effect io.db.read}
     def to_a: () -> Array[Elem]
+    %a{rigor:v1:effect io.db.read}
     def to_ary: () -> Array[Elem]
+    %a{rigor:v1:effect io.db.read}
     def entries: () -> Array[Elem]
+    %a{rigor:v1:effect io.db.read}
     def load: (?untyped) -> self
+    %a{rigor:v1:effect io.db.read}
     def reload: () -> self
+    %a{pure}
     def reset: () -> self
+    %a{pure}
     def loaded?: () -> bool
+    %a{pure}
     def to_sql: () -> String
+    %a{rigor:v1:effect io.db.read}
     def explain: (*untyped) -> String
+    %a{rigor:v1:effect io.db.read}
     def cache_key: (?untyped) -> String
+    %a{rigor:v1:effect io.db.read}
     def cache_version: (?untyped) -> untyped
+    %a{rigor:v1:effect io.db.read}
     def to_json: (*untyped) -> String
+    %a{rigor:v1:effect io.db.read}
     def as_json: (?untyped) -> untyped
+    %a{rigor:v1:effect io.db.read}
     def blank?: () -> bool
+    %a{rigor:v1:effect io.db.read}
     def present?: () -> bool
+    %a{pure}
     def klass: () -> untyped
+    %a{pure}
     def model: () -> untyped
+    %a{pure}
     def table: () -> untyped
+    %a{pure}
     def arel: () -> untyped
 
     # --- whole-relation persistence ---
+    %a{rigor:v1:effect io.db.write}
     def update_all: (untyped) -> Integer
+    %a{rigor:v1:effect io.db.write}
     def delete_all: () -> Integer
+    %a{rigor:v1:effect io.db.write}
     def destroy_all: () -> Array[Elem]
+    %a{rigor:v1:effect io.db.write}
     def update: (*untyped) -> untyped
+    %a{rigor:v1:effect io.db.write}
     def update!: (*untyped) -> untyped
+    %a{rigor:v1:effect io.db.write}
     def delete_by: (*untyped) -> Integer
+    %a{rigor:v1:effect io.db.write}
     def destroy_by: (*untyped) -> Array[Elem]
+    %a{rigor:v1:effect io.db.write}
     def touch_all: (*untyped) -> Integer
+    %a{rigor:v1:effect io.db.write}
     def insert_all: (untyped, **untyped) -> untyped
+    %a{rigor:v1:effect io.db.write}
     def insert_all!: (untyped, **untyped) -> untyped
+    %a{rigor:v1:effect io.db.write}
     def upsert_all: (untyped, **untyped) -> untyped
 
     # --- instantiating builders (return an element) ---
+    %a{pure}
     def new: (*untyped) ?{ (Elem) -> void } -> Elem
+    %a{pure}
     def build: (*untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.write}
     def create: (*untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.write}
     def create!: (*untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.write}
     def find_or_create_by: (untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.write}
     def find_or_create_by!: (untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.read}
     def find_or_initialize_by: (untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.write}
     def create_or_find_by: (untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.write}
     def create_or_find_by!: (untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.write}
     def first_or_create: (?untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.write}
     def first_or_create!: (?untyped) ?{ (Elem) -> void } -> Elem
+    %a{rigor:v1:effect io.db.read}
     def first_or_initialize: (?untyped) ?{ (Elem) -> void } -> Elem
   end
 end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    class Activestorage < Rigor::Plugin::Base
+      # rigor-activestorage's effect contract (ADR-103 WD10; design note § 11.2; issue #387).
+      #
+      # ActiveStorage is the design note's argument for framework labels in miniature: the *transport* is
+      # whatever `config/storage.yml` names — the local disk, S3, GCS — and is therefore statically
+      # unknowable, while the *operation* is fixed. So every row carries bare `io` for the transport and
+      # `rails.activestorage.read` / `.write` for the meaning, which is the half a policy can grip.
+      #
+      # Almost every write is also an `io.db.write`: an attachment is a row in `active_storage_attachments`
+      # and a blob is a row in `active_storage_blobs`, so `user.avatar.attach(io)` really does touch the
+      # database whether or not the bytes go to S3. A "no database writes on this path" envelope is right
+      # to object, and would be wrong not to.
+      module Effects
+        ATTACHED_ONE = "ActiveStorage::Attached::One"
+        ATTACHED_MANY = "ActiveStorage::Attached::Many"
+        BLOB = "ActiveStorage::Blob"
+        ATTACHMENT = "ActiveStorage::Attachment"
+
+        READ = ["io", "rails.activestorage.read"].freeze
+        WRITE = ["io", "rails.activestorage.write", "io.db.write"].freeze
+        # `download` / `open` pull bytes out of the service and touch no row.
+        PURE_READ = ["io", "rails.activestorage.read"].freeze
+
+        ATTACH_TARGETS = [ATTACHED_ONE, ATTACHED_MANY].freeze
+
+        module_function
+
+        def attributions
+          attach_rows + blob_rows
+        end
+
+        def attach_rows
+          ATTACH_TARGETS.flat_map do |receiver|
+            [
+              row(receiver, :attach, WRITE,
+                  "uploads the bytes to the configured service AND inserts the attachment + blob rows"),
+              row(receiver, :purge, WRITE, "deletes the stored file and the attachment + blob rows"),
+              row(receiver, :purge_later, WRITE,
+                  "enqueues the purge; the attachment row is detached now, so the database write is here"),
+              row(receiver, :detach, ["io.db.write"], "removes the attachment row and touches no service"),
+              row(receiver, :download, PURE_READ, "pulls the bytes back out of the service"),
+              row(receiver, :open, PURE_READ, "streams the bytes into a tempfile")
+            ]
+          end
+        end
+
+        def blob_rows
+          [
+            row(BLOB, :download, PURE_READ, "reads the object out of the storage service"),
+            row(BLOB, :open, PURE_READ, "streams the object into a tempfile"),
+            row(BLOB, :upload, WRITE, "writes the object to the service and records its checksum"),
+            row(BLOB, :purge, WRITE, "deletes the object and its row"),
+            row(BLOB, :purge_later, WRITE, "enqueues the object's deletion; the row goes now"),
+            row(BLOB, :create_and_upload!, WRITE, "inserts the blob row and uploads in one call",
+                singleton: true),
+            row(BLOB, :url, READ, "signs a URL against the service, which for some services is a request"),
+            row(ATTACHMENT, :purge, WRITE, "deletes the stored file and the attachment row"),
+            row(ATTACHMENT, :download, PURE_READ, "reads the attached object out of the service")
+          ]
+        end
+
+        def row(receiver, selector, labels, why, singleton: false)
+          EffectAttribution.new(receiver: receiver, method: selector, labels: labels,
+                                singleton: singleton, discharge: true,
+                                why: "#{why}; the transport is bare `io` because `config/storage.yml` " \
+                                     "decides it per environment and no static reading can")
+        end
+      end
+    end
+  end
+end

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

@@ -5,6 +5,7 @@ require "rigor/plugin"
 require_relative "activestorage/attachment_discoverer"
 require_relative "activestorage/attachment_index"
 require_relative "activestorage/analyzer"
+require_relative "activestorage/effects"
 
 module Rigor
   module Plugin
@@ -41,7 +42,11 @@ module Rigor
         config_schema: {
           "model_search_paths" => { kind: :array, default: ["app/models"] }
         },
-        consumes: [{ plugin_id: "activerecord", name: :model_index, optional: true }]
+        consumes: [{ plugin_id: "activerecord", name: :model_index, optional: true }],
+        # ADR-103 WD10 (#387) — see {Effects} for what each row is and why.
+        effect_root: "rails",
+        effect_labels: %w[rails.activestorage.read rails.activestorage.write],
+        effect_attributions: Effects.attributions
       )
 
       # Cached: attachment index. Walks every `.rb` file under `model_search_paths` for `has_*_attached`