rigortype 0.3.1 → 0.3.2

data/lib/rigor/bleeding_edge.rb

@@ -11,29 +11,86 @@ module Rigor
   #
   # The WD2 foundation slice wired the surface end-to-end (`bleeding_edge:` config, the
   # `rigor show-bleedingedge` command, the severity-composition hook in
-  # {Configuration::SeverityProfile.resolve}), so a discipline lands as a single {FEATURES}
-  # entry with no engine plumbing — as the first one, `reject-unparseable-signatures`, does.
+  # {Configuration::SeverityProfile.resolve}), so a *severity* discipline lands as a single
+  # {FEATURES} entry with no engine plumbing — as the first one,
+  # `reject-unparseable-signatures`, does.
+  #
+  # A queued change whose effect is not a severity move — a measurement, an algorithm, or a
+  # default that changes while every rule keeps its severity — is a `:behaviour` feature
+  # instead. It carries no severity map; its call sites ask
+  # {Configuration#bleeding_edge_active?} whether the id is adopted for the run.
+  #
+  # A `:behaviour` feature MUST NOT change the output of `rigor check` analysis unless its
+  # feature id is folded into the analysis-cache identity. Rationale, verified 2026-08-01:
+  # severity features are safe because severity is stamped POST-cache — {Analysis::SeverityStamp}
+  # (ADR-87 WD4) stores the authored severity and applies the profile + bleeding-edge overrides
+  # identically on the miss path and the warm-hit path, so a warm HIT re-resolves under the
+  # current selector. A behaviour feature that altered analysis results themselves would poison
+  # warm caches across selector changes, because the selector is not part of the cache key. The
+  # two queued consumers (#253, #254) change what a separate command measures, not what `check`
+  # analyses, so neither is affected.
   #
   # Each feature carries a **stable feature id** — part of the ADR-50 WD1 contract
   # vocabulary: the config, the `show` command, and the eventual CHANGELOG migration note all
-  # name the same id, and a feature graduates to default-on at a major by being removed from
-  # {FEATURES}.
+  # name the same id, and a feature graduates to default-on at a major (ADR-50 § WD7) by
+  # moving from {FEATURES} to {GRADUATED}.
   module BleedingEdge
+    # The two kinds a queued change can take. `:severity` composes through
+    # {Configuration::SeverityProfile.resolve}; `:behaviour` is read at a call site through
+    # {Configuration#bleeding_edge_active?}.
+    KINDS = %i[severity behaviour].freeze
+
+    # The severity map a `:behaviour` feature carries: none.
+    NO_SEVERITY_OVERRIDES = {}.freeze
+
     # One queued change.
     #
+    # The two kinds are exclusive by construction: a `:severity` feature MUST name at least
+    # one rule, and a `:behaviour` feature MUST name none — a behaviour switch that also
+    # moved a severity would be two changes wearing one id, and the id is what a CHANGELOG
+    # migration note and a user's `bleeding_edge:` list both key on.
+    #
     # @!attribute id
     #   @return [String] the stable feature id (contract vocabulary).
     # @!attribute summary
-    #   @return [String] a one-line description of what it changes.
+    #   @return [String] a one-line description of what it changes. For a `:behaviour`
+    #     feature this is the *whole* explanation — there is no severity diff to read.
+    # @!attribute kind
+    #   @return [Symbol] one of {KINDS}.
     # @!attribute severity_overrides
     #   @return [Hash{String => Symbol}] canonical rule id → the severity this feature
     #     imposes. Composed *below* the user's own `severity_overrides:` and *above* the
-    #     active `severity_profile` (see {Configuration::SeverityProfile.resolve}).
-    Feature = Data.define(:id, :summary, :severity_overrides) do
+    #     active `severity_profile` (see {Configuration::SeverityProfile.resolve}). Empty for
+    #     a `:behaviour` feature.
+    Feature = Data.define(:id, :summary, :kind, :severity_overrides) do
+      def initialize(id:, summary:, kind:, severity_overrides: NO_SEVERITY_OVERRIDES)
+        raise ArgumentError, "kind must be one of #{KINDS.inspect}, got #{kind.inspect}" unless KINDS.include?(kind)
+
+        if kind == :severity && severity_overrides.empty?
+          raise ArgumentError, "bleeding-edge feature #{id.inspect} is :severity but overrides no rule"
+        end
+        if kind == :behaviour && !severity_overrides.empty?
+          raise ArgumentError, "bleeding-edge feature #{id.inspect} is :behaviour but carries severity_overrides"
+        end
+
+        super
+      end
+
+      # @return [Boolean]
+      def severity?
+        kind == :severity
+      end
+
+      # @return [Boolean]
+      def behaviour?
+        kind == :behaviour
+      end
+
       def to_h
         {
           "id" => id,
           "summary" => summary,
+          "kind" => kind.to_s,
           "severity_overrides" => severity_overrides.transform_values(&:to_s)
         }
       end
