rigortype 0.3.3 → 0.3.5

data/lib/rigor/analysis/worker_session.rb

@@ -10,6 +10,9 @@ require_relative "../rbs_extended/reporter"
 require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "../inference/coverage_scanner"
+require_relative "../effects/attribution"
+require_relative "../effects/collector"
+require_relative "../effects/envelope_index"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/method_dispatcher/file_folding"
 require_relative "check_rules"
@@ -93,6 +96,14 @@ module Rigor
         # normal `--workers N` run leaves it false and pays nothing (the recorder's disabled fast path).
         @record_dependencies = record_dependencies
         @file_dependencies = {}
+        # ADR-103 WD13 — effect collection, derived from the configuration exactly as `Runner` derives it,
+        # so a worker and the parent agree without a flag to keep in sync. Records marshal back through
+        # {#drain_effects}.
+        @record_effects = configuration.effects_enabled?
+        # ADR-103 WD6 / #385 — same table, derived the same way, for the same reason as `@record_effects`
+        # above: a worker and the parent agree without a flag to keep in sync.
+        @effect_attribution = Effects::Attribution.build(configuration.effects_attribution)
+        @file_effects = {}
         # ADR-32 WD4 — full project file list (frozen Array<String>) for env-build-time invocation of any
         # loaded plugin's `source_rbs_synthesizer` callable.
         @source_files = source_files
@@ -144,14 +155,52 @@ module Rigor
       # worker captures the file's cross-file reads for {#drain_dependencies}; the recorder's own disabled
       # fast path makes the unwrapped case free.
       def analyze(path)
-        return analyze_body(path) unless @record_dependencies
+        return analyze_with_effects(path) unless @record_dependencies
 
         diagnostics = nil
-        record = DependencyRecorder.record_for(path) { diagnostics = analyze_body(path) }
+        record = DependencyRecorder.record_for(path) { diagnostics = analyze_with_effects(path) }
         @file_dependencies[path] = record
         diagnostics
       end
 
+      # ADR-103 WD13 — the worker-side mirror of `Runner#analyze_with_effects`.
+      def analyze_with_effects(path)
+        return analyze_body(path) unless @record_effects
+
+        diagnostics = nil
+        collection = Effects::Collector.collect_for(
+          path, attribution: @effect_attribution, envelopes: effect_envelope_index,
+                plugin_facts: effect_plugin_facts
+        ) do
+          diagnostics = analyze_body(path)
+        end
+        @file_effects[path] = collection
+        diagnostics
+      end
+      private :analyze_with_effects
+
+      # ADR-103 WD6 / #386 — the worker-side mirror of `Runner#effect_envelope_index`. Derived from the
+      # same configuration and the session's own environment, so a worker's `≤` lane is the one the
+      # parent would have computed for the same file.
+      # ADR-103 WD10 / #387 — the worker-side mirror of `Runner#effect_plugin_facts`. The superclass table
+      # arrives with the coordinator's scope seed, so a worker resolves an `ActiveRecord::Base` row through
+      # the same project ancestry the parent would have walked.
+      def effect_plugin_facts
+        @effect_plugin_facts ||= Effects::PluginFacts.build(
+          @plugin_registry,
+          superclasses: @project_scope_seed[:discovered_superclasses] || {},
+          includes: @project_scope_seed[:discovered_includes] || {}
+        )
+      end
+      private :effect_plugin_facts
+
+      def effect_envelope_index
+        @effect_envelope_index ||= Effects::EnvelopeIndex.build(
+          configuration: @configuration, environment: @environment, plugin_facts: effect_plugin_facts
+        )
+      end
+      private :effect_envelope_index
+
       def analyze_body(path)
         parse_result = parse_source(path)
         unless parse_result.errors.empty?
@@ -160,6 +209,7 @@ module Rigor
           return parse_diagnostics(path, parse_result)
         end
 
+        Effects::Collector.record_root(parse_result.value)
         scope = seed_project_scope(Scope.empty(environment: @environment, source_path: path))
         index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
         # ADR-53 B4 — built-in collectors + plugin node rules share one walk.
@@ -204,6 +254,14 @@ module Rigor
         @file_dependencies
       end
 
