rigortype 0.3.3 → 0.3.5

data/lib/rigor/inference/pre_eval_constants.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../scope"
+require_relative "../type"
+require_relative "scope_indexer"
+
+module Rigor
+  module Inference
+    # Issue #352 / [ADR-17](../../../docs/adr/17-monkey-patch-pre-evaluation.md) — the constant half of the
+    # `pre_eval:` publication surface.
+    #
+    # ADR-17 slice 2 gave `pre_eval:` a project-wide **method** registry ({ProjectPatchedMethods}). A
+    # constant declared in the same file stayed invisible across the file boundary: `Scope#in_source_constants`
+    # is per-file and is deliberately not part of `Runner#project_scope_seed_tables`, so only class-shaped
+    # constants (a `class` / `module` declaration, or one of the four meta-new forms `ScopeIndexer`'s
+    # `record_class_new_constant_decl` promotes) ever crossed. `TIMEOUT = 30` in a listed file read as
+    # `Dynamic[top]` everywhere else.
+    #
+    # This collector closes that half. It walks the `pre_eval:` files with the SAME constant pre-pass the
+    # per-file path uses ({ScopeIndexer.build_in_source_constants}) and publishes the result — widened — into
+    # the project seed. Files not listed under `pre_eval:` are untouched, so the feature is opt-in by
+    # construction and its cost stays proportional to the listed file count (ADR-17 WD1's cost-bounded
+    # argument, which is also why slice 5's full-project two-pass stayed rejectable).
+    #
+    # ## The widening rule — why the published type is not the same-file type
+    #
+    # Same-file constant propagation is **value-pinned**: `42`, `"hello"`, a `Tuple`, a `HashShape`. Carrying
+    # that verbatim across a file boundary would land diagnostics in files whose author never opened the
+    # constant's definition — `CONFIG = { a: 1 }` arriving as a closed `HashShape` makes `CONFIG.fetch(:b)`
+    # fire, `ARR = [1, 2]` arriving as a `Tuple` routes through `ShapeDispatch` instead of the RBS overload a
+    # call site relied on. Today's cross-file `Dynamic[top]` is false-positive-free *by construction*, so
+    # precision here can only spend that budget; AGENTS.md § "Implementation Guidelines" ranks false positives
+    # above worst-case static reading, so this slice spends as little of it as possible.
+    #
+    # {.widen} therefore publishes the **erased class**, never the value:
+    #
+    # | Declared | Same file | Published cross-file |
+    # | --- | --- | --- |
+    # | `INT_LIT = 42` | `42` | `Integer` |
+    # | `STR_LIT = "hello"` | `"hello"` | `String` |
+    # | `ARR_LIT = [1, 2]` | `[1, 2]` (Tuple) | `Array` (raw, elements dropped) |
+    # | `HSH_LIT = { a: 1 }` | `{ a: 1 }` (HashShape) | `Hash` (raw, keys dropped) |
+    # | `ALIAS_CLS = String` | `singleton(String)` | `singleton(String)` |
+    # | `Nest::NESTED_INT = 7` | `7` | `Integer` |
+    #
+    # Anything the rule does not recognise **declines** — the name is simply not published and reads exactly
+    # as it does today. Declining is always the safe answer here, which is why the `else` arm is `nil` rather
+    # than a fallback. `Constant[nil]` declines on purpose: a `X = nil` at declaration position is a
+    # placeholder for a value assigned at runtime far more often than it is a genuine `NilClass`, and
+    # publishing `NilClass` project-wide would make every use of it a diagnostic.
+    #
+    # Value-pinning a *provably* frozen single-write literal cross-file is a strictly later question; it needs
+    # its own FP measurement and is deliberately not attempted here.
+    #
+    # ## The multi-file write rule — widen on conflict, all the way to `Dynamic[top]`
+    #
+    # Within one file, `ScopeIndexer#record_constant_write` unions repeated writes; that union is widened as a
+    # whole (`X = 1; X = "a"` in one file publishes `Integer | String`). ACROSS files the same union would be
+    # a type neither author can see, so the rule is **widen on conflict**: when two listed files publish the
+    # same qualified name with different widened types, the name is dropped from the table entirely and reads
+    # as `Dynamic[top]` — the widest type there is, and the one the name already had. Agreeing writes (`X = 1`
+    # here, `X = 2` there — both `Integer`) are not a conflict at all, which is the point of widening first:
+    # `1 | 2` is never produced.
+    #
+    # ## Ordering
+    #
+    # The published table seeds `Scope#in_source_constants`, which `Reflection.constant_type_at` consults
+    # AFTER the class registry and `discovered_classes`. A published entry can therefore never mask a
+    # class-shaped constant that already crossed, and the per-file table always wins over the seed (see
+    # {ScopeIndexer.index}'s merge) — same-file remains the most specific authority.
+    module PreEvalConstants
+      EMPTY = {}.freeze
+
+      module_function
+
+      # Collects and widens the constants every `pre_eval:` file declares.
+      #
+      # @param paths [Array<String>] absolute paths to the `pre_eval:` files that exist on disk.
+      # @param scope_builder [#call] `path -> Rigor::Scope`; the caller supplies a project-seeded, environment-
+      #   bound scope so the rvalue typer resolves cross-file classes exactly as per-file analysis would.
+      # @param target_ruby [String, nil] the Prism parse version (`Configuration#target_ruby`).
+      # @param buffer [Rigor::Analysis::BufferBinding, nil] editor-mode binding; when set, a listed file that
+      #   matches the in-flight buffer is read from its physical bytes.
+      # @return [Hash{String => Rigor::Type}] frozen qualified-name -> published type table.
+      def collect(paths:, scope_builder:, target_ruby: nil, buffer: nil)
+        published = {}
+        conflicted = {}
+        paths.each do |path|
+          file_constants(path, scope_builder: scope_builder, target_ruby: target_ruby, buffer: buffer)
+            .each { |name, type| merge_publication(published, conflicted, name, type) }
+        end
+        published.freeze
+      end
+
+      # Folds one declaration into the accumulator under the widen-on-conflict rule. A name that has already
+      # conflicted stays out for the rest of the collection — a later agreeing write must not resurrect it.
+      def merge_publication(published, conflicted, name, type)
+        return if conflicted.key?(name)
+
+        widened = widen(type)
+        return if widened.nil?
+
+        existing = published[name]
+        return published[name] = widened if existing.nil?
+        return if existing == widened
+
+        published.delete(name)
+        conflicted[name] = true
+      end
+      private_class_method :merge_publication
+
+      # The per-file constant table, typed through the same pre-pass the per-file path runs. Deliberately NOT
+      # a full `ScopeIndexer.index`: ADR-17 WD4 keeps the pre-eval pass a discovery walk, and the constant
+      # pre-pass (plus the declaration artifacts it needs to resolve in-file class references) is exactly the
+      # discovery facet this feature consumes. Fails soft to the empty table — a pre-eval file that cannot be
+      # read or parsed already surfaces a `pre-eval.parse-error` warning from {ProjectPatchedScanner}, and it
+      # must never break the run.
+      def file_constants(path, scope_builder:, target_ruby: nil, buffer: nil)
+        physical = buffer ? buffer.resolve(path) : path
+        parse_result = Prism.parse(File.read(physical), filepath: path, version: target_ruby)
+        return EMPTY unless parse_result.errors.empty?
+
+        root = parse_result.value
+        ScopeIndexer.build_in_source_constants(root, declaration_seeded_scope(root, scope_builder.call(path)))
+      rescue StandardError
+        EMPTY
+      end
+      private_class_method :file_constants
+
+      # Mirrors the head of {ScopeIndexer.index}: seed the file's own declaration overrides and discovered
+      # classes onto the project-seeded scope so a `CONST = SomeClassDefinedRightHere.new` rvalue types the
+      # same way it does during real analysis.
+      def declaration_seeded_scope(root, scope)
+        declared_types, discovered_classes = ScopeIndexer.build_declaration_artifacts(root)
+        scope.with_discovery(
+          scope.discovery.with(
+            declared_types: declared_types,
+            discovered_classes: scope.discovered_classes.merge(discovered_classes)
+          )
+        )
+      end
+      private_class_method :declaration_seeded_scope
+
+      # The publication widening. Returns the type to publish, or `nil` to decline (the name keeps today's
+      # `Dynamic[top]` cross-file reading). See the module doc for why declining is the safe default.
+      def widen(type)
+        case type
+        when Type::Constant then widen_constant(type)
+        when Type::Refined then widen(type.base)
+        when Type::IntegerRange then Type::Combinator.nominal_of("Integer")
+        when Type::Tuple then Type::Combinator.nominal_of("Array")
+        when Type::HashShape then Type::Combinator.nominal_of("Hash")
+        when Type::Nominal then type.type_args.empty? ? type : Type::Combinator.nominal_of(type.class_name)
+        when Type::Singleton then type
+        when Type::DataInstance, Type::StructInstance then nominal_for_class_name(type.class_name)
+        when Type::Union then widen_union(type)
+        end
+      end
+
+      # `Constant[v]` publishes `v`'s class. `nil` declines (see the module doc); so does a value whose class
+      # is anonymous, which has no name to publish under.
+      def widen_constant(type)
+        return nil if type.value.nil?
+
+        nominal_for_class_name(type.value.class.name)
+      end
+      private_class_method :widen_constant
+
+      def nominal_for_class_name(class_name)
+        return nil unless class_name.is_a?(String) && !class_name.empty?
+
+        Type::Combinator.nominal_of(class_name)
+      end
+      private_class_method :nominal_for_class_name
+
+      # A union publishes only when EVERY member widens: one unrecognised arm means the union's real extent is
+      # unknown, and a partial union would be narrower than the truth — the false-positive direction.
+      def widen_union(type)
+        widened = type.members.map { |member| widen(member) }
+        return nil if widened.any?(&:nil?)
+
+        Type::Combinator.union(*widened)
+      end
+      private_class_method :widen_union
+    end
+  end
+end