@@ -48,6 +105,7 @@ module Rigor
     FEATURES = [
       Feature.new(
         id: "reject-unparseable-signatures",
+        kind: :severity,
         summary: "A broken `signature_paths:` RBS set fails the run instead of degrading it silently. An " \
                  "unparseable `.rbs` is otherwise skipped with a warning, and a duplicate-declaration " \
                  "conflict (a file that parses fine but collides on resolve — typically against Rigor's " \
@@ -61,6 +119,7 @@ module Rigor
       ),
       Feature.new(
         id: "use-of-void-value",
+        kind: :severity,
         summary: "Using a value recovered from an author-declared `-> void` return in value context (an " \
                  "assignment right-hand side, a call receiver, or an argument) becomes a `:warning`. An " \
                  "explicit `-> void` is the strongest possible \"do not rely on this return\" signal, so " \
@@ -70,9 +129,51 @@ module Rigor
         severity_overrides: {
           "static.value-use.void" => :warning
         }.freeze
+      ),
+      Feature.new(
+        id: "discovery-seeded-mutation-sites",
+        kind: :behaviour,
+        summary: "`rigor coverage --protection --mutation` (Tier 2) measures against the same cross-file " \
+                 "project discovery Tier 1 already seeds, instead of an empty scope — both when picking the " \
+                 "sites and when re-analysing each breakage to decide whether it was caught. A call whose " \
+                 "receiver is a project class declared in a *sibling* file (`Post.where`, " \
+                 "`Rigor::Protection::Mutator.new`) then resolves to the type it really has rather than " \
+                 "`Dynamic`, so the site is measured instead of dropped — and a breakage there can actually " \
+                 "be caught. This makes the two tiers judge a site " \
+                 "by one standard, but it ADDS sites to the denominator, so the reported effectiveness ratio " \
+                 "goes DOWN on the same code — and `--threshold=RATIO` exits 1 when that ratio falls below a " \
+                 "number pinned in CI. Off by default for that reason: it is a queued change for the next " \
+                 "major, not a fix you should be opted into mid-release."
+      ),
+      Feature.new(
+        id: "dependent-closure-kill-oracle",
+        kind: :behaviour,
+        summary: "`rigor coverage --protection --mutation` (Tier 2) decides a breakage was caught when the " \
+                 "diagnostic appears anywhere in the mutated file OR the files that depend on it, instead of " \
+                 "in the mutated file alone. Changing what a method returns is caught in its *callers* — the " \
+                 "cross-file reach the analyzer exists for — and that catch is scored as a miss today. The " \
+                 "measurement re-analyses the dependent closure (ADR-46's dependency graph) against the " \
+                 "mutated bytes, so those catches count. It can only ADD kills, never remove one, so the " \
+                 "reported ratio moves up or not at all; a recorded ratio nonetheless stops being comparable " \
+                 "with one measured without it. It costs roughly a third more wall time per mutant, and on " \
+                 "the two corpora measured so far (Rigor's own `lib`, redmine `app/models`) it added no " \
+                 "kills — every surviving breakage there is one the analyzer reports nowhere at all, not one " \
+                 "it reports in a caller."
       )
     ].freeze
 
+    # ADR-50 § WD7 — the ids that have already graduated to default-on.
+    #
+    # A feature graduates at a major by moving *here* from {FEATURES} rather than by simply
+    # disappearing: {Configuration#bleeding_edge_active?} then answers an unconditional `true`
+    # for the id, so a call site still asking about it keeps the graduated behaviour and gate
+    # cleanup can lag graduation by as many releases as it takes. The id also stays in the
+    # contract vocabulary the CHANGELOG migration note keys on. Entries are removed only once
+    # no call site names them.
+    #
+    # @return [Array<String>]
+    GRADUATED = [].freeze
+
     module_function
 
     # @return [Array<Feature>] the whole overlay.
