rigortype 0.3.2 → 0.3.4

data/docs/manual/plugins/rigor-rspec.md

@@ -67,6 +67,14 @@ to enable project-wide alongside non-spec files.
   not flagged.
 - Constant validation (`RSpec.describe SomeClass`) is the
   engine's job, not this plugin's.
+- **No roots for [`rigor unused`](../02-cli-reference.md#rigor-unused).**
+  `RSpec.describe User` is already recorded as a reference, stamped
+  with the `test` role because it came from a spec. Publishing spec
+  references as roots would strip that role, promote every
+  spec-referenced class to production-reachable, and delete the
+  report's **Reachable only from test code** section — the row that
+  tells you a class is dead production code with a live test. The
+  ordinary handling is the correct one.
 
 ## Related plugins
 

data/docs/manual/plugins/rigor-sidekiq.md

@@ -50,11 +50,61 @@ plugins:
     config:
       worker_search_paths: ["app/workers", "app/sidekiq"]          # default
       worker_marker_modules: ["Sidekiq::Job", "Sidekiq::Worker"]   # default
+      schedule_paths:                                              # default
+        - "config/schedule.yml"
+        - "config/sidekiq.yml"
 ```
 
 The default `worker_marker_modules` covers both modern Sidekiq
 (`Sidekiq::Job`, since 6.3) and the legacy `Sidekiq::Worker`.
 
+`schedule_paths` are the schedule *files* — not directories — behind
+the reachability roots below. The defaults are where the two schedule
+layouts conventionally live; list your own path if you keep the
+schedule elsewhere.
+
+## Worker roots for `rigor unused`
+
+A cron-scheduled worker is enqueued **by name from YAML**, so
+`NightlyReportWorker` can appear nowhere in your code. Without help,
+[`rigor unused`](../02-cli-reference.md#rigor-unused) reports a job
+that runs every night as possibly dead. This plugin supplies the
+workers your schedule names, so they drop out of the candidate list:
+
+```yaml
+# config/schedule.yml (sidekiq-cron)      config/sidekiq.yml (sidekiq-scheduler)
+nightly_report:                           :scheduler:
+  cron: "0 3 * * *"                         :schedule:
+  class: "NightlyReportWorker"                nightly_report:
+                                                every: "1h"
+                                                class: "NightlyReportWorker"
+```
+
+It reads the `class:` key and nothing else. In particular a **queue
+name is not a class name**: the `:queues:` list in `sidekiq.yml`
+supplies no roots, because inflecting `report_worker` into
+`ReportWorker` would root a worker on a naming coincidence. And a
+`class:` naming a worker the plugin never discovered is dropped rather
+than published, so a typo costs you a root instead of quietly hiding a
+dead worker.
+
+`MyWorker.perform_async` still supplies nothing — it is an ordinary
+constant reference the report already sees. Neither does the mere
+existence of a file under `app/workers`: a worker nothing enqueues
+stays in the report, which is the answer you wanted.
+
+The schedule is read with `YAML.safe_load`; nothing boots.
+A missing, unreadable or malformed file is skipped without affecting
+the rest of the run.
+
+If your workers include a project concern (`include ApplicationWorker`)
+rather than `Sidekiq::Job` directly, add that concern to
+`worker_marker_modules` — otherwise the plugin discovers no workers,
+every scheduled name is dropped, and you get no roots at all. GitLab's
+`config/schedule.yml` names 111 workers, all of them concern-based:
+with the default markers that is 0 roots, and with `ApplicationWorker`
+added it is 100.
+
 ## Limitations
 
 - **Direct `include` only.** A worker that mixes in a custom concern
@@ -68,6 +118,10 @@ The default `worker_marker_modules` covers both modern Sidekiq
   `perform_at` is consumed as the schedule regardless of its type.
 - **Chained `set(...)`** (`Worker.set(queue: "low").perform_async(...)`)
   is validated as a normal call; `set`'s own options are not checked.
+- **Schedule roots are read from `class:` only.** `sidekiq-cron`'s
+  alternative `klass:` spelling, and a schedule built in Ruby with
+  `Sidekiq::Cron::Job.load_from_hash!`, supply no roots — the worker
+  stays a `rigor unused` candidate rather than being guessed at.
 
 ## Plugin internals
 

data/lib/rigor/analysis/check_rules/always_truthy_condition_collector.rb

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../../source/node_children"
+require_relative "../../inference/optimistic_origin"
 require_relative "inferred_param_guard"
 
 module Rigor
@@ -108,6 +109,13 @@ module Rigor
           # the precision-additive contract.
           return if InferredParamGuard.rooted?(predicate, scope)
 
+          # Issue #313 — a predicate whose constancy rests on an optimistically nil-free carrier is a bet, not
+          # proof: `MAP[key]` omits `nil` because pessimising the defaulted-Hash idiom costs more false
+          # positives than the miss it would model, so `MAP[key].nil?` folding to `false` says nothing about
+          # whether the key was there. The spec forbids this rule concluding from such a value; the derivation
+          # is what carries the mark across `.nil?`, `!` and `&&` / `||` to the predicate the rule reads.
+          return unless Inference::OptimisticOrigin.resolve(predicate, scope).nil?
+
           predicate_type = scope.type_of(predicate)
           return unless predicate_type.is_a?(Type::Constant)
 

data/lib/rigor/analysis/check_rules/declaration_sourced_guard.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # ADR-58 WD1 — the shared "is this value's optionality declaration-sourced?" predicate.
+      #
+      # A `nil` whose only provenance is a declaration (the class-ivar index seed of a ctor `@x = nil`, a
+      # non-definitely-assigned ivar read) is real type information but not diagnostic fuel: the working
+      # program's cross-method invariant is assumed per the robustness principle ([ADR-5]). Every negative rule
+      # that would fire *because of* such a nil must therefore consult the same provenance question, and get the
+      # same answer.
+      #
+      # Before issue #324 each rule spelled the lookup itself, and they drifted: `call.possible-nil-receiver`
+      # read the `:local` mark (so `r = @right; r.key` was excused — ADR-58's own motivating shape), while both
+      # `call.argument-type-mismatch` gates opened by requiring a literal `Prism::InstanceVariableReadNode`, so
+      # `c = @count; sink.take_int(c)` fired on the same value with the same provenance. This module is that one
+      # question, asked in one place.
+      #
+      # **The mark is deliberately NOT transitive.** `Scope#with_declaration_sourced_local`
+      # ({Inference::StatementEvaluator#eval_local_write}) stamps `:local` only when the RHS is a *pure read of a
+      # currently declaration-sourced ivar*, so a second hop (`c = @count; d = c`) and an `||=` rewrite land on
+      # the plain `with_local` path and carry no mark.
+      #
+      # A branch join is NOT one of those cases, contrary to what this comment claimed when it landed: both
+      # arms of `if c then r = @count else r = @count end` stamp `(:local, :r)`, and `join_declaration_sourced`
+      # INTERSECTS, so the mark survives. Only an *asymmetric* join drops it, and by that intersection rather
+      # than by reaching `with_local`. The normative statement — establishment, drop, join and the full list of
+      # unmarked shapes, each verified against the implementation — is
+      # `docs/internal-spec/inference-engine.md` § "Declaration-sourced provenance mark (ADR-58)"; keep this
+      # comment subordinate to it.
+      #
+      # So `marked?` matches exactly the two node shapes the scope actually models and invents no propagation
+      # of its own; anything flow-live keeps firing.
+      module DeclarationSourcedGuard
+        module_function
+
+        # True when `node` is a direct read of a binding whose optionality is purely declaration-sourced. Any
+        # flow-live touch (a method-local `@x = nil` write, a failed-guard narrowing, a rebinding local write)
+        # drops the mark upstream, so this returns false there and the caller fires exactly as before.
+        def marked?(node, scope)
+          case node
+          when Prism::InstanceVariableReadNode then scope.declaration_sourced?(:ivar, node.name)
+          when Prism::LocalVariableReadNode then scope.declaration_sourced?(:local, node.name)
+          else false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/check_rules/rule_ids.rb

@@ -44,6 +44,28 @@ module Rigor
       # return, used in value context. Authored `:warning`, resolved `:off` by every profile and promoted to
       # `:warning` only by the `use-of-void-value` bleeding-edge feature.
       RULE_VALUE_USE_VOID = "static.value-use.void"
+      # ADR-103 WD8 / #383 — the first `effect.*` id: a method whose PROVEN effect labels are not
+      # subsumed by the envelope its author declared (`%a{pure}` / `%a{rigor:v1:effect ...}`). Opt-in
+      # twice over — the `effects:` block enables collection, and the envelope is the author's own
+      # directive — so it is never unsolicited.
+      RULE_EFFECT_ENVELOPE_EXCEEDED = "effect.envelope-exceeded"
+      # ADR-103 WD1 / #384 — the paired vocabulary diagnostic. An unknown label degrades the whole tag
+      # to ⊤, which is silent by construction; this is what keeps that fail-open reading honest. It
+      # fires only where label intent is evident (`Effects::LabelIntent`'s four signals), so a project
+      # opening its own vocabulary is never nagged, and it is gated by the same `effects.check` switch
+      # as its sibling: opting into envelope enforcement is exactly what turns on the diagnostic that
+      # says an envelope stopped enforcing.
+      RULE_EFFECT_UNKNOWN_LABEL = "effect.unknown-label"
+      # ADR-103 WD1 / WD14 / #386 — the inherited-bound reading. An override performs, or itself
+      # declares, an effect the envelope written on the method it overrides does not admit. Implementations
+      # may be purer than the bound they inherit, never less pure; both-sides-authored in the ADR-35 sense,
+      # so nothing fires unless someone wrote an envelope on the ancestor.
+      RULE_EFFECT_LISKOV_WIDENED = "effect.liskov-widened"
+      # ADR-103 WD13 commitment 1 / #384 — the residual. A project whose RBS carries `%a{pure}` /
+      # `%a{rigor:v1:effect …}` but no `effects:` block gets ONE `:info` per run saying so. An
+      # annotation must never turn collection on by itself (that would be a project-wide cost cliff
+      # nobody asked for), and it must equally never be silently inert.
+      RULE_EFFECT_ANNOTATIONS_UNCHECKED = "effect.annotations-unchecked"
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
@@ -72,7 +94,11 @@ module Rigor
         RULE_SUPPRESSION_UNKNOWN_RULE,
         RULE_SUPPRESSION_EMPTY,
         RULE_SUPPRESSION_UNKNOWN_MARKER,
-        RULE_VALUE_USE_VOID
+        RULE_VALUE_USE_VOID,
+        RULE_EFFECT_ENVELOPE_EXCEEDED,
+        RULE_EFFECT_LISKOV_WIDENED,
+        RULE_EFFECT_UNKNOWN_LABEL,
+        RULE_EFFECT_ANNOTATIONS_UNCHECKED
       ].freeze
 
       # Backward-compat alias table (ADR-8 § "Backward compatibility"). Existing user code with
