rigortype 0.3.4 → 0.3.6

data/docs/manual/README.md

@@ -65,6 +65,11 @@ flag, key, or command that *acts* on it.
     `rigor unused` as a campaign on an old codebase: why the list
     starts long, which lever actually shortens it, what to confirm
     before deleting, and how to make the case to a reviewer.
+19. [Effect labels](19-effect-labels.md) — what your code *does*
+    beside what it returns: the label vocabulary, the `rigor
+    effects` report, the committed `.rigor-effects.yml` snapshot
+    and its review loop, the CI gate, and the envelopes and
+    `%a{pure}` annotations that bound a layer.
 
 ### Integration and operations
 
@@ -75,7 +80,7 @@ flag, key, or command that *acts* on it.
     Cline, …) via `rigor mcp`.
 11. [Running Rigor in CI](11-ci.md) — a clean CI job, inline
     PR/MR diagnostics (SARIF / GitHub Actions / GitLab Code
-    Quality), copy-paste [templates](ci-templates/), and
+    Quality), copy-paste [templates](ci-templates), and
     version pinning.
 12. [Caching](12-caching.md) — where the cache lives, what
     invalidates it, and how to clear it.
@@ -89,4 +94,4 @@ flag, key, or command that *acts* on it.
 - [`docs/types.md`](../types.md) — one-page type-system guide.
 - [`docs/type-specification/`](../type-specification/README.md)
   — the normative spec corpus.
-- [`docs/adr/`](../adr/) — architecture decision records.
+- [`docs/adr/`](../adr) — architecture decision records.

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

@@ -17,10 +17,10 @@ plugins:
 ## What it checks
 
 ```text
-demo.rb:7:1:  info:  `UserMailer.welcome` matches mailer action (arity 1..2)
-errors_demo.rb:7:1:  error: `UserMailer.welcome` expects 1..2 argument(s), got 0
-errors_demo.rb:15:1: error: `UserMailer.does_not_exist` is not a defined mailer action (known actions: digest, reset_password, welcome)
-app/mailers/user_mailer.rb:14:7: warning: `UserMailer#digest` has no view template under `app/views/user_mailer/`
+demo.rb:7:1: info: `UserMailer.welcome` matches mailer action (arity 1..2) [plugin.actionmailer.mailer-call]
+errors_demo.rb:10:1: error: `UserMailer.welcome` expects 1..2 argument(s), got 0 [plugin.actionmailer.wrong-arity]
+errors_demo.rb:18:1: error: `UserMailer.does_not_exist` is not a defined mailer action (known actions: digest, reset_password, welcome) [plugin.actionmailer.unknown-action]
+app/mailers/user_mailer.rb:26:7: warning: `UserMailer#digest` has no view template under `app/views/user_mailer/` [plugin.actionmailer.missing-view]
 ```
 
 1. **Action existence** — `Mailer.unknown_action(...)` →

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

@@ -18,9 +18,9 @@ Given a job whose `#perform` takes one required and one optional
 argument (arity `1..2`):
 
 ```text
-demo.rb:6:1:  info:  `WelcomeEmailJob.perform_later` matches `#perform` (arity 1..2)
-demo.rb:9:1:  error: `WelcomeEmailJob.perform_later` expects 1..2 argument(s), got 0
-demo.rb:12:1: error: `WelcomeEmailJob.perform_later` expects 1..2 argument(s), got 3
+demo.rb:8:1: info: `WelcomeEmailJob.perform_later` matches `#perform` (arity 1..2) [plugin.activejob.job-call]
+errors_demo.rb:10:1: error: `WelcomeEmailJob.perform_later` expects 1..2 argument(s), got 0 [plugin.activejob.wrong-arity]
+errors_demo.rb:14:1: error: `WelcomeEmailJob.perform_later` expects 1..2 argument(s), got 3 [plugin.activejob.wrong-arity]
 ```
 
 A `*rest` parameter yields an unbounded upper bound (`arity 0+`).

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

@@ -18,11 +18,11 @@ plugins:
 ## What it checks
 
 ```text
