rigortype 0.3.3 → 0.3.5

data/lib/rigor/effects/envelope_index.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "config_envelopes"
+require_relative "envelope"
+require_relative "method_key"
+require_relative "registry"
+require_relative "signature_sources"
+
+module Rigor
+  module Effects
+    # The envelopes a **call site** may import as a `≤` bound, looked up by the callee the typer named
+    # (ADR-103 WD6; #386; normative in `docs/type-specification/effect-labels.md` § The declared lane at
+    # call sites).
+    #
+    # {EnvelopeCheck} asks "what bounds THIS method's body?" and answers it from the project's own
+    # declarations alone, because that is the stratum a contract can be checked against. This index asks
+    # the other question — "what does the thing I am calling promise?" — and so reads one stratum more:
+    # an **accepted signature**'s annotation, from the built RBS environment. WD6's trust ladder puts
+    # both on the discharging side, and the two questions are kept in two objects because only the first
+    # one may ever produce a finding.
+    #
+    # Four sources, nearest-first, exactly the check's precedence with the accepted stratum appended:
+    #
+    #     per-method annotation  >  class-level annotation  >  `effects.envelopes:`  >  accepted signature
+    #
+    # The carrier is **nominal**: the lookup is by the receiver's *static* class name as the typer
+    # projected it (or, for an implicit-self call, by the unit's own class), never by walking ancestors.
+    # A structural interface erases to `Dynamic[top]` today and has nothing to attach a bound to
+    # ([ADR-103](../../../docs/adr/103-effect-labels.md) WD6); an inherited envelope reaches an override
+    # through `effect.liskov-widened` instead, which is a judgment rather than an import.
+    #
+    # Two bounds of the slice, both deliberate:
+    #
+    # - An `effects.envelopes:` entry selected by **`match:`** does not participate here. A path glob is
+    #   a fact about where a class is *defined*, which a per-file collection window cannot see without
+    #   the whole-project class-source table; `namespace:` needs only the name and does participate. The
+    #   entry still bounds its own classes' methods for {EnvelopeCheck} and the Liskov check.
+    # - Lookup is by the *exact* owner. `repo.find` on a receiver typed `PgRepo` does not import
+    #   `Repo#find`'s bound.
+    #
+    # Values are Marshal-clean ({Envelope} over frozen Strings and {LabelSet}s), because the index is
+    # built per process — the parent and each fork-pool worker build their own from the same
+    # configuration and the same signature content, so the two agree without a channel to keep in sync.
+    class EnvelopeIndex
+      NO_ENVELOPES = {}.freeze
+      private_constant :NO_ENVELOPES
+
+      NO_ENTRIES = [].freeze
+      private_constant :NO_ENTRIES
+
+      # The index a run with no declaration of any kind uses — and the fail-soft answer for a build that
+      # raised. Every lookup on it is one `empty?` read.
+      def self.empty
+        @empty ||= new
+      end
+
+      # Reads every stratum this index serves, once per process.
+      #
+      # @param configuration [Rigor::Configuration]
+      # @param plugin_facts [Rigor::Effects::PluginFacts, nil] the loaded plugins' effect contributions
+      #   (#387); their `effect_labels:` join the vocabulary an annotation is read against, so a gem's
+      #   `%a{rigor:v1:effect rails.activejob.enqueue}` resolves rather than reading as unknown.
+      # @param environment [Rigor::Environment, nil] the run's environment. Its loader supplies the
+      #   rbs-inline / plugin `virtual_rbs` buffers and the built RBS environment the accepted stratum is
+      #   read from; without one, both are simply absent (the fail-quiet direction — a missing `≤` bound
+      #   costs precision, never a finding).
+      # @return [EnvelopeIndex]
+      def self.build(configuration:, environment: nil, plugin_facts: nil)
+        # Required here rather than at the top of the file: the reader pulls in the whole
+        # `RbsExtended` surface, and this build runs only under an `effects:` block.
+        require_relative "../rbs_extended/envelope_scanner"
+
+        registry = Registry.for_configuration(configuration, plugin_facts: plugin_facts)
+        loader = environment&.rbs_loader
+        scan = RbsExtended::EnvelopeScanner.scan(
+          sources: SignatureSources.collect(
+            signature_paths: configuration.signature_paths, virtual_rbs: loader&.virtual_rbs
+          ),
+          registry: registry
+        )
+        new(
+          method_envelopes: scan.method_envelopes, class_envelopes: scan.class_envelopes,
+          config_entries: ConfigEnvelopes.build(entries: configuration.effects_envelopes, registry: registry),
+          accepted: accepted_for(loader, registry)
+        )
+      rescue StandardError
+        empty
+      end
+
+      # The accepted stratum — every `%a{pure}` / `%a{rigor:v1:effect …}` on a method definition in the
+      # **built** RBS environment: a gem's shipped signatures, Rigor's bundled overlays, core RBS.
+      #
+      # It is read-only by construction. Nothing here can bound a project method's body, because the
+      # contract check ({EnvelopeCheck}) reads {RbsExtended::EnvelopeScanner}'s project-source tables and
+      # never this one; what an accepted signature can do is state what a call into it promises. The
+      # project's own signatures are in the built environment too and therefore appear here as well —
+      # harmlessly, since the project strata are consulted first and both discharge.
+      def self.accepted_for(loader, registry)
+        return NO_ENVELOPES if loader.nil?
+
+        RbsExtended::EnvelopeScanner.from_loader(loader: loader, registry: registry)
+      rescue StandardError
+        NO_ENVELOPES
+      end
+      private_class_method :accepted_for
+
+      def initialize(method_envelopes: NO_ENVELOPES, class_envelopes: NO_ENVELOPES,
+                     config_entries: NO_ENTRIES, accepted: NO_ENVELOPES)
+        @method_envelopes = method_envelopes.freeze
+        @class_envelopes = class_envelopes.freeze
+        @config_entries = config_entries.reject { |entry| entry.namespace.nil? }.freeze
+        @accepted = accepted.freeze
+        @config_cache = {}
+        freeze
+      end
+
+      # Whether no stratum has anything to say. The scan's fast path: a project with no envelope of any
+      # kind pays one predicate per call site and nothing else.
+      def empty?
+        @method_envelopes.empty? && @class_envelopes.empty? && @config_entries.empty? && @accepted.empty?
+      end
+
+      # The envelope bounding `owner`'s `selector`, or nil.
+      #
+      # @param owner [String] the receiver's static class name, as the typer projected it
+      # @param singleton [Boolean] whether the call is `Owner.selector` rather than `Owner#selector`
+      # @param selector [String]
+      # @return [Envelope, nil] never a ⊤ envelope: a bound that bounds nothing is not a bound, and
+      #   importing it would both add nothing and discharge a taint on the strength of a typo.
+      def [](owner, singleton, selector)
+        return nil if owner.nil? || empty?
+
+        key = "#{owner}#{singleton ? '.' : '#'}#{selector}"
+        envelope = @method_envelopes[key] || @class_envelopes[owner] || config_envelope(owner) ||
+                   @accepted[key]
+        return nil if envelope.nil? || envelope.top?
+
+        envelope
+      end
+
+      private
+
+      # The first `namespace:` entry selecting `owner`, memoised per class name — one call site's owner
+      # is asked for once per site and a project has a handful of entries.
+      def config_envelope(owner)
+        return nil if @config_entries.empty?
+
+        if @config_cache.key?(owner)
+          @config_cache[owner]
+        else
+          entry = @config_entries.find { |candidate| ConfigEnvelopes.namespace_match?(candidate.namespace, owner) }
+          @config_cache[owner] = entry && ConfigEnvelopes.envelope_for(entry, owner)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/effects/file_collection.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "summary"
+
+module Rigor
+  module Effects
+    # What one analyzed file contributes to the project's effect graph (ADR-103 WD12).
+    #
+    # The collector produces one of these per file and the runner marshals it back from a fork-pool worker
+    # with the file's diagnostics, so every field is Marshal-clean: frozen Hashes of Strings, {Summary}
+    # values, and `Data` edges. Nothing here holds a Prism node, a `Scope` or an environment.
+    #
+    # It carries four tables:
+    #
+    # - {#summaries} — the **direct** summary of each method the file defines, keyed `Class#m` / `Class.m` /
+    #   `<toplevel>#m` (WD14). A reopening in another file contributes the same key and the two join.
+    # - {#edges} — per method key, the calls that must be resolved against the *project* before they become
+    #   graph edges. Resolution is deferred to the propagator because a file cannot see the whole class
+    #   graph; the collector only records what the typer decided about the receiver.
+    # - {#superclasses} / {#includes} — the ancestry the propagator needs to resolve an edge through
+    #   inherited methods and to find every project-known override of a call's target (the closed-world
+    #   join of WD4).
+    #
+    # Merging is associative and commutative in every table, so folding a run's files in pool-completion
+    # order yields exactly the table sequential analysis yields.
+    class FileCollection
+      # One recorded call, before the project can say which definition it reaches.
+      #
+      # `receiver_class` is the class name the typer had at the call site (nil when it had none — a Dynamic
+      # receiver, or a construct that is not a call). `kind` is `:instance` for a `Nominal` receiver and
+      # `:singleton` for a `Singleton` one. `self_call` marks an implicit-self call, which is the only shape
+      # whose failure to resolve is an `unresolved-self-call` taint rather than silence.
+      #
+      # `super_call` marks the edge a `super` contributes (#446). It carries the ENCLOSING unit's class and
+      # selector rather than a receiver's, and the propagator resolves it against the ancestry *above* that
+      # class with no closed-world override join — a different question from every other edge, which is why
+      # it is a field rather than a convention over the other three.
+      Edge = Data.define(:receiver_class, :kind, :selector, :self_call, :super_call) do
+        # Defaulted because every producer but the `super` one records an ordinary call, and an ordinary
+        # call is not a `super`.
+        def initialize(super_call: false, **) = super
+      end
+
+      NO_TABLE = {}.freeze
+      private_constant :NO_TABLE
+
+      # The collection a file with nothing to say contributes — a parse failure, a file of constants, or a
+      # run where the collector was never activated.
+      def self.empty(path = nil)
+        new(path: path)
+      end
+
+      attr_reader :path, :summaries, :edges, :superclasses, :includes
+
+      def initialize(path: nil, summaries: NO_TABLE, edges: NO_TABLE,
+                     superclasses: NO_TABLE, includes: NO_TABLE, failed: false)
+        @path = path
+        @summaries = freeze_table(summaries)
+        @edges = freeze_edges(edges)
+        @superclasses = freeze_table(superclasses)
+        @includes = freeze_table(includes)
+        @failed = failed ? true : false
+        freeze
+      end
+
+      # Whether the collector gave up on this file entirely (the fail-soft path). Its methods contribute
+      # nothing rather than contributing a wrong summary; `rigor check` is unaffected either way.
+      def failed?
+        @failed
+      end
+
+      def empty?
+        @summaries.empty? && @edges.empty?
+      end
+
+      # Folds another collection into this one. Summaries join per key, edge lists union, ancestry merges.
+      #
+      # **Fold a whole run with {merge_all}, not with this in a `reduce`.** Every call here rebuilds and
+      # re-freezes the accumulated tables, so folding a run one file at a time costs O(files × methods) —
+      # it was 5.1 s of mastodon's 6.4 s collection overhead and the whole of gitlab's superlinear one
+      # (`docs/notes/20260817-effect-collection-perf.md`). This stays for a two-collection merge, which is
+      # what its cost model fits.
+      def merge(other)
+        return self if other.empty? && !other.failed?
+
+        self.class.merge_all([self, other])
+      end
+
+      # Folds a run's collections in one linear pass: each key's summaries join once, each table is built
+      # once, and the frozen result is constructed once at the end. Order-independent in every table
+      # except `superclasses`, where a later collection's spelling wins exactly as a chain of {merge}
+      # calls would leave it, so a path-sorted fold is reproducible.
+      #
+      # A collection that is {empty?} and not {failed?} contributes nothing, which is {merge}'s own
+      # short-circuit spelled once: a file with no methods and no calls has no summary to fold, and its
+      # ancestry has no unit to attach to.
+      def self.merge_all(collections)
+        summaries = {}
+        edges = {}
+        superclasses = {}
+        includes = {}
+        failed = false
+
+        collections.each do |collection|
+          failed ||= collection.failed?
+          next if collection.empty?
+
+          fold_summaries(summaries, collection.summaries)
+          fold_lists(edges, collection.edges)
+          superclasses.update(collection.superclasses)
+          fold_lists(includes, collection.includes)
+        end
+
+        includes.each_value(&:uniq!)
+        new(path: nil, summaries: summaries, edges: edges,
+            superclasses: superclasses, includes: includes, failed: failed)
+      end
+
+      def self.fold_summaries(into, table)
+        table.each do |key, summary|
+          existing = into[key]
+          into[key] = existing ? existing.join(summary) : summary
+        end
+      end
+      private_class_method :fold_summaries
+
+      # De-duplication is deferred to the single pass at the end of {merge_all} — `freeze_edges` uniqs
+      # and sorts anyway, and uniqing per file is what made the fold quadratic.
+      def self.fold_lists(into, table)
+        table.each do |key, list|
+          existing = into[key]
+          existing ? existing.concat(list) : into[key] = list.dup
+        end
+      end
+      private_class_method :fold_lists
+
+      def ==(other)
+        other.is_a?(FileCollection) && other.summaries == @summaries && other.edges == @edges &&
+          other.superclasses == @superclasses && other.includes == @includes && other.failed? == @failed
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, @summaries, @edges, @superclasses, @includes, @failed].hash
+      end
+
+      private
+
+      def freeze_table(table)
+        return NO_TABLE if table.empty?
+
+        table.transform_values { |value| value.is_a?(Array) ? value.freeze : value }.freeze
+      end
+
+      # Edge lists are sorted so a marshalled worker collection and a sequential one are `==` and the
+      # report they feed is byte-identical. The key is TOTAL over the de-duplicated list — `self_call` and
+      # `super_call` are in it because two edges can otherwise agree on every other field (`def emit; super;
+      # emit; end` records both), and `sort_by` is not stable.
+      def freeze_edges(table)
+        return NO_TABLE if table.empty?
+
+        table.transform_values do |list|
+          sorted = list.uniq
+          sorted.sort_by! { |edge| edge_order(edge) }
+          sorted.freeze
+        end.freeze
+      end
+
+      def edge_order(edge)
+        [edge.receiver_class.to_s, edge.kind.to_s, edge.selector, edge.self_call ? 1 : 0, edge.super_call ? 1 : 0]
+      end
+    end
+  end
+end