@@ -102,7 +128,7 @@ module Rigor
 
       # Family wildcard — a `<family>` token in a suppression comment or `disable:` list disables every rule
       # whose canonical id starts with `<family>.`. Per ADR-8 § "1".
-      RULE_FAMILIES = %w[call flow assert dump def suppression static].freeze
+      RULE_FAMILIES = %w[call flow assert dump def suppression static effect].freeze
 
       # Families of diagnostics the engine emits OUTSIDE the CheckRules catalogue (aggregator-level and
       # reporter-level diagnostics such as `rbs_extended.unsatisfied-conformance`,

data/lib/rigor/analysis/check_rules/rule_walk.rb

@@ -145,6 +145,13 @@ module Rigor
             return unless node.is_a?(Prism::Node)
 
             dispatch(node, hooks, context)
+            # Issue #318 — `defined?`'s operand is never evaluated (the runtime inspects it statically), so
+            # nothing under a `DefinedNode` is reachable, evaluated code. Dispatching the DefinedNode itself
+            # is fine (a collector may care that it exists); descending into `#value` would feed collectors
+            # source that can never execute, e.g. `undefined_method_diagnostic` flagging a call inside
+            # `defined? @x && @x.method_call`.
+            return if node.is_a?(Prism::DefinedNode)
+
             child_context = descend(node, context)
             node.rigor_each_child { |child| walk(child, hooks, child_context) }
           end

