rigortype 0.3.3 → 0.3.5

data/docs/manual/ci-templates/README.md

@@ -26,6 +26,15 @@ comments (it works the same way against GitLab, Gerrit, Bitbucket, and Gitea
 — see the [`rigor-ci-setup`](../../../skills/rigor-ci-setup/SKILL.md) skill).
 All run Rigor the same way — only the output format and publish step differ.
 
+Every template ends with a **commented-out `rigor effects check` step**.
+Uncomment it once the project has an `effects:` block and a committed
+`.rigor-effects.yml`, and CI will fail when a branch changes what the code
+*does* — a job that starts talking to the network, a presenter that starts
+querying. It ships commented because `effects check` exits `1` when the
+snapshot file is absent, which is exactly what you want on a project that
+has one and pure noise on a project that does not. The workflow around it
+is [chapter 19, "Effect labels"](../19-effect-labels.md).
+
 ## Other runners (generic recipe)
 
 On any CI system, the four steps are: provision Ruby 4.0, install

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

@@ -64,6 +64,11 @@ plugins:
 - A brand-new view file does not invalidate the cached index until
   something the mailer file touches changes (the read-tracking
   trade-off).
+- **No roots for [`rigor unused`](../02-cli-reference.md#rigor-unused).**
+  `MyMailer.welcome(...)` names the mailer as an ordinary constant,
+  which the report already records. Rooting every class under
+  `app/mailers` instead would mark a mailer nothing sends reachable
+  forever on no evidence.
 
 ## Plugin internals
 

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

@@ -36,8 +36,47 @@ plugins:
     config:
       job_search_paths: ["app/jobs"]                            # default
       job_base_classes: ["ApplicationJob", "ActiveJob::Base"]   # default
+      recurring_paths: ["config/recurring.yml"]                 # default
 ```
 
+`recurring_paths` are the schedule *files* — not directories —
+behind the reachability roots below. The default is where Solid
+Queue's recurring schedule conventionally lives; list your own path
+if you keep it elsewhere.
+
+## Job roots for `rigor unused`
+
+Solid Queue is the Active Job backend Rails ships by default from
+8.0, and a **recurring task names its job by string**:
+
+```yaml
+# config/recurring.yml
+production:
+  send_reminder:
+    class: "SendReminderJob"
+    schedule: "*/3 * * * *"
+```
+
+That job runs every three minutes and there is no `perform_later`
+for it anywhere, so the constant scan sees nothing and
+[`rigor unused`](../02-cli-reference.md#rigor-unused) reports live
+production code as possibly dead. This plugin supplies the jobs your
+recurring schedule names, so they drop out of the candidate list.
+
+**Every environment block is read**, not just `production:` — a job
+scheduled in `staging:` is still live code. A flat, environment-less
+document works too.
+
+Only `class:` is read. A `command:` entry is inline Ruby
+(`command: "SomeModel.cleanup"`), and parsing a constant out of an
+arbitrary snippet would root a class on a guess, so it supplies
+nothing. A `class:` naming a job the plugin never discovered is
+dropped rather than published: a typo costs you a root instead of
+quietly hiding a dead job.
+
+The schedule is read with `YAML.safe_load`. Nothing boots Rails and
+nothing loads Solid Queue.
+
 ## Limitations
 
 - **Direct-superclass match only.** `class WelcomeJob < BaseJob`
@@ -48,6 +87,14 @@ plugins:
 - **Positional arity only.** Required keyword arguments are
   recorded by the discoverer but not yet validated at the call
   site.
+- **Roots only from a recurring schedule.** A job is rooted for
+  `rigor unused` when `config/recurring.yml` names it, and never for
+  existing under `app/jobs`: `MyJob.perform_later` names the job as
+  an ordinary constant the report already records, and rooting every
+  discovered job would mark an orphaned one reachable forever on no
+  evidence. A schedule loaded from Ruby rather than from a file under
+  `recurring_paths` supplies nothing, by the same "read only what is
+  written" rule.
 
 ## Plugin internals
 

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

@@ -54,6 +54,22 @@ plugins:
       # Minitest projects: ["test/factories"]
 ```
 
+## Factory references for `rigor unused`
+
+`factory :user, class: "Admin::User"` names a class as a string, and
+a bare `factory :user` relies on FactoryBot constantizing the factory
+name. Neither is a constant reference, so
+[`rigor unused`](../02-cli-reference.md#rigor-unused) cannot see them
+and would report a factoried model as dead.
+
+This plugin supplies those model classes — as **test-role
+references**, not as roots. A class reached only through a factory
+therefore leaves the candidate list and appears under **Reachable
+only from test code** instead. That is deliberate: a model kept alive
+by its factory and its spec and nothing else is dead production code
+with a live test, and rooting factories would have hidden exactly
+that finding.
+
 ## Limitations
 
 - **Literal arguments only** — `FactoryBot.create(name)` with a

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

@@ -48,8 +48,34 @@ plugins:
     config:
       policy_search_paths: ["app/policies"]    # default
       policy_base_classes: ["ApplicationPolicy"]  # default
+      authorization_call_paths: ["app/controllers"]  # default
 ```
 
+`authorization_call_paths` is where the plugin looks for the
+`authorize` / `policy` / `policy_scope` calls behind the reachability
+roots below. Widen it if you also authorize from `app/graphql` or
+`app/services`; it defaults narrow because the walk is a parse per
+file on every run.
+
+## Policy roots for `rigor unused`
+
+`authorize @post` runs `PostPolicy#update?`, and the name
+`PostPolicy` is never written down. So without help,
+[`rigor unused`](../02-cli-reference.md#rigor-unused) reports every
+policy in your app as possibly dead. This plugin supplies the
+policies your code actually authorizes against, so they drop out of
+the candidate list.
+
+It publishes the policies **an authorization call names**, not every
+class under `policy_search_paths`. A policy nothing authorizes
+against stays in the report, which is the answer you wanted to see:
+a root source that claims more than it can show hides real dead code
+without telling you.
+
+A policy the plugin cannot attribute to a call — a namespaced
+`Admin::PostPolicy`, a record argument it cannot read — stays a
+candidate rather than being guessed at.
+
 ## Limitations
 
 - **Direct-superclass match only.** `class AdminPostPolicy <

data/docs/manual/plugins/rigor-rails-routes.md

@@ -83,6 +83,44 @@ The parsed helper table is published as the `:helper_table`
 cross-plugin fact (ADR-9), which `rigor-actionpack` consumes to
 validate helper calls inside controllers.
 
+### Controller roots for `rigor unused`
+
+The same parse also yields the **controller classes** your routes
+dispatch to, published as the `:reachability_roots` fact that
+[`rigor unused`](../02-cli-reference.md#rigor-unused) seeds its
+reachability report with.
+
+This matters because Rails reaches a controller by *name* at request
+time. Nothing in your code references `Admin::UsersController`, so
+without route knowledge every controller in the app reads as
+unreferenced — on Mastodon that was 233 spurious candidates.
+
+Controller names are composed the way Rails composes them:
+`resources :users` inside `namespace :admin` is
+`Admin::UsersController`; a singular `resource :profile` is served by
+the plural `ProfilesController`; `scope module:` and a `module:`
+option on a resource extend the namespace; `to: "posts#index"`,
+`controller:`, and the hashrocket `get "help" => "help#show"` form
+are all read. Acronyms declared in
+`config/initializers/inflections.rb` are applied, so
+`scope module: :activitypub` resolves to `ActivityPub::…`.
+
+Two properties follow from parsing rather than booting, and are the
+reason to prefer this over reading a running app's route table:
+
+- **No Rails runtime is loaded.**
+- **A route under a conditional is still a root.**
+  `get "/beta", to: "beta#index" if ENV["ENABLE_BETA"]` does not
+  appear in a booted app's route table unless the condition happened
+  to hold; both branches are visible to a static read.
+
+**Not covered as roots** (deliberately, rather than half-covered):
+controllers remapped by `devise_for … controllers:`, by
+`use_doorkeeper … controllers:`, or served through a mounted Grape
+API. Those mappings name controllers the plugin does not resolve, so
+they may appear as `rigor unused` candidates even though they are
+routed. Helper-name recognition for all three is unaffected.
+
 ## Limitations
 
 - **Statically unfoldable route definitions.** Helpers produced by
@@ -92,9 +130,10 @@ validate helper calls inside controllers.
   `unknown-helper`. Record those in a baseline, or
   `# rigor:disable` the line.
 - **Project-custom inflections** declared in
-  `config/initializers/inflections.rb` are not yet ingested
+  `config/initializers/inflections.rb` are not yet fully ingested
   (ADR-39 slice 3); the standard ActiveSupport inflections are
-  covered.
+  covered, and `inflect.acronym` declarations are read for
+  controller-class composition only.
 
 ## Plugin internals
 

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

@@ -62,6 +62,11 @@ The plugin has no configuration knobs.
   / `have_received` (overlap engine constant / undefined-method rules).
 - **Literal arguments only** — a status passed via a variable or method
   call is not statically checkable, so it's accepted silently.
+- **No roots for [`rigor unused`](../02-cli-reference.md#rigor-unused)**,
+  for the reason [`rigor-rspec`](rigor-rspec.md#limitations) gives: a
+  spec's constant reference is already recorded with the `test` role,
+  and rooting it would delete the report's "reachable only from tests"
+  answer.
 
 ## Plugin internals
 

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/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/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