rigortype 0.3.3 → 0.3.4

data/lib/rigor/analysis/runner/effect_envelope_pass.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../diagnostic"
+require_relative "../check_rules"
+require_relative "../../effects/config_envelopes"
+require_relative "../../effects/envelope_check"
+require_relative "../../effects/liskov_check"
+require_relative "../../effects/method_key"
+require_relative "../../effects/registry"
+require_relative "../../effects/signature_sources"
+require_relative "../../effects/unknown_label_check"
+require_relative "../../rbs_extended/envelope_scanner"
+require_relative "declaration_position"
+require_relative "envelope_messages"
+
+module Rigor
+  module Analysis
+    class Runner
+      # `effect.envelope-exceeded` and `effect.unknown-label`, end to end (ADR-103 WD1 / WD8 / WD12;
+      # #383 / #384).
+      #
+      # The two ride one gate and one walk on purpose. `effect.unknown-label` reports that an envelope
+      # STOPPED bounding — the fail-open degradation an unrecognised label causes — so opting into
+      # envelope enforcement is exactly what should turn it on, and reading it off any other pass
+      # would mean walking the project's signatures twice.
+      #
+      # Three steps, and the order is the cost model:
+      #
+      # 1. **Read the envelopes** off the project's own RBS ({RbsExtended::EnvelopeScanner}). A project
+      #    with `effects:` but no envelope pays this walk and stops here.
+      # 2. **Force cross-file discovery**, but only when step 1 found something — the diagnostic is
+      #    positioned at the Ruby `def`, and the discovery tables are what map a method key to one.
+      # 3. **Judge** ({Effects::EnvelopeCheck}) and render, then run the findings through the ordinary
+      #    suppression filter so `# rigor:disable effect.envelope-exceeded` on the `def` line and
+      #    `disable:` in `.rigor.yml` work exactly as they do for a per-file rule.
+      #
+      # **Why this is not part of the cached run assembly.** ADR-103 WD12 says envelope diagnostics are
+      # recomputed every run from the (possibly cached) summaries and never stored. The `effects:` block
+      # is deliberately absent from the diagnostics cache identity — that absence is what lets a project
+      # turn collection on without invalidating its check — so a finding baked into that entry would
+      # survive an `effects.check: false` edit. The pass therefore runs OUTSIDE
+      # `Runner#compute_run_diagnostics`, over whatever table the run ended up with, warm or cold.
+      class EffectEnvelopePass
+        NO_DIAGNOSTICS = [].freeze
+        private_constant :NO_DIAGNOSTICS
+
+        RULE = CheckRules::RULE_EFFECT_ENVELOPE_EXCEEDED
+        LISKOV_RULE = CheckRules::RULE_EFFECT_LISKOV_WIDENED
+        UNKNOWN_LABEL_RULE = CheckRules::RULE_EFFECT_UNKNOWN_LABEL
+
+        # Where a diagnostic about a configuration value is positioned when the loader cannot say
+        # which line the key was written on — the `rbs.coverage.quarantined-signature` precedent.
+        CONFIG_PATH = ".rigor.yml"
+        private_constant :CONFIG_PATH
+
+        RUBY_EXTENSION = ".rb"
+        private_constant :RUBY_EXTENSION
+
+        # What a `.rigor.yml` label list stops doing once one of its members is unrecognised.
+        TOLERATED_CONSEQUENCE = "the entry discharges nothing"
+        private_constant :TOLERATED_CONSEQUENCE
+
+        # An `envelopes[].effect` list degrades exactly as an annotation does: the whole tag reads ⊤.
+        ENVELOPE_CONSEQUENCE = "the entry now bounds nothing"
+        private_constant :ENVELOPE_CONSEQUENCE
+
+        # An attribution's labels are a *claim*, so an unrecognised member costs meaning rather than a
+        # bound: the labels are still attributed, and nothing in the vocabulary explains them.
+        ATTRIBUTION_CONSEQUENCE = "the attributed label means nothing to the vocabulary"
+        private_constant :ATTRIBUTION_CONSEQUENCE
+
+        # `effects.labels:` is the one list whose whole point is to introduce a spelling, so a member of
+        # it can only be unrecognised by being unregisterable — a root the loader dropped.
+        LABELS_CONSEQUENCE = "the label is not registered"
+        private_constant :LABELS_CONSEQUENCE
+
+        # @param configuration [Rigor::Configuration]
+        # @param rbs_loader [Rigor::Environment::RbsLoader, nil] the run's loader; nil disables the pass.
+        # @param effect_table [Rigor::Effects::EffectTable] the propagated graph.
+        # @param discovery [#call] forces and returns the cross-file discovery tables as
+        #   `[def_sources, singleton_def_sources, class_sources]`. Called only when an envelope exists.
+        # @param sources [Hash{String => String}] in-memory sources, for the buffer-backed run path.
+        # @param unit_sources [Hash{String => Array<String>}] `Runner#effect_sources` — where each effect
+        #   unit is defined, which is what an `effects.envelopes[].match:` path glob selects on. Its paths
+        #   are relativised against the working directory, which is the project root for every run that
+        #   reaches here (the same assumption `Snapshot.build` makes about `reach:`).
+        # @param ancestry [#call, nil] returns the run's as-written superclass table
+        #   (`FileCollection#superclasses`) — the nominal relation `effect.liskov-widened` reads. A
+        #   lambda, and called only once an envelope exists, because merging the run's collections is
+        #   not free.
+        # @param apply_tolerated [Boolean] false runs the judgment with an empty tolerated set
+        #   (`--no-tolerated-effects`).
+        def initialize(configuration:, rbs_loader:, effect_table:, discovery:, # rubocop:disable Metrics/ParameterLists
+                       sources: nil, unit_sources: nil, ancestry: nil, apply_tolerated: true,
+                       plugin_facts: nil)
+          @configuration = configuration
+          @plugin_facts = plugin_facts
+          @rbs_loader = rbs_loader
+          @effect_table = effect_table
+          @discovery = discovery
+          @sources = sources || {}
+          @unit_sources = unit_sources || {}
+          @ancestry_source = ancestry
+          @apply_tolerated = apply_tolerated
+        end
+
+        # @return [Array<Diagnostic>] one per (method, exceeding label) plus one per unrecognised
+        #   label, suppression already applied.
+        def diagnostics
+          return NO_DIAGNOSTICS unless @configuration.effects_check?
+
+          produced = config_label_diagnostics + config_envelope_diagnostics + declaration_diagnostics
+          return NO_DIAGNOSTICS if produced.empty?
+
+          suppress(produced)
+        rescue StandardError
+          # Fail-soft, like every other effects surface: an envelope Rigor cannot read must not fail a
+          # check that would otherwise pass.
+          NO_DIAGNOSTICS
+        end
+
+        private
+
+        # The envelopes, from both strata, and the judgment over them.
+        #
+        # The `.rbs` / rbs-inline walk is the expensive half and stays lazy: a project with `effects:` and
+        # no annotation pays it and stops. It is also **skipped entirely** when there is no loader — a
+        # project that writes no RBS at all still gets the configured envelopes judged, which is the whole
+        # point of the convention surface (design note § 6.2, "value on day one").
+        def declaration_diagnostics
+          scan = scan_declarations
+          return NO_DIAGNOSTICS if scan.nil? && config_envelopes.empty?
+
+          unknown_label_diagnostics(scan) + exceeded_diagnostics(scan)
+        end
+
+        def scan_declarations
+          return nil if @rbs_loader.nil?
+
+          scan = RbsExtended::EnvelopeScanner.scan(sources: signature_sources, registry: registry)
+          scan.empty? ? nil : scan
+        end
+
+        # The envelope contract itself. Needs the propagated graph and the discovery tables the `def`
+        # positions come from, so it is skipped when collection produced nothing — an unrecognised
+        # label is still reported in that case, because it is a fact about the declaration alone.
+        #
+        # The two contracts ride one resolution of the strata and one force of the discovery tables:
+        # `effect.envelope-exceeded` asks whether a method honours its OWN bound, `effect.liskov-widened`
+        # whether an override honours the one it inherits, and both read the same distributed table.
+        def exceeded_diagnostics(scan)
+          return NO_DIAGNOSTICS if @effect_table.empty?
+
+          judge(scan).map { |finding| build_diagnostic(finding) } +
+            judge_liskov(scan).map { |finding| build_liskov_diagnostic(finding) }
+        end
+
+        def unknown_label_diagnostics(scan)
+          return NO_DIAGNOSTICS if scan.nil?
+
+          findings = Effects::UnknownLabelCheck.for_envelopes(
+            method_envelopes: scan.method_envelopes, class_envelopes: scan.class_envelopes,
+            registry: registry
+          )
+          build_unknown_label_diagnostics(findings)
+        end
+
+        # The `.rigor.yml` label lists. Their SHAPE is already a tier-2 load error; this is the other
+        # half, a member the registry does not know after plugin load, which would otherwise fail
+        # silently — a `tolerated:` entry that discharges nothing, an envelope that reads ⊤, an
+        # attribution nothing can interpret.
+        def config_label_diagnostics
+          findings = config_label_findings("effects.tolerated", @configuration.effects_tolerated,
+                                           TOLERATED_CONSEQUENCE) +
+                     config_label_findings("effects.labels", @configuration.effects_labels,
+                                           LABELS_CONSEQUENCE) +
+                     attribution_findings
+          build_unknown_label_diagnostics(findings)
+        end
+
+        def config_label_findings(key_path, labels, consequence)
+          return [] if labels.empty?
+
+          Effects::UnknownLabelCheck.for_config(
+            labels: labels, key_path: key_path, consequence: consequence, registry: registry
+          )
+        end
+
+        def attribution_findings
+          @configuration.effects_attribution.flat_map do |key, labels|
+            config_label_findings("effects.attribution.#{key}", labels, ATTRIBUTION_CONSEQUENCE)
+          end
+        end
+
+        # `envelopes[].effect` — reported per entry, so the message names the stanza a reader has to edit
+        # rather than the label list it happens to share with another entry.
+        def config_envelope_diagnostics
+          findings = config_envelopes_entries.flat_map do |entry|
+            next [] if entry.unknown_labels.empty?
+
+            config_label_findings("effects.envelopes[#{entry.index}].effect", entry.labels,
+                                  ENVELOPE_CONSEQUENCE)
+          end
+          build_unknown_label_diagnostics(findings)
+        end
+
+        def build_unknown_label_diagnostics(findings)
+          findings.map { |finding| build_unknown_label_diagnostic(finding) }
+                  .sort_by { |diagnostic| [diagnostic.path, diagnostic.line, diagnostic.message] }
+        end
+
+        def build_unknown_label_diagnostic(finding)
+          path, line = position_of(finding)
+          Diagnostic.new(
+            path: path, line: line, column: 1, message: finding.message,
+            severity: :info, rule: UNKNOWN_LABEL_RULE, source_family: :builtin
+          )
+        end
+
+        def position_of(finding)
+          DeclarationPosition.of(finding, sources: @sources)
+        end
+
+        # The vocabulary an unknown label is judged against: the shipped registry plus whatever
+        # `effects.labels:` opened, plus every loaded plugin's `effect_labels:` (#387). A project may open
+        # any root — the listing IS the vouching act — so nothing the project writes can raise on
+        # ownership; a plugin overreaching its root is refused inside {Effects::PluginFacts}, whose warning
+        # rides the report rather than this diagnostic stream.
+        def registry
+          @registry ||= Effects::Registry.for_configuration(@configuration, plugin_facts: @plugin_facts)
+        end
+
+        # `effects.envelopes:`, resolved against the vocabulary once per run.
+        def config_envelopes_entries
+          @config_envelopes_entries ||= Effects::ConfigEnvelopes.build(
+            entries: @configuration.effects_envelopes, registry: registry
+          )
+        end
+
+        # The classes those entries select, as class-keyed envelopes. Keyed off the effect table's own
+        # class names, so an entry naming a namespace or a path with no analysed unit behind it simply
+        # selects nothing.
+        def config_envelopes
+          @config_envelopes ||= Effects::ConfigEnvelopes.for_classes(
+            entries: config_envelopes_entries, class_names: table_class_names, sources: @unit_sources
+          )
+        end
+
+        def table_class_names
+          @effect_table.keys.filter_map { |key| Effects::MethodKey.owner(key) }.uniq
+        end
+
+        def judge(scan)
+          Effects::EnvelopeCheck.run(
+            table: @effect_table,
+            method_envelopes: scan&.method_envelopes || {}, class_envelopes: scan&.class_envelopes || {},
+            config_envelopes: config_envelopes,
+            positions: positions,
+            apply_tolerated: @apply_tolerated
+          )
+        end
+
+        def judge_liskov(scan)
+          Effects::LiskovCheck.run(
+            table: @effect_table, superclasses: ancestry,
+            method_envelopes: scan&.method_envelopes || {}, class_envelopes: scan&.class_envelopes || {},
+            config_envelopes: config_envelopes,
+            positions: positions,
+            apply_tolerated: @apply_tolerated
+          )
+        end
+
+        # The discovery tables both judgments position their findings from, forced once.
+        def positions
+          @positions ||= begin
+            def_sources, singleton_def_sources, class_sources = @discovery.call
+            Effects::EnvelopeCheck::Positions.build(
+              def_sources: def_sources, singleton_def_sources: singleton_def_sources,
+              class_sources: class_sources
+            )
+          end
+        end
+
+        def ancestry
+          @ancestry ||= @ancestry_source&.call || {}
+        end
+
+        # Everything an envelope may be written in — {Effects::SignatureSources} owns the stratum rule.
+        def signature_sources
+          Effects::SignatureSources.collect(
+            signature_paths: @configuration.signature_paths, virtual_rbs: @rbs_loader.virtual_rbs
+          )
+        end
+
+        def build_diagnostic(finding)
+          Diagnostic.new(
+            path: finding.path || ".rigor.yml",
+            line: finding.line,
+            column: 1,
+            message: message_for(finding),
+            severity: :warning,
+            rule: RULE,
+            source_family: :builtin,
+            method_name: method_name_of(finding.key)
+          )
+        end
+
+        def message_for(finding)
+          EnvelopeMessages.exceeded(finding)
+        end
+
+        def build_liskov_diagnostic(finding)
+          Diagnostic.new(
+            path: finding.path || CONFIG_PATH,
+            line: finding.line,
+            column: 1,
+            message: EnvelopeMessages.liskov(finding),
+            severity: :warning,
+            rule: LISKOV_RULE,
+            source_family: :builtin,
+            method_name: method_name_of(finding.key)
+          )
+        end
+
+        def method_name_of(key)
+          index = key.index("#") || key.index(".")
+          index.nil? ? nil : key[(index + 1)..]
+        end
+
+        # The ordinary suppression pipeline, per file: `# rigor:disable` / `# rigor:disable-file` comments
+        # from the Ruby file the diagnostic is positioned in, plus the project's `disable:` list. Reading
+        # the comments costs one parse per file that actually carries a finding.
+        def suppress(diagnostics)
+          diagnostics.group_by(&:path).flat_map do |path, group|
+            CheckRules.filter_suppressed(
+              group, comments: comments_for(path), disabled_rules: @configuration.disabled_rules
+            )
+          end
+        end
+
+        # Only a Ruby file has Ruby comments. An `effect.unknown-label` positioned in `.rbs` or at
+        # `.rigor.yml` is suppressible by the `disable:` list and by the baseline, never by an in-file
+        # comment — parsing YAML or RBS as Ruby to look for one would be a lie dressed as a feature.
+        def comments_for(path)
+          return [].freeze unless path.end_with?(RUBY_EXTENSION)
+
+          source = @sources[path]
+          result = source ? Prism.parse(source) : Prism.parse_file(path)
+          result.comments
+        rescue StandardError
+          [].freeze
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/runner/envelope_messages.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    class Runner
+      # How an effect-envelope finding is worded (ADR-103 WD14; #383 / #386).
+      #
+      # One module for both contracts, because their messages are one sentence with a swapped middle:
+      # `effect.envelope-exceeded` names the bound the method carries, `effect.liskov-widened` names the
+      # bound it inherits, and both end by naming the label that escaped. Keeping the two here is what
+      # stops them drifting into two dialects of the same explanation — and what keeps
+      # {EffectEnvelopePass} about *when* a finding is produced rather than about how it reads.
+      #
+      # The shape a reviewer can act on without re-running anything: what the method does, the shortest
+      # route to whatever proves it, the author's own spelling of the bound quoted back, and where that
+      # bound was written.
+      module EnvelopeMessages
+        module_function
+
+        # `Effects::EnvelopeCheck::Finding` — a method against its own bound.
+        def exceeded(finding)
+          "Method #{finding.key} performs #{finding.label}#{explanation(finding)}, but is declared " \
+            "#{finding.envelope.spelling}#{declared_at(finding.envelope)}, so #{finding.label} exceeds " \
+            "the envelope."
+        end
+
+        # `Effects::LiskovCheck::Finding` — an override against the bound it inherits. Two variants of
+        # one sentence, and which one a reader gets says which comparison produced the finding: what the
+        # override *does* against the inherited bound, or what it *declares* against it. Both name the
+        # ancestor's declaration, because that is where the fix usually goes.
+        def liskov(finding)
+          "Method #{finding.key} #{liskov_subject(finding)}, but overrides #{finding.ancestor_key}, " \
+            "which is declared #{finding.ancestor_envelope.spelling}" \
+            "#{declared_at(finding.ancestor_envelope)}, so #{finding.label} exceeds the inherited envelope."
+        end
+
+        def liskov_subject(finding)
+          own = finding.own_envelope
+          return "is declared #{own.spelling}#{declared_at(own)}" if own
+
+          "performs #{finding.label}#{explanation(finding)}"
+        end
+
+        def explanation(finding)
+          hops = Array(finding.chain)[1..] || []
+          parts = [finding.origin, ("via #{hops.join(' → ')}" unless hops.empty?)].compact
+          parts.empty? ? "" : " (#{parts.join(' ')})"
+        end
+
+        # A distributed annotation names the class it came from; a configured envelope does not, because
+        # its `location` already names the stanza (`.rigor.yml effects.envelopes[2]`) and the method key
+        # at the head of the message already names the class.
+        def declared_at(envelope)
+          owner = envelope.source == :class_annotation ? " on #{envelope.owner_key.split(/[#.]/).first}" : ""
+          where = envelope.location ? " at #{envelope.location}" : ""
+          "#{owner}#{where}"
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/runner/pool_coordinator.rb