data/lib/rigor/effects/framework_units.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "file_collection"
+require_relative "label_set"
+require_relative "origin"
+require_relative "summary"
+
+module Rigor
+  module Effects
+    # The framework **edges** a plugin declared, materialised as effect units on the framework class itself
+    # (ADR-103 WD10; design note § 11.2 "Framework edges"; #387).
+    #
+    # `user.save` runs `User`'s `before_save :normalize`; `WelcomeJob.perform_now` runs
+    # `WelcomeJob#perform`; `UserMailer.welcome(u)` runs `UserMailer#welcome`. Each is real, synchronous,
+    # in-process control flow that the *syntax* does not contain, so without the plugin the caller's
+    # summary stops one hop short of the code that actually runs.
+    #
+    # ## Why units on the class rather than edges at the call site
+    #
+    # The call site is in another file. `app/controllers/users_controller.rb` writes `@user.save` and knows
+    # nothing about `User`'s callbacks — those are in `app/models/user.rb`, and a per-file collection window
+    # sees one file at a time. Synthesising `User#save` **where `User` is declared**, with edges to the
+    # callback methods, moves the framework knowledge to the file that has it and leaves the call site an
+    # ordinary edge. The propagator then resolves `(User, :instance, "save")` to the synthetic unit exactly
+    # as it resolves any other, ancestry and closed-world override join included — no second mechanism, no
+    # cross-file harvest, and a `save` on a subclass picks up that subclass's own callbacks for free.
+    #
+    # A project that defines `User#save` itself simply joins with the synthetic unit, which is the honest
+    # reading: an override still runs the callbacks unless it skips them.
+    #
+    # ## What is deliberately not here
+    #
+    # `perform_later` → `perform`. The deferred body runs in another process on another stack, and ADR-103
+    # WD4 fixes attribution to the code rather than to the clock: the enqueue is the effect, and the job's
+    # body belongs to the job's own entry point. {Plugin::EffectEdge::TARGETS} has no spelling for it.
+    module FrameworkUnits
+      IO_DB_READ = LabelSet.new(["io.db.read"]).freeze
+      private_constant :IO_DB_READ
+
+      # ActiveRecord's class-body callback macros, grouped by which persistence selectors run them. The
+      # grouping is coarse on purpose: an effect summary is an **upper bound**, and the cost of attributing
+      # a `before_create` to `save` (which does run it, when the record is new) is nothing, while the cost of
+      # a group fine enough to be wrong somewhere is a missing effect.
+      VALIDATION_MACROS = %w[validate before_validation after_validation].freeze
+
+      SAVE_MACROS = %w[
+        before_save around_save after_save before_create around_create after_create
+        before_update around_update after_update after_touch
+        before_commit after_commit after_rollback
+        after_create_commit after_update_commit after_save_commit
+      ].freeze
+
+      DESTROY_MACROS = %w[
+        before_destroy around_destroy after_destroy after_destroy_commit after_commit after_rollback
+      ].freeze
+
+      # Macros whose literal symbol arguments name methods on the same class. Everything the strategy reads.
+      CALLBACK_MACROS = (VALIDATION_MACROS + SAVE_MACROS + DESTROY_MACROS).uniq.freeze
+
+      # The uniqueness validator is a `SELECT` before the write — the one validation whose effect a reviewer
+      # is entitled to see in a summary. Both spellings Rails accepts.
+      UNIQUENESS_MACRO = "validates_uniqueness_of"
+      VALIDATES_MACRO = "validates"
+      UNIQUENESS_OPTION = "uniqueness"
+
+      # Which selectors run which group. `create` / `create!` are the singleton twins of `save`.
+      SAVE_TRIGGERS = %w[save save! update update! update_attribute touch increment! decrement!].freeze
+      DESTROY_TRIGGERS = %w[destroy destroy! delete].freeze
+      VALIDATION_TRIGGERS = %w[valid? invalid? validate!].freeze
+      SINGLETON_SAVE_TRIGGERS = %w[create create!].freeze
+
+      # `initialize` is not a mailer action, and neither is a method a plugin would want double-counted.
+      NON_ACTION_METHODS = %w[initialize].to_set.freeze
+
+      module_function
+
+      # Every synthetic unit `class_name` earns, as `[key, Summary, edges]` triples.
+      #
+      # @param class_name [String]
+      # @param instance_methods [Array<String>] the instance methods the class body defines, in source order
+      # @param macros [Hash{String=>Array<String>}] receiver-less class-body calls to their literal symbol
+      #   arguments, as the scanner harvested them
+      # @param uniqueness [Boolean] whether the class body declares a uniqueness validator
+      # @param plugin_facts [PluginFacts]
+      # @param own_units [Hash{String=>Boolean}] the units the class body itself defines, keyed by the
+      #   suffix a synthetic key carries (`"#save"`, `".create"`), each mapped to whether that body
+      #   reaches `super`. Read by {.framework_row} and by nothing else.
+      def synthesize(class_name:, instance_methods:, macros:, uniqueness:, plugin_facts:, own_units: {})
+        units = []
+        plugin_facts.edges_for(:activerecord_callbacks).each do |edge|
+          next unless plugin_facts.descends_from?(class_name, edge.receiver)
+
+          units.concat(active_record_units(class_name, macros, uniqueness, plugin_facts, own_units))
+        end
+        plugin_facts.edges_for(:perform_now).each do |edge|
+          next unless plugin_facts.descends_from?(class_name, edge.receiver)
+
+          # `selector` (the edge's `method:`) names the synthesised selector, defaulting to
+          # `perform_now`. The one other value it
+          # ever takes is `perform_later` — and ONLY from a plugin that has read the project's own
+          # `queue_adapter = :inline`, where Rails really does run the job on the caller's stack. That is a
+          # project fact narrowing a transport, not a general edge (ADR-103 WD4).
+          units << unit("#{class_name}.#{edge.selector || :perform_now}", [edge_to(class_name, "perform")])
+        end
+        plugin_facts.edges_for(:mailer_body).each do |edge|
+          next unless plugin_facts.descends_from?(class_name, edge.receiver)
+
+          units.concat(mailer_units(class_name, instance_methods))
+        end
+        units
+      end
+
+      # `save` and friends, edged to the callbacks the class body declared. A trigger with no callbacks and
+      # no uniqueness validator is NOT synthesised: an empty unit would put `User#save` in the snapshot for
+      # every model in the project and say nothing.
+      def active_record_units(class_name, macros, uniqueness, plugin_facts, own_units)
+        validation = callbacks(macros, VALIDATION_MACROS)
+        save = validation + callbacks(macros, SAVE_MACROS)
+        destroy = callbacks(macros, DESTROY_MACROS)
+        read = uniqueness ? uniqueness_summary(class_name) : nil
+        context = { plugin_facts: plugin_facts, own_units: own_units }
+
+        units = []
+        units.concat(triggers(class_name, SAVE_TRIGGERS, save, read, singleton: false, **context))
+        units.concat(triggers(class_name, SINGLETON_SAVE_TRIGGERS, save, read, singleton: true, **context))
+        units.concat(triggers(class_name, VALIDATION_TRIGGERS, validation, read, singleton: false, **context))
+        units.concat(triggers(class_name, DESTROY_TRIGGERS, destroy, nil, singleton: false, **context))
+        units
+      end
+
+      # ActionMailer's class-method-to-instance mapping: `UserMailer.welcome(u)` instantiates the mailer and
+      # runs `#welcome`. One synthetic singleton twin per instance method the mailer defines.
+      def mailer_units(class_name, instance_methods)
+        instance_methods.reject { |name| NON_ACTION_METHODS.include?(name) }.uniq.map do |name|
+          unit("#{class_name}.#{name}", [edge_to(class_name, name)])
+        end
+      end
+
+      # A synthesised trigger exists only when the class body earned it — see {.active_record_units} — but
+      # once it exists it stands for the whole of `save`, so it carries the framework's own claim about the
+      # selector as well as the callbacks (#440).
+      def triggers(class_name, selectors, targets, read, singleton:, plugin_facts:, own_units:)
+        return [] if targets.empty? && read.nil?
+
+        edges = targets.map { |target| edge_to(class_name, target) }
+        selectors.map do |selector|
+          row = framework_row(class_name, selector, singleton, plugin_facts, own_units)
+          unit("#{class_name}#{singleton ? '.' : '#'}#{selector}", edges,
+               declared_bundles(read, row), causes(row))
+        end
+      end
+
+      # What the loaded plugins say `class_name`'s `selector` itself does — `ActiveRecord::Base#save` is
+      # `io.db.write` — read off the very table a call site reads (#440).
+      #
+      # Without it the synthetic unit carried the validator's `SELECT` and nothing else, so a model with a
+      # `before_save` or a uniqueness validator reported `AuthSource#save: ≤ io.db.read`: the write was
+      # attributed at every *call site* and never on the row that names the method, which is the row a
+      # reviewer reads. A `narrow:` row is skipped, because narrowing reads an argument at a call site and
+      # there is no call site here.
+      def framework_row(class_name, selector, singleton, plugin_facts, own_units)
+        return nil if replaced?(own_units, selector, singleton)
+
+        row = plugin_facts.class_row(class_name, singleton, selector)
+        return nil if row.nil? || row.narrow || row.labels.empty?
+
+        row
+      end
+
+      # Whether the class spelled the selector out itself and never reaches `super`. Such a body REPLACED
+      # the framework's implementation, so the framework's claim no longer describes what runs: a
+      # `def save = false` that persists nothing must keep reporting nothing. A body that does reach
+      # `super` keeps the claim, which is the case the exemption exists to not break.
+      def replaced?(own_units, selector, singleton)
+        key = "#{singleton ? '.' : '#'}#{selector}"
+        own_units.key?(key) && !own_units[key]
+      end
+
+      def declared_bundles(read, row)
+        bundles = read ? read.dup : {}
+        bundles[Origin.plugin(row.key)] = row.labels if row
+        bundles
+      end
+
+      # Mirrors {UnitScan#attribute_plugin}: a row may discharge and still taint, and a row from a plugin
+      # the engine does not bundle is a claim that leaves the unit non-exhaustive.
+      def causes(row)
+        return [] if row.nil?
+
+        list = []
+        list << [row.taint, row.key] if row.taint
+        list << ["plugin-attribution", row.key] unless row.discharge?
+        list
+      end
+
+      def callbacks(macros, names)
+        names.flat_map { |name| macros[name] || [] }.uniq
+      end
+
+      # The uniqueness validator's own query. It rides the DECLARED lane with no taint, exactly as every
+      # other first-party plugin contribution does (ADR-103 WD6): the plugin read the app's own
+      # `validates … uniqueness: true` and knows what Rails does with it, but the analyzer did not read a
+      # body, so this is a trusted claim rather than a proof.
+      def uniqueness_summary(class_name)
+        { Origin.plugin("#{class_name}:uniqueness-validator") => IO_DB_READ }
+      end
+
+      def unit(key, edges, declared = nil, causes = [])
+        summary = Summary.new(declared_bundles: declared || {}, exhaustive: causes.empty?, causes: causes)
+        [key, summary, edges]
+      end
+
+      def edge_to(class_name, selector)
+        FileCollection::Edge.new(receiver_class: class_name, kind: :instance, selector: selector,
+                                 self_call: false)
+      end
+
+      private_class_method :active_record_units, :mailer_units, :triggers, :framework_row, :replaced?,
+                           :declared_bundles, :causes, :callbacks, :uniqueness_summary, :unit, :edge_to
+    end
+  end
+end

