rigortype 0.3.9 → 0.4.0

data/plugins/rigor-active-model-serializers/lib/rigor/plugin/active_model_serializers.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "active_model_serializers/serializer_index"
+require_relative "active_model_serializers/serializer_discoverer"
+
+module Rigor
+  module Plugin
+    # rigor-active-model-serializers — types the implicit-self `object` reader inside a serializer as the
+    # model the serializer serializes.
+    #
+    # It emits no diagnostic. What it contributes is one return type and the gem's own framework
+    # constants, and both exist for the same measurement: the 2026-09-01 corpus opacity sweep (#534
+    # item 6) found `object` to be Mastodon's single largest unresolved implicit-self send — 751 sites in
+    # `app/serializers` alone — with no plugin owning ActiveModelSerializers at all. Every
+    # `object.account.username` chain below one of those sites was dispatching on `Dynamic[top]`.
+    #
+    #     plugins:
+    #       - gem: rigor-active-model-serializers
+    #         config:
+    #           serializer_search_paths: ["app/serializers", "app/lib"]  # default; optional
+    #           serializer_base_classes: ["ActiveModel::Serializer"]     # default; optional
+    #           model_overrides: {}                                      # default; optional
+    #
+    # ## What `object` types to, and when it declines
+    #
+    # AMS's `object` is `ActiveModel::Serializer#object`, the resource the serializer was constructed
+    # with. Nothing in a serializer's source STATES that resource's class — AMS binds it at `new` time —
+    # so the type is only ever derived, and two independent things have to agree before it is:
+    #
+    # 1. The `<Model>Serializer` naming convention resolves to exactly one model `rigor-activerecord`
+    #    discovered (`REST::AccountSerializer` → `Account`), and
+    # 2. that model ANSWERS the serializer: every name the serializer will read off its resource — the
+    #    `attributes` / `has_many` / `has_one` declarations it does not define itself, plus every
+    #    `object.<name>` in its body — is a column, association, enum, alias or scope of that model, or a
+    #    method the project defines on it.
+    #
+    # A `model_overrides` entry short-circuits both: the project asserted the answer. Anything else
+    # DECLINES, and `object` keeps whatever the engine would have given it (`Dynamic`).
+    #
+    # ## Why the name alone is not enough
+    #
+    # The name is a guess and the model index only proves the guessed class EXISTS, never that this
+    # serializer serializes it. Mastodon has three serializers where the guess is wrong and the class is
+    # real: `REST::ConversationSerializer` serializes an `AccountConversation` (its `unread`,
+    # `participant_accounts` and `last_status` are all absent from `Conversation`), and both
+    # `REST::InstanceSerializer` and `REST::V1::InstanceSerializer` serialize an `InstancePresenter`
+    # (`object.contact`, `object.thumbnail`). A corpus diff cannot see the damage, because an Active
+    # Record model's surface is open and a wrong-but-real model absorbs every read in silence — so the
+    # check has to be a positive one, made before the answer is contributed.
+    #
+    # Requiring EVERY name to be answered, rather than most of them, is the same choice: a serializer
+    # whose resource is a decorator around the model shares most of the model's surface, and it is
+    # exactly the one or two extra names that say so.
+    #
+    # ## Scope
+    #
+    # - **SimpleForm inputs are NOT handled.** The sweep's 875-site `object` count mixes AMS serializers
+    #   with `SimpleForm::Inputs::Base#object`, a different gem with a different resource story
+    #   (`object` there is the form's record, named by the `simple_form_for` call site, not by the input
+    #   class). That belongs in a `rigor-simple-form` plugin and is deliberately left out.
+    # - **`serializer:` / `each_serializer:` options are not read.** `has_many :emojis, serializer:
+    #   REST::CustomEmojiSerializer` states which serializer renders an association, never which model a
+    #   serializer serializes, so it cannot ground `object`.
+    # - **A serializer with no declarations and no `object` reads gets no answer.** There is nothing to
+    #   check the name against, and the name alone is what this refuses to trust.
+    class ActiveModelSerializers < Rigor::Plugin::Base
+      manifest(
+        id: "active-model-serializers",
+        target_gems: ["active_model_serializers"],
+        version: "0.1.0",
+        description: "Types the implicit-self `object` reader inside ActiveModel::Serializer subclasses " \
+                     "as the serializer's model, and declares the gem's framework constants.",
+        config_schema: {
+          # `app/lib` is in the default set because a project base serializer routinely lives outside
+          # `app/serializers` — Mastodon's `ActivityPub::Serializer`, the parent of 60 of its 153
+          # serializers, is at `app/lib/activitypub/serializer.rb`. Without it the ancestry closure stops
+          # at the base class and two fifths of the project's serializers are simply not serializers as
+          # far as this plugin is concerned. A directory the project does not have costs one probe.
+          "serializer_search_paths" => { kind: :array, default: ["app/serializers", "app/lib"] },
+          "serializer_base_classes" => { kind: :array, default: ["ActiveModel::Serializer"] },
+          # Serializer class name => model class name, for the resources the derivation cannot reach: a
+          # serializer whose resource is a presenter or a decorator, or one named for a JSON shape rather
+          # than a model. An override is the project's own assertion and is NOT re-checked — a project
+          # that names a class Rigor has no RBS for gets a lenient nominal.
+          "model_overrides" => { kind: :hash, default: {} }
+        },
+        # Optional on purpose: without `rigor-activerecord` there is no model set to check a name
+        # against, and every non-overridden serializer declines. That is the designed degradation — the
+        # plugin contributes less, never something wrong.
+        consumes: [{ plugin_id: "activerecord", name: :model_index, optional: true }],
+        # ADR-25 (#534 item 7, same admission rule as `rigor-activerecord`'s `sig/active_record/
+        # framework.rbs`) — the gem's own constants, declared so they resolve and asserting nothing else.
+        signature_paths: ["sig"],
+        # ADR-26 — every class and module the bundled signature names is open, so that declaring it buys
+        # constant resolution and asserts nothing about a member. `ActiveModel::Serializer` is the row
+        # that matters most (a project's serializers inherit from it, and its whole instance surface —
+        # `object`, `scope`, `read_attribute_for_serialization`, the `_attributes` class state — is
+        # unenumerated), and `ActiveModelSerializers` / `::Adapter` are the ones the canonical
+        # initializer dispatches on: `ActiveModelSerializers.config.adapter = :json_api` and
+        # `ActiveModelSerializers::Adapter.register(...)` are what an AMS `config/initializers` file says.
+        open_receivers: [
+          "ActiveModel::Serializer",
+          "ActiveModel::Serializer::CollectionSerializer",
+          "ActiveModelSerializers",
+          "ActiveModelSerializers::Adapter",
+          "ActiveModelSerializers::Model",
+          "ActiveModelSerializers::SerializableResource"
+        ]
+      )
+
+      producer :serializer_index, watch: -> { [[@serializer_search_paths, "**/*.rb"]] } do |_params|
+        SerializerDiscoverer.new(
+          io_boundary: io_boundary,
+          search_paths: @serializer_search_paths,
+          base_classes: @serializer_base_classes
+        ).discover
+      end
+
+      def init(_services)
+        @serializer_search_paths = Array(config.fetch("serializer_search_paths")).map(&:to_s)
+        @serializer_base_classes = Array(config.fetch("serializer_base_classes")).map(&:to_s)
+        @model_overrides = config.fetch("model_overrides").to_h { |k, v| [k.to_s.delete_prefix("::"), v.to_s] }
+        @derivations = {}
+      end
+
+      # The `methods:` gate keeps this off every dispatch whose name is not `object`; the receiver and
+      # argument checks keep it off `foo.object` and `object(x)`, neither of which is the AMS reader.
+      dynamic_return methods: [:object] do |call_node, scope|
+        next nil unless call_node.is_a?(Prism::CallNode)
+        next nil unless call_node.receiver.nil?
+        next nil unless call_node.arguments.nil?
+
+        entry = serializer_entry(scope)
+        next nil if entry.nil?
+        # An explicit `def object`, here or on an ancestor, is the definition that runs. Answering over
+        # it would replace a type the engine derived from real source with a guess, and silence whatever
+        # that source proves.
+        next nil if entry.defines_object? || project_defines_object?(entry.class_name, scope)
+
+        model_name = model_class_name_for(entry, scope)
+        next nil if model_name.nil?
+
+        Rigor::Type::Combinator.nominal_of(model_name)
+      end
+
+      private
+
+      # The discovered serializer whose body `self` is in, or nil. Membership of the index is the only
+      # gate: a `*Serializer` name is not evidence of anything, since `object` is an ordinary method name
+      # that a `Json::ConversationSerializer` or an `Oj::AccountSerializer` may define for itself.
+      def serializer_entry(scope)
+        self_type = scope&.self_type
+        return nil unless self_type.respond_to?(:class_name)
+
+        name = self_type.class_name
+        return nil if name.nil? || name.empty?
+
+        producer_value(:serializer_index)&.find(name)
+      end
+
+      def project_defines_object?(serializer_name, scope)
+        return false unless scope.respond_to?(:user_def_through_ancestors)
+
+        !scope.user_def_through_ancestors(serializer_name, :object).first.nil?
+      end
+
+      # The model a serializer serializes, or nil where nothing corroborates it. Memoised per serializer
+      # class INCLUDING the nil answer: the ancestor walks behind `project_defines?` are run once per
+      # name per serializer, and `object` is read hundreds of times across a real `app/serializers`.
+      def model_class_name_for(entry, scope)
+        return @derivations[entry.class_name] if @derivations.key?(entry.class_name)
+
+        @derivations[entry.class_name] = derive_model_class_name(entry, scope)
+      end
+
+      def derive_model_class_name(entry, scope)
+        override = @model_overrides[entry.class_name]
+        return override unless override.nil? || override.empty?
+
+        # The published `:model_index` fact is a Hash keyed by the model's DE-ROOTED constant path
+        # (#583). `rigor-activerecord` withholds it entirely in reduced mode (no `db/schema.rb` /
+        # `db/structure.sql`), so a schema-less project declines here rather than typing `object` off a
+        # name alone.
+        index = read_fact(plugin_id: "activerecord", name: :model_index)
+        return nil if index.nil? || index.empty?
+
+        resolved = convention_candidates(entry.class_name).select { |candidate| index.key?(candidate) }
+        # Two readings that both name a real model (`Admin::AccountSerializer` where `Admin::Account` and
+        # `Account` both exist) is an ambiguity, not a first-hit: nothing here ranks one above the other.
+        return nil unless resolved.size == 1
+
+        model = resolved.first
+        answers?(entry, index.fetch(model), model, scope) ? model : nil
+      end
+
+      # Whether the model ANSWERS the serializer — see the class comment for why this is required and why
+      # it is required of every name rather than most of them. A serializer that declares nothing and
+      # reads nothing states nothing to check, and is declined for that reason rather than admitted for
+      # it.
+      def answers?(entry, row, model_name, scope)
+        declarations = entry.unhandled_declarations
+        reads = entry.resource_reads
+        return false if declarations.empty? && reads.empty?
+
+        members = model_members(row)
+        # A declaration the serializer itself renders is not a read of the resource at all. The entry
+        # subtracts the serializer's OWN methods; a base serializer's `def formatted` is only visible to
+        # the engine's ancestor walk, and a declaration it handles says nothing about the model.
+        declarations.all? do |name|
+          project_defines?(entry.class_name, name, scope) ||
+            members.include?(name) || project_defines?(model_name, name, scope)
+        end && reads.all? { |name| members.include?(name) || project_defines?(model_name, name, scope) }
+      end
+
+      # Every name the model answers that its `:model_index` row states. The `?` forms are Active
+      # Record's own per-column predicates, which a serializer reads as readily as the column.
+      #
+      # `macro_methods` (#1049) is the row's name-only set: `delegate`'s methods, the Paperclip / Active
+      # Storage attachment readers, and an `enum`'s per-value predicates, from the model body and from every
+      # concern the model includes. It is what lets `REST::AccountSerializer`'s `followers_count` / `user` /
+      # `avatar` reads resolve; an older producer that does not publish the key reads as the empty set here,
+      # which declines exactly as before rather than erroring.
+      def model_members(row)
+        columns = Array(row[:columns]).map(&:to_s)
+        associations = Array(row[:associations]).map { |a| a[:name].to_s }
+        enums = row[:enums].is_a?(Hash) ? row[:enums].keys.map(&:to_s) : []
+        aliases = row[:aliases].is_a?(Hash) ? row[:aliases].keys.map(&:to_s) : []
+        scopes = Array(row[:scopes]).map(&:to_s)
+        macros = Array(row[:macro_methods]).map(&:to_s)
+        (columns + columns.map { |c| "#{c}?" } + associations + enums + aliases + scopes + macros).to_set
+      end
+
+      # A method the project writes in Ruby on `class_name` or an ancestor of it. On the model side that
+      # is `Account#local?` or a concern's reader — the model index cannot see these, and without them
+      # the check would decline nearly every real serializer. On the serializer side it is a base
+      # serializer's own rendering method, which is not a read of the resource at all.
+      def project_defines?(class_name, method_name, scope)
+        return false unless scope.respond_to?(:user_def_through_ancestors)
+
+        !scope.user_def_through_ancestors(class_name, method_name.to_sym).first.nil?
+      end
+
+      # `REST::AccountSerializer` offers two readings — the namespaced `REST::Account` and the
+      # demodulized `Account` — and Rails apps use both (`Admin::AccountSerializer` for `Admin::Account`
+      # is as real as Mastodon's `REST::AccountSerializer` for `Account`). Both are offered to the model
+      # index, and exactly one of them has to land.
+      def convention_candidates(serializer_name)
+        return [] unless serializer_name.end_with?("Serializer")
+        # A class named exactly `Serializer` is a namespace's base serializer, never a model's.
+        return [] if serializer_name.split("::").last == "Serializer"
+
+        stripped = serializer_name.delete_suffix("Serializer").delete_suffix("::")
+        return [] if stripped.empty?
+
+        [stripped, stripped.split("::").last].uniq.reject(&:empty?)
+      end
+    end
+
+    Rigor::Plugin.register(ActiveModelSerializers)
+  end
+end