-demo.rb:20:1: info: `User.find` returns User (table: `users`) [plugin.activerecord.model-call]
-demo.rb:23:1: info: `User.where` (:admin) on table `users` [plugin.activerecord.model-call]
+demo.rb:18:1: info: `User.find` returns User (table: `users`) [plugin.activerecord.model-call]
+demo.rb:21:1: info: `User.where` (:admin) on table `users` [plugin.activerecord.model-call]
 
-errors_demo.rb:13:1: error: `User.where(emial: ...)` references unknown column `emial` on table `users` (did you mean `:email`?) [plugin.activerecord.unknown-column]
-errors_demo.rb:25:1: error: `User.find` expects at least 1 argument, got 0 [plugin.activerecord.wrong-arity]
+errors_demo.rb:12:1: error: `User.where(emial: ...)` references unknown column `emial` on table `users` (did you mean `:email`?) [plugin.activerecord.unknown-column]
+errors_demo.rb:24:1: error: `User.find` expects at least 1 argument, got 0 [plugin.activerecord.wrong-arity]
 ```
 
 | Diagnostic | Severity | Rule |

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

@@ -19,11 +19,11 @@ Against a locale catalogue, every statically-resolvable call site
 is validated:
 
 ```text
-demo.rb:14:1: info:    `t('users.welcome')` resolves in en, ja
-errors_demo.rb:12:1: error:   missing translation key `users.welcom` in any locale (did you mean `users.welcome`?)
-errors_demo.rb:16:1: error:   `t('users.welcome')` expects interpolation `name`, got (none)
-errors_demo.rb:20:1: warning: `t('users.welcome')` does not use interpolation `extra` (known placeholders: `name`)
-errors_demo.rb:25:1: warning: `t('errors.messages.blank')` is missing from locale(s) ja
+demo.rb:12:1: info: `t('users.welcome')` resolves in en, ja [plugin.rails-i18n.translation-call]
+errors_demo.rb:10:1: error: missing translation key `users.welcom` in any locale (did you mean `users.welcome`?) [plugin.rails-i18n.unknown-key]
+errors_demo.rb:14:1: error: `t('users.welcome')` expects interpolation `name`, got (none) [plugin.rails-i18n.wrong-interpolation]
+errors_demo.rb:18:1: warning: `t('users.welcome')` does not use interpolation `extra` (known placeholders: `name`) [plugin.rails-i18n.extra-interpolation]
+errors_demo.rb:23:1: warning: `t('errors.messages.blank')` is missing from locale(s) ja [plugin.rails-i18n.missing-locale]
 ```
 
 1. **Key existence** — a key absent from every locale is flagged,

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

@@ -29,9 +29,13 @@ RSpec.describe "User" do
 end
 ```
 
+The snippet above is condensed for reading; the output below is what
+Rigor actually prints for the plugin's own demo
+(`plugins/rigor-rspec/demo/`), so the line numbers are that file's:
+
 ```text
-spec/user_spec.rb:5:3: warning: duplicate `let(:user)` in this scope (first declared at line 4); the last declaration wins at runtime
-spec/user_spec.rb:7:3: error:   `let(:tags)` references its own name `tags` — this will infinite-loop at runtime
+spec/errors_spec.rb:23:3: warning: duplicate `let(:user)` in this scope (first declared at line 22); the last declaration wins at runtime [plugin.rspec.duplicate-let]
+spec/errors_spec.rb:27:3: error: `let(:tags)` references its own name `tags` — this will infinite-loop at runtime [plugin.rspec.self-reference]
 ```
 
 1. **Duplicate `let` / `subject` declarations** within the same

data/lib/rigor/analysis/diagnostic.rb

@@ -134,14 +134,25 @@ module Rigor
       end
 
       # Text rendering for `rigor check`. The qualified rule identifier (per ADR-2 § "Plugin Diagnostic
