rigortype 0.3.1 → 0.3.3

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

@@ -389,16 +389,13 @@ module Rigor
         # copy-on-write-inherited session and writes the Marshal'd payload to `out_path`. `exit!` skips
         # `at_exit` / stdio flush — the payload is already durable on disk by then.
         def run_fork_worker(session, slice, out_path)
-          # Re-arm deferred YJIT in the child. The parent (`check` / `coverage`) armed `enable_after` on a
-          # background thread, but `fork` copies only the calling thread — the sleeping deadline thread does not
-          # survive into the child, so a worker forked before the deadline fires would otherwise run its whole
-          # (dominant) analysis slice un-JITted no matter how long it takes. If the parent already enabled YJIT
-          # before forking (a slow env build pushed the fork past the deadline), the child inherited the enabled
-          # state and this is a no-op; otherwise the child times its own slice and JITs the tail once it proves
-          # long enough — the same amortization contract, per worker. Parallel mode is opted into for large
-          # projects, so a worker slice reliably outlasts the deadline; a small-project worker finishes first and
-          # stays at no-YJIT parity, exactly as the sequential path would.
-          Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
+          # Re-arm deferred YJIT in the child: the parent's deadline thread does not survive `fork`, so a worker
+          # forked before the deadline fires would otherwise run its whole (dominant) analysis slice un-JITted
+          # no matter how long it takes. {Runtime::Jit.rearm_after_fork} carries what is *left* of the parent's
+          # window, so the run's amortization deadline stays one deadline rather than one per worker. Parallel
+          # mode is opted into for large projects, so a slice reliably outlasts the remainder; a small-project
+          # worker finishes first and stays at no-YJIT parity, exactly as the sequential path would.
+          Runtime::Jit.rearm_after_fork
           results = slice.to_h { |path| [path, session.analyze(path)] }
           payload = { results: results, reporters: session.drain_reporters,
                       dependencies: session.drain_dependencies }

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

@@ -186,7 +186,9 @@ module Rigor
         # Translates a prebuilt {ProjectScan} snapshot supplied to `Runner.new(prebuilt: ...)` into a
         # {Result} the runner adopts the same way it adopts a fresh pre-pass run. The discovery tables are
         # not part of the snapshot (the LSP path seeds an empty project scope), and `Runner#ensure_project_discovery`
-        # is a no-op under `prebuilt`, so they stay at their frozen-empty constructor defaults.
+        # is a no-op under `prebuilt`, so they stay at their frozen-empty constructor defaults — unless the
+        # caller opted into `Runner.new(discovery_seed:)` (issue #260), which seeds the per-file scopes
+        # directly and leaves these ivars alone.
         def adopt_prebuilt(scan)
           Result.new(
             plugin_registry: scan.plugin_registry,

data/lib/rigor/analysis/runner.rb

@@ -40,6 +40,7 @@ require_relative "runner/run_snapshots"
 require_relative "runner/project_pre_passes"
 require_relative "runner/pool_coordinator"
 require_relative "runner/diagnostic_aggregator"
+require_relative "runner/buffer_pool_dispatcher"
 
 module Rigor
   module Analysis
@@ -95,12 +96,19 @@ module Rigor
       #   pass a shared env so per-publish work doesn't repeat the `Environment.for_project` build (bundler
       #   / lockfile / collection discovery, RbsLoader construction). Pool mode ignores the override — each
       #   worker continues to build its own Environment.
+      # @param discovery_seed [Hash, nil] issue #260 — opt-in cross-file discovery tables, keyed by
+      #   {Scope::DiscoveryIndex} slot name, seeded onto every per-file scope through
+      #   `project_scope_seed_tables`. The ONE deliberate exception to "a `prebuilt:` runner carries no
+      #   discovery tables": {Protection::DiagnosticOracle} threads the table set Tier 2's site filter already
+      #   judges anchors against, so a site admitted because a sibling-file class resolved is also a site the
+      #   oracle can kill at. nil (the default) leaves the prebuilt/LSP contract byte-identical.
       def initialize(configuration:, explain: false, # rubocop:disable Metrics/ParameterLists,Metrics/AbcSize,Metrics/MethodLength
                      cache_store: Cache::Store.new(root: DEFAULT_CACHE_ROOT),
                      plugin_requirer: nil, workers: 0, collect_stats: true,
                      buffer: nil, prebuilt: nil, environment: nil,
                      record_dependencies: false, record_self_calls: false, analyze_only: nil,
-                     seed_bundles: nil, collect_seed_bundles: false)
+                     seed_bundles: nil, collect_seed_bundles: false, param_inferred_types: nil,
+                     discovery_seed: nil)
         @configuration = configuration
         @explain = explain
         @cache_store = enforce_read_only_cache(cache_store, buffer)