@@ -91,6 +192,19 @@ module Rigor
       FEATURES.find { |f| f.id == id }
     end
 
+    # @param id [String]
+    # @return [Boolean] whether the id has graduated to default-on ({GRADUATED}).
+    def graduated?(id)
+      GRADUATED.include?(id)
+    end
+
+    # @param id [String]
+    # @return [Boolean] whether the id names a feature this gem knows at all — queued or
+    #   graduated. Distinct from "adopted"; see {Configuration#bleeding_edge_active?}.
+    def known_id?(id)
+      graduated?(id) || FEATURES.any? { |f| f.id == id }
+    end
+
     # Resolves a normalized `bleeding_edge:` selector (see {Configuration#bleeding_edge}) to
     # the active {Feature} list. Unknown ids in a `list` / `except` selector are simply
     # absent from the overlay and contribute nothing — symmetric with how
@@ -125,6 +239,17 @@ module Rigor
       end.freeze
     end
 
+    # The ids the active features expose to {Configuration#bleeding_edge_active?}, as a frozen
+    # `Set` so a call site on the hot path pays a hash lookup rather than an Array scan.
+    # Precomputed once per Configuration; frozen (with frozen members) so the carrier stays
+    # `Ractor.shareable?` across the worker boundary.
+    #
+    # @param selector [Hash] see {#active_features}.
+    # @return [Set<String>]
+    def active_ids_for(selector)
+      Set.new(active_features(selector).map(&:id)).freeze
+    end
+
     # Feature ids named by a selector that are NOT in the overlay (typo / graduated / from a
     # newer gem). Surfaced by `rigor show-bleedingedge` as a hint; never an error.
     #

data/lib/rigor/cache/descriptor.rb

@@ -33,7 +33,12 @@ module Rigor
       # content digests. Old entries must read as misses so the first writable run rebuilds them in the new
       # format for a clean one-shot migration (the #57 marker discipline: the bump clears the root and
       # reclaims the unreadable bytes).
-      SCHEMA_VERSION = 5
+      # v6: #237 — `append_stub_declarations` now emits the declaration KIND each referenced-type stub needs
+      # (`interface` / `type` / `module` / `class`) and validates each declaration on its own, so a project
+      # whose RBS dangles an interface or type-alias reference gets stubs where an older Rigor discarded the
+      # whole batch and cached an env in which those signatures are inert. Same reasoning as v3: the
+      # marshalled env is the cached value, so it MUST be rebuilt for the fix to take effect.
+      SCHEMA_VERSION = 6
 
       # Per-slot entry value objects. Constructors validate enums / required fields and freeze the resulting
       # struct so no caller can mutate after the entry is in a Descriptor.