data/plugins/rigor-active-model-serializers/lib/rigor-active-model-serializers.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Gem entry point. Required by Rigor's plugin loader when `.rigor.yml` lists
+# `rigor-active-model-serializers` under `plugins:`. The loader expects this `require` to side-effect a
+# call to `Rigor::Plugin.register`, which the body of
+# `lib/rigor/plugin/active_model_serializers.rb` performs at load time.
+require_relative "rigor/plugin/active_model_serializers"

data/plugins/rigor-active-model-serializers/sig/active_model_serializers.rbs

@@ -0,0 +1,45 @@
+# The ActiveModelSerializers gem's own constants — issue #534 item 6.
+#
+# The 2026-09-01 corpus opacity sweep counted `ActiveModel::Serializer` 101 times on Mastodon,
+# `ActiveModelSerializers::Model` 29 and `ActiveModelSerializers::SerializableResource` 25, every
+# one of them resolving to `untyped` because nothing in the bundle named the constant. This file
+# names them, and nothing more.
+#
+# ## The admission rule
+#
+# The same rule `plugins/rigor-activerecord/sig/active_record/framework.rbs` states: declaring a
+# constant makes it RBS-KNOWN, and a known class with an incomplete signature turns every member the
+# signature omits into a false `call.undefined-method`. Every class here is therefore ALSO listed in
+# the manifest's `open_receivers:` (ADR-26), which is what keeps the members this file does not
+# enumerate lenient.
+#
+# That pairing is load-bearing rather than defensive here, because — unlike the Active Record
+# exception hierarchy, which is rescued and not dispatched on — `ActiveModel::Serializer` and
+# `ActiveModelSerializers::Model` are exactly the "class a project INHERITS from" shape the Active
+# Record file declines to declare. `class REST::AccountSerializer < ActiveModel::Serializer` is what
+# an AMS application looks like, and `object`, `scope`, `read_attribute_for_serialization`,
+# `attributes`, `has_many` and the rest of the AMS surface are not enumerated below. The Mastodon
+# before/after diff recorded in `docs/notes/20260917-ams-object-recognizer.md` is the evidence that
+# the pairing holds on a real application.
+#
+# `ActiveModel` is declared as a module by `rigor-activerecord` as well; RBS reopens a module across
+# files, so the two declarations compose rather than collide, and neither plugin depends on the
+# other being enabled.
+
+module ActiveModel
+  class Serializer
+    class CollectionSerializer
+    end
+  end
+end
+
+module ActiveModelSerializers
+  class Model
+  end
+
+  class SerializableResource
+  end
+
+  module Adapter
+  end
+end

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