-      # Provenance" — `plugin.<id>.<rule>`, `rbs_extended.<rule>`, `generated.<provider>.<rule>`) is appended
-      # in brackets whenever the diagnostic carries a non-default `source_family`, so plugin / RBS::Extended
-      # / generated provenance is visible in the standard text output without changing the layout for
-      # built-in rules. Slice 5 (v0.1.0) wires this surface.
+      # Provenance" — `call.undefined-method`, `plugin.<id>.<rule>`, `rbs_extended.<rule>`,
+      # `generated.<provider>.<rule>`) is appended in brackets.
+      #
+      # Slice 5 (v0.1.0) introduced the bracket for non-builtin families only, "without changing the layout
+      # for built-in rules" — a layout-conservatism call made when provenance was the point, not a judgment
+      # that the identifier is noise. The consequence outlived the reason (#431): the exception covers the
+      # rules `docs/manual/04-diagnostics.md` tells the reader to suppress with `# rigor:disable <id>` and
+      # to key `severity_profile:` on, so the default output was the one place the identifier could not be
+      # read. A run could not be grepped for a rule either — the effect-system walkthrough grepped
+      # `effect\.` over a whole Redmine run, got nothing, and concluded the feature was broken.
+      #
+      # The cost is bounded and was measured before the change: on Redmine every diagnostic carries an
+      # identifier, only 13 distinct ones appear across the project, and the suffix adds 14 characters to a
+      # 165-character median line.
+      #
+      # `rule` is nil for diagnostics no rule produced — parse errors, path errors, internal analyzer
+      # errors — and those stay unsuffixed, because there is nothing to suppress or configure.
       def to_s
         base = "#{path}:#{line}:#{column}: #{severity}: #{message}"
-        return base if source_family == DEFAULT_SOURCE_FAMILY
-
         qualified = qualified_rule
         return base if qualified.nil?
 