data/lib/rigor/cache/engine_source.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "../version"
+
+module Rigor
+  module Cache
+    # Issue #285 — the identity of the ENGINE'S OWN SOURCE, as a cache-key slot.
+    #
+    # Every Rigor cache whose value is a function of what the analyzer COMPUTES (the ADR-45 run-result
+    # cache, the #134 mutation-result cache) keys on `Rigor::VERSION`. For a gem installed from RubyGems
+    # that is exact — the version pins the bytes. For anyone running an edited working tree it is not, and
+    # the failure is invisible: a warm `rigor check` replays the pre-edit diagnostics verbatim, so a
+    # before/after measurement of an engine change reports `0 new, 0 gone` no matter what the change does.
+    # That shape of false zero survived into #152's FP evaluation before it was caught.
+    #
+    # ## The two regimes
+    #
+    # {.identity} answers `nil` for a tree whose identity `Rigor::VERSION` already fixes — a RubyGems
+    # install, recognised by its `<gem_home>/gems/rigortype-<VERSION>` directory layout. The caller then
+    # adds NO slot, so a released gem's cache key is byte-identical to the one it had before this module
+    # existed and pays not one syscall for it. Everything else — a contributor's checkout, a `bundle add
+    # rigor, github:` clone (where two commits share one `Rigor::VERSION`), a `path:` gem — is treated as
+    # mutable and gets a content digest of the engine's source tree.
+    #
+    # The predicate is deliberately POSITIVE about being pinned, so every case it fails to recognise lands
+    # on the safe side: an unrecognised release pays one directory walk and one extra cache generation,
+    # while an unrecognised checkout would have served a stale answer.
+    #
+    # ## Why a content digest and not a stat tuple
+    #
+    # A `(size, mtime, ctime, inode)` walk is ~3× cheaper (measured: 5.4 ms vs 17 ms over this repo's 539
+    # engine files), and ADR-87 WD1 trusts exactly that tuple for FRESHNESS. It cannot be used here:
+    # {Descriptor::FileEntry} states the rule directly — a stat tuple carries machine-local, per-run
+    # nondeterministic data and MUST NOT enter a descriptor used as a cache KEY. On the freshness side a
+    # moved tuple falls back to the recorded digest, so a fresh checkout of unchanged content still
+    # validates; a KEY has no such fallback, so keying on stat would make every CI run and every branch
+    # switch a total miss for the `github:`-tracking users this module exists to protect.
+    #
+    # ## Never a wrong hit
+    #
+    # A mutable tree whose digest cannot be computed raises {Unavailable} rather than answering `nil`.
+    # Both callers already rescue a malformed key into "no cache for this run", which is the only sound
+    # reading: falling back to the version-only key would restore precisely the blind spot being fixed.
+    module EngineSource
+      # Raised when the tree is not version-pinned AND its source cannot be digested. Deliberately not
+      # rescued in this module — see the class doc's last paragraph.
+      class Unavailable < StandardError; end
+
+      # The RubyGems package name. `<name>-<version>` is the install directory layout {.version_pinned?}
+      # recognises; the constant is not read from the gemspec because this file loads on the boot-slimming
+      # probe path, which must not touch RubyGems' specification machinery.
+      GEM_NAME = "rigortype"
+
+      # Engine source, relative to the gem root. `plugins/` ships inside the same gem and its recognisers
+      # move diagnostics exactly as `lib/` does, so an edit there must invalidate too; `examples/`,
+      # `apps/` and `tool/` are not loaded by an analysis and stay out.
+      SOURCE_DIRECTORIES = %w[lib plugins].freeze
+
+      # The one directory whose absence means "this is not an engine tree". `plugins/` may legitimately be
+      # missing (a slimmed install contributes nothing); a missing `lib/` would silently shrink the digest
+      # to whatever else happened to be there, which is exactly the weakening this module forbids.
+      REQUIRED_DIRECTORY = "lib"
+
+      module_function
+
+      # @return [String] the gem root — the directory holding `lib/`, three levels above this file.
+      def root
+        @root ||= File.expand_path("../../..", __dir__)
+      end
+
+      # @param root [String] the gem root, defaulted through {.root} so a spec can relocate the tree.
+      # @return [String, nil] a digest identifying the engine's current source, or nil when the tree is
+      #   version-pinned and the caller should add no slot at all.
+      # @raise [Unavailable] when a mutable tree's source cannot be read.
+      def identity(root = self.root)
+        return nil if version_pinned?(root)
+
+        digest_tree(root)
+      end
+
+      # {.identity} for THIS process's engine, computed once. Every production caller wants this; the
+      # uncached {.identity} stays the computation, and the seam a spec relocates.
+      #
+      # A memo, not a per-call walk, on two grounds.
+      #
+      # Cost. #285 could afford the walk because the two callers it wired reached it at most twice per
+      # process. Adding {IncrementalSnapshot.fingerprint} (#289) breaks that: {Protection::MutationCache}
+      # builds a fingerprint per snapshot-root candidate, so one `rigor coverage --protection --mutation
+      # PATH` reaches this five times — 90 ms of walking for a value that cannot differ between the calls.
+      #
+      # Correctness, which is the stronger reason. The digest exists to identify the engine that COMPUTED a
+      # cached value, and that engine is fixed when the process finishes requiring — nothing an edit does to
+      # `lib/` mid-run changes the code already running. Re-reading the tree would eventually key values
+      # against source that never produced them, so the memo is the more faithful answer, not merely the
+      # cheaper one. That is also why a fork-pool worker inheriting it is right: `PoolCoordinator` builds one
+      # session on the parent and forks children that copy-on-write inherit its image, so parent and child
+      # run the same engine by construction — and the fingerprints are computed on the parent before a pool
+      # exists at all. The same reading covers the long-running `rigor lsp` process.
+      #
+      # {Unavailable} propagates and is deliberately NOT memoised: the ivar is only assigned on success.
+      def process_identity
+        return @process_identity if defined?(@process_identity)
+
+        @process_identity = identity
+      end
+
+      # Discards the {.process_identity} memo; production code MUST NOT call this — a run that recomputed
+      # mid-flight would key cached values against source that did not compute them, which is the whole
+      # argument for the memo. It exists because a spec process is many logical "processes", and a memo that
+      # outlived one example would silently ignore the next one's stub of {.root} / {.identity} and pass for
+      # the wrong reason. `spec_helper` calls it before every example so no spec has to know it is here.
+      def reset_process_identity!
+        remove_instance_variable(:@process_identity) if defined?(@process_identity)
+      end
+
+      # True when `Rigor::VERSION` already pins this tree's bytes: an immutable RubyGems install, laid out
+      # as `…/gems/rigortype-<VERSION>`. The `.git` probe is the belt to that braces — a working tree that
+      # somehow occupies a release-shaped path is still a working tree.
+      def version_pinned?(root)
+        return false unless File.basename(root) == "#{GEM_NAME}-#{Rigor::VERSION}"
+        return false unless File.basename(File.dirname(root)) == "gems"
+
+        !File.exist?(File.join(root, ".git"))
+      end
+
+      # A SHA-256 over every engine `.rb` file: its ROOT-RELATIVE path (so the digest survives moving or
+      # re-cloning the checkout) followed by its bytes, in sorted path order.
+      #
+      # The walk itself is not memoised — {.process_identity} is where a production caller gets the
+      # once-per-process value, and this stays the computation so a spec can point it at another tree.
+      def digest_tree(root)
+        unless File.directory?(File.join(root, REQUIRED_DIRECTORY))
+          raise Unavailable, "#{root} has no #{REQUIRED_DIRECTORY}/ to identify the engine by"
+        end
+
+        digest = Digest::SHA256.new
+        prefix = "#{root}#{File::SEPARATOR}"
+        count = 0
+        source_files(root).each do |path|
+          digest << path.delete_prefix(prefix) << "\0"
+          digest.file(path)
+          count += 1
+        end
+        raise Unavailable, "no engine source found under #{root}" if count.zero?
+
+        digest.hexdigest
+      rescue SystemCallError, IOError => e
+        raise Unavailable, "engine source under #{root} could not be read: #{e.message}"
+      end
+
+      # Sorted absolute paths of every engine `.rb` file, across the directories that exist.
+      def source_files(root)
+        SOURCE_DIRECTORIES.flat_map do |relative|
+          directory = File.join(root, relative)
+          File.directory?(directory) ? Dir.glob(File.join(directory, "**", "*.rb")) : []
+        end.sort
+      end
+    end
+  end
+end