@@ -49,6 +49,7 @@ module Rigor
           "shoryuken" => ["io.net"], "backburner" => ["io.net"], "sucker_punch" => [],
           "async" => [], "inline" => [], "test" => []
         }.freeze
+        Ractor.make_shareable(TRANSPORTS)
 
         # The meaning half, which is adapter-independent and is what a policy actually names.
         MEANING = ["rails.activejob.enqueue", "job.enqueue"].freeze

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

@@ -129,12 +129,12 @@ module Rigor
         services.fact_store.publish(plugin_id: manifest.id, name: :reachability_roots, value: roots)
       end
 
-      # File-level only: the load-error emission. Per-call arity validation runs over the engine-owned
+      # File-level only: the load-error disclosure. Per-call arity validation runs over the engine-owned
       # walk via the node_rule below (ADR-37). The job index is lazily loaded + memoised by
       # `producer_value`, shared by both surfaces.
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         index = producer_value(:job_index)
-        return [load_error_diagnostic(path)] if index.nil? && producer_error(:job_index)
+        disclose_load_error if index.nil? && producer_error(:job_index)
 
         []
       end
@@ -148,10 +148,14 @@ module Rigor
 
       private
 
-      def load_error_diagnostic(path)
+      # Issue #1056 — "the job index did not load" is a fact about the run's INPUTS, not about the file being
+      # analysed, so it is registered rather than returned: see {Plugin::Base#disclose_once} for the
+      # channel, the `(plugin id, key)` de-duplication and why the engine positions it at `.rigor.yml:1:1`.
+      # Returned from the per-file hook it carried no once-guard at all and repeated on every file.
+      def disclose_load_error
         error = producer_error(:job_index)