data/lib/rigor/analysis/effects_cache_probe.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "path_expansion"
+require_relative "run_cache_key"
+require_relative "../cache/store"
+require_relative "../cache/file_digest"
+require_relative "../effects/identity"
+require_relative "../effects/plugin_facts"
+require_relative "../effects/registry"
+require_relative "../plugin"
+require_relative "../plugin/loader"
+require_relative "../plugin/services"
+require_relative "../reflection"
+require_relative "../type/combinator"
+
+module Rigor
+  module Analysis
+    # ADR-104 — the boot-slimming probe for the effects surfaces, the shape ADR-87 WD4's
+    # {RunCacheProbe} gave `rigor check`.
+    #
+    # A warm `rigor effects` had almost no work left after #475 and #482 and still cost 2–2.5× a warm
+    # `rigor check`, because it loaded the inference engine to compute two cache keys and adopt two
+    # cached values. This serves the report from the #482 summary entry — the propagated table and the
+    # unit sources — loading configuration, the cache, the plugin loader and the `effects/*` value
+    # layer, and never `rigor/inference`.
+    #
+    # ## What makes an engine-free key possible
+    #
+    # The effects identity ({Effects::Identity.descriptor}) is the run's diagnostics key descriptor plus
+    # the vocabulary version, the catalogue identity, the `effects:` digest and {Effects::PluginFacts}'
+    # own digest. The first is what {RunCacheProbe} already computes without a loader; the rest are pure
+    # functions of shipped data, configuration, and the plugins' class-level declarations — a plugin's
+    # contributions are fixed by `init`, which the loader runs, so `#prepare` (the expensive half) is
+    # not needed. `PluginFacts#digest` is computed before the project's superclass table is even
+    # assigned to it, so the discovery tables a probe cannot build do not participate.
+    #
+    # ## Why a decline is always safe
+    #
+    # Every reason to decline — a key this path cannot reproduce, a miss, a stale dependency — ends in
+    # the caller running the full `Analysis::Runner`, which answers exactly as it does today. The one
+    # reproducibility gap is deliberate and inherited: a project whose plugins synthesise virtual RBS
+    # gets a key without the `rbs.virtual_rbs` slot the runner writes, so it misses here rather than
+    # matching something it should not.
+    #
+    # The rule the surfaces are held to (ADR-104's criterion): a probe may serve a surface only when
+    # every answer that surface can give is reproducible from stored values and declarations alone.
+    # `rigor effects` and the snapshot verbs qualify because their output is a pure function of the
+    # table, the sources, the configuration and the vocabulary — the envelope diagnostics the full path
+    # also computes are discarded by every one of them.
+    class EffectsCacheProbe
+      # What a served run hands back: the two cached tables, plus the vocabulary the caller would
+      # otherwise rebuild (the probe loaded the plugins to key the entry, so it already knows it).
+      Served = Data.define(:table, :sources, :registry, :plugin_facts)
+
+      # @param configuration [Rigor::Configuration] with effects already enabled by the caller.
+      # @param cache_root [String, nil]
+      def initialize(configuration:, cache_root:)
+        @configuration = configuration
+        @cache_root = cache_root
+      end
+
+      # @param paths [Array<String>] the analysed set — `configuration.paths` unioned with any path
+      #   arguments, exactly what {CLI::EffectsCommand#analyze} hands the runner, because the analysed
+      #   set is part of the diagnostics key.
+      # @return [Served, nil] nil to decline, on any failure whatsoever.
+      def serve(paths)
+        return nil if @cache_root.nil? || !@configuration.effects_check?
+
+        descriptor = effects_descriptor(paths)
+        return nil if descriptor.nil?
+
+        summary = validated_summary(descriptor)
+        return nil if summary.nil?
+
+        table, sources, = summary
+        Served.new(table: table, sources: sources, registry: registry, plugin_facts: plugin_facts)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def effects_descriptor(paths)
+        files = PathExpansion.ruby_files(paths, @configuration.exclude_patterns)
+        base = RunCacheKey.descriptor(
+          configuration: @configuration, files: files, explain: false,
+          rbs_config_entries: RunCacheKey.libraries_config_entries(@configuration)
+        )
+        return nil if base.nil?
+
+        Effects::Identity.descriptor(base: base, configuration: @configuration, registry: registry,
+                                     plugin_facts: plugin_facts)
+      end
+
+      # The same shape guard the runner's own read half applies, for the same reason: a miss, a stale
+      # dependency, a corrupt entry and a value of the wrong shape all mean "run it properly".
+      def validated_summary(descriptor)
+        store = Cache::Store.new(root: @cache_root, max_bytes: @configuration.cache_max_bytes)
+        cached = Cache::FileDigest.with_run(strict: @configuration.cache_validation_strict?) do
+          store.peek_validated(
+            producer_id: RunCacheKey::RUN_EFFECTS_TABLE_PRODUCER_ID, key_descriptor: descriptor
+          )
+        end
+        return nil unless cached.is_a?(Array) && cached.length == 3
+        return nil unless cached[0].is_a?(Effects::EffectTable) && cached[1].is_a?(Hash)
+
+        cached
+      end
+
+      # Loaded once, and shared by the key and the answer. `#prepare` is deliberately not run: a
+      # plugin's effect contributions are fixed by `init`, and `#prepare` is the half that parses
+      # routes and walks worker trees — the cost this probe exists to skip.
+      def plugin_facts
+        return @plugin_facts if defined?(@plugin_facts)
+
+        @plugin_facts = Effects::PluginFacts.build(plugin_registry)
+      end
+
+      def plugin_registry
+        services = Plugin::Services.new(reflection: Reflection, type: Type::Combinator,
+                                        configuration: @configuration, cache_store: nil)
+        Plugin::Loader.load(configuration: @configuration, services: services)
+      rescue StandardError, ScriptError
+        nil
+      end
+
+      def registry
+        @registry ||= Effects::Registry.for_configuration(@configuration, plugin_facts: plugin_facts)
+      end
+    end
+  end
+end

data/lib/rigor/analysis/reachability/graph.rb

@@ -54,16 +54,25 @@ module Rigor
           reachable = walk(edges, seeds: production_seeds | test_seeds, roles: %i[production task config test])
           unreached = @owned - reachable
           namespaces = namespace_only(unreached, reachable)
