rigortype 0.4.2 → 0.4.3

data/lib/rigor/analysis/run_stats.rb

@@ -24,18 +24,31 @@ module Rigor
     # `class_decl_paths` (a frozen `Hash<String, String>` populated once per environment by the RBS loader;
     # ~1000-2000 entries × one `String#start_with?`).
     class RunStats
-      attr_reader :wall_seconds, :peak_rss_bytes,
+      attr_reader :wall_seconds,
                   :target_files,
                   :rbs_classes_total, :rbs_classes_project_sig, :rbs_classes_bundled,
                   :gem_walk_classes, :gem_walk_gems, :rbs_attribution_available
 
-      def initialize(wall_seconds:, peak_rss_bytes:, # rubocop:disable Metrics/ParameterLists
+      # The live probe a run's summary uses: reads this process's RSS when first asked. The probe is a constant
+      # lambda, so the RunStats it rides on never captures the Runner (and its analysis state) through `Result`.
+      CURRENT_PROCESS_PEAK_RSS = Ractor.make_shareable(-> { RunStats.peak_rss_bytes })
+
+      # Issue #1529 — the peak RSS is read on the first {#peak_rss_bytes} call, not when the summary is built. A run
+      # that prints no summary (`--incremental` recheck, `--no-stats`) therefore never forks `ps` or reads `/proc`.
+      # The read stays in this process: the summary is built and printed by the process that ran the analysis.
+      #
+      # @param peak_rss_bytes — a value to report directly (specs, or a caller that already read it). Ignored when
+      #   `peak_rss_probe:` is given.
+      # @param peak_rss_probe — a zero-argument callable returning the RSS in bytes, called at most once, lazily.
+      def initialize(wall_seconds:, # rubocop:disable Metrics/ParameterLists
                      target_files:,
                      rbs_classes_total:, rbs_classes_project_sig:, rbs_classes_bundled:,
                      gem_walk_classes:, gem_walk_gems:,
-                     rbs_attribution_available: true)
+                     rbs_attribution_available: true, peak_rss_bytes: nil, peak_rss_probe: nil)
         @wall_seconds = wall_seconds
-        @peak_rss_bytes = peak_rss_bytes
+        @peak_rss_probe = peak_rss_probe || -> { peak_rss_bytes }
+        # A frozen RunStats cannot memoise into an ivar, so the first read lands in this (unfrozen) Hash.
+        @peak_rss_memo = {}
         @target_files = target_files
         @rbs_classes_total = rbs_classes_total
         @rbs_classes_project_sig = rbs_classes_project_sig
@@ -46,6 +59,15 @@ module Rigor
         freeze
       end
 
+      # The peak RSS in bytes, read once on first call and memoised (nil when no route answers). The check command
+      # forces the first call straight after the analysis (#1529), before `--coverage` or any output, so the figure
+      # covers the analysis alone. On Linux it is the kernel's VmHWM high-water mark, so a later read is never below
+      # the run-end value. On macOS it is `ps`'s current RSS, so the reading is the process as it stood at that
+      # first call, not a high-water mark.
+      def peak_rss_bytes
+        @peak_rss_memo.fetch(:value) { @peak_rss_memo[:value] = @peak_rss_probe.call }
+      end
+
       # Reports the process's resident set size in bytes. Source ordering: `/proc/self/status` (Linux — reads
       # `VmHWM:`, the peak RSS the kernel records) first; otherwise `ps -o rss= -p <pid>` (macOS / BSD —
       # reports CURRENT RSS, the closest universally-available proxy). Returns nil when neither route works
@@ -146,7 +168,7 @@ module Rigor
         end
         out.puts("#{prefix}Process")
         out.puts("#{prefix}  Wall time:   #{Kernel.format('%.2fs', @wall_seconds)}")
-        out.puts("#{prefix}  Memory peak: #{format_bytes(@peak_rss_bytes)}")
+        out.puts("#{prefix}  Memory peak: #{format_bytes(peak_rss_bytes)}")
       end
 
       def to_h