-        Rigor::Analysis::Diagnostic.new(
-          path: path, line: 1, column: 1,
+        disclose_once(
+          :job_index_load_failed,
           message: "rigor-activejob: failed to discover jobs: #{error.class}: #{error.message}",
           severity: :warning,
           rule: "load-error"

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

@@ -13,13 +13,15 @@ module Rigor
       # | Method | Recognised arg shape | Validation |
       # | --- | --- | --- |
       # | `Model.find(id)` | any positional | arity check (1+ args) |
+      # | `Model.find { … }` | a block, no args | none (`Enumerable#find`) |
       # | `Model.find_by(col: v, ...)` | keyword args | each key must be a column |
       # | `Model.where(col: v, ...)` | keyword args | each key must be a column |
       # | `Model.where(string)` | String literal | parser-side; not validated |
       #
       # Successful matches surface as `:info` diagnostics naming the resolved table; unknown columns
       # surface as `:error`. Calls whose receiver is not a model in the index, and calls with
-      # non-keyword arguments to `where` / `find_by`, stay silent.
+      # non-keyword arguments to `where` / `find_by`, stay silent. A model's own `self.find` owns its arity,
+      # so the arity check and the notes for the forms the return-type tier leaves to it stay silent too.
       class Analyzer
         # Methods that take a column → value Hash and need each key validated against the receiver's
         # column set. The bang variants (`find_by!` raises instead of returning nil; `find_or_create_by!`
@@ -35,9 +37,13 @@ module Rigor
 
         attr_reader :diagnostics
 
-        def initialize(path:, model_index:)
+        # `scope` is the file's entry scope, which carries the project's discovered methods; it answers
+        # whether a model defines its own `self.find`. An editor run seeds none, so there the check misses
+        # even a same-file `self.find` the typer sees (#1329).
+        def initialize(path:, model_index:, scope:)
           @path = path
           @model_index = model_index
+          @scope = scope
           @diagnostics = []
         end
 
@@ -69,16 +75,42 @@ module Rigor
           end
         end
 
+        # A block turns `find` into `Enumerable#find` over `all` (see `Activerecord#block_find_return_type`),
+        # which takes no id, so the zero-argument check applies only to the block-less id lookup.
+        #
+        # The arity check and the notes describe Rails' `find`. A model's own `self.find` has its own arity,
+        # and the return-type tier (`Activerecord#finder_return_type`) leaves the multi-id and block forms to
+        # it, so a note there would claim a type the call does not get. One id still types as the model.
         def validate_find(node, entry)
+          return validate_block_find(node, entry) if node.block
+
           arity = call_argument_count(node)
           if arity.zero?
+            return if own_find?(entry)
+
             push_error(node, "wrong-arity",
                        "`#{entry.class_name}.find` expects at least 1 argument, got 0")
             return
           end
+          return if arity >= 2 && own_find?(entry)
 
+          returned = arity >= 2 ? "Array[#{entry.class_name}]" : entry.class_name
           push_info(node, "model-call",
-                    "`#{entry.class_name}.find` returns #{entry.class_name} (table: `#{entry.table_name}`)")
+                    "`#{entry.class_name}.find` returns #{returned} (table: `#{entry.table_name}`)")
+        end
+
+        def validate_block_find(node, entry)
+          return unless call_argument_count(node).zero?
+          return if own_find?(entry)
+
+          push_info(node, "model-call",
+                    "`#{entry.class_name}.find` returns #{entry.class_name} | nil (table: `#{entry.table_name}`)")
+        end
+
+        # The predicate `Activerecord#finder_return_type` declines on, so the note and the type agree in a
+        # CLI run. In an editor run this scope lacks the file's own methods (#1329).
+        def own_find?(entry)
+          @scope.discovered_method_through_ancestors?(entry.class_name, :find, :singleton)
         end
 
         def validate_column_hash_call(node, entry)

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

@@ -38,32 +38,55 @@ module Rigor
 
         READ = ["io.db.read"].freeze
         WRITE = ["io.db.write"].freeze
+        READ_WRITE = ["io.db.read", "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.
+        # them from `where`, which returns a relation and issues nothing. An `async_*` calculation schedules
+        # it on the async executor, or runs it at once when there is none. `first_or_initialize` is
+        # `first || new`, and `extract_associated` loads the association it preloads.
         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
+          second second! third third! fourth fourth! fifth fifth! forty_two forty_two!
+          second_to_last second_to_last! third_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
+          find_or_initialize_by first_or_initialize extract_associated
+          async_ids async_count async_average async_minimum async_maximum async_sum async_pluck async_pick
         ].freeze
 
-        # Class-side writers.
+        # Class-side writers that issue their statement and query nothing of their own: `create` is
+        # `new(…).save`, the bulk writers compile one `INSERT`, and the counter writers are an `update_all` on
+        # `unscoped`, which cannot eager-load.
         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
+          update_counters increment_counter decrement_counter
+        ].freeze
+
+        # Class-side writers that query as well, checked against activerecord 8.1.3.1. Most are in
+        # `Querying::QUERYING_METHODS`, which Rails delegates to `all`, so each is the Relation method of the
+        # same name and the row carries the read that `relation.rbs` gives it: a lookup before the write, a
+        # `find_by!` after a failed insert, the records `destroy_all` loads, or the `SELECT` of distinct
+        # primary keys an eager-loading, limited scope runs before its UPDATE / DELETE. `all` adds the default
+        # scope, which can eager-load. `delete` is `where(id:).delete_all`, and `destroy` calls `find`. Three
+        # are not delegated and read on their own: `update(!)` calls `find` or walks `all.each`, and
+        # `reset_counters` counts the association before it writes the column.
+        SINGLETON_READ_WRITES = %w[
+          update update! update_all delete delete_all delete_by destroy destroy_all destroy_by touch_all
+          find_or_create_by find_or_create_by! create_or_find_by create_or_find_by!
+          first_or_create first_or_create! reset_counters
         ].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-side writers. Each is a statement issued now, and none queries on its own: `update` is