@@ -61,6 +61,11 @@ module Rigor
           # slice's cross-file reads, marshalled back into `#collected_dependencies` for the runner's graph.
           @record_dependencies = record_dependencies
           @collected_dependencies = {}
+          # ADR-103 WD13 — effect collection, derived from the configuration exactly as `Runner` and
+          # `WorkerSession` derive it. A worker's per-file collections marshal back into
+          # `#collected_effects`, so a pooled run's effect graph is the sequential run's graph.
+          @record_effects = configuration.effects_enabled?
+          @collected_effects = {}
           @collect_stats = collect_stats
           @buffer = buffer
           @environment_override = environment_override
@@ -81,6 +86,11 @@ module Rigor
         # so the incremental session's dependency graph is refreshed whether analysis ran sequential or pooled.
         attr_reader :collected_dependencies
 
+        # ADR-103 WD12 — the per-file {Effects::FileCollection}s the fork pool captured this run (empty
+        # unless the configuration carries an `effects:` block and a pool run occurred). The runner merges
+        # these with its own sequential records before the post-pool fixpoint.
+        attr_reader :collected_effects
+
         # ADR-15 Phase 4b — pool mode is enabled when `@workers > 0`. Editor mode (`buffer:` non-nil)
         # silently overrides pool mode to sequential: per design § "Ractor pool mode", the pool's warm-up
         # cost dominates one-file wall time, so the pool gains nothing on a per-buffer invocation. The