@@ -159,7 +181,7 @@ module Rigor
           gem_walk_classes: @gem_walk_classes,
           gem_walk_gems: @gem_walk_gems,
           wall_seconds: @wall_seconds,
-          peak_rss_bytes: @peak_rss_bytes
+          peak_rss_bytes: peak_rss_bytes
         }
       end
 

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

@@ -128,7 +128,32 @@ module Rigor
               source_family: :builtin
             )
           end
-          not_found + Array(pre_eval_diagnostics_from_scanner).map { |hash| diagnostic_from_hash(hash) }
+          scanned = Array(pre_eval_diagnostics_from_scanner).map { |hash| diagnostic_from_hash(hash) }
+          suppress_pre_eval(not_found + scanned)
+        end
+
+        # The ordinary suppression pipeline for the `pre-eval.*` rows: the `# rigor:disable` /
+        # `# rigor:disable-file` comments of the file a row is positioned in (a `pre_eval:` file need not be
+        # under `paths:`, so its comments are read here rather than by per-file analysis) and the project's
+        # `disable:` list. A row positioned at `.rigor.yml` has no Ruby comments (`.yml` is skipped) and answers to
+        # `disable:` only.
+        # Stream order is the output contract, so survivors are picked out of the original sequence.
+        def suppress_pre_eval(diagnostics)
+          kept = diagnostics.group_by(&:path).flat_map do |path, group|
+            CheckRules.filter_suppressed(
+              group, comments: pre_eval_comments(path), disabled_rules: @configuration.disabled_rules
+            )
+          end
+          kept_ids = kept.to_set(&:object_id)
+          diagnostics.select { |diagnostic| kept_ids.include?(diagnostic.object_id) }
+        end
+
+        def pre_eval_comments(path)
+          return [].freeze unless File.file?(path) && !path.end_with?(".rbs", ".yml", ".yaml")
+
+          Prism.parse_file(path).comments
+        rescue StandardError
+          [].freeze
         end
 
         def diagnostic_from_hash(hash)

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

@@ -46,7 +46,7 @@ module Rigor
                        synthetic_method_index:, project_patched_methods:,
                        analyze_file:, project_scope_seed: -> { {} }, record_dependencies: false,
                        restored_run_level_rows: nil, template_units: -> { TemplateUnits.empty },
-                       feature_sources: -> { {} })
+                       feature_sources: -> { {} }, plugin_prepare: -> { [[], []] })
           @configuration = configuration
           @cache_store = cache_store
           @explain = explain
@@ -84,6 +84,10 @@ module Rigor
           # inherits the same compiled bytes.
           @template_units_reader = template_units
           @analyze_file = analyze_file
+          # Issue #1541 — `() -> [rows, disclosure records]`, a `#prepare` run on a throwaway registry. Read
+          # only by {#serve_empty_closure}: a pooled run's `#prepare` happens inside its workers, and an
+          # empty closure dispatches none.
+          @plugin_prepare = plugin_prepare
           # Issues #796 / #794 — the previous full run's run-level rows, handed down by
           # {Analysis::IncrementalSession} on a NARROWED run only (a recheck's closure, a
           # `--verify-incremental` partition). A full run leaves this nil and derives everything itself.
@@ -146,10 +150,8 @@ module Rigor
         #   (`expansion.fetch(:files)`), independent of any `analyze_only` narrowing of `files`; see
         #   {#serve_empty_closure} for what an empty `files` does with it.
         def analyze_files(files, environment: nil, project_files: nil)
-          if files.empty?
-            serve_empty_closure(environment, project_files)
-            return []
-          end
+          return serve_empty_closure(environment, project_files) if files.empty?
+
           # Issue #784 / #793 — `files` is what this run ANALYSES; `source_files` is what its environment
           # is BUILT over, and the two are the same only on a full run. A narrowed run (`analyze_only`: an
           # incremental closure, a `--verify-incremental` partition) used to build its environment over the