data/lib/rigor/effects/identity.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "../cache/descriptor"
+require_relative "catalog"
+require_relative "registry"
+
+module Rigor
+  module Effects
+    # The **effects cache identity** — the second of ADR-103 WD13's "one cache, two identities, one extra
+    # slot" (issue #382; the contract is `docs/internal-spec/effect-summaries.md` § Caching).
+    #
+    # A run has one identity for its diagnostics and one for its effect summaries. The diagnostics identity
+    # is today's and is deliberately untouched by this file: collection is observational, so a diagnostics
+    # entry computed with effects on is valid for a run with effects off and vice versa. The effects
+    # identity is that identity **plus** the three things that change what a summary means without changing
+    # a single analyzed byte:
+    #
+    # - the **vocabulary version** ({Registry#vocabulary_version}) — a rename or a removal re-reads every
+    #   persisted label;
+    # - the **catalogue identity** ({Catalog#identity}, schema + a digest of `data/effects/core.yml`) — an
+    #   audited row moving from `io` to `io.fs.write` re-colours summaries the analyzed source never moved;
+    # - the **`effects:` block digest** — the same value the snapshot header carries, so a `tolerated:` or
+    #   `reach:` edit is one visible regeneration event rather than two silently disagreeing digests;
+    # - the **plugin fact digest** ({PluginFacts#digest}, #387) — the loaded plugins' labels, attributions,
+    #   edges and presets. A plugin upgrade that moves `perform_later` from `io` to `io.db.write` re-colours
+    #   summaries the analyzed source never moved, exactly as a re-audited catalogue row does, and the
+    #   plugin set is otherwise invisible to a key derived from configuration alone.
+    #
+    # This module is the ONE place that answers it. {.digest} is the string form (what the ADR-46 snapshot
+    # payload carries beside `return_summaries`) and {.descriptor} is the {Cache::Descriptor} form (what the
+    # ADR-45 whole-run effects slot is keyed by): the same three inputs, spelled for the two stores.
+    #
+    # Nothing here is consulted when collection is off — no entry is written, no key is perturbed, and the
+    # `effects:` block stays out of `Configuration#to_h` so enabling the feature invalidates no existing
+    # project's diagnostics cache.
+    module Identity
+      # The `configs:` slot the effects identity adds on top of a run's diagnostics key descriptor.
+      CONFIG_KEY = "effects.identity"
+
+      module_function
+
+      # The effects identity as a hex digest — the form a store with no descriptor of its own (the ADR-46
+      # incremental snapshot) carries alongside its payload, and compares verbatim on restore.
+      #
+      # @param configuration [Rigor::Configuration]
+      # @param registry [Registry] the vocabulary whose version participates
+      # @param catalog [Catalog] the catalogue whose identity participates
+      # @return [String] hex SHA-256
+      def digest(configuration:, registry: Registry.default, catalog: Catalog.default, plugin_facts: nil)
+        Digest::SHA256.hexdigest(
+          [
+            "vocabulary:#{registry.vocabulary_version}",
+            "catalog:#{catalog.identity}",
+            "effects:#{config_digest(configuration)}",
+            "plugins:#{plugin_facts&.digest || 'none'}"
+          ].join("\x00")
+        )
+      end
+
+      # The effects identity as a cache KEY descriptor: the run's own diagnostics key descriptor plus one
+      # `configs:` entry carrying {.digest}. Composing (rather than rebuilding) is what makes the effects
+      # slot inherit every diagnostics-invalidating input — engine version, engine source, RBS libraries,
+      # the analyzed-path set — for free, so "the effects identity is the diagnostics identity plus three
+      # things" is a property of the code rather than a claim about it.
+      #
+      # @param base [Cache::Descriptor] the run's diagnostics key descriptor
+      # @return [Cache::Descriptor]
+      def descriptor(base:, configuration:, registry: Registry.default, catalog: Catalog.default,
+                     plugin_facts: nil)
+        Cache::Descriptor.compose(
+          base,
+          Cache::Descriptor.new(
+            configs: [
+              Cache::Descriptor::ConfigEntry.new(
+                key: CONFIG_KEY,
+                value_hash: digest(configuration: configuration, registry: registry, catalog: catalog,
+                                   plugin_facts: plugin_facts)
+              )
+            ]
+          )
+        )
+      end
+
+      # The `effects:` block of `.rigor.yml`, canonicalised (keys sorted at every depth, rendered as JSON)
+      # and hashed. {Snapshot.config_digest} is this method — the snapshot header and the cache identity
+      # MUST agree, and the cheapest way to guarantee that is for there to be one implementation.
+      def config_digest(configuration)
+        Digest::SHA256.hexdigest(JSON.generate(canonicalize(configuration.effects || {})))
+      end
+
+      def canonicalize(value)
+        case value
+        when Hash then value.map { |key, member| [key.to_s, canonicalize(member)] }.sort_by(&:first).to_h
+        when Array then value.map { |member| canonicalize(member) }
+        when Symbol then value.to_s
+        else value
+        end
+      end
+    end
+  end
+end