@@ -140,6 +148,16 @@ module Rigor
         @collect_seed_bundles = collect_seed_bundles
         @restored_seed_bundles = seed_bundles || {}
         @seed_bundles = {}.freeze
+        # ADR-67 WD6c lift — a precomputed inferred-param table. When the incremental session already ran the
+        # collector (it must, to diff the table against its snapshot BEFORE deciding the re-analyse closure),
+        # it hands the result here so `seed_parameter_inference` seeds without a second whole-project collect
+        # — and so the table the diff was decided on and the table this run seeds from are the SAME object,
+        # not merely an equal recomputation. nil (the default) keeps the runner self-sufficient.
+        @param_inferred_types_override = param_inferred_types
+        # Issue #260 — the opt-in cross-file discovery seed (see the `discovery_seed:` doc above). Frozen and
+        # never mutated; `project_scope_seed_tables` starts from a copy of it and lets any table this run
+        # actually computed win.
+        @discovery_seed = discovery_seed&.freeze
         @file_dependencies = {}
         @plugin_registry = Plugin::Registry::EMPTY
         @dependency_source_index = DependencySourceInference::Index::EMPTY
@@ -324,6 +342,32 @@ module Rigor
         result.transform_values(&:freeze).freeze
       end
 
+      # ADR-67 WD6c lift — the inferred-param table this run seeded from (frozen; empty when
+      # `parameter_inference:` is off or the pre-pass failed soft). The incremental session reads it back
+      # after a baseline so the snapshot records the seeds the cached diagnostics were computed under.
+      def param_inferred_types
+        @project_param_inferred_types
+      end
+
+      # ADR-67 WD6c lift — computes the whole-project inferred-param table without running an analysis.
+      # The incremental session calls this BEFORE deciding its re-analyse closure: the table's diff against
+      # the snapshot's stored table is what invalidates a callee whose seeds moved because a *caller* file
+      # changed. Same collector invocation as {#seed_parameter_inference} (one round, same workers), so the
+      # session-computed table and an in-run collect are byte-identical by construction. Fails soft to the
+      # empty table — which the caller's diff then treats as "every stored entry removed", the conservative
+      # direction (those callees re-check).
+      def collect_param_inference_table(files)
+        return {}.freeze unless @configuration.parameter_inference
+
+        environment = @pool_coordinator.resolve_sequential_environment(source_files: files)
+        Inference::ParameterInferenceCollector.collect(
+          files: files, environment: environment,
+          target_ruby: @configuration.target_ruby, max_rounds: 1, workers: @workers
+        )
+      rescue StandardError
+        {}.freeze
+      end
+
       # ADR-89 WD2 — the per-method observed-key return summaries the run's ADR-84 return memo just captured.
       # For each project method with live memo entries, a bounded `{ keys:, returns:, effects: }` summary the
       # incremental session persists: `keys` the observed `[receiver, arg_types]` type tuples, `returns` their
@@ -511,6 +555,11 @@ module Rigor
       def seed_parameter_inference(expansion, environment)
         return environment unless @configuration.parameter_inference
 