-          undecidable = tainted(unreached - namespaces)
+          # The data-file demotion applies to BOTH buckets it can speak to, which is what the tier
+          # contract says and what the implementation had narrowed (#370). See {#tainted}.
+          test_only = reachable - production
+          undecidable = tainted(unreached - namespaces).merge(tainted(test_only))
+          build_report(edges: edges, reachable: reachable, unreached: unreached, namespaces: namespaces,
+                       test_only: test_only, undecidable: undecidable)
+        end
+
+        private
+
+        def build_report(edges:, reachable:, unreached:, namespaces:, test_only:, undecidable:)
+          demoted = undecidable.keys.to_set
           Report.new(declared: @owned.size, reachable: reachable.size,
-                     candidates: rows(unreached - namespaces - undecidable.keys.to_set),
+                     candidates: rows(unreached - namespaces - demoted),
                      undecidable: undecidable.map { |fqn, reason| undecidable_row(fqn, reason) }.freeze,
-                     test_only: rows(reachable - production),
+                     test_only: rows(test_only - demoted),
                      namespaces: namespaces.size, roots: production_seeds.size, edges: edges.size)
         end
 
-        private
-
         # A literal-argument `"Foo::Bar".constantize` names its constant exactly, so it is a REFERENCE, not an
         # unknown. Keeping this distinct from the taint below is what stops the tier being a blanket namespace
         # poison — Rigor knows the argument's shape, and a type-free indexer does not.
@@ -76,17 +85,27 @@ module Rigor
           end
         end
 
-        # `{fqn => reason}` for every unreached declaration a dynamic site could still be naming. A site with a
+        # `{fqn => reason}` for every declaration in `fqns` a dynamic site could still be naming. A site with a
         # literal prefix taints that namespace and everything under it; a site with no prefix at all cannot be
         # bounded, so it taints nothing rather than everything — poisoning the whole project would empty the
         # report and teach the reader that the tier means nothing.
-        def tainted(unreached)
-          prefixes = @dynamic_uses.filter_map { |use| [use.prefix, use] if use.name.nil? && use.prefix }
+        #
+        # Asked of the unreached AND of the test-only set (#370). The tier contract says a name appearing in a
+        # data file "MUST demote to this tier"; the implementation had asked only about the unreached, so a
+        # declaration a spec references AND `config/recurring.yml` names kept its data-file evidence discarded
+        # and landed under "live test, dead production path". That heading is an assertion about production,
+        # and a scheduler entry is evidence against it — the reported case runs every three minutes.
+        #
+        # Both buckets ask a different question of the same ambiguity ("is this dead?" against "is the
+        # production path dead?"), and the answer for both is that this reading cannot settle it. The reason
+        # string is what tells the two apart for a reader, so it names the evidence rather than the bucket.
+        def tainted(fqns)
+          sites = @dynamic_uses.select { |use| use.name.nil? && use.prefix }
 
-          return {} if prefixes.empty?
+          return {} if sites.empty?
 
-          unreached.each_with_object({}) do |fqn, out|
-            _, use = prefixes.find { |prefix, _| fqn == prefix || fqn.start_with?("#{prefix}::") }
+          fqns.each_with_object({}) do |fqn, out|
+            use = sites.find { |site| site.taints?(fqn) }
             out[fqn] = use.site.nil? ? use.reason : "#{use.reason} (#{use.site})" if use
           end
         end

data/lib/rigor/analysis/reachability/plugin_roots.rb

@@ -86,12 +86,16 @@ module Rigor
         # @param configuration [Rigor::Configuration] the loaded project configuration.
         # @param plugin_requirer [#call] how a plugin gem is brought into the process. The same seam
         #   `Analysis::Runner` exposes, so a spec can register a plugin class without publishing a gem.