data/lib/rigor/inference/scope_indexer.rb

@@ -88,10 +88,13 @@ module Rigor
         # program and types its rvalue under a scope that carries the surrounding qualified prefix as `self_type`, so
         # the rvalue typer sees in-class references resolve correctly. Multiple writes to the same qualified name union
         # via `Type::Combinator.union`.
+        # Issue #352 — the per-file table merges OVER whatever the base scope already published (the
+        # `pre_eval:` constant seed `Runner#project_scope_seed_tables` applies). Same-file declarations are the
+        # most specific authority, exactly as `merged_classes` above resolves the same collision. Without the
+        # merge, the assignment below would silently drop the project seed on every file.
         in_source_constants = build_in_source_constants(root, seeded_scope)
-        seeded_scope = seeded_scope.with_discovery(
-          seeded_scope.discovery.with(in_source_constants: in_source_constants)
-        )
+        merged_constants = merge_seeded_constants(default_scope.in_source_constants, in_source_constants)
+        seeded_scope = seeded_scope.with_discovery(seeded_scope.discovery.with(in_source_constants: merged_constants))
 
         # Slice 7 phase 12. In-source method discovery. Walks every class/module body for `Prism::DefNode` and
         # recognised `define_method` calls and records the introduced method names. `rigor check` consults the table to