data/lib/rigor/analysis/check_rules.rb

@@ -5,11 +5,13 @@ require "prism"
 require_relative "../reflection"
 require_relative "../source/node_walker"
 require_relative "../source/constant_path"
+require_relative "../inference/singleton_object_constant"
 require_relative "../type"
 require_relative "diagnostic"
 require_relative "dependency_recorder"
 require_relative "check_rules/rule_ids"
 require_relative "check_rules/inferred_param_guard"
+require_relative "check_rules/declaration_sourced_guard"
 require_relative "check_rules/rule_walk"
 require_relative "check_rules/always_truthy_condition_collector"
 require_relative "check_rules/unreachable_clause_collector"
@@ -424,6 +426,12 @@ module Rigor
       #   only. `# rigor:disable all` on a line suppresses
       #   every rule on that line.
       #
+      # Both in-source forms are recognised only when the
+      # marker is the FIRST thing in the comment, so a
+      # directive quoted inside ordinary prose — as the bullets
+      # above quote it — is not a directive. See the pattern
+      # constants below.
+      #
       # Diagnostics with `rule == nil` (parse errors, path
       # errors, internal analyzer errors) are NEVER
       # suppressed — they represent failures the user cannot
@@ -443,17 +451,26 @@ module Rigor
         end
       end
 