@@ -199,7 +201,16 @@ module Rigor
         #   whether anyone could have demanded anything at all: with no files, nobody could have, and an
         #   empty project keeps paying no env build. Keyed on the project's files rather than on
         #   `analyze_only`, because a recheck over an EMPTY project narrows to `Set[]`, which is non-nil.
+        #
+        # Issue #1541 — and, in pool mode, its `prepare` rows. A pooled run's `#prepare` happens inside the
+        # workers and its rows reach the stream through their first payload, so the coordinator-side
+        # pre-pass skips it ({ProjectPrePasses#run}) and {DiagnosticAggregator#pre_file_diagnostics} omits
+        # the cached rows; with no worker dispatched the row appeared nowhere, and a plugin whose `#prepare`
+        # raises turned a red project green on a nothing-changed `--incremental --workers N` recheck. They
+        # are returned as the run's per-file stream head, where the pool path puts them (`.rigor.yml`).
+        # Sequential, whose pre-pass already ran `#prepare`, returns no rows here.
         def serve_empty_closure(environment, project_files)
+          prepare_rows = pool_mode? ? pooled_prepare_rows : []
           env = environment || @environment_override
           # Resolved over the project's OWN file list — not `[]`, which would drop every plugin-synthesized
           # virtual RBS (`Environment.collect_virtual_rbs` short-circuits on an empty list) and scan a
@@ -217,9 +228,16 @@ module Rigor
           # `env` rather than `resolve.call`: read the demand the snapshots above just made when they built
           # an environment, and force nothing when they did not.
           record_definition_build_failures(env&.rbs_loader&.definition_build_failures)
-          return if replayed_restored_run_level_rows?
+          record_hkt_scan_failure(hkt_scan_outcome(resolve.call)) unless replayed_restored_run_level_rows?
+          prepare_rows
+        end
 
-          record_hkt_scan_failure(hkt_scan_outcome(resolve.call))
+        # Issue #1541 — the pooled empty closure's `#prepare`: the rows go to the caller, the run-scoped
+        # registrations into the table the workers' payloads would have filled.
+        def pooled_prepare_rows
+          rows, records = @plugin_prepare.call
+          merge_run_disclosures(records)
+          Array(rows)
         end
 
         # Issue #794 — the signature-state snapshot's own gates, asked BEFORE an environment exists. Every
@@ -700,8 +718,9 @@ module Rigor
         # Issue #1051, known exception: run-scoped disclosures a plugin registered from `#prepare` are NOT
         # recovered here — nor, since #1060, a positioned `#emit_once` batch registered there, which rides
         # the same table. There is no session to drain — this backend builds none on the coordinator — and
-        # `#prepare` deliberately does not run on the coordinator-side registry under pool mode, so a
-        # prepare-time disclosure lives only inside the Ractor that died with it. A disclosure registered
+        # `#prepare` does not run on the coordinator-side registry under pool mode (only an empty closure
+        # runs it, on a throwaway registry; see {#serve_empty_closure}), so a prepare-time disclosure lives
+        # only inside the Ractor that died with it. A disclosure registered
         # from `#diagnostics_for_file` IS recovered, because the re-analysis below runs the coordinator-side
         # plugin instances that {DiagnosticAggregator#plugin_run_disclosure_diagnostics} reads directly.
         # Left as is: recovering the rest means running `#prepare` on the coordinator registry, which would

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

@@ -59,7 +59,7 @@ module Rigor
           :unpositioned_mixins, :discovered_class_sources, :constant_values, :constant_sources, :constant_writes,
           :discovered_method_visibilities, :discovered_methods, :discovered_parameter_envelopes, :data_member_layouts,
           :struct_member_layouts, :discovered_deferred_ranges, :discovered_refinements, :siblings,
-          :discovered_global_write_census
+          :discovered_global_write_census, :singleton_class_sources
         )
 
         # Internal: drives every EAGER project-wide pre-pass — the ones whose products feed the RBS