+      # ADR-103 WD12 — the per-file {Effects::FileCollection}s this session collected (empty unless the
+      # configuration carries an `effects:` block). Marshal-clean by construction — frozen Hashes of
+      # Strings, `LabelSet`s of frozen Arrays, and `Data` edges — so the fork pool ships them back to the
+      # coordinator, which folds them into the runner's collection exactly as the sequential path would.
+      def drain_effects
+        @file_effects
+      end
+
       private
 
       # Mirrors {Runner#seed_project_scope}: applies the cross-file pre-pass discovery tables the

data/lib/rigor/bleeding_edge.rb

@@ -159,6 +159,28 @@ module Rigor
                  "the two corpora measured so far (Rigor's own `lib`, redmine `app/models`) it added no " \
                  "kills — every surviving breakage there is one the analyzer reports nowhere at all, not one " \
                  "it reports in a caller."
+      ),
+      # ADR-103 WD15 — the owner-ruled preview of the v0.4.0 default. `:behaviour` because it moves no rule's
+      # severity; safe under the header comment's cache-identity rule for a reason specific to this feature
+      # rather than the generic WD13 argument, so it is spelled out here: `effects:` collection is
+      # OBSERVATIONAL (ADR-103 WD13) and the `effects:` block itself is deliberately absent from the
+      # diagnostics cache-key identity, so whether this feature is adopted never changes what a `rigor check`
+      # diagnostics entry holds — only whether the (separately identity-keyed) effects sidecar slot
+      # (`Effects::Identity.descriptor`, `lib/rigor/analysis/runner.rb`) gets populated. Envelope findings
+      # (`effect.envelope-exceeded`) are recomputed every run from that sidecar and are never written into
+      # the diagnostics entry (ADR-103 WD12), so a warm diagnostics HIT is correct whichever way this feature
+      # is set, exactly like every other `:behaviour` feature. Verified against `Runner#compute_run_diagnostics`
+      # / `#serve_effect_collections` on 2026-08-17.
+      Feature.new(
+        id: "effects-on-by-default",
+        kind: :behaviour,
+        summary: "With it, a project whose `.rigor.yml` carries no `effects:` key at all behaves as though " \
+                 "it had written `effects: {}` — effect collection, the `rigor effects` verbs' cache sharing, " \
+                 "and `effects.check` all turn on with every sub-key at its default. Writing `effects: false` " \
+                 "explicitly still opts out, and a project that writes its own `effects:` block keeps that " \
+                 "block's shape untouched either way. Graduates to default-on at v0.4.0 (owner ruling, " \
+                 "2026-08-17): ADR-50 § WD7 reads \"at a major\" as \"at v0.4.0\" for this feature on the 0.x " \
+                 "evaluation line. See ADR-103 § WD15 for the preconditions that gate the flip."
       )
     ].freeze
 

data/lib/rigor/cache/incremental_snapshot.rb

@@ -51,8 +51,11 @@ module Rigor
       # nil (a clean cold rebuild — no migration). 11: ADR-67 WD6c lift adds `param_table` (the inferred-param
       # seed table the run's diagnostics were computed under, diffed on the next recheck to invalidate a
       # callee whose seeds moved because a caller changed); a pre-11 blob mismatches the SCHEMA gate and
-      # loads as nil (a clean cold rebuild — no migration).
-      SCHEMA = 11
+      # loads as nil (a clean cold rebuild — no migration). 12: ADR-103 WD13 / issue #382 adds the effects
+      # sidecar — `effect_collections` (the per-file {Rigor::Effects::FileCollection}s a collecting run
+      # produced) and the `effects_identity` they were produced under; a pre-12 blob mismatches the SCHEMA
+      # gate and loads as nil (a clean cold rebuild — no migration).
+      SCHEMA = 12
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -87,10 +90,22 @@ module Rigor
       # recomputes the table fresh (the pre-pass is whole-project by design) and diffs it against this copy;
       # a changed entry invalidates the callee's file and its symbol dependents. The types are Marshal-clean
       # by the session's per-entry filter; a dropped entry re-checks its callee, the conservative direction.