-      LINE_SUPPRESSION_PATTERN = /#\s*rigor:disable(?!-file)\s+(?<rules>[\w.,\s-]+)/
+      # Every suppression-recognition pattern below is anchored with `\A` against the COMMENT SLICE —
+      # Prism hands us a slice that starts at the `#`, so `\A#` means "the marker is the first thing in
+      # the comment". A real directive always has that shape, in both the whole-line form and the
+      # trailing `code # rigor:disable <rule>` form; prose that merely quotes a directive
+      # (`... like `# rigor:disable-file all` ...`) has text before the inner `#` and no longer
+      # activates anything. Two consequences worth naming: a doc-tool `##` comment never activates (the
+      # second `#` is neither whitespace nor the marker word), and an `=begin`/`=end` block comment
+      # never activates either (its slice starts at `=begin`). Unanchored, these patterns silently
+      # file-suppressed this very file — see issue #306.
+      LINE_SUPPRESSION_PATTERN = /\A#\s*rigor:disable(?!-file)\s+(?<rules>[\w.,\s-]+)/
       private_constant :LINE_SUPPRESSION_PATTERN
 
-      FILE_SUPPRESSION_PATTERN = /#\s*rigor:disable-file\s+(?<rules>[\w.,\s-]+)/
+      FILE_SUPPRESSION_PATTERN = /\A#\s*rigor:disable-file\s+(?<rules>[\w.,\s-]+)/
       private_constant :FILE_SUPPRESSION_PATTERN
 
       # A `rigor:disable[-file]` marker word regardless of whether any rule tokens follow. Used only by the
       # `suppression.empty` detection — the two suppression patterns above require at least one token
       # character, so a bare `# rigor:disable` never reaches them. The lookahead keeps
       # `rigor:disable-something-else` from counting as a marker.
-      BARE_SUPPRESSION_MARKER = /#\s*rigor:disable(?<file>-file)?(?![\w-])(?<rest>.*)/
+      BARE_SUPPRESSION_MARKER = /\A#\s*rigor:disable(?<file>-file)?(?![\w-])(?<rest>.*)/
       private_constant :BARE_SUPPRESSION_MARKER
 
       # A `rigor:` marker word that is NOT part of Rigor's suppression grammar but reads like an attempted
@@ -463,7 +480,7 @@ module Rigor
       # surveillance they silently suppress nothing. Matches `disable-<suffix>` for any suffix other than
       # `file`, and `enable` with or without a suffix.
       UNKNOWN_SUPPRESSION_MARKER =
-        /#\s*rigor:(?<marker>disable-(?!file(?![\w-]))[\w-]+|enable(?:-[\w-]+)?)(?![\w-])(?<rest>.*)/
+        /\A#\s*rigor:(?<marker>disable-(?!file(?![\w-]))[\w-]+|enable(?:-[\w-]+)?)(?![\w-])(?<rest>.*)/
       private_constant :UNKNOWN_SUPPRESSION_MARKER
 
       # @return [Array<(Hash{Integer => Set}, Set)>] pair of
@@ -527,9 +544,10 @@ module Rigor
       end
 
       # A comment carrying the marker word but not the token-bearing suppression grammar. A remainder of
-      # nothing but whitespace / commas is a genuinely empty marker (`# rigor:disable`); anything else
-      # (documentation prose like "`# rigor:disable <rule>` comments") is left alone as an ordinary
-      # comment, matching the parse path, which never treats it as a suppression either.
+      # nothing but whitespace / commas is a genuinely empty marker (`# rigor:disable`); anything else is
+      # left alone as an ordinary comment, matching the parse path, which never treats it as a
+      # suppression either. Prose that merely quotes a marker is already excluded a step earlier by the
+      # `\A` anchor, since the quotation is not at the start of the comment.
       def diagnose_bare_suppression_marker(path, comment, source, diagnostics)
         bare = BARE_SUPPRESSION_MARKER.match(source)
         if bare
@@ -545,8 +563,9 @@ module Rigor
 
       # `# rigor:disable-next-line <rule>` / `# rigor:enable <rule>` — a marker word Rigor's grammar does
       # not recognise but that reads as an attempted suppression (the RuboCop reflex). Fires only when the