data/lib/rigor/cache/incremental_snapshot.rb

@@ -4,6 +4,8 @@ require "fileutils"
 require "digest"
 require "zlib"
 
+require_relative "engine_source"
+
 module Rigor
   module Cache
     # ADR-46 — disk persistence for the incremental analyzer's per-file state, so a `--incremental` session
@@ -14,8 +16,16 @@ module Rigor
     # this snapshot is loaded UNCONDITIONALLY when the global fingerprint matches — the per-file digests
     # *inside* it drive the incremental re-analysis decision; they do not gate the load. The fingerprint
     # captures the inputs whose change requires a full rebuild — the resolved configuration, the RBS
-    # environment, the engine version — but NOT the analyzed source contents. A fingerprint mismatch (config /
-    # gem / version change) drops the snapshot and forces a full re-analysis, the conservative direction.
+    # environment, the engine version and (on a checkout) the engine's own source — but NOT the analyzed
+    # source contents. A fingerprint mismatch (config / gem / version / engine change) drops the snapshot and
+    # forces a full re-analysis, the conservative direction.
+    #
+    # An engine change drops the WHOLE snapshot rather than part of it, which is a soundness point before it
+    # is a simplicity one: every section here except `digests` is a value the analyzer computed, so a changed
+    # engine can move any of it — including the dependency edges, where a new engine recording an edge the old
+    # one missed would let a recheck skip the very file that needed re-analysing. Retaining the one
+    # engine-independent section would not pay either: `digests` is 2.5% of a 2.5 MB snapshot of this repo,
+    # and re-deriving it is a file-digest walk costing ~0.2% of the full run it would be saving.
     #
     # Every operation is fault-tolerant: a missing, unreadable, schema-mismatched, fingerprint-mismatched, or
     # corrupt snapshot loads as nil (→ a cold full run), and a write failure is swallowed (→ the next run is