+      # ADR-103 WD13 / issue #382 — the effects sidecar, ADR-46's half of "one cache, two identities, one
+      # extra slot":
+      # `effect_collections` maps an analyzed path to the {Rigor::Effects::FileCollection} that file
+      # contributed (`{}` when collection is off), so a recheck re-collects only the changed closure and
+      # serves the rest from here. The propagated table is NEVER stored — it is recomputed from the merged
+      # whole every run, because a leaf's summary reaches every caller and a stored table would have to be
+      # invalidated by all of them.
+      # `effects_identity` is {Rigor::Effects::Identity.digest} at the run that wrote them (nil when
+      # collection was off). It is a SEPARATE gate from the global `fingerprint`: the `effects:` block is
+      # deliberately absent from `Configuration#to_h`, so turning collection on invalidates no diagnostics,
+      # and a vocabulary / catalogue / `effects:` change must invalidate the summaries alone.
       Payload = Data.define(:cache, :sources, :digests, :analyzed,
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
                             :missing, :class_decls, :seed_bundles, :plugin_fact_digest,
-                            :return_summaries, :param_table)
+                            :return_summaries, :param_table,
+                            :effect_collections, :effects_identity)
 
       # The global fingerprint that gates a snapshot load: a digest of the inputs whose change requires a full
       # rebuild — the engine version + schema, the engine's own SOURCE when the version does not pin it, the
@@ -206,7 +221,9 @@ module Rigor
           seed_bundles: data[:seed_bundles] || {},
           plugin_fact_digest: data[:plugin_fact_digest],
           return_summaries: data[:return_summaries] || {},
-          param_table: data[:param_table] || {}
+          param_table: data[:param_table] || {},
+          effect_collections: data[:effect_collections] || {},
+          effects_identity: data[:effects_identity]
         )
       end
       private :payload_from
@@ -227,7 +244,9 @@ module Rigor
           seed_bundles: payload.seed_bundles,
           plugin_fact_digest: payload.plugin_fact_digest,
           return_summaries: payload.return_summaries,
-          param_table: payload.param_table
+          param_table: payload.param_table,
+          effect_collections: payload.effect_collections,
+          effects_identity: payload.effects_identity
         )
         blob = Zlib::Deflate.deflate(raw)
         tmp = "#{@path}.#{Process.pid}.tmp"

data/lib/rigor/cli/check_command.rb

@@ -459,6 +459,11 @@ module Rigor
           # key. `:unset` means "no flag — use the configured selection"; `true` adopts the whole overlay, `false`
           # adopts none, and an Array of ids adopts only those (see `apply_bleeding_edge_override`).
           bleeding_edge: :unset,
+          # ADR-103 WD1 / #385 — the effect-policy audit switch. Judges `effect.envelope-exceeded` as if
+          # `effects.tolerated:` were empty, so a project can see what its discharge policy is hiding
+          # without editing the policy. Judgment-time only: the run, its collection and its cache identity
+          # are identical either way.
+          no_tolerated_effects: false,
           # Type-precision coverage block. Off by default — it is a second precision pass over the analyzed files (the
           # same scan `rigor coverage` runs), so it is opt-in to keep the default check path's cost unchanged. When set,
           # `--format json` gains a `coverage` object (scan_files + precision tiers) and the text output prints a
@@ -528,6 +533,10 @@ module Rigor
                   "ADR-50: ignore any configured bleeding_edge: selection for this run") do
             options[:bleeding_edge] = false
           end
+          opts.on("--no-tolerated-effects",
+                  "ADR-103: check effect envelopes as if effects.tolerated: were empty") do
+            options[:no_tolerated_effects] = true
+          end
         end
         parser.parse!(@argv)
         options
@@ -558,9 +567,12 @@ module Rigor
 
         path = options.fetch(:config) || Configuration.discover
         data = path && File.exist?(path) ? Configuration.load_with_includes(path) : {}
+        # ADR-103 WD15 — captured before `DEFAULTS.merge` below folds "no `effects:` key" and "`effects:
+        # false`" into the same value; see `Configuration.load`'s identical capture.
+        effects_key_present = data.key?("effects")
         data = data.dup
         data["plugins"] = inject_treat_all_as_inline_rbs(Array(data["plugins"]))