-      # remainder is empty or looks like a rule list, so prose mentioning the spelling in backticks stays
-      # an ordinary comment — the same escape the empty-marker detection observes.
+      # marker opens the comment and the remainder is empty or looks like a rule list, so prose mentioning
+      # the spelling in backticks stays an ordinary comment — the same escape the empty-marker detection
+      # observes.
       def diagnose_unknown_suppression_marker(path, comment, source, diagnostics)
         unknown = UNKNOWN_SUPPRESSION_MARKER.match(source)
         return if unknown.nil?
@@ -656,6 +675,13 @@ module Rigor
           # non-nil constituent (which, for a cross-file project def, would
           # be a working-code false positive).
           receiver_type = safe_navigation_receiver(call_node, scope)
+
+          # #320 — the private-singleton-object idiom (`class << Merger = Object.new`). The body's methods
+          # are recorded on the constant's own name, but the receiver reads back as `Object`, so the
+          # class-keyed probes below cannot see them. Recover the name from the receiver syntax. Scoped to
+          # the recorded name only: `Merger.nope` still fires.
+          return nil if Inference::SingletonObjectConstant.recorded?(call_node, receiver_type, call_node.name, scope)
+
           class_name = concrete_class_name(receiver_type)
           # A union receiver has no single concrete class. The scalar path
           # below cannot reason about it, but the call is still definitely
@@ -1255,8 +1281,12 @@ module Rigor
           # principle. The nil stays in the displayed type; only its use as
           # diagnostic fuel is withheld. Any flow-live touch (method-local
           # nil write, failed-guard narrowing) drops the mark upstream, so
-          # flow-observed nil keeps firing exactly as before.
-          return nil if scope.declaration_sourced?(:local, call_node.receiver.name)
+          # flow-observed nil keeps firing exactly as before. The receiver
+          # is already narrowed to a local read above, so this asks
+          # {DeclarationSourcedGuard} exactly what it asked before — but it
+          # now asks it through the predicate the argument-type gates share
+          # (issue #324), which is what keeps the two rules from drifting.
+          return nil if DeclarationSourcedGuard.marked?(call_node.receiver, scope)
 
           # ADR-67 WD6b — an inferred-parameter receiver's type (incl. any nil constituent unioned in from a
           # nil call site) is an open-call-site lower bound; a possible-nil firing against it is an FP by
@@ -2383,13 +2413,16 @@ module Rigor
           params.map { |param| param.type.to_s.delete_prefix("::") }.uniq.join(" | ")
         end
 
-        # ADR-58 parity for the nil channel: a declaration-sourced ivar read
-        # that types as nil is the same not-diagnostic-fuel case the union
-        # path gates in {#declaration_sourced_nil_only_mismatch?}; suppress it
-        # here too so a ctor-seeded `@x = nil` read passed as an argument does
-        # not fire on a working program's cross-method invariant.
+        # ADR-58 parity for the nil channel: a declaration-sourced read that
+        # types as nil is the same not-diagnostic-fuel case the union path
+        # gates in {#declaration_sourced_nil_only_mismatch?}; suppress it here
+        # too so a ctor-seeded `@x = nil` read passed as an argument does not
+        # fire on a working program's cross-method invariant. Issue #324 —
+        # delegates to {DeclarationSourcedGuard}, so a local copy of the ivar
+        # (`c = @count`) is excused on the same terms `possible-nil-receiver`
+        # already excused it.
         def declaration_sourced_nil_argument?(arg, scope)
-          arg.is_a?(Prism::InstanceVariableReadNode) && scope.declaration_sourced?(:ivar, arg.name)
+          DeclarationSourcedGuard.marked?(arg, scope)
         end
 
         def first_argument_mismatch(method_type, call_node, scope, param_overrides)
@@ -2452,14 +2485,15 @@ module Rigor
           !declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
         end
 
-        # True when `arg` is a declaration-sourced ivar read whose rejection is
+        # True when `arg` is a declaration-sourced read whose rejection is
         # caused solely by its nil constituent: stripping nil from the argument
         # type yields a type the parameter accepts (gradual mode). Mirrors the
-        # `possible-nil-receiver` WD1 gate, keyed on the ivar provenance mark
-        # rather than a local copy.
+        # `possible-nil-receiver` WD1 gate — since issue #324 through the very
+        # same {DeclarationSourcedGuard} predicate, so the ivar read and its
+        # local copy (`c = @count`) are one case rather than two spellings that
+        # can drift apart again.
         def declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