@@ -1206,6 +1209,15 @@ module Rigor
         accumulator.freeze
       end
 
+      # Issue #352 — folds the project-wide `pre_eval:` constant seed under this file's own table. Returns the
+      # per-file table unchanged (same frozen object) when nothing was seeded, so a run without `pre_eval:`
+      # constants allocates and compares exactly what it did before.
+      def merge_seeded_constants(seeded, per_file)
+        return per_file if seeded.nil? || seeded.empty?
+
+        seeded.merge(per_file).freeze
+      end
+
       def walk_constant_writes(node, qualified_prefix, default_scope, accumulator)
         return unless node.is_a?(Prism::Node)
 

data/lib/rigor/plugin/base.rb

@@ -710,6 +710,34 @@ module Rigor
         manifest.protocol_contracts
       end
 
+      # ADR-103 WD6 / WD10 (#387) — the plugin's effect contributions. Each defaults to the manifest field
+      # and each MAY be overridden to fold in per-project facts, exactly as {#protocol_contracts} may.
+      #
+      # {#effect_attributions} is the one that needs it: a Rails app's ActiveJob transport is whatever
+      # `config.active_job.queue_adapter` names, so rigor-activejob answers `io.db.write` for Solid Queue
+      # and `io.net` for Sidekiq by reading the project's own configuration. That read is a plugin-side I/O
+      # boundary read and must not happen on a run with effects off — {Registry#effect_contributions} is
+      # lazy for exactly that reason, and nothing asks unless the project has an `effects:` block.
+      def effect_attributions
+        manifest.effect_attributions
+      end
+
+      def effect_edges
+        manifest.effect_edges
+      end
+
+      def effect_labels
+        manifest.effect_labels
+      end
+
+      def effect_entry_points
+        manifest.effect_entry_points
+      end
+
+      def effect_ancestry
+        manifest.effect_ancestry
+      end
+
       # ADR-7 § "Slice 6-A/6-B" — per-plugin {IoBoundary}. Memoised so the boundary's accumulated `FileEntry`
       # rows persist across producer invocations within the same plugin instance and feed cache invalidation
       # via `cache_for`.