-        Configuration.new(Configuration::DEFAULTS.merge(data))
+        Configuration.new(Configuration::DEFAULTS.merge(data), effects_key_present)
       end
 
       # ADR-50 § WD2 — applies the `--bleeding-edge[=ids]` / `--no-bleeding-edge` CLI selection over the configured

data/lib/rigor/cli/check_runner_factory.rb

@@ -35,7 +35,10 @@ module Rigor
           cache_store: cache_store,
           collect_stats: options.fetch(:stats),
           workers: resolve_workers(options, configuration),
-          buffer: buffer
+          buffer: buffer,
+          # ADR-103 #385 — absent from `doctor`'s option hash and every other reuser's, so it defaults off
+          # for them without each having to declare a key about a feature they do not surface.
+          no_tolerated_effects: options.fetch(:no_tolerated_effects, false)
         )
       end
 

data/lib/rigor/cli/effects_command.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "optionparser"
+
+require_relative "../configuration"
+require_relative "../analysis/runner"
+require_relative "../effects/plugin_facts"
+require_relative "../effects/registry"
+require_relative "../plugin/loader"
+require_relative "../cache/store"
+require_relative "command"
+require_relative "effects_renderer"
+require_relative "effects_report"
+require_relative "effects_snapshot_command"
+require_relative "options"
+
+module Rigor
+  class CLI
+    # ADR-103 — executes `rigor effects`.
+    #
+    # Two surfaces behind one command, the shape `rigor baseline` already has:
+    #
+    # - `rigor effects [PATH…]` — the **report**. Runs the same analysis `rigor check` runs, with effect
+    #   collection on, and prints the resulting summaries instead of the diagnostic stream.
+    # - `rigor effects {update,check,diff,explain}` — the committed **effect snapshot** and its drift
+    #   gate, in {EffectsSnapshotCommand}.
+    #
+    # Neither emits a diagnostic nor enters `rigor check`'s stream; the report always exits 0, and only
+    # `check` ever exits non-zero (1 on drift, 64 on a usage error).
+    #
+    # The command turns collection on for its own run by loading the project's configuration and enabling
+    # an implicit `effects: {}` when the file carries no `effects:` block — the ad-hoc mode ADR-103 WD14
+    # describes. A project that *does* configure `effects:` gets its own settings instead, and then this
+    # run shares the whole cache with `rigor check`: the diagnostics come from the ADR-45 run entry and the
+    # summaries from the effects sidecar keyed beside it (#382), so `rigor effects` after `rigor check` in
+    # the same job is a warm hit plus the fixpoint. The ad-hoc mode digests a different `effects:` block
+    # than the project's, so it shares the diagnostics entry and keys its own effects slot.
+    class EffectsCommand < Command
+      USAGE = "Usage: rigor effects [options] [paths]"
+
+      # @return [Integer] CLI exit status: 0 on success, 1 on `check` drift, 64 on a usage error.
+      def run
+        verb = @argv.first
+        return run_verb(verb) if EffectsSnapshotCommand::VERBS.include?(verb)
+        return print_help if %w[help --help -h].include?(verb)
+
+        run_report
+      end
+
+      private
+
+      def run_verb(verb)
+        @argv.shift
+        EffectsSnapshotCommand.new(argv: @argv, verb: verb, out: @out, err: @err).run
+      end
+
+      def print_help
+        @out.puts(help)
+        0
+      end
+
+      def help
+        <<~HELP
+          #{USAGE}
+
+          With no subcommand, prints one line per method: its proven effect labels and whether that
+          list is exhaustive. A PATH selects which methods are printed, never which are analysed.
+
+          Options:
+            --config=PATH        Path to the Rigor configuration file
+            --format=FORMAT      Output format: text (default) or json
+            --full               List every method, including the ones with nothing to say
+            --label=LABEL        Only methods carrying LABEL (or a label under it), in either lane
+            --pure               Only methods proven to do nothing beyond mutate.local
+            --limit=N            Print at most N methods
+            --why                Expand each method's unresolved reasons and declared-lane sources
+            --list-labels        Print the effect vocabulary this project can name, and exit
+
+          Subcommands (the committed effect snapshot, ADR-103 WD7):
+            update      Write the snapshot to effects.snapshot.path. Commit it; review its diff.
+            check       Recompute and compare; exits 1 on drift, 0 when fresh.
+            diff        The same comparison, never gating.
+            explain     The shortest edge path behind a reach change (--symbol KEY for one unit).
+
+          Run `rigor effects <subcommand> --help` for subcommand options.
+        HELP
+      end
+
+      def run_report
+        options = parse_options
+        return usage_error("unsupported format: #{options.fetch(:format)}") unless FORMATS.include?(options[:format])
+
+        configuration = Configuration.load(options.fetch(:config)).with_effects_enabled
+        return list_labels(configuration) if options.fetch(:list_labels)
+
+        scope = @argv.dup
+        table, sources = analyze(configuration, scope)
+        report = EffectsReport.build(
+          table, full: options.fetch(:full), sources: sources, scope: scope,
+                 label: options.fetch(:label), pure: options.fetch(:pure), limit: options.fetch(:limit)
+        )
+        note_scope(scope, report, table)
+        EffectsRenderer.new(out: @out, why: options.fetch(:why)).render(report, format: options.fetch(:format))
+        0
+      end
+
+      # A path argument is a **view**, and the note says so (#439).
+      #
+      # It used to narrow the analysed set, and effect labels are transitive over whatever was analysed —
+      # so `rigor effects app/controllers/issues_controller.rb` reported `IssuesController#create: [] …?`
+      # where the whole-project run reported four labels and a declared lane. The weakened answer was
+      # indistinguishable from a genuinely effect-free method, and a path argument is the only tractability
+      # lever the report has, so it was the thing an adopter reached for first.
+      #
+      # The note goes to stderr rather than into the report: it is about the invocation, not about the
+      # code, and `--format json` and `rigor effects … > report.txt` both stay exactly what they were.
+      def note_scope(scope, report, table)
+        return if scope.empty?
+
+        if report.empty?
+          @err.puts("rigor: no effect unit is defined in #{scope.join(', ')} " \
+                    "(a path selects what is printed, not what is analysed)")
+          return
+        end
+
+        @err.puts("rigor: showing #{report.rows.length} of #{table.size} units, selected by " \
+                  "#{scope.join(', ')}; a path narrows the printing and not the analysis, so every " \
+                  "label is the one the whole-project run reports")
+      end
+
+      FORMATS = %w[text json].freeze
+      private_constant :FORMATS
+
+      def parse_options
+        options = { config: nil, format: "text", full: false, no_tolerated: false, label: [], pure: false,
+                    limit: nil, why: false, list_labels: false }
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          Options.add_config(opts, options)
+          opts.on("--format=FORMAT", "Output format: text (default) or json") { |value| options[:format] = value }
+          opts.on("--full", "List every method, including the ones with nothing to say") do
+            options[:full] = true
+          end
+          opts.on("--label=LABEL", "Only methods carrying LABEL (or a label under it), in either lane") do |value|
+            options[:label].concat(value.split(",").map(&:strip).reject(&:empty?))
+          end
+          opts.on("--pure", "Only methods proven to do nothing beyond mutate.local — the %a{pure} set") do
+            options[:pure] = true
+          end
+          opts.on("--limit=N", Integer, "Print at most N methods") { |value| options[:limit] = value }
+          opts.on("--why", "Expand each method's unresolved reasons and declared-lane sources") do
+            options[:why] = true
+          end
+          opts.on("--list-labels", "Print the effect vocabulary this project can name, and exit") do
+            options[:list_labels] = true
+          end
+          # Accepted here and deliberately inert, exactly as it is on `update`: the report is an
+          # observation, and observations are undischarged. Only a JUDGMENT reads `effects.tolerated:` —
+          # `rigor effects check` / `diff`, and `rigor check`'s envelope contract.
+          opts.on("--no-tolerated-effects", "Judge as if effects.tolerated: were empty (inert on the report)") do
+            options[:no_tolerated] = true
+          end
+        end.parse!(@argv)
+        options
+      end
+
+      def usage_error(message)
+        @err.puts(message)
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
+      # Sequential and cache-backed, through the same ADR-45 whole-run result cache `rigor check` uses:
+      # the diagnostics entry serves the run and the #382 effects sidecar serves the collections, leaving
+      # only the fixpoint. Sequential is not a cache decision — the run-result cache declines pool mode —
+      # but a collecting run is pinned to the fork backend anyway, so `workers: 0` costs nothing here.
+      # #429 — the vocabulary, from the product rather than from a document the gem does not ship.
+      #
+      # Four configuration keys and two annotation forms all require typing an effect label, and until
+      # this there was no way to find out what the labels are: the manual's pointers resolve into
+      # `docs/type-specification/`, which `rigortype.gemspec` does not package. The registry is shipped
+      # data and already knows the answer; nothing surfaced it.
+      #
+      # It loads plugins but never analyses, because a plugin is where `rails.flash.write` comes from and
+      # a reader deciding what to write in `effects.envelopes:` needs to see it. A plugin that fails to
+      # load costs its labels and nothing else — `rigor plugins` is where that failure is reported.
+      def list_labels(configuration)
+        registry = project_registry(configuration)
+        @out.puts("Effect vocabulary — #{registry.labels.length} labels (vocabulary #{registry.vocabulary_version})")
+        registry.roots.each do |root|
+          @out.puts
+          @out.puts(root_heading(root, registry))
+          in_root = registry.labels.select { |label| Effects::Label.root(label) == root }
+          in_root.each_slice(4) { |slice| @out.puts("  #{slice.join(', ')}") }
+        end
+        @out.puts
+        @out.puts("A bound naming a label admits everything under it and nothing above it: `io` covers " \
+                  "`io.db.read`, `io.db.read` does not cover `io`.")
+        0
+      end
+
+      # A shipped root carries the registry's own one-liner; a root a plugin or this project opened
+      # carries where it came from instead, which is the more useful thing to say about it.
+      def root_heading(root, registry)
+        description = registry.descriptions[root]
+        return "#{root} — #{description}" if description
+
+        "#{root} — opened by a plugin or by this project's `effects.labels:`"
+      end
+
+      def project_registry(configuration)
+        services = Plugin::Services.new(reflection: Reflection, type: Type::Combinator,
+                                        configuration: configuration, cache_store: nil)
+        plugins = Plugin::Loader.load(configuration: configuration, services: services)
+        Effects::Registry.for_configuration(configuration, plugin_facts: Effects::PluginFacts.build(plugins))
+      rescue StandardError
+        Effects::Registry.for_configuration(configuration)
+      end
+
+      # The analysed set is the configured `paths:` **plus** whatever the arguments name — never the
+      # arguments alone (#439). An effect summary is transitive over whatever was analysed, so analysing
+      # less does not filter the report, it lowers every answer in it: `rigor effects
+      # app/controllers/issues_controller.rb` used to report `IssuesController#create: [] …?` where the
+      # whole-project run reported four labels and a declared lane, with nothing marking the difference.
+      #
+      # The union rather than the configured paths alone, so that pointing the command at a tree the
+      # configuration does not cover — which is what every `rigor effects PATH` invocation from outside a
+      # project does — still analyses it. Inside a project the argument is already under `paths:` and the
+      # union is the configured set unchanged.
+      #
+      # @return [Array(Rigor::Effects::EffectTable, Hash{String=>Array<String>})] the table, and which
+      #   file each unit was defined in — the map {EffectsReport} needs to answer a path argument.
+      def analyze(configuration, scope)
+        runner = Analysis::Runner.new(
+          configuration: configuration,
+          cache_store: Cache::Store.new(root: configuration.cache_path),
+          collect_stats: false,
+          workers: 0
+        )
+        runner.run((configuration.paths + scope).uniq)
+        [runner.effect_table, runner.effect_sources]
+      end
+    end
+  end
+end