-          return false unless arg.is_a?(Prism::InstanceVariableReadNode)
-          return false unless scope.declaration_sourced?(:ivar, arg.name)
+          return false unless DeclarationSourcedGuard.marked?(arg, scope)
           return false unless arg_type.is_a?(Type::Union)
           return false unless union_contains_nil?(arg_type)
 
@@ -2720,6 +2754,12 @@ module Rigor
 
         # Returns true when `override_visibility` is strictly more restrictive than `parent_visibility`
         # under the public > protected > private ordering.
+        #
+        # The nil guard below is defence, not dead code. `VISIBILITY_RANK` is a closed literal hash read
+        # with a dynamic key, so a symbol outside the table reads as nil at runtime. The engine folds that
+        # read to the nil-free value union `0 | 1 | 2`, which `internal-spec/inference-engine.md` declares
+        # OPTIMISTIC rather than proof — and since issue #313 that mark survives the `.nil?` fold and the
+        # `||` composition, so no suppression directive is needed here.
         def visibility_reduced?(parent_visibility, override_visibility)
           parent_rank = VISIBILITY_RANK[parent_visibility]
           override_rank = VISIBILITY_RANK[override_visibility]

data/lib/rigor/analysis/incremental_session.rb

@@ -5,6 +5,9 @@ require_relative "incremental"
 require_relative "plugin_fact_fingerprint"
 require_relative "../cache/file_digest"
 require_relative "../cache/incremental_snapshot"
+require_relative "../effects/file_collection"
+require_relative "../effects/identity"
+require_relative "../effects/propagator"
 require_relative "../inference/scope_indexer"
 
 module Rigor
@@ -105,6 +108,7 @@ module Rigor
         # and a missing invalidation edge is impossible by construction — the reason this is a table diff
         # and not the caller→callee edge recording #204 first sketched.
         @param_table = {}
+        reset_effect_state
         # ADR-88 WD1 — the plugin fact-surface digest computed for THIS invocation (nil until a
         # `#run_incremental` pass runs / a plugin-free project) and the reporting flags a caller (the CLI
         # banner + `--cache-stats`) reads after `#run_incremental`. `@last_runner` is the analysis runner the
@@ -122,6 +126,32 @@ module Rigor
         @analyzed
       end
 
+      # ADR-103 WD12 / issue #382 — the session's effect graph: the fixpoint over the merged whole,
+      # recomputed on every ask. This is the invariant that makes per-file collection reuse sound — the
+      # closure is never partially reused, only its per-file *inputs* are, so a leaf edit whose new label
+      # reaches a caller in an unchanged file still shows up in that caller's `reach`.
+      def effect_table
+        Effects::Propagator.propagate(
+          effect_collection, discharge: Effects::Discharge.new(@configuration.effects_tolerated)
+        )
+      end
+
+      # The merged direct summaries the table above closes over.
+      def effect_collection
+        Effects::FileCollection.merge_all(sorted_effect_collections)
+      end
+
+      # Where each unit was defined — the same shape (and the same purpose: the snapshot's `reach:` globs)
+      # as `Runner#effect_sources`, answered from the session's own per-file collections.
+      def effect_sources
+        sorted_effect_collections.each_with_object({}) do |collection, out|
+          path = collection.path
+          next if path.nil?
+
+          collection.summaries.each_key { |key| (out[key] ||= []) << path }
+        end
+      end
+
       # Full baseline analysis with recording. Returns the run's diagnostics; populates the in-process cache
       # + dependency state.
       def baseline
@@ -135,6 +165,9 @@ module Rigor
         # ADR-67 WD6c lift — the seed table the runner's own pre-pass computed ({} when the gate is off).
         # Reading it back, rather than computing it here, keeps the baseline single-collect.
         @param_table = runner.param_inferred_types
+        # ADR-103 WD13 / #382 — a baseline collects every file, so its collections are the whole world.
+        @effect_collections = runner.effect_collections_by_path
+        @effects_identity = current_effects_identity
         @cache = per_file(diagnostics)
         @digests = @analyzed.to_h { |path| [path, pack_digest(path)] }
         diagnostics
@@ -417,10 +450,18 @@ module Rigor
           # (types with no fingerprint surface) make the snapshot un-reusable.
           if restored
             restore(restored)