+        # `assign_attributes` plus `save`, and `increment!` / `update_columns` compile one UPDATE. What `save`
+        # or `destroy` reads beyond that comes from the model's callbacks and validators. The callback edge
+        # carries the ones it reads: symbol-argument callback macros and a uniqueness validator. Nothing
+        # carries the reads a required `belongs_to`, a `touch:` option or a `dependent:` option registers.
         INSTANCE_WRITES = %w[
           save save! update update! update_attribute update_attributes update_attributes!
           update_column update_columns destroy destroy! delete touch increment! decrement!
@@ -80,6 +103,26 @@ module Rigor
           all? any? none? one? include? member? first count sum
         ].freeze
 
+        # The writers an association's `CollectionProxy` defines, plus its `delete` / `destroy`, which
+        # override a plain Relation's own `delete(id_or_array)` / `destroy(id)`. Those are
+        # `where(id:).delete_all` and `find(id).destroy`, both inside this row's labels. Each adds records
+        # to the association's in-memory target or removes them from it. Depending on whether the owner is
+        # saved and on the association's `dependent:` option, it may also read, write, and open a
+        # transaction, so the row names all three rather than the parent `io.db`, which
+        # `--label io.db.write` would not match.
+        #
+        # The mutation is spelt from the call site, as every row here is, and bare `mutate` is the label
+        # for a receiver that is not the caller's `self`: the proxy is an object the caller holds, like the
+        # session in rigor-actionpack's `SESSION_WRITE`. The RBS envelopes on `build` / `reset` are written
+        # from the callee's side instead, and say `mutate.self`.
+        #
+        # A saved owner's `<<` saves the record, which runs the model's `before_save` / `after_commit`
+        # callbacks. No edge carries those to the caller, which is the same gap `Relation#create` has: the
+        # call site's receiver is `Relation[Post]`, and the edge that would reach `Post#save` needs the type
+        # argument, which the collector does not record (#1313).
+        PROXY_WRITERS = %w[<< push append concat replace delete destroy clear].freeze
+        PROXY_WRITE = ["io.db.read", "io.db.write", "io.db.transaction", "mutate"].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
@@ -103,6 +146,12 @@ module Rigor
         # Ambient AR calls that are neither a read nor a write of rows.
         TRANSACTIONAL = %w[transaction with_lock lock!].freeze
 