@@ -38,8 +48,11 @@ module Rigor
       # bundle (the per-def parameter-shape / visibility / ancestry surface the declaration-stability gate
       # compares) and WD2 adds `return_summaries` (per-def observed-key return descriptors + mutation-effect
       # sets the behavioural-stability gate compares); a pre-10 blob mismatches the SCHEMA gate and loads as
-      # nil (a clean cold rebuild — no migration).
-      SCHEMA = 10
+      # nil (a clean cold rebuild — no migration). 11: ADR-67 WD6c lift adds `param_table` (the inferred-param
+      # seed table the run's diagnostics were computed under, diffed on the next recheck to invalidate a
+      # callee whose seeds moved because a caller changed); a pre-11 blob mismatches the SCHEMA gate and
+      # loads as nil (a clean cold rebuild — no migration).
+      SCHEMA = 11
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -68,20 +81,35 @@ module Rigor
       # (Marshal-clean type tuples), their `describe(:short)` return descriptors, and the content-mutated
       # parameter positions. A recheck re-evaluates a declaration-stable changed callee at these keys and,
       # when every return + the effects are unchanged, skips its symbol dependents.
+      # ADR-67 WD6c lift:
+      # `param_table` is the `parameter_inference:` seed table (`[class, method, kind] => {param => Type}`)
+      # the run that wrote the snapshot seeded its analysis from — `{}` when the gate is off. A recheck
+      # recomputes the table fresh (the pre-pass is whole-project by design) and diffs it against this copy;
+      # a changed entry invalidates the callee's file and its symbol dependents. The types are Marshal-clean
+      # by the session's per-entry filter; a dropped entry re-checks its callee, the conservative direction.
       Payload = Data.define(:cache, :sources, :digests, :analyzed,
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
                             :missing, :class_decls, :seed_bundles, :plugin_fact_digest,
-                            :return_summaries)
+                            :return_summaries, :param_table)
 
       # The global fingerprint that gates a snapshot load: a digest of the inputs whose change requires a full
-      # rebuild — the engine version + schema, the resolved configuration, the analysis **roots** (the path
-      # arguments, e.g. `["lib"]`, NOT the expanded file list — so a snapshot is keyed to an invocation's roots
-      # but adding / removing a file under them is handled incrementally by the session, not a full rebuild),
-      # the resolved gem set (`Gemfile.lock` / `rbs_collection`), and the project's own RBS (`signature_paths`
-      # file contents). Built WITHOUT constructing the RBS environment so the warm path can gate the load
-      # cheaply, before the costly env build. The `--verify-incremental` gate is the safety net for any
-      # under-capture (it would surface as an incremental-vs-full mismatch). Returns nil on any error → the
-      # caller falls back to a non-persisted run.
+      # rebuild — the engine version + schema, the engine's own SOURCE when the version does not pin it, the
+      # resolved configuration, the analysis **roots** (the path arguments, e.g. `["lib"]`, NOT the expanded
+      # file list — so a snapshot is keyed to an invocation's roots but adding / removing a file under them is
+      # handled incrementally by the session, not a full rebuild), the resolved gem set (`Gemfile.lock` /
+      # `rbs_collection`), and the project's own RBS (`signature_paths` file contents). Built WITHOUT
+      # constructing the RBS environment so the warm path can gate the load cheaply, before the costly env
+      # build. The `--verify-incremental` gate is the safety net for any under-capture (it would surface as an
+      # incremental-vs-full mismatch). Returns nil on any error → the caller falls back to a non-persisted run.
+      #
+      # Issue #285, wired here by #289 — every value in this snapshot is something the ANALYZER computed, so
+      # `Rigor::VERSION` alone is not enough to identify what produced it. A version pins the engine's bytes
+      # for a RubyGems install and for nothing else, so on a checkout a warm recheck served diagnostics a
+      # pre-edit analyzer had computed: editing `lib/rigor/inference/*.rb` moved no ANALYZED file, the changed
+      # set came back empty, and 357 unchanged files replayed their old answers.
+      # {EngineSource.process_identity} closes it, and answers nil for a version-pinned tree — which adds no
+      # part, so a released gem's fingerprint is byte-identical to the pre-#289 one and its warm snapshots
+      # survive the upgrade untouched.
       def self.fingerprint(configuration:, roots:)
         parts = [
           "engine:#{Rigor::VERSION}:#{SCHEMA}",
@@ -91,8 +119,15 @@ module Rigor
           "rbs_collection:#{digest_file_if_present('rbs_collection.lock.yaml')}",
           "sig:#{digest_signature_paths(configuration.signature_paths)}"
         ]