+        # @param cache_store [Rigor::Cache::Store, nil] when given, each plugin's `#prepare` producers read
+        #   and write the same ADR-60 record-and-validate slots they use under `rigor check`, instead of
+        #   recomputing from scratch — a routes parse or a factory discovery is a validated cache read on
+        #   every invocation after the first. Nil keeps the historical recompute-always behaviour.
         # @return [Contribution] sorted and de-duplicated. Empty whenever the project declares no plugins, no
         #   plugin contributes anything, or anything at all goes wrong.
-        def collect(configuration:, plugin_requirer: ->(name) { require name })
+        def collect(configuration:, plugin_requirer: ->(name) { require name }, cache_store: nil)
           return Contribution.empty if configuration.plugins.empty?
 
-          services = build_services(configuration)
+          services = build_services(configuration, cache_store)
           registry = Plugin::Loader.load(configuration: configuration, services: services,
                                          requirer: plugin_requirer)
           return Contribution.empty if registry.nil? || registry.empty?
@@ -102,16 +106,15 @@ module Rigor
           Contribution.empty
         end
 
-        # Mirrors `CLI::ProbeEnvironment.load_plugin_registry`: a `Plugin::Services` with no cache store
-        # (this is a one-shot report, so a producer recomputes rather than reading and writing cache slots)
-        # driving `Plugin::Loader.load`. Holding the `Services` is what gives access to the fact store the
-        # loaded plugins share — the loader hands the same instance to every plugin.
-        def build_services(configuration)
+        # Mirrors `Analysis::WorkerSession`'s services: the shared fact store plus whatever cache store the
+        # caller holds. Holding the `Services` is what gives access to the fact store the loaded plugins
+        # share — the loader hands the same instance to every plugin.
+        def build_services(configuration, cache_store)
           Plugin::Services.new(
             reflection: Reflection,
             type: Type::Combinator,
             configuration: configuration,
-            cache_store: nil
+            cache_store: cache_store
           )
         end
 

data/lib/rigor/analysis/reachability/scan.rb

@@ -33,10 +33,26 @@ module Rigor
 
         # ADR-102 WD4 — a site where a constant is reached by a mechanism the static reading cannot follow.
         # `name` is the exact constant when the argument is a literal (`"Foo".constantize`), in which case this
-        # is as good as a reference. `prefix` is the namespace a dynamic construction can reach into
-        # (`"Foo::#{k}".constantize` → `"Foo"`, and `nil` when even that is unknown), which taints every
-        # declaration at or below it rather than proving any single one used.
-        DynamicUse = Data.define(:name, :prefix, :reason, :site, :path, :line)
+        # is as good as a reference. `prefix` is what a dynamic construction can reach, and `scope` says how
+        # far — the two kinds of weak evidence are not the same shape:
+        #
+        # - `:namespace` — `"Foo::#{k}".constantize` can construct ANY name under `Foo`, so it taints `Foo`
+        #   and every declaration beneath it. This is the default and the original meaning of `prefix`.
+        # - `:exact` — a data-file or template match names ONE declaration and says nothing about its
+        #   children (#370). `config/recurring.yml` mentioning `Admin` is not evidence about
+        #   `Admin::CollectionPolicy`; treating it as such demoted 18 unrelated Mastodon rows off one
+        #   Afrikaans word ("Administrasie" contains "Admin").
+        DynamicUse = Data.define(:name, :prefix, :reason, :site, :path, :line, :scope) do
+          def initialize(scope: :namespace, **) = super
+
+          # Whether this site's evidence reaches `fqn`.
+          def taints?(fqn)
+            return false if prefix.nil?
+            return fqn == prefix if scope == :exact
+
+            fqn == prefix || fqn.start_with?("#{prefix}::")
+          end
+        end
 
         Result = Data.define(:declarations, :references, :dynamic_uses)
 