@@ -175,6 +175,8 @@ module Rigor
             # object's `extend`s reach `Narrowing` from a sibling file the way its `include`s already do.
             discovered_extends: def_index.fetch(:extends), unpositioned_mixins: def_index.fetch(:unpositioned_mixins),
             discovered_class_sources: def_index.fetch(:class_sources),
+            # Issue #1752 — the files opening `class << Const`, for the class-declaration diff alone.
+            singleton_class_sources: def_index.fetch(:singleton_class_sources, {}),
             # Issue #644 — the cross-file value-constant publication table and its write attribution.
             constant_values: def_index.fetch(:constant_values), constant_sources: def_index.fetch(:constant_sources),
             constant_writes: def_index.fetch(:constant_writes),
@@ -251,6 +253,24 @@ module Rigor
           registry
         end
 
+        # Issue #1541 — what a pooled run's workers would have produced from `#prepare`, for the coordinator's
+        # empty-closure branch, which dispatches none: the `#prepare` error rows and the run-scoped
+        # registrations (`#disclose_once` / `#emit_once`) made there. It runs on a THROWAWAY registry, so
+        # nothing `#prepare` records on a plugin instance (a trust refusal, say) reaches the coordinator-side
+        # instances {DiagnosticAggregator} reads — a pooled cold run never shows those either.
+        # Returns the rows first, then the disclosure records.
+        def prepare_throwaway_registry
+          registry = load_plugins
+          rows = plugin_prepare_diagnostics(registry)
+          records = registry.plugins.flat_map do |plugin|
+            plugin_id = safe_plugin_id(plugin)
+            Array(plugin.run_disclosure_records).map { |record| record.merge(plugin_id: plugin_id) }
+          rescue StandardError
+            []
+          end
+          [rows, records]
+        end
+
         # Returns the per-run shared `Plugin::FactStore` instance. All loaded plugins share this store
         # through their respective `Plugin::Services` (the same instance is threaded by
         # `Plugin::Loader.load`). Returns `nil` when no plugins are loaded.

data/lib/rigor/analysis/runner.rb

@@ -297,8 +297,13 @@ module Rigor
                      record_dependencies: false, record_self_calls: false, analyze_only: nil,
                      seed_bundles: nil, collect_seed_bundles: false, param_inferred_types: nil,
                      discovery_seed: nil, no_tolerated_effects: false,
-                     restored_run_level_rows: nil, served_per_file_diagnostics: nil)
+                     restored_run_level_rows: nil, served_per_file_diagnostics: nil, on_file_indexed: nil)
         @configuration = configuration
+        # ADR-113 WD2 — `rigor lens` reads a target's seeded index here: called with `(path, parse_result, scope,
+        # index)` for every file this process indexes, after its rules ran and inside the run window, so the reader
+        # sees what `check` saw. A pooled file is indexed in a worker and never reaches it; the incremental session
+        # analyses forced targets with `workers: 0` for that reason.
+        @on_file_indexed = on_file_indexed
         # Issues #796 / #794 — the previous full run's run-level rows, supplied only by
         # {IncrementalSession} on a narrowed run; see {PoolCoordinator#replay_restored_run_level_rows}.
         @restored_run_level_rows = restored_run_level_rows
@@ -431,6 +436,7 @@ module Rigor
         # Issue #1367 — the project's `Inference::GlobalWriteCensus`, which the `global.*` write rules read.
         @project_discovered_global_write_census = Set.new.freeze
         @project_discovered_class_sources = {}.freeze
+        @project_singleton_class_sources = {}.freeze
         # Issue #644 — the cross-file VALUE-constant publication table (`{qualified name => Type::Constant}`,
         # literal writes only) and its per-name write attribution. The first seeds `in_source_constants` on
         # every per-file scope so `FOO = :sym` in one file reads as `:sym` in another; the second seeds
@@ -648,8 +654,8 @@ module Rigor
       # subclasses (`subclass_of:<last segment>`).
       def class_declarations
         result = Hash.new { |hash, key| hash[key] = Set.new }