data/lib/rigor/plugin/box.rb

@@ -32,14 +32,30 @@ module Rigor
       # Requires `feature` into the shared box exactly once. Returns true when the feature is available in the
       # box, false when it could not be loaded (the caller then declines — never falls back to loading into the
       # main space, which would defeat the boundary).
+      #
+      # The rescue is `::`-qualified and covers `::ScriptError`, matching {Isolation::Process.run_worker_loop}:
+      # a failed box require raises `::LoadError` — a ScriptError, not a StandardError — and a plain
+      # `rescue StandardError` lets it escape and abort the whole run instead of the clean decline.
       def require_feature(feature)
         @required ||= {}
         return @required[feature] if @required.key?(feature)
 
         shared.require(feature)
         @required[feature] = true
-      rescue StandardError
-        @required[feature] = false
+      rescue ::StandardError, ::ScriptError
+        @required[feature] = eval_require(feature)
+      end
+
+      # The gem-resolving fallback: `Ruby::Box#require` resolves against the raw `$LOAD_PATH` only (it
+      # calls the C-level require directly), so a target library installed as a gem is reachable only
+      # through the box's own RubyGems — the `Kernel#require` *inside* the box. `feature` is a fixed,
+      # plugin-declared name rendered via `String#inspect` (a safe Ruby literal), so the eval carries no
+      # free input. Returns false when the box cannot load the feature either way (the caller declines).
+      def eval_require(feature)
+        shared.eval("require #{feature.inspect}") # require "active_support/inflector"
+        true
+      rescue ::StandardError, ::ScriptError
+        false
       end
 
       # Evaluates `code` inside the shared box and returns the result across the box boundary. The caller MUST