+        identity = EngineSource.process_identity
+        parts << "engine-source:#{identity}" if identity
         Digest::SHA256.hexdigest(parts.join("\x00"))
       rescue StandardError
+        # {EngineSource::Unavailable} lands here too, and nil is the answer it requires rather than one it
+        # merely tolerates: an engine we cannot identify must DISABLE the snapshot, never fall back to the
+        # version-only key that is the blind spot above. Nil does disable it on both sides —
+        # {Analysis::IncrementalSession} guards the load AND the save on the fingerprint, so nothing stale is
+        # read and no nil-keyed blob is written for the next equally-unidentifiable run to match against.
         nil
       end
 
@@ -124,9 +159,42 @@ module Rigor
       # The stored {Payload}, or nil when absent / unreadable / schema or fingerprint mismatch / corrupt.
       # Never raises.
       def load(fingerprint:)
+        data = read_data
+        return nil unless data && data[:fingerprint] == fingerprint
+
+        payload_from(data)
+      end
+
+      # Issue #134 slice 2 — the same load against SEVERAL acceptable fingerprints, reading the blob once.
+      # A reader that did not itself write the snapshot cannot know which analysis ROOTS it was written under
+      # (`rigor check --incremental lib` and a bare `rigor check --incremental` produce different fingerprints
+      # for the same project), and `#load` would have to re-inflate + re-unmarshal the whole blob per candidate.
+      # The fingerprint that matched is returned alongside the payload so the caller can mix it into ITS own
+      # cache key — the snapshot's identity is exactly what "these dependency edges came from that world" means.
+      #
+      # @param fingerprints [Array<String>] candidates, most-specific first.
+      # @return [Array(String, Payload), nil] `[matched fingerprint, payload]`, or nil on any miss.
+      def load_any(fingerprints:)
+        data = read_data
+        return nil if data.nil?
+
+        matched = Array(fingerprints).compact.find { |candidate| data[:fingerprint] == candidate }
+        return nil if matched.nil?
+
+        [matched, payload_from(data)]
+      end
+
+      # The raw stored Hash when it is present, readable, and schema-current; nil otherwise. Never raises —
+      # a missing, corrupt, or stale-schema snapshot is a cold run, not an error (the ADR-45 invariant).
+      def read_data
         data = Marshal.load(Zlib::Inflate.inflate(File.binread(@path))) # rubocop:disable Security/MarshalLoad
-        return nil unless data.is_a?(Hash) && data[:schema] == SCHEMA && data[:fingerprint] == fingerprint
+        data.is_a?(Hash) && data[:schema] == SCHEMA ? data : nil
+      rescue StandardError
+        nil
+      end
+      private :read_data
 
+      def payload_from(data)
         Payload.new(
           cache: data[:cache], sources: data[:sources],
           digests: data[:digests], analyzed: data[:analyzed],
@@ -137,11 +205,11 @@ module Rigor
           class_decls: data[:class_decls] || {},
           seed_bundles: data[:seed_bundles] || {},
           plugin_fact_digest: data[:plugin_fact_digest],
-          return_summaries: data[:return_summaries] || {}
+          return_summaries: data[:return_summaries] || {},
+          param_table: data[:param_table] || {}
         )
-      rescue StandardError
-        nil
       end
+      private :payload_from
 
       # Persist `payload` under `fingerprint`. Writes via a temp file + atomic rename so a concurrent reader
       # never sees a half-written snapshot. Returns true on success, false on any failure (never raises).
@@ -158,7 +226,8 @@ module Rigor
           class_decls: payload.class_decls,
           seed_bundles: payload.seed_bundles,
           plugin_fact_digest: payload.plugin_fact_digest,
-          return_summaries: payload.return_summaries
+          return_summaries: payload.return_summaries,
+          param_table: payload.param_table
         )
         blob = Zlib::Deflate.deflate(raw)
         tmp = "#{@path}.#{Process.pid}.tmp"