-        @project_discovered_class_sources.each do |class_name, files|
-          files.each { |file| result[file] << class_name }
+        [@project_discovered_class_sources, @project_singleton_class_sources].each do |sources|
+          sources.each { |class_name, files| files.each { |file| result[file] << class_name } }
         end
         Incremental.add_superclass_edges(result, @project_discovered_class_sources, @project_discovered_superclasses)
         result.transform_values(&:freeze).freeze
@@ -1748,6 +1754,8 @@ module Rigor
         @project_discovered_prepends = discovery.discovered_prepends
         @project_discovered_extends = discovery.discovered_extends
         @project_unpositioned_mixins = discovery.unpositioned_mixins
+        # Issue #1752 — the files that open `class << Const`, read only by {#class_declarations}.
+        @project_singleton_class_sources = discovery.singleton_class_sources
       end
 
       # Internal: builds the deferred cross-file discovery tables at most once per run and adopts them.
@@ -1804,10 +1812,8 @@ module Rigor
       # the pre-pass then saw two writers for every constant a file declares and withheld its publication (#644),
       # and every file was a discovered-not-analysed dependency of the run's cache entry.
       #
-      # The widening decision itself still compares the paths as spelled. `exclude:` patterns match a path as it
-      # is spelled, so until #1576 is fixed the configured absolute `lib` can discover files the argument `lib`
-      # excludes (a relative `lib/gen/**` pattern never matches `/abs/lib/gen/x.rb`), and treating the two as the
-      # same root would drop those files from discovery.
+      # The widening decision itself compares the paths as spelled. `exclude:` patterns apply to both spellings
+      # alike (#1576), so the configured absolute `lib` and the argument `lib` exclude the same files.
       def project_discovery_expansion(paths, expansion)
         return nil unless widen_discovery_to_project?(paths)
 
@@ -2017,7 +2023,8 @@ module Rigor
           template_units: -> { template_units },
           analyze_file: ->(path, environment) { analyze_file(path, environment) },
           restored_run_level_rows: @restored_run_level_rows,
-          feature_sources: -> { required_feature_sources }
+          feature_sources: -> { required_feature_sources },
+          plugin_prepare: -> { @pre_passes.prepare_throwaway_registry }
         )
         @diagnostic_aggregator = DiagnosticAggregator.new(
           configuration: @configuration,
@@ -2063,7 +2070,8 @@ module Rigor
         )
         RunStats.new(
           wall_seconds: Process.clock_gettime(Process::CLOCK_MONOTONIC) - wall_started_at,
-          peak_rss_bytes: RunStats.peak_rss_bytes,
+          # Issue #1529 — read lazily on the summary's first use, so a run that prints none never forks for it.
+          peak_rss_probe: RunStats::CURRENT_PROCESS_PEAK_RSS,
           # #392 — the template units count too: they are files this run parsed and typed, and a stats line
           # that omitted them would under-report exactly the work a views-heavy project added.
           target_files: expansion.fetch(:files).size + template_units.paths.size,
@@ -2176,7 +2184,8 @@ module Rigor
         bad = []
         Array(paths).each do |path|
           if File.directory?(path)
-            files.concat(PathExpansion.directory_files(path, @configuration.exclude_patterns))
+            files.concat(PathExpansion.directory_files(path, @configuration.exclude_patterns,
+                                                       base: @configuration.exclude_base))
           # Editor-mode bypass: the buffer's logical path is treated as a real `.rb` file regardless of
           # on-disk presence — `parse_source` reads bytes from the buffer's physical path. Common case: LSP
           # client editing a brand-new file.
@@ -2591,10 +2600,11 @@ module Rigor
         # the rule is active or `record_self_calls:` opted in.
         index = nil
         self_call_record = with_self_call_recording(path) do
-          index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
+          index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope, widen_clauses: true)
         end
         self_call_misses = self_call_record ? self_call_record.calls : []
         diagnostics = rule_and_plugin_diagnostics(path, parse_result, scope, index, self_call_misses)