data/lib/rigor/plugin/effect_ancestry.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "effect_attribution"
+
+module Rigor
+  module Plugin
+    # One entry of a plugin's `effect_ancestry:` — an ancestry edge the plugin's own gem introduces and
+    # the project's source never writes down (ADR-103 WD17; [#465](https://github.com/rigortype/rigor/issues/465)).
+    #
+    # `Effects::PluginFacts` walks the project's own `class … <` and `include` lines and nothing else,
+    # deliberately: reading the RBS ancestor chain instead would make a row's reach a function of whether
+    # anyone happened to run `rbs prototype`. The cost is that a chain which leaves project source never
+    # comes back. `class UserMailer < Devise::Mailer` is the measured case — `Devise::Mailer <
+    # ActionMailer::Base` is a line in the devise gem, so `rigor-actionmailer`'s rows stop one step short
+    # of every mailer a Devise application writes, and the five `Auth::*Controller < Devise::*Controller`
+    # subclasses beside it are entry points.
+    #
+    # A plugin that models a gem knows that gem's own inheritance. Declaring it here keeps the rule that
+    # Rigor reads *declarations* rather than RBS: the declaration simply comes from the plugin instead of
+    # from project source.
+    #
+    # ## What a claim may say
+    #
+    # `parent:` need only be a **true ancestor**, not the immediate superclass. The sole use of the
+    # ancestry is to make a row reachable, and no plugin row is ever keyed on a project class, so
+    # skipping intermediate links loses nothing — while insisting on the immediate parent would force a
+    # claim that is sometimes false: `Devise::SessionsController`'s real parent is `DeviseController`,
+    # whose own parent is `Devise.parent_controller` and therefore configurable per project. A claim that
+    # skips links MUST say so in its `why:`.
+    #
+    # ## Who may make one
+    #
+    # Bundled plugins only ({Rigor::Plugin::FirstParty}), enforced in `PluginFacts`. An ancestry claim
+    # carries no labels of its own, so it looks harmless — but it makes *other* plugins' rows reachable,
+    # and a third-party plugin asserting `Foo < ActiveRecord::Base` would pull rigor-activerecord's
+    # first-party discharging rows onto `Foo`. The `effect_root:` demotion and the `discharge:` grant
+    # both answer their own version of that question the same way.
+    class EffectAncestry
+      attr_reader :child, :parent, :why
+
+      def initialize(child:, parent:, why:)
+        @child = validate_class_name!(child, "child")
+        @parent = validate_class_name!(parent, "parent")
+        @why = validate_why!(why)
+        freeze
+      end
+
+      def to_h
+        { "child" => @child, "parent" => @parent }
+      end
+
+      def ==(other)
+        other.is_a?(EffectAncestry) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_class_name!(value, role)
+        name = value.to_s
+        unless EffectAttribution::CLASS_NAME.match?(name)
+          raise ArgumentError, "effect ancestry #{role} must be a class name, got #{value.inspect}"
+        end
+
+        name.dup.freeze
+      end
+
+      def validate_why!(why)
+        value = why.to_s
+        raise ArgumentError, "effect ancestry #{@child} < #{@parent} needs a `why:` justification" if value.empty?
+
+        value.dup.freeze
+      end
+    end
+  end
+end