data/lib/rigor/analysis/reachability/scan_cache.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "zlib"
+
+require_relative "../../version"
+
+module Rigor
+  module Analysis
+    module Reachability
+      # ADR-102 — the warm cache for `rigor unused`'s two per-file passes: the Prism reachability
+      # scan over `.rb` / `.rake` files, and the capital-run extraction over template files. Both
+      # passes are pure functions of one file's bytes, and both were measured re-running in full on
+      # every invocation (2.0 s of a 2.6 s warm run on Mastodon; the Marshal restore is 25× cheaper
+      # than the rescan, `docs/notes/20260825-feature-warm-cold-corpus-perf.md`).
+      #
+      # One self-validating zlib-Marshal blob under the cache root, the ADR-46 IncrementalSnapshot
+      # shape rather than an ADR-54 `Cache::Store` producer: the sound unit of reuse is the FILE
+      # (any subset of files may change between runs), so the payload carries a stat signature per
+      # entry and validates each on read, where a store entry validates all-or-nothing and a miss
+      # would throw away every unchanged file's work. The whole-project answer stays complete —
+      # every file is still consulted every run; an unchanged one contributes its cached product.
+      #
+      # Fail-soft everywhere: a missing, torn, or stale-schema blob is an empty cache, and a file
+      # whose signature cannot be taken is computed and never recorded. Nothing here can change
+      # what the report says — only whether a per-file product was recomputed to say it.
+      class ScanCache
+        SCHEMA = 1
+        FILE_NAME = "reachability-scan.bundle"
+
+        # The sources whose behaviour the cached products embody. Digested into the header so a
+        # checkout that edits the scan invalidates its survey targets' bundles without anyone
+        # remembering to bump {SCHEMA} — the `Cache::EngineSource` idea, scoped to this feature.
+        SOURCE_FILES = [
+          File.expand_path("scan.rb", __dir__),
+          File.expand_path(__FILE__)
+        ].freeze
+
+        # A file modified within this window of the recording instant is computed but never
+        # recorded — the FileDigest racy-write guard, one tier simpler because a refused signature
+        # costs one rescan on the next run, never a wrong answer.
+        RACY_WINDOW_NS = 2_000_000_000
+        private_constant :RACY_WINDOW_NS
+
+        # @param cache_path [String, nil] the configuration's cache root; nil or empty is an inert
+        #   cache (every fetch computes, nothing persists).
+        # @param target_ruby [String, nil] parse-affecting configuration, part of the identity.
+        def self.open(cache_path, target_ruby: nil)
+          return new(path: nil, header: nil) if cache_path.nil? || cache_path.to_s.empty?
+
+          new(path: File.join(cache_path.to_s, FILE_NAME),
+              header: "#{SCHEMA}:#{Rigor::VERSION}:#{target_ruby}:#{source_digest}")
+        end
+
+        def self.source_digest
+          Digest::SHA256.hexdigest(SOURCE_FILES.map { |path| File.read(path) }.join)
+        rescue StandardError
+          "unreadable"
+        end
+
+        def initialize(path:, header:)
+          @path = path
+          @header = header
+          @entries = load_entries
+          @live = {}
+          @dirty = false
+        end
+
+        # Serves the cached product for `(kind, path)` while the file's stat signature holds;
+        # otherwise computes via the block and records the fresh product.
+        def serve(kind, path)
+          key = [kind, path]
+          sig = signature(path)
+          cached = @entries[key]
+          if cached && sig && cached[0] == sig
+            @live[key] = cached
+            return cached[1]
+          end
+
+          value = yield
+          @live[key] = [sig, value] if sig
+          @dirty = true
+          value
+        end
+
+        # Best-effort persist, only when something changed. Carries forward entries this run never
+        # consulted (a path-argument run must not shrink the full-project bundle) but drops the ones
+        # whose file no longer exists; tmp-then-rename so a torn write is never read back.
+        def save
+          return if @path.nil? || !@dirty
+
+          keep = @entries.merge(@live).select { |(_, path), _| File.exist?(path) }
+          FileUtils.mkdir_p(File.dirname(@path))
+          tmp = "#{@path}.#{Process.pid}.tmp"
+          File.binwrite(tmp, Zlib::Deflate.deflate(Marshal.dump([@header, keep])))
+          File.rename(tmp, @path)
+          nil
+        rescue StandardError
+          FileUtils.rm_f(tmp) if tmp
+          nil
+        end
+
+        private
+
+        def load_entries
+          return {} if @path.nil?
+
+          # Same trust model as the ADR-45 store and the ADR-46 snapshot: the blob lives in the
+          # project's own cache directory and a corrupt one degrades to an empty cache.
+          header, entries = Marshal.load(Zlib::Inflate.inflate(File.binread(@path))) # rubocop:disable Security/MarshalLoad
+          header == @header && entries.is_a?(Hash) ? entries : {}
+        rescue StandardError
+          {}
+        end
+
+        def signature(path)
+          st = File.stat(path)
+          mtime_ns = (st.mtime.to_i * 1_000_000_000) + st.mtime.nsec
+          now_ns = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+          return nil if mtime_ns >= now_ns - RACY_WINDOW_NS
+
+          [st.size, mtime_ns, (st.ctime.to_i * 1_000_000_000) + st.ctime.nsec, st.ino]
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/rule_catalog.rb