+        if @param_inferred_types_override
+          @project_param_inferred_types = @param_inferred_types_override
+          return environment
+        end
+
         files = expansion.fetch(:files)
         environment ||= @pool_coordinator.resolve_sequential_environment(source_files: files)
         @project_param_inferred_types = Inference::ParameterInferenceCollector.collect(
@@ -638,7 +687,9 @@ module Rigor
       # surface. The cross-file discovery tables are NOT carried here — `#run` (prebuilt-less) and
       # `adopt_prebuilt` both leave them at their frozen-empty constructor defaults, and the analysis path
       # fills them lazily via {#ensure_project_discovery}. The prebuilt (LSP) path never fills them, matching
-      # the original adopt behaviour that seeded an empty project scope.
+      # the original adopt behaviour that seeded an empty project scope — with ONE deliberate exception, the
+      # opt-in `discovery_seed:` constructor seam (issue #260), which bypasses the ivars entirely and rides
+      # `project_scope_seed_tables`. A prebuilt runner constructed without it is unchanged.
       def apply_pre_passes_result(result)
         @plugin_registry = result.plugin_registry
         @dependency_source_index = result.dependency_source_index
@@ -669,7 +720,9 @@ module Rigor
       # Internal: builds the deferred cross-file discovery tables at most once per run and adopts them.
       # Memoised on `@project_discovery_done` (reset at the start of `#run`). No-op under `@prebuilt` — the
       # LSP path deliberately seeds an empty project scope from a snapshot that carries no discovery tables,
-      # so forcing a build there would change that contract. Called eagerly from `#run` for the recording /
+      # so forcing a build there would change that contract. A caller that DOES want cross-file knowledge under
+      # `prebuilt:` supplies it explicitly through `discovery_seed:` (issue #260) rather than by re-walking the
+      # project here. Called eagerly from `#run` for the recording /
       # subset (ADR-46) modes and lazily from `#assemble_run_diagnostics` on the analysis path, so a warm
       # cache HIT (which never assembles) never pays the double parse.
       def ensure_project_discovery(expansion)
@@ -757,11 +810,18 @@ module Rigor
       def target_files(expansion)
         files = expansion.fetch(:files)
         # ADR-46 slice 2 — restrict the analyzed set to the affected closure while the pre-pass (run
-        # separately over `expansion`'s full file list) keeps the cross-file index complete. Buffer mode
-        # takes precedence — its single logical path is the analyzed set.
-        files = files.select { |path| @analyze_only.include?(path) } if @analyze_only
+        # separately over `expansion`'s full file list) keeps the cross-file index complete.
+        if @analyze_only
+          # Editor mode option B (#146) — with BOTH set, the closure wins and the buffer is one member of it.
+          # The logical path joins even when it is not on disk under `paths:` (design § "Failure envelope"),
+          # the same allowance option A makes below.
+          files = files.select { |path| @analyze_only.include?(path) }
+          files |= [@buffer.logical_path] if @buffer && @analyze_only.include?(@buffer.logical_path)
+          return files
+        end
         return files if @buffer.nil?
 
+        # Editor mode option A — no closure, so the buffer's single logical path IS the analyzed set.
         [@buffer.logical_path]
       end
 
@@ -1023,8 +1083,12 @@ module Rigor
       # The cross-file pre-pass tables {#seed_project_scope} applies, as a plain Hash so the fork-pool path
       # can hand the same seed to its {WorkerSession} (whose per-file scopes would otherwise miss every
       # cross-file def — ADR-15 sequential-equivalence contract).
+      #
+      # Issue #260 — an opt-in `discovery_seed:` is the BASE of the result, so every table this run computed
+      # for itself still wins. Under `prebuilt:` (the only caller that passes one today) the run computes
+      # none, so the seed applies wholesale.
       def project_scope_seed_tables
-        tables = {}
+        tables = discovery_seed_base
         # ADR-84 WD2 — the run-scope token rides the same seed so the fork/Ractor `WorkerSession` scopes
         # bucket identically to the sequential path.
         tables[:run_generation] = @run_generation if @run_generation
@@ -1055,6 +1119,13 @@ module Rigor
         tables
       end
 
+      # Issue #260 — the mutable starting point {#project_scope_seed_tables} fills in: a copy of the opt-in
+      # `discovery_seed:` when one was supplied, otherwise the empty Hash every other run has always started
+      # from. Extracted so the seed costs {#project_scope_seed_tables} no branch of its complexity budget.
+      def discovery_seed_base
+        @discovery_seed ? @discovery_seed.dup : {}
+      end
+
       # ADR-46 — seed the instance + singleton `"path:line"` def-source tables (each only when non-empty).
       # Extracted to keep {#project_scope_seed_tables} under the complexity budget. The singleton table (slice 4
       # extension) rides the same seed so a pooled `WorkerSession` records singleton symbol edges identically.

data/lib/rigor/analysis/severity_stamp.rb

@@ -35,7 +35,8 @@ module Rigor
         Diagnostic.new(
           path: diagnostic.path, line: diagnostic.line, column: diagnostic.column,
           message: diagnostic.message, severity: resolved, rule: diagnostic.rule,
-          source_family: diagnostic.source_family
+          source_family: diagnostic.source_family, receiver_type: diagnostic.receiver_type,
+          method_name: diagnostic.method_name, project_definition_site: diagnostic.project_definition_site
         )
       end
     end

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