+            # ADR-103 WD13 / #382 — the effects sidecar joins the same reuse decision, for a structurally
+            # identical reason: a snapshot whose summaries were collected under a different vocabulary /
+            # catalogue / `effects:` block restores as empty, and a recheck only re-collects the changed
+            # closure, so the merged table would be missing every unchanged file. A full baseline is the
+            # honest answer — it is what "recompute effects" means when collecting requires analysing, and
+            # it is paid on the first collecting run and on an identity change, never with collection off.
+            # Asked BEFORE the recheck, which re-stamps the session with the current identity.
+            effects_reusable = effects_reuse_permitted?(restored)
             result = recheck
             adopt_plugin_fact_fingerprint
-            reuse = @plugin_fact_reusable.reusable_against?(restored.plugin_fact_digest)
-            if reuse
+            fact_reusable = @plugin_fact_reusable.reusable_against?(restored.plugin_fact_digest)
+            if fact_reusable && effects_reusable
               diagnostics = result.diagnostics
               warm = true
               # ADR-87 WD3 — a warm recheck that changed nothing leaves the session state byte-equivalent to the
@@ -428,10 +469,12 @@ module Rigor
               # A cold baseline always persists — there was no valid snapshot to reuse.
               skip_save = result.no_change?
             else
-              # The fact surface moved (a plugin sig/catalog edit) or a plugin is opaque: the cached-served
-              # files the recheck merged may be stale, so re-analyze the whole tree. The current fact-surface
+              # The fact surface moved (a plugin sig/catalog edit), a plugin is opaque, or the effects
+              # identity moved: the cached-served files the recheck merged may be stale (or, for effects, a
+              # partial collection cannot be closed), so re-analyze the whole tree. The current fact-surface
               # digest (from the recheck runner) is unchanged by the re-analysis, so it is kept for the save.
-              @fact_surface_invalidated = true
+              # Only a genuine fact-surface reason sets the reporting flag the CLI banner reads.
+              @fact_surface_invalidated = true unless fact_reusable
               diagnostics = baseline
               warm = false
               skip_save = false
@@ -459,6 +502,12 @@ module Rigor
 
       private
 
+      # Path-sorted, so the fold is reproducible whatever order the files were absorbed in (the same reason
+      # `Runner#effect_collections` sorts).
+      def sorted_effect_collections
+        @effect_collections.sort_by { |path, _| path.to_s }.map(&:last)
+      end
+
       # ADR-88 WD1 — capture this invocation's fact-surface fingerprint (from the last analysis runner) onto the
       # reporting ivars + the `@plugin_fact_reusable` decision object.
       def adopt_plugin_fact_fingerprint
@@ -509,6 +558,12 @@ module Rigor
         @class_decls       = payload.class_decls || {}
         @return_summaries  = payload.return_summaries || {}
         @param_table       = payload.param_table || {} # ADR-67 WD6c lift — the seeds the cache was built under.
+        # ADR-103 WD13 / #382 — the effects sidecar rides its own identity, so a snapshot whose summaries
+        # were collected under a different vocabulary / catalogue / `effects:` block restores as EMPTY
+        # rather than as stale rows. {#run_incremental} turns that emptiness into a full baseline, because
+        # a partial re-collection cannot be closed into a whole-project fixpoint.
+        @effects_identity  = payload.effects_identity
+        @effect_collections = effect_collections_reusable?(payload) ? payload.effect_collections.dup : {}
         @symbol_dependents = Incremental.invert_symbols(@symbol_sources)
         @ancestry_dependents = Incremental.invert(@ancestry_sources)
         @negative_dependents = Incremental.invert(@missing)
@@ -522,10 +577,71 @@ module Rigor
           class_decls: @class_decls, seed_bundles: @seed_bundles,
           plugin_fact_digest: @plugin_fact_digest,
           return_summaries: marshal_safe_return_summaries,
-          param_table: marshal_safe_param_table
+          param_table: marshal_safe_param_table,
+          effect_collections: marshal_safe_effect_collections,
+          effects_identity: @effects_identity
         )
       end
 