data/lib/rigor/cli/effects_diff_renderer.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../effects/snapshot_diff"
+require_relative "renderable"
+
+module Rigor
+  class CLI
+    # Prints a {Rigor::Effects::SnapshotDiff} — what `rigor effects check` and `rigor effects diff` show a
+    # reviewer (ADR-103 WD7).
+    #
+    # The text form is grouped by table and then by policy: real drift under `methods:` / `reach:`,
+    # policy-discharged drift under `tolerated:`, and a regeneration event — a record written by a
+    # different Rigor, vocabulary or `effects:` block — under `regeneration:` above both. It closes with
+    # the one line the whole workflow turns on: intent is expressed by regenerating and committing the
+    # file, not by annotating the code.
+    #
+    # It is deliberately not a diagnostic format: no severities, no positions, no exit-code weight of its
+    # own. The exit code comes from the gate.
+    class EffectsDiffRenderer
+      include Renderable
+
+      # How each category renders as the marker after the symbol. Steins' event vocabulary, made
+      # symmetric: `≤` is the declared lane, and a hedged removal says why it is hedged.
+      MARKERS = {
+        Effects::SnapshotDiff::LABEL_ADDED => "+ %<label>s",
+        Effects::SnapshotDiff::LABEL_REMOVED => "- %<label>s",
+        Effects::SnapshotDiff::DECLARED_ADDED => "≤+ %<label>s",
+        Effects::SnapshotDiff::DECLARED_REMOVED => "≤- %<label>s",
+        Effects::SnapshotDiff::MATERIALISED => "materialised %<label>s (declared → proven)",
+        Effects::SnapshotDiff::SYMBOL_ADDED => "+symbol %<detail>s",
+        Effects::SnapshotDiff::SYMBOL_REMOVED => "-symbol %<detail>s"
+      }.freeze
+
+      HEDGED_REMOVAL = "-? %<label>s (current summary is not exhaustive)"
+
+      # Both commands, because they answer the two questions a drift report raises and a reader almost
+      # always asks them in this order (#435). `explain` is the one the manual's own narrative reaches for
+      # first, and the footer used to name only the one that makes the report go away.
+      CLOSING_LINE = "Run `rigor effects explain` to see what caused this, and `rigor effects update` to " \
+                     "accept it."
+
+      def initialize(out:, path:)
+        @out = out
+        @path = path
+      end
+
+      private
+
+      def render_text(diff)
+        if diff.fresh?
+          @out.puts("No effect drift against #{@path}.")
+          return
+        end
+
+        @out.puts("Effect drift against #{@path}:")
+        %w[snapshot header methods reach].each { |table| render_section(table, diff.events_for(table)) }
+        render_section("tolerated", diff.tolerated_events, qualified: true)
+        render_footer(diff)
+      end
+
+      # `qualified:` names each event's table inline, which the `tolerated:` heading needs: it pools events
+      # from both tables, and one symbol commonly appears in each.
+      def render_section(table, events, qualified: false)
+        return if events.empty?
+
+        @out.puts("")
+        @out.puts("#{section_name(table)}:")
+        events.each do |event|
+          suffix = qualified ? "  (#{event.table})" : ""
+          @out.puts("  #{render_event(event)}#{suffix}")
+        end
+      end
+
+      def section_name(table)
+        case table
+        when "header" then "regeneration"
+        when "snapshot" then "snapshot"
+        else table
+        end
+      end
+
+      def render_event(event)
+        marker = marker_for(event)
+        event.symbol.nil? ? marker : "#{event.symbol}  #{marker}"
+      end
+
+      def marker_for(event)
+        return format(HEDGED_REMOVAL, label: event.label) if
+          event.category == Effects::SnapshotDiff::LABEL_REMOVED && event.hedged?
+
+        template = MARKERS[event.category]
+        return event.detail.to_s unless template
+
+        format(template, label: event.label.to_s, detail: event.detail.to_s)
+      end
+
+      def render_footer(diff)
+        footer = diff.footer
+        @out.puts("")
+        unless footer[:added_symbols].zero? && footer[:removed_symbols].zero?
+          @out.puts("symbols: +#{footer[:added_symbols]} / -#{footer[:removed_symbols]} " \
+                    "(a rename is one of each)")
+        end
+        @out.puts(CLOSING_LINE)
+      end
+
+      def render_json(diff)
+        @out.puts(JSON.pretty_generate(
+                    "fresh" => diff.fresh?,
+                    "events" => diff.events.map(&:to_h),
+                    "footer" => {
+                      "added_symbols" => diff.footer[:added_symbols],
+                      "removed_symbols" => diff.footer[:removed_symbols]
+                    },
+                    "header" => {
+                      "snapshot" => @path,
+                      "gate" => diff.gate.to_s,
+                      "recorded" => diff.recorded&.header,
+                      "current" => diff.current.header
+                    }
+                  ))
+      end
+    end
+  end
+end