+        notify_file_indexed(path, parse_result, scope, index)
         diagnostics + explain_diagnostics(path, parse_result.value, scope)
       rescue Errno::ENOENT => e
         [
@@ -2618,6 +2628,14 @@ module Rigor
         ]
       end
 
+      # ADR-113 WD2 — the `on_file_indexed` observer. It reads; an error inside it never changes this file's
+      # diagnostics, so it is contained here rather than reaching {#analyze_file_body}'s crash row.
+      def notify_file_indexed(path, parse_result, scope, index)
+        @on_file_indexed&.call(path, parse_result, scope, index)
+      rescue StandardError
+        nil
+      end
+
       # ADR-53 B4 — the built-in node collectors and the plugin node rules share ONE traversal of the file.
       # The collectors are built here (they need the completed `index`) and populated by the converged
       # plugin walk; `node_results` carries the per-plugin node-rule output. Both the built-in `diagnose`

data/lib/rigor/analysis/worker_session.rb

@@ -228,7 +228,7 @@ module Rigor
         scope = @template_units.seed(
           seed_project_scope(Scope.empty(environment: @environment, source_path: path)), path
         )
-        index = Inference::ScopeIndexer.index(root, default_scope: scope)
+        index = Inference::ScopeIndexer.index(root, default_scope: scope, widen_clauses: true)
         # ADR-53 B4 — built-in collectors + plugin node rules share one walk.
         node_collectors = CheckRules.build_node_collectors(path, index, root)
         node_results = node_rule_results_by_plugin(path, root, scope, node_collectors, index)

data/lib/rigor/cache/engine_source.rb

@@ -59,6 +59,19 @@ module Rigor
       # `apps/` and `tool/` are not loaded by an analysis and stay out.
       SOURCE_DIRECTORIES = %w[lib plugins].freeze
 
+      # Engine DATA the analysis reads at runtime, relative to the gem root (issue #1492). A data edit moves
+      # diagnostics as surely as a `lib/` edit, yet the caches that key only on `signature_paths` plus this
+      # digest (the `--incremental` snapshot fingerprint, `Protection::MutationCache`) see nothing else.
+      #
+      # - YAML: `data/builtins` (`MethodCatalog::DATA_ROOT`) and `data/effects` (`Effects::Catalog`,
+      #   `Effects::Registry`).
+      # - RBS: every `.rbs` under `data/` (`core_overlay`, `vendored_gem_sigs`, `capability_roles`,
+      #   `gem_overlay`) plus each bundled plugin's `plugins/*/sig`. `RbsDescriptor` digests the same files
+      #   into the run-result and env caches, but those are the only two consumers that do.
+      #
+      # Tooling-only trees (`data/oss-sweep`) are not read by an analysis and stay out.
+      DATA_GLOBS = %w[data/builtins/**/*.yml data/effects/**/*.yml data/**/*.rbs plugins/*/sig/**/*.rbs].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.
@@ -153,8 +166,9 @@ module Rigor
         !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.
+      # A SHA-256 over every engine `.rb` file and {DATA_GLOBS} data 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.
@@ -178,12 +192,12 @@ module Rigor
         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.
+      # Sorted, de-duplicated absolute paths of every engine `.rb` file and {DATA_GLOBS} data file, across
+      # the directories that exist. `plugins/*/sig/**/*.rbs` overlaps nothing else but is de-duplicated anyway.
       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
+        sources = SOURCE_DIRECTORIES.flat_map { |relative| Dir.glob(File.join(root, relative, "**", "*.rb")) }
+        data = DATA_GLOBS.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }
+        (sources + data).uniq.sort
       end
     end
   end

data/lib/rigor/cache/incremental_snapshot.rb

@@ -260,7 +260,11 @@ module Rigor
       # {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:)