@@ -179,8 +189,12 @@ module Rigor
         # per-worker dependency records back, and the Ractor path additionally lacks the cross-file
         # `project_scope_seed` its worker would need to record complete edges. Without `fork` (Windows) a
         # recording run degrades to sequential, which records correctly through `@analyze_file`.
+        #
+        # An effects run (ADR-103 WD13) is pinned for exactly the same reason — the Ractor messages carry
+        # no side-table channel — and degrades the same way. The degrade is sound rather than merely safe:
+        # the sequential fallback still collects, so the effect graph is complete either way.
         def dispatch_pool(files)
-          if @record_dependencies
+          if @record_dependencies || @record_effects
             return analyze_files_in_fork_pool(files) if Process.respond_to?(:fork)
 
             return analyze_files_sequentially_fallback(
@@ -250,6 +264,14 @@ module Rigor
         # replayed into the runner-side accumulators via their `record_*` APIs, which dedupe on the same
         # keys as a single-session run would. Net result: reporter state is identical to the sequential
         # path.
+        #
+        # **This backend cannot analyse a file under rbs 4.x, and the blocker is upstream** (#414).
+        # `RBS::Namespace.[]` interns every namespace through a process-wide flyweight cache held in
+        # module ivars (`@intern_trie_absolute` / `@intern_trie_relative`, mutable by design), and reading
+        # an unshareable module ivar from a non-main Ractor is `Ractor::IsolationError` — so every file a
+        # worker touches comes back as an internal analyzer error. What the code below fixes is the
+        # failure MODE, not the backend: the run used to hang forever instead of saying anything. Reviving
+        # the backend needs an upstream change, which is why `pool_backend` keeps `fork` as the default.
         def analyze_files_in_pool(files) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
           # Pre-warm class-level lazy memos on the MAIN Ractor. `Environment::ClassRegistry.default` is the
           # default kwarg threaded through `Environment.new` inside each worker session; lazy-initialising
@@ -303,15 +325,30 @@ module Rigor
             end
           end
 
+          # #414 — every worker is monitored BEFORE any file is dispatched, so a worker that dies at
+          # construction is still observed. `Ractor#monitor` posts `:exited` / `:aborted` to this
+          # Ractor's default port, which is the same mailbox the workers push their results to.
+          pool.each { |worker| worker.monitor(Ractor.current.default_port) }
+
           files.each_with_index { |path, index| pool[index % pool.size].send(path) }
           pool.each { |worker| worker.send(nil) }
 
           prepare_diagnostics = nil
           results_by_path = {}
-          done_count = 0
-
-          while done_count < pool.size
+          terminated = 0
+
+          # Bounded by TERMINATION, not by `:done`. A worker that dies never says `:done`, and the loop
+          # that counted `:done` blocked on `Ractor.receive` for as long as the process lived — the whole
+          # backend hung that way once `Environment.for_project` started raising `Ractor::IsolationError`
+          # inside `WorkerSession#initialize` (#414). Monitor notices are bare Symbols; worker messages
+          # are Arrays, so the two never collide.
+          while terminated < pool.size
             message = Ractor.receive
+            if message.is_a?(Symbol)
+              terminated += 1
+              next
+            end
+
             case message.first
             when :prepare
               prepare_diagnostics ||= message.last
@@ -319,13 +356,27 @@ module Rigor
               results_by_path[message[1]] = message[2]
             when :done
               merge_worker_reporters(message.last)
-              done_count += 1
             end
           end
 
-          pool.each(&:join)
+          # `join` re-raises an abnormal worker's exception as `Ractor::RemoteError`; the degrade below is
+          # this path's answer to that, so the raise carries no information the coordinator acts on.
+          pool.each do |worker|
+            worker.join
+          rescue Ractor::Error
+            nil
+          end
+
+          # The files no worker reported — every file of a worker that died, and any file in flight when
+          # it did. Re-analysed in process, exactly as the fork backend re-analyses a dead child's slice.
+          degraded = files.reject { |path| results_by_path.key?(path) }
+          unless degraded.empty?
+            environment = build_runner_environment(source_files: files)
+            degraded.each { |path| results_by_path[path] = @analyze_file.call(path, environment) }
+          end
 
-          Array(prepare_diagnostics) + files.flat_map { |path| results_by_path.fetch(path, []) }
+          diagnostics = Array(prepare_diagnostics) + files.flat_map { |path| results_by_path.fetch(path, []) }
+          degraded.empty? ? diagnostics : diagnostics.unshift(pool_degraded_diagnostic(degraded.size, "ractor"))
         end
 
         # ADR-15 Amendment (2026-05-20) — fork-based worker pool, the active backend for `workers > 0`.
@@ -378,11 +429,12 @@ module Rigor
             # The degraded slice was re-analysed on the parent session, so its dependency records live there,
             # not in a child payload — fold them in alongside the successful children's.
             @collected_dependencies.merge!(session.drain_dependencies) if @record_dependencies
+            @collected_effects.merge!(session.drain_effects) if @record_effects
           end
 
           diagnostics = Array(session.prepare_diagnostics) +
                         files.flat_map { |path| results_by_path.fetch(path, []) }
-          degraded.empty? ? diagnostics : diagnostics.unshift(fork_degraded_diagnostic(degraded.size))
+          degraded.empty? ? diagnostics : diagnostics.unshift(pool_degraded_diagnostic(degraded.size, "fork"))
         end
 
         # Child-process body for {#analyze_files_in_fork_pool}. Analyses the slice with the
@@ -399,6 +451,9 @@ module Rigor
           results = slice.to_h { |path| [path, session.analyze(path)] }
           payload = { results: results, reporters: session.drain_reporters,
                       dependencies: session.drain_dependencies }
+          # ADR-103 WD13 — the effects slot exists only on a collecting run, so a normal `--workers N` run
+          # marshals exactly the payload it marshalled before the feature existed.
+          payload[:effects] = session.drain_effects if @record_effects
           File.binwrite(out_path, Marshal.dump(payload))
           exit!(0)
         rescue StandardError
@@ -430,6 +485,7 @@ module Rigor
               results_by_path.merge!(payload.fetch(:results))
               merge_worker_reporters(payload.fetch(:reporters))
               @collected_dependencies.merge!(payload.fetch(:dependencies, {})) if @record_dependencies
+              @collected_effects.merge!(payload.fetch(:effects, {})) if @record_effects
             else
               degraded.concat(child[:slice])
             end
@@ -448,10 +504,12 @@ module Rigor
           nil
         end
 
-        def fork_degraded_diagnostic(count)
+        # Both pool backends degrade the same way — the files a dead worker owed are re-analysed in
+        # process — so they say so the same way, naming which backend it was (#414).
+        def pool_degraded_diagnostic(count, backend)
           Diagnostic.new(
             path: ".rigor.yml", line: 1, column: 1,
-            message: "fork pool degraded: #{count} file(s) re-analysed in-process " \
+            message: "#{backend} pool degraded: #{count} file(s) re-analysed in-process " \
                      "after a worker exited abnormally",
             severity: :warning, rule: "pool-degraded", source_family: :builtin
           )