+      # ADR-103 WD13 / issue #382 — the per-file effect collections the session serves unchanged files
+      # from, and the effects identity they were collected under. Empty / nil when collection is off, which
+      # is every run that does not carry an `effects:` block. The PROPAGATED table is never kept here:
+      # {#effect_table} re-runs the fixpoint over the merged whole on every ask, because a leaf's summary
+      # reaches every caller and there is no per-file invalidation for a whole-graph closure.
+      def reset_effect_state
+        @effect_collections = {}
+        @effects_identity = nil
+      end
+
+      # Whether the effects half of a restored snapshot permits reuse. Collection off is vacuously true —
+      # the session keeps no collections, writes none, and the pre-#382 reuse decision stands unchanged.
+      def effects_reuse_permitted?(payload)
+        !@configuration.effects_enabled? || effect_collections_reusable?(payload)
+      end
+
+      # ADR-103 WD13 / #382 — whether a restored payload's effect collections may be served this run:
+      # collection is on, and they were collected under the identity this run computes. Collection being
+      # OFF answers false and costs nothing — the session then keeps no collections, writes none, and is
+      # the pre-#382 session in every observable way.
+      def effect_collections_reusable?(payload)
+        return false unless @configuration.effects_enabled?
+        return false if payload.effects_identity.nil? || !payload.effect_collections.is_a?(Hash)
+
+        payload.effects_identity == current_effects_identity
+      end
+
+      # The effects identity for THIS run, memoised: it digests a YAML catalogue and the `effects:` block,
+      # and a recheck asks for it on both the restore and the absorb side. nil when collection is off, so a
+      # non-collecting run never loads the catalogue at all.
+      #
+      # **Deliberately plugin-blind**, unlike the ADR-45 whole-run effects slot, whose descriptor carries
+      # {Effects::PluginFacts#digest} (#387). The two sides of this comparison sit on opposite sides of the
+      # run: the restore asks before any plugin is loaded and the save asks after, so folding the plugin
+      # facts in here would compare a blind digest against a sighted one and miss every single time. The
+      # bound it leaves — a plugin upgrade that moves a row does not invalidate an `--incremental`
+      # snapshot's effect collections — is recorded in `docs/internal-spec/effect-summaries.md`; the
+      # primary (whole-run) path has no such hole, and `--incremental` is opt-in.
+      def current_effects_identity
+        return nil unless @configuration.effects_enabled?
+
+        @current_effects_identity ||= Effects::Identity.digest(configuration: @configuration)
+      end
+
+      # The same Marshal-clean guard {#marshal_safe_return_summaries} applies, for the same reason: a
+      # snapshot save must never raise. A dropped collection makes that file's summaries absent from the
+      # next run's merged table, which understates its effects — so it is dropped only when it genuinely
+      # will not serialise, and {FileCollection} is built to (the fork pool marshals one per file already).
+      def marshal_safe_effect_collections
+        return {} unless @configuration.effects_enabled?
+
+        @effect_collections.each_with_object({}) do |(path, collection), safe|
+          Marshal.dump(collection)
+          safe[path] = collection
+        rescue StandardError
+          next
+        end
+      end
+
       # ADR-89 WD2 — the return summaries filtered to Marshal-clean entries. A summary's `keys` hold live
       # `Type` objects; the common carriers (Nominal, Constant, Union, shapes, Dynamic) Marshal, but a type
       # holding a live AST node would raise and abort the WHOLE snapshot save (a cache must never break a
@@ -568,6 +684,21 @@ module Rigor
         end
         absorb_dependency_graph(runner)
         refresh_return_summaries(runner, analyze_set)
+        refresh_effect_collections(runner, analyze_set)
+      end
+
+      # ADR-103 WD13 / #382 — the effects analogue of {#refresh_return_summaries}, and the same soundness
+      # order: drop every re-analyzed file's collection first, then fold this run's harvest in. A file the
+      # recheck did NOT analyze keeps the collection the snapshot carried, which is exactly the reuse the
+      # slot exists for; a re-analyzed file that produced nothing (a parse failure, a file of constants)
+      # correctly ends up with nothing rather than with its pre-edit summaries.
+      def refresh_effect_collections(runner, analyze_set)
+        return unless @configuration.effects_enabled?
+
+        analyzed = analyze_set.to_set
+        @effect_collections.reject! { |path, _| analyzed.include?(path) }
+        @effect_collections.merge!(runner.effect_collections_by_path)
+        @effects_identity = current_effects_identity
       end
 
       # ADR-89 WD2 — replace the behavioural summaries of every re-analyzed file with THIS run's harvest: drop
@@ -599,6 +730,9 @@ module Rigor
         @symbol_fingerprints.delete(path)
         # ADR-89 WD2 — drop every behavioural summary a removed file provided (keys are `[path, symbol]`).
         @return_summaries.reject! { |(summary_path, _symbol), _| summary_path == path }
+        # ADR-103 WD13 / #382 — and its effect collection, so a deleted file stops contributing summaries
+        # and edges to the merged table the fixpoint closes.
+        @effect_collections.delete(path)
         # @class_decls is wholesale-replaced from the (removed-excluding)
         # pre-pass in absorb_dependency_graph, and is frozen, so no delete.
       end