data/lib/rigor/plugin/effect_attribution.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # One row of a plugin's `effect_attributions:` — "a call to this receiver's method contributes these
+    # effect labels" (ADR-103 WD6 / WD10; design note § 6.6; the contract is
+    # `docs/internal-spec/plugin.md` § Effect contributions).
+    #
+    # A framework method has no body Rigor reads, so someone must colour it. Three channels can, in
+    # descending order of preference:
+    #
+    # 1. a `%a{rigor:v1:effect …}` annotation in the plugin's own `signature_paths:` RBS — tier 1, read
+    #    through {Rigor::Effects::EnvelopeIndex}'s accepted stratum, and the right channel whenever the
+    #    plugin already ships a signature for the method;
+    # 2. this field, for the methods RBS cannot name per app — association readers, `find_by_*`, scopes —
+    #    and for classes the plugin ships no RBS for at all;
+    # 3. the project's own `effects.attribution:` table, which is the user's answer for everything left.
+    #
+    # ## The receiver
+    #
+    # `receiver` is spelled one of two ways, and the spelling picks the matching rule:
+    #
+    # - a **class name** (`"ActiveRecord::Base"`, `"I18n"`) matches the class the call's receiver
+    #   projects to, **through the project's inheritance chain**: an `ActiveRecord::Base` row applies to
+    #   `User.find` because the project declares `User < ApplicationRecord < ActiveRecord::Base`. This is
+    #   the difference from a catalogue row, which matches its exact owner and nothing else — Ruby's core
+    #   classes are leaves in practice and a framework's base class never is.
+    # - a **receiver path** (`"Rails.cache"`, `"Time.zone"`, `"Rails.application.credentials"`) matches
+    #   the receiver *expression* as the syntax spells it. `Rails.cache.read` has no receiver class the
+    #   typer can name — `Rails.cache` is a call, and its return type is adapter-dependent by design —
+    #   so the only honest handle on it is the path that was written.
+    # - a **self path** (`"self.session"`, `"self.flash.now"`, `"self.cookies.encrypted"`) is the same
+    #   thing rooted at implicit self, and is what a Rails controller's accessors actually look like:
+    #   `session[:user_id] = id` is `[]=` on the result of a receiver-less `session`. A self-path row MUST
+    #   name a `within:` class, because a receiver-less `session` in some other project class is a
+    #   different `session` — the row applies only inside a class whose project ancestry reaches `within`.
+    #
+    # `on_result: true` shifts a class-name row one link outwards: it matches a call on **what a call to
+    # that class returned**. `UserMailer.welcome(u).deliver_now` and `WelcomeJob.set(wait: 1.hour)
+    # .perform_later` are the two idioms that need it — the object in the middle is a lazy
+    # `MessageDelivery` / `ConfiguredJob` whose type nothing in the project declares, while the class that
+    # produced it is written right there in the source. Without it the send and the enqueue, the two calls
+    # a reviewer most wants coloured, would go unattributed in the spelling Rails actually uses.
+    #
+    # ## Discharge
+    #
+    # `discharge: true` says the label is derived from the framework's own semantics rather than guessed,
+    # so the site is exhaustive rather than tainted. ADR-103 WD6 grants that only to a **first-party
+    # bundled** plugin ({FirstParty}), gated by `make check-plugins`; a third-party plugin's `true` is
+    # ignored with a load-time warning and the row behaves like the project's `effects.attribution:`
+    # table — declared, and carrying a `plugin-attribution` taint.
+    #
+    # Either way the labels land in the **declared** lane, never the proven one. A discharging row is a
+    # trusted claim, exactly like an accepted signature's `%a{…}`: "this is what it does", not "the
+    # analyzer read the body and saw this".
+    class EffectAttribution
+      # A receiver spelled as a `Constant::Path` — the class-name form. Anything else with a `.` in it is
+      # read as a receiver path.
+      CLASS_NAME = /\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/
+
+      # A receiver path: a constant head followed by one or more sends (`Rails.cache`,
+      # `Rails.application.credentials`).
+      RECEIVER_PATH = /\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*(\.[a-z_][A-Za-z0-9_]*)+\z/
+
+      # A self path: implicit self followed by one or more receiver-less sends (`self.flash.now`).
+      SELF_PATH = /\Aself(\.[a-z_][A-Za-z0-9_]*)+\z/
+
+      # What a self path is rooted at, once the `self.` head is stripped.
+      SELF_HEAD = "self"
+
+      attr_reader :receiver, :method, :singleton, :labels, :narrow, :discharge, :within, :on_result,
+                  :taint, :why
+
+      # The taint causes a plugin row may name. A closed subset of
+      # {Rigor::Effects::TaintCause::ALL}: a plugin may say "and there is more here I cannot see", but
+      # only for the two reasons a framework model can honestly have — a template it does not read, and a
+      # callable whose body is supplied by the application.
+      TAINT_CAUSES = %w[template-not-analysed opaque-callable].freeze
+
+      # @param receiver [String] a class name or a receiver path (see above)
+      # @param method [Symbol, String] the selector this row colours
+      # @param singleton [Boolean] whether the row is `Receiver.method` rather than `Receiver#method`.
+      #   Meaningless — and ignored — for a receiver path, whose head already fixes the receiver object.
+      # @param labels [Array<String>] the effect labels the call contributes
+      # @param narrow [String, nil] a {Rigor::Effects::Narrowing} handler name, when the call's own
+      #   argument literals settle a question the row cannot (`connection.execute("SELECT …")`)
+      # @param discharge [Boolean] see above; honoured only for a first-party bundled plugin
+      # @param why [String] the audit justification, required exactly as `data/effects/core.yml` requires
+      #   one of every row: a label with no stated reason is a claim nobody can review.
+      def initialize(receiver:, method:, labels:, why:, singleton: false, narrow: nil, discharge: false, # rubocop:disable Metrics/ParameterLists
+                     within: nil, on_result: false, taint: nil)
+        @receiver = validate_receiver!(receiver)
+        @method = method.to_sym
+        @singleton = singleton ? true : false
+        @labels = normalize_labels(labels)
+        @narrow = narrow.nil? ? nil : narrow.to_s.dup.freeze
+        @discharge = discharge ? true : false
+        @within = validate_within!(within)
+        @on_result = on_result ? true : false
+        validate_on_result!
+        @taint = validate_taint!(taint)
+        @why = validate_why!(why)
+        freeze
+      end
+
+      # Whether {#receiver} is a receiver path (`Rails.cache`) rather than a class name or a self path.
+      def receiver_path?
+        @receiver.include?(".") && !self_path?
+      end
+
+      # Whether {#receiver} is a self path (`self.flash.now`).
+      def self_path?
+        @receiver.start_with?("#{SELF_HEAD}.")
+      end
+
+      # The key an origin and a report spell this row as.
+      def key
+        return "#{@receiver}.#{@method}" if receiver_path? || self_path?
+        return "#{@receiver}()##{@method}" if @on_result
+
+        "#{@receiver}#{@singleton ? '.' : '#'}#{@method}"
+      end
+
+      def to_h
+        {
+          "receiver" => @receiver, "method" => @method.to_s, "singleton" => @singleton,
+          "labels" => @labels, "narrow" => @narrow, "discharge" => @discharge, "within" => @within,
+          "on_result" => @on_result, "taint" => @taint
+        }
+      end
+
+      def ==(other)
+        other.is_a?(EffectAttribution) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_receiver!(receiver)
+        value = receiver.to_s
+        unless CLASS_NAME.match?(value) || RECEIVER_PATH.match?(value) || SELF_PATH.match?(value)
+          raise ArgumentError,
+                "effect attribution receiver must be a class name, a receiver path or a self path, " \
+                "got #{receiver.inspect}"
+        end
+
+        value.dup.freeze
+      end
+
+      # A self path with no `within:` would colour a receiver-less `session` in any project class at all.
+      def validate_within!(within)
+        if within.nil?
+          raise ArgumentError, "effect attribution #{key} is a self path and must name a `within:` class" if self_path?
+
+          return nil
+        end
+
+        value = within.to_s
+        raise ArgumentError, "effect attribution `within:` must be a class name, got #{within.inspect}" unless
+          CLASS_NAME.match?(value)
+
+        value.dup.freeze
+      end
+
+      def normalize_labels(labels)
+        list = Array(labels).map { |label| label.to_s.dup.freeze }
+        raise ArgumentError, "effect attribution for #{@receiver} must declare at least one label" if list.empty?
+
+        list.uniq.sort.freeze
+      end
+
+      # `on_result:` shifts the match one link outwards, which only a class-name row can do: a receiver
+      # path already names the object, and a self path already names the frame.
+      def validate_on_result!
+        return unless @on_result
+        return unless receiver_path? || self_path?
+
+        raise ArgumentError, "effect attribution #{key} may not combine `on_result:` with a path receiver"
+      end
+
+      # A row may state a bound AND say the bound is not the whole story. `render` is the case that needs
+      # it: what the controller does IS `mutate.self` + `rails.response.write`, and what the TEMPLATE does
+      # is unknown until views become effect units (ADR-103 WD11). Reporting only the first would be a
+      # summary that reads exhaustive and is not.
+      def validate_taint!(taint)
+        return nil if taint.nil?
+
+        value = taint.to_s
+        return value.dup.freeze if TAINT_CAUSES.include?(value)
+
+        raise ArgumentError,
+              "effect attribution #{key} may only taint with one of #{TAINT_CAUSES.inspect}, " \
+              "got #{taint.inspect}"
+      end
+
+      def validate_why!(why)
+        value = why.to_s
+        raise ArgumentError, "effect attribution #{key} needs a `why:` justification" if value.empty?
+
+        value.dup.freeze
+      end
+    end
+  end
+end