@@ -36,9 +36,16 @@ module Rigor
     module RuleCatalog # rubocop:disable Metrics/ModuleLength
       # Stable documentation home for a built-in rule. `documentation_url` appends a per-rule fragment that
       # resolves to the rule's anchor in the published diagnostics catalogue; the page itself points at
-      # `rigor explain <rule>` as the authoritative per-rule reference. Mirrors the gemspec
-      # `documentation_uri` URL scheme (`…/tree/main`).
-      DOCUMENTATION_BASE = "https://github.com/rigortype/rigor/blob/main/docs/manual/04-diagnostics.md"
+      # `rigor explain <rule>` as the authoritative per-rule reference.
+      #
+      # The canonical docs host, deliberately NOT a `github.com/…/blob/<ref>/…` path (ADR-65 amendment,
+      # #438): a git ref inside a frozen public contract is a mutable component, and the one that was
+      # baked in here — `main`, a branch this repository has never had — made every emitted URL 404 from
+      # the day the field shipped. A branch name rots on a rename and a tag only resolves once that tag
+      # is pushed (so every unreleased build would emit 404s); the published site carries no ref at all.
+      # The site renders `docs/manual/04-diagnostics.md` verbatim, `<a id="rule-…">` anchors included, so
+      # the fragment half of the contract is unchanged.
+      DOCUMENTATION_BASE = "https://rigor.typedduck.fail/manual/04-diagnostics/"
 
       class Entry < Data.define(:id, :summary, :fires_when, :does_not_fire_when,
                                 :suppression, :severity_authored, :severity_by_profile,

data/lib/rigor/analysis/run_cache_key.rb

@@ -48,6 +48,18 @@ module Rigor
       # collecting run wrote elsewhere.
       RUN_EFFECTS_PRODUCER_ID = "analysis.run-effects"
 
+      # #482 — the **serving** half of the sidecar, under the same effects identity: the propagated table,
+      # the unit sources and the merged as-written superclass table. Everything a warm run reads, and
+      # nothing else.
+      #
+      # It is a separate entry rather than a section of {RUN_EFFECTS_PRODUCER_ID} because the collections
+      # blob is large in exactly the projects where warm latency matters — 6.9 MB and 0.71 s of `Marshal`
+      # on gitlab `app lib`, against ~40 KB here — and a warm run consumes none of it. The collections
+      # entry stays, read lazily by the paths that genuinely need per-file form (an ADR-46 recheck, the
+      # fail-soft re-propagation), so a consumer this split did not anticipate loads the blob rather than
+      # seeing an empty table.
+      RUN_EFFECTS_TABLE_PRODUCER_ID = "analysis.run-effects-table"
+
       # The run-result producer's declared compaction budget (`Cache::Store#evict!` pass 2). Whole-project,
       # but unlike the `rbs.*` producers several generations can be live at once: the `paths` key slot means
       # one entry per analyzed-path SET, so `rigor check` over the whole project, over `lib`, and over a