+      #
+      # Issue #1533 — `explain:` is the run's `--explain` flag. It adds `:info` rows to the per-file diagnostics
+      # the snapshot caches, so a snapshot written without it holds none and one written with it holds rows a
+      # plain run must not print. No part for the default, so every plain run's fingerprint is as it was.
+      def self.fingerprint(configuration:, roots:, explain: false)
         bundler_lock, collection_lock = Analysis::RunCacheKey.resolved_lockfile_paths(configuration)
         parts = [
           "engine:#{Rigor::VERSION}:#{SCHEMA}",
@@ -279,14 +283,11 @@ module Rigor
         # dependency edge records, so the whole snapshot goes. Scanned over the configured paths plus the roots'
         # files, the set the run's environment scans; no part when nothing is required, so every other
         # project's fingerprint is as it was.
-        features = Environment::RequiredFeatures.for_configuration(
-          configuration, Analysis::PathExpansion.ruby_files(roots, configuration.exclude_patterns)
-        )
+        features = required_features(configuration, roots)
         parts << "required-features:#{features.join(',')}" unless features.empty?
         # ADR-116 WD5 — the snapshot's per-file rows and seed bundles are only as checked as the run that
         # wrote them ({Inference::DeclarationWalk::Shadow}); nil with the harness off adds no part.
-        shadow = Analysis::ShadowHarness.cache_identity
-        parts << "shadow-harness:#{shadow}" if shadow
+        parts.concat(run_mode_parts(explain))
         Digest::SHA256.hexdigest(parts.join("\x00"))
       rescue StandardError
         # {EngineSource::Unavailable} lands here too, and nil is the answer it requires rather than one it
@@ -297,6 +298,12 @@ module Rigor
         nil
       end
 
+      def self.required_features(configuration, roots)
+        files = Analysis::PathExpansion.ruby_files(roots, configuration.exclude_patterns,
+                                                   base: configuration.exclude_base)
+        Environment::RequiredFeatures.for_configuration(configuration, files)
+      end
+
       # ADR-10 slice 3, issue #1814 — the walked gems' versions: their method catalogue, their refinement table and the
       # constants they bind reach every file's checks, and the lockfile digest above does not cover a project with none.
       # No part for a project that lists no gem, so its fingerprint is what it was.
@@ -314,6 +321,15 @@ module Rigor
       end
       private_class_method :digest_file_if_present
 
+      # The parts naming how the run was asked to behave rather than what it reads: the ADR-116 WD5 shadow harness
+      # (the snapshot's rows are only as checked as the run that wrote them; nil with the harness off) and
+      # `--explain` (#1533).
+      def self.run_mode_parts(explain)
+        shadow = Analysis::ShadowHarness.cache_identity
+        [("shadow-harness:#{shadow}" if shadow), ("explain:true" if explain)].compact
+      end
+      private_class_method :run_mode_parts
+
       # Content-digest every `pre_eval:` file in configuration order, so an edit to one invalidates the snapshot
       # even when it lies outside the analysed paths. A missing file digests as "absent", so creating it counts too.
       def self.digest_pre_eval(paths)
@@ -346,8 +362,20 @@ module Rigor
       end
       private_class_method :digest_signature_paths
 
-      def initialize(root:)
-        @path = File.join(root.to_s, "incremental", "snapshot.bin")
+      # Issue #1867 — one snapshot FILE per fingerprint mode. A run whose fingerprint carries run-mode parts
+      # (`--explain`, the ADR-116 shadow harness) keeps its own file so it neither reads nor overwrites the
+      # plain run's warm snapshot, and the reverse. The plain file name is unchanged. The fingerprint still
+      # carries the mode parts, so the files never cross-serve.
+      def initialize(root:, explain: false)
+        @path = File.join(root.to_s, "incremental", self.class.file_name(explain: explain))
+      end
+
+      # `snapshot.bin` for a plain run; `snapshot-<mode digest>.bin` when {run_mode_parts} is non-empty.
+      def self.file_name(explain: false)
+        parts = run_mode_parts(explain)
+        return "snapshot.bin" if parts.empty?
+
+        "snapshot-#{Digest::SHA256.hexdigest(parts.join("\x00"))[0, 12]}.bin"
       end
 
       attr_reader :path