+        # The instance-side locks re-read the row: `lock!` is `reload(lock:)`, a `SELECT … FOR UPDATE`, and
+        # `with_lock` runs it inside a transaction. `lock!` opens no transaction of its own, so on it the
+        # transaction label names the one whose end releases the lock, and over-states a `lock!` outside one.
+        INSTANCE_LOCKS = %w[with_lock lock!].freeze
+        LOCK = ["io.db.read", "io.db.transaction"].freeze
+
         module_function
 
         def attributions
@@ -114,7 +163,11 @@ module Rigor
                                             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") +
+                                                why: "issues an INSERT at the call and queries nothing first") +
+            rows(BASE, SINGLETON_READ_WRITES, READ_WRITE,
+                 singleton: true,
+                 why: "issues an UPDATE / DELETE / INSERT at the call, and a SELECT before it or after " \
+                      "a failed insert") +
             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")
@@ -125,14 +178,21 @@ module Rigor
                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")
+            rows(BASE, TRANSACTIONAL - INSTANCE_LOCKS, TRANSACTION, why: "opens a transaction around the block") +
+            rows(BASE, INSTANCE_LOCKS, LOCK,
+                 why: "re-reads the row with `SELECT … FOR UPDATE`; `with_lock` does it inside a transaction")
         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")
+                    "declared in the bundled RBS because declaring it would change how it types") +
+            rows(RELATION, PROXY_WRITERS, PROXY_WRITE,
+                 why: "a CollectionProxy writer: it changes the association's target and, for a saved " \
+                      "owner, the rows behind it. Keyed on Relation because that is the type the plugin " \
+                      "gives an association reader. A plain Relation either has no such method or, through " \
+                      "its own `delete` / `destroy`, deletes by id or finds and destroys, which stays inside " \
+                      "the bound. The model's save callbacks are not edged")
         end
 
         # Two rows per selector, because raw SQL is written two ways and only one of them names a type.