rigortype 0.3.6 → 0.3.8

data/lib/rigor/analysis/crash_signature.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # Issues #665 / #674 / #683 / #686 / #696 — the ONE definition of "an internal failure made this run
+    # report less than it should have".
+    #
+    # Every member of that family shares a defect: the run still exits 0 and its diagnostic list still
+    # looks like an answer, so an absence assertion (`not_to include(...)`, `be_empty`, `all(eq(...))`)
+    # holds on it and a comparison of two such runs (`baseline == mutant`, `recheck == full_run`) reports
+    # "no difference" — because both sides carry the same synthetic row, not because the code agreed. Four
+    # separate consumers needed to recognise these shapes, and before this module each recognised them by
+    # matching a diagnostic MESSAGE with its own string literal. A fourth copy is what this exists to stop:
+    # a reworded message silently disarms whichever copies were not updated, and nothing goes red.
+    #
+    # ## The three shapes
+    #
+    # - `:check_rule` — message begins `internal analyzer error`, `rule: nil`. Built by
+    #   `Runner#analyze_file_body` / `WorkerSession#analyze_body`'s `rescue StandardError`.
+    # - `:plugin` — `severity: :error`, `source_family: :plugin_loader`, `rule: "runtime-error"`. Built by
+    #   `Runner#collect_plugin_diagnostics` / `Runner::ProjectPrePasses#invoke_plugin_prepare`.
+    # - `:rbs_build` — `rule` in {RBS_BUILD_FAILURE_RULES}. Recorded by `Environment::RbsLoader`'s
+    #   env-build and definition-build rescues, surfaced by {Runner::DiagnosticAggregator}.
+    #
+    # The `:plugin` shape is keyed on the structured `(severity, source_family, rule)` triple rather than on
+    # the bare rule name: a plugin is free to define its OWN `"runtime-error"` (or `"load-error"`) under its
+    # own `source_family: "plugin.<id>"`, and several specs legitimately assert on one. Only the
+    # `:plugin_loader` family paired with `"runtime-error"` is the isolation envelope's own row.
+    #
+    # ## Only ONE shape discards a file's analysis
+    #
+    # {.discards_file_analysis?} answers true for `:check_rule` alone, and the distinction is not pedantry —
+    # it decides whether a consumer may still read the run's diagnostics.
+    #
+    # - `:check_rule` — `Runner#analyze_file_body` rescues around the WHOLE per-file body, so what comes
+    #   back is `[crash_row]` and every diagnostic that file would have produced is gone. Nothing is left to
+    #   read.
+    # - `:plugin` — `collect_plugin_diagnostics` replaces only the raising PLUGIN's contribution;
+    #   `CheckRules.diagnose` has already returned, and `invoke_plugin_prepare` adds one row at `.rigor.yml`
+    #   and lets the run proceed. The builtin rules ran, and their diagnostics are all still there. A
+    #   consumer that refuses the whole run over this throws away a real measurement — and because the
+    #   prepare row is appended to every sequential run, it would refuse every run for the life of the
+    #   process.
+    # - `:rbs_build` — the analysis ran to completion and every rule fired, over a type universe missing one
+    #   class (`rbs.coverage.definition-build-failed`), all of them
+    #   (`rbs.coverage.environment-build-failed`), or only the HKT registrations the `type` aliases and the
+    #   loaded plugins' manifests would have contributed (`rbs.coverage.hkt-scan-failed`, issues #784 and
+    #   #791). The first two are degradations
+    #   the user causes and the diagnostic itself reports; a project can sit on one for a release while it
+    #   fixes its `sig/`. The third is NOT the user's: post-#783 the scan raising is an analyzer defect, and
+    #   the overlay stage is a defect in Rigor or in a plugin the user installed, never in their `sig/`. It
+    #   still belongs here rather than under `:check_rule`, because the question this classification
+    #   answers is "may a consumer still read the run's diagnostics?" — and it may: every rule fired. What
+    #   differs is whether the run is a valid measurement OF RIGOR, which is {.analyzer_defect?}'s question.
+    #
+    # The two consumer tiers therefore differ on purpose. The ADR-69 kill oracles arm `:check_rule` only:
+    # refusing a run they could still have measured is the same "manufactures work" error as scoring an
+    # unmeasured mutant a survivor, pointed the other way (issue #686 review). The spec harness additionally
+    # arms `:plugin`, which is suite POLICY rather than a claim about the diagnostics — no spec has a reason
+    # to want a plugin crashing under it, and `allow_plugin_crash:` is the opt-out for the handful whose
+    # subject IS the isolation envelope.
+    module CrashSignature
+      # The `rescue StandardError` in `Runner#analyze_file_body` / `WorkerSession#analyze_body` folds a
+      # raising check rule (or a plugin's node-rule contribution) into ONE diagnostic per file with this
+      # message prefix. Matched on the prefix alone, exactly as the pre-#696 guards did: adding a `rule.nil?`
+      # conjunct would NARROW the match, and the whole point of a guard against a bug is that it stays armed
+      # when the shape shifts.
+      CHECK_RULE_MESSAGE_PREFIX = "internal analyzer error"
+
+      PLUGIN_SOURCE_FAMILY = :plugin_loader
+      PLUGIN_RULE = "runtime-error"
+
+      # The `rbs.coverage.*` rules that mean declared types went missing from this run — the implicit-HKT
+      # scan over `type` aliases (#784), a per-class definition build (#696), and the env-wide collapse.
+      # Ordered widest consequence last, the way the rows sit in `docs/type-specification/diagnostic-policy.md`.
+      RBS_BUILD_FAILURE_RULES = %w[
+        rbs.coverage.hkt-scan-failed
+        rbs.coverage.definition-build-failed
+        rbs.coverage.environment-build-failed
+      ].freeze
+
+      # The one reason that means a file's whole diagnostic list was replaced by a crash row. `:plugin` and
+      # `:rbs_build` both leave a readable run behind — see the class doc.
+      DISCARDS_FILE_ANALYSIS_REASON = :check_rule
+
+      # The `:rbs_build` rules whose cause is Rigor, not the user's `sig/` (issue #784). Readable for the
+      # user — every rule fired — but NOT a valid measurement of Rigor itself, so a harness that scores
+      # Rigor's behaviour should treat one of these as a crash finding the way it treats `:check_rule`, or
+      # a mutant that re-breaks the HKT scan (#776 was one) scores as a measurement over a silently degraded
+      # universe. What consults it today: `tool/mutation`'s fuzz crash detector — on the severity-resolved
+      # stream, so a `severity_overrides: rbs: off` hides the row from it. What does NOT yet: the ADR-69
+      # kill oracle (`Protection::AnalysisGuard` reads `Result#crashed?`, which excludes every
+      # `:rbs_build` row), and both harnesses still reuse one Environment across mutants, which memoises
+      # the degraded registry after the first defect. Arming the oracle, inspecting the pre-severity row,
+      # and resetting the Environment are issue #790.
+      ANALYZER_DEFECT_RULES = %w[
+        rbs.coverage.hkt-scan-failed
+      ].freeze
+
+      module_function
+
+      # The message `Runner#analyze_file_body` / `WorkerSession#analyze_body` fold a raised `StandardError`
+      # into. Built here, not at either rescue site, so the two twins cannot drift (issue #665) — and so
+      # the appended crash frame is derived identically on the sequential and pooled paths. Keeps the
+      # {CHECK_RULE_MESSAGE_PREFIX} prefix every consumer matches on; the frame is a trailing hint.
+      #
+      # @param error [StandardError]
+      # @return [String]
+      def check_rule_message(error)
+        base = "#{CHECK_RULE_MESSAGE_PREFIX}: #{error.class}: #{error.message}"
+        frame = crash_frame(error)
+        frame ? "#{base} (#{frame})" : base
+      end
+
+      # The first `lib/rigor/` backtrace frame — the raise site, path made repo-relative so it reads the
+      # same whether Rigor runs from a checkout or an installed gem. A LOCATION, not an attribution: a
+      # bundled or third-party plugin also lives under `lib/rigor/<plugin>/`, so a frame here says where
+      # the raise was, never whose defect it is. Falls back to the raw top frame when the crash is entirely
+      # inside a dependency, and to nil when there is no backtrace at all.
+      #
+      # @param error [Exception]
+      # @return [String, nil]
+      def crash_frame(error)
+        frames = error.backtrace
+        return nil if frames.nil? || frames.empty?
+
+        relativize_frame(frames.find { |f| f.include?("/lib/rigor/") } || frames.first)
+      end
+
+      # The repo-relative half of {.crash_frame}, pulled out on its own so a second caller — the #784
+      # `rbs.coverage.hkt-scan-failed` diagnostic, which stores its raw frame across a `Marshal` boundary
+      # (the fork pool) rather than deriving it fresh from a live `Exception` — can relativize the frame it
+      # already has without re-deriving `.crash_frame`'s "which frame" choice. Nil-safe, and a no-op (`sub`
+      # never matches) on a frame with no `lib/rigor/` segment at all.
+      #
+      # @param frame [String, nil]
+      # @return [String, nil]
+      def relativize_frame(frame)
+        frame&.sub(%r{\A.*/(lib/rigor/)}, '\1')
+      end
+
+      # @param diagnostic [Rigor::Analysis::Diagnostic]
+      # @return [Symbol, nil] `:check_rule`, `:plugin`, `:rbs_build`, or nil for an ordinary diagnostic.
+      def reason(diagnostic)
+        return :check_rule if diagnostic.message.to_s.start_with?(CHECK_RULE_MESSAGE_PREFIX)
+        return :plugin if plugin_isolation_row?(diagnostic)
+        return :rbs_build if RBS_BUILD_FAILURE_RULES.include?(diagnostic.rule)
+
+        nil
+      end
+
+      # True when `diagnostic` is the rescue row that REPLACED a file's analysis — the only shape after which
+      # the run's diagnostics say nothing about the code. NOT a general "something went wrong" predicate; see
+      # the class doc for why `:plugin` and `:rbs_build` are excluded.
+      #
+      # @param diagnostic [Rigor::Analysis::Diagnostic]
+      def discards_file_analysis?(diagnostic)
+        reason(diagnostic) == DISCARDS_FILE_ANALYSIS_REASON
+      end
+
+      # True when `diagnostic` reports a failure inside Rigor that left the run readable but invalid as a
+      # measurement of Rigor — see {ANALYZER_DEFECT_RULES}. Orthogonal to {.discards_file_analysis?}: the
+      # user-facing tier reads the run; the Rigor-measuring tier should refuse it (the mutation fuzz does,
+      # the ADR-69 kill oracle does not yet — #790).
+      #
+      # @param diagnostic [Rigor::Analysis::Diagnostic]
+      def analyzer_defect?(diagnostic)
+        ANALYZER_DEFECT_RULES.include?(diagnostic.rule)
+      end
+
+      # A one-line "<reason> at <path>:<line>: <message>" for a failure message, so whoever reads the raise
+      # sees which shape fired and where without re-deriving it.
+      #
+      # @param diagnostic [Rigor::Analysis::Diagnostic]
+      # @return [String]
+      def describe(diagnostic)
+        "#{reason(diagnostic) || :unknown} at #{diagnostic.path}:#{diagnostic.line}: #{diagnostic.message}"
+      end
+
+      def plugin_isolation_row?(diagnostic)
+        diagnostic.severity == :error &&
+          diagnostic.source_family == PLUGIN_SOURCE_FAMILY &&
+          diagnostic.rule == PLUGIN_RULE
+      end
+      private_class_method :plugin_isolation_row?
+    end
+  end
+end

data/lib/rigor/analysis/dependency_recorder.rb

@@ -168,9 +168,17 @@ module Rigor
         accumulate_read(accumulator, path, symbol)
       end
 
-      # Records a cross-file lookup of `name` (kind `:method` / `:class` / `:const` / …) that resolved to
-      # nothing — a negative dependency.
-      def read_missing(kind, name)
+      # Records a NAME-KEYED cross-file dependency: this consumer's answer depends on what the project makes
+      # of `name` under `kind`, so a recheck must re-analyze it when that changes. The recorded key is
+      # inverted into `negative_dependents` and matched against the producer for its kind.
+      #
+      # For `:method` / `:class` / `:toplevel` this is recorded only on a MISS ({read_missing}) — a resolved
+      # method or class already carries a positive edge to its definition site, which covers every later
+      # change to it. Issue #644's `:constant` kind is recorded on a HIT as well, because a constant's
+      # published value is a function of the WHOLE project's write set for the name, not of the one file that
+      # currently wins: a second declarer appearing in a file the reader has no edge to must drop the name to
+      # `Dynamic` at that reader, and only a name-keyed edge can see it.
+      def read_name(kind, name)
         accumulator = Thread.current[KEY]
         return if accumulator.nil?
 
@@ -179,6 +187,13 @@ module Rigor
         accumulator.missing.add(entry)
       end
 
+      # The miss-only spelling of {read_name}: a cross-file lookup of `name` (kind `:method` / `:class` /
+      # `:toplevel` / …) that resolved to nothing. Kept as the name the internal spec's negative-edge
+      # contract uses.
+      def read_missing(kind, name)
+        read_name(kind, name)
+      end
+
       # The positive-edge aggregation shared by {read_site} and {replay}.
       def accumulate_read(accumulator, path, symbol)
         accumulator.sources << path

data/lib/rigor/analysis/dependency_source_inference/walker.rb

@@ -139,7 +139,8 @@ module Rigor
         def descend_class_or_module(node, qualified_prefix, in_singleton_class, accumulator, budget)
           name = Source::ConstantPath.qualified_name_or_nil(node.constant_path)
           if name && node.body
-            walk_node(node.body, qualified_prefix + [name], in_singleton_class, accumulator, budget)
+            child_prefix = Source::ConstantPath.declaration_prefix(qualified_prefix, node.constant_path)
+            walk_node(node.body, child_prefix, in_singleton_class, accumulator, budget)
           else
             walk_children(node, qualified_prefix, in_singleton_class, accumulator, budget)
           end

data/lib/rigor/analysis/incremental.rb

@@ -120,6 +120,34 @@ module Rigor
         appeared.freeze
       end
 
+      # Issue #644 — the qualified constant names whose PUBLICATION could have moved in this edit: the names
+      # whose per-file census descriptor differs between the before- and after-state of any file in `paths`.
+      # The value-constant twin of {appeared_classes}, and deliberately NOT its analogue — a class either
+      # exists or does not, whereas a constant's published answer is a function of the whole project's write
+      # set for the name, so a *name* diff is the wrong question. All four ways the answer moves are a
+      # descriptor change and none of them is an appearance:
+      #
+      # - the value edited (`[50]` -> `[7]`),
+      # - the write becoming unpublishable or publishable again (`[50]` <-> `:unpublishable`),
+      # - a SECOND declarer appearing, which drops the name to `Dynamic` (`{}` -> `{NAME => …}` in that file),
+      # - a second declarer going away, which restores the precise answer.
+      #
+      # `paths` MUST therefore include removed files as well as changed and added ones; a removed file's
+      # after-state is simply absent, so its whole before-census counts as changed. Returns a frozen Set of
+      # qualified-name Strings. `before` / `after` map a path to `{name => descriptor}`.
+      def changed_constant_publications(paths, before, after)
+        moved = Set.new
+        paths.each do |path|
+          was = before[path] || {}
+          now = after[path]  || {}
+          # `eql?`, not `==`: `[1] == [1.0]` is TRUE, so `LIMIT = 1` becoming `LIMIT = 1.0` would move the
+          # published type (`Constant[1]` -> `Constant[1.0]`) while this diff called it unchanged. The
+          # declaration signature backstops that case today; the producer must not depend on it.
+          (was.keys | now.keys).each { |name| moved << name unless was[name].eql?(now[name]) }
+        end
+        moved.freeze
+      end
+
       # ADR-46 slice 3 — the consumers to re-check because a name they looked up and *missed* (a negative
       # dependency) now resolves. `keys` is the set of negative-dependency keys (`"toplevel:foo"` /
       # `"method:C#m"`) the appeared symbols would satisfy; `negative_dependents` maps each key to the Set of

data/lib/rigor/analysis/incremental_session.rb

@@ -98,6 +98,10 @@ module Rigor
         @missing = {}              # consumer => Set<"kind:name"> it looked up and missed
         @negative_dependents = {}  # "kind:name" => Set<consumer> (inverted @missing)
         @class_decls = {}          # path => Set<qualified class name declared in the file>
+        # Issue #644 — the value-constant twin: path => { qualified constant name => publication descriptor }.
+        # Diffed on a recheck to find every constant whose PUBLISHED answer could have moved, which satisfies
+        # the `constant:` edges a reader records at every reference, resolved or not.
+        @constant_decls = {}
         # ADR-89 WD2 — per-def observed-key return summaries: [path, symbol] => { keys:, returns:, effects: }.
         # Harvested from the ADR-84 return memo after each run; drives the behavioural-stability gate.
         @return_summaries = {}
@@ -168,7 +172,7 @@ module Rigor
         # ADR-103 WD13 / #382 — a baseline collects every file, so its collections are the whole world.
         @effect_collections = runner.effect_collections_by_path
         @effects_identity = current_effects_identity
-        @cache = per_file(diagnostics)
+        @cache = per_file(runner.per_file_diagnostics)
         @digests = @analyzed.to_h { |path| [path, pack_digest(path)] }
         diagnostics
       end
@@ -198,7 +202,7 @@ module Rigor
         @last_runner = runner # ADR-88 WD1 — the post-hoc fact-surface fingerprint reads this prepared registry.
         reused = (current & previous) - affected.to_a
         merged = fresh + reused.flat_map { |path| @cache[path] || [] }
-        absorb(runner, fresh, current, analyze_set, removed)
+        absorb(runner, current, analyze_set, removed)
         @param_table = fresh_params
         Recheck.new(diagnostics: merged, changed: changed.to_set, added: added.to_set,
                     removed: removed.to_set, affected: affected, reused: reused.to_set)
@@ -259,6 +263,7 @@ module Rigor
         declaration_signatures = (summary && summary[:declaration_signatures]) || {}
         new_fps = symbol_fingerprints_from_index(scan_index)
         new_class_decls = class_declarations_from_index(scan_index)
+        new_constant_decls = constant_declarations_from_index(scan_index)
         changed_pairs = Incremental.changed_symbol_pairs(changed, @symbol_fingerprints, new_fps)
         # ADR-89 WD1 — a changed file whose DECLARATION signature (per-def parameter shape / visibility /
         # ancestry / member layout / def line, bodies excluded) is byte-identical to the snapshot is
@@ -275,7 +280,8 @@ module Rigor
         # minus those stable pairs, and only it (not `changed_pairs`) drives the symbol-dependent fan-out.
         symbol_pairs = behaviourally_unstable_pairs(changed_pairs, unstable, scan_index) | param_pairs
         base = dependents_base(unstable, symbol_pairs)
-        closure = base | changed.to_set | added.to_set | negative_affected(scan, new_fps, new_class_decls)
+        closure = base | changed.to_set | added.to_set |
+                  negative_affected(scan, removed, new_fps, new_class_decls, new_constant_decls)
         closure = param_seed_closure(closure, param_files)
         removed.each { |path| closure |= @dependents[path] || Set.new }
         closure.freeze
@@ -550,12 +556,7 @@ module Rigor
         @symbol_sources    = payload.symbol_sources    || {}
         @ancestry_sources  = payload.ancestry_sources  || {}
         @symbol_fingerprints = payload.symbol_fingerprints || {}
-        # ADR-46 slice 3 — restore negative edges if present (absent in pre-slice-3 snapshots → empty, which
-        # only loses the appeared-symbol re-check refinement; such a snapshot is never loaded by a slice-3+
-        # engine because the engine version + schema is part of the snapshot fingerprint, and
-        # `--verify-incremental` backstops any residual under-capture, so it is never unsound).
-        @missing           = payload.missing || {}
-        @class_decls       = payload.class_decls || {}
+        restore_structural_declarations(payload)
         @return_summaries  = payload.return_summaries || {}
         @param_table       = payload.param_table || {} # ADR-67 WD6c lift — the seeds the cache was built under.
         # ADR-103 WD13 / #382 — the effects sidecar rides its own identity, so a snapshot whose summaries
@@ -569,12 +570,24 @@ module Rigor
         @negative_dependents = Incremental.invert(@missing)
       end
 
+      # ADR-46 slice 3 / issue #644 — the structural tier's negative-edge state: the per-consumer missed
+      # lookups plus the two per-file DECLARATION sets (`class_decls`, `constant_decls`) whose diff says what
+      # APPEARED in an edit. Absent in an older snapshot → empty, which only loses the appeared-symbol
+      # refinement; such a snapshot is never loaded by a newer engine (the version + SCHEMA are part of the
+      # fingerprint) and `--verify-incremental` backstops any residual under-capture. Extracted to keep
+      # {#restore} under its ABC budget.
+      def restore_structural_declarations(payload)
+        @missing        = payload.missing || {}
+        @class_decls    = payload.class_decls || {}
+        @constant_decls = payload.constant_decls || {}
+      end
+
       def to_payload
         Cache::IncrementalSnapshot::Payload.new(
           cache: @cache, sources: @sources, digests: @digests, analyzed: @analyzed,
           symbol_sources: @symbol_sources, ancestry_sources: @ancestry_sources,
           symbol_fingerprints: @symbol_fingerprints, missing: @missing,
-          class_decls: @class_decls, seed_bundles: @seed_bundles,
+          class_decls: @class_decls, constant_decls: @constant_decls, seed_bundles: @seed_bundles,
           plugin_fact_digest: @plugin_fact_digest,
           return_summaries: marshal_safe_return_summaries,
           param_table: marshal_safe_param_table,
@@ -671,13 +684,13 @@ module Rigor
       # Fold a #recheck's fresh results back into the cache + graph so the session is correct across
       # multiple edits: the analyzed set gets fresh diagnostics + digests + dependency edges, removed files
       # are evicted from every map, and the analyzed-file list advances to `current`.
-      def absorb(runner, fresh, current, analyze_set, removed)
+      def absorb(runner, current, analyze_set, removed)
         removed.each { |path| forget(path) }
         @analyzed = current
         # ADR-85 WD2 — the recheck's discovery folded the restored bundles and refreshed them (changed files
         # re-walked, removed files dropped, added files built), so adopt the runner's current set wholesale.
         @seed_bundles = runner.seed_bundles
-        fresh_by_file = per_file(fresh)
+        fresh_by_file = per_file(runner.per_file_diagnostics)
         analyze_set.each do |path|
           @cache[path] = fresh_by_file[path] || []
           @digests[path] = pack_digest(path)
@@ -754,6 +767,7 @@ module Rigor
         # Wholesale replace (the subset runner's pre-pass is complete): a file that lost its last class must
         # drop out of the map so a later re-add registers as an appearance.
         @class_decls = runner.class_declarations
+        @constant_decls = runner.constant_declarations
       end
 
       # Per-symbol body fingerprints from the pre-parsed `index` (the shared scan-summary def-index — Prism
@@ -792,11 +806,18 @@ module Rigor
       # a prior missed lookup. Maps each appeared `"ClassName#method"` to the negative-dependency key it
       # would satisfy (`toplevel:foo` for a top-level def, `method:C#m` otherwise), then unions the recorded
       # negative-dependents of those keys.
-      def negative_affected(changed, new_fingerprints, new_class_decls)
+      def negative_affected(changed, removed, new_fingerprints, new_class_decls, new_constant_decls)
         appeared_methods = Incremental.appeared_symbols(changed, @symbol_fingerprints, new_fingerprints)
         appeared_classes = Incremental.appeared_classes(changed, @class_decls, new_class_decls)
+        # Issue #644 — a constant whose PUBLICATION moved satisfies the `constant:` kind, keyed on the same
+        # last segment the consumer recorded. REMOVED files join the diff here and nowhere else: deleting a
+        # second declarer restores the precise answer, and no other producer input can see that.
+        moved_constants = Incremental.changed_constant_publications(
+          changed + removed, @constant_decls, new_constant_decls
+        )
         keys = appeared_methods.map { |symbol| negative_key_for(symbol) }
         keys.concat(appeared_classes.map { |klass| "class:#{klass.split('::').last}" })
+        keys.concat(moved_constants.map { |name| "constant:#{name.split('::').last}" })
         Incremental.negative_closure(keys, @negative_dependents)
       end
 
@@ -812,6 +833,20 @@ module Rigor
         result.transform_values(&:freeze).freeze
       end
 
+      # Issue #644 — the per-file PUBLICATION CENSUS of the pre-parsed `index`:
+      # `{ path => { constant name => descriptor } }`, the twin of {#class_declarations_from_index}. The
+      # descriptor is what the diff compares — see {Incremental.changed_constant_publications} for why a bare
+      # name set cannot answer the question.
+      def constant_declarations_from_index(index)
+        return {} if index.nil?
+
+        result = Hash.new { |hash, key| hash[key] = {} }
+        index[:constant_writes].each do |name, by_path|
+          by_path.each { |path, descriptor| result[path][name] = descriptor }
+        end
+        result.transform_values(&:freeze).freeze
+      end
+
       # ADR-89 WD2 — the (live, freshly parsed) def node for a `"Class#method"` / `"Class.method"` symbol in
       # the changed-set scan index, or nil. Instance methods live under `def_nodes`, singleton under
       # `singleton_def_nodes`, both keyed by class name then method Symbol.
@@ -949,9 +984,21 @@ module Rigor
         @paths ? runner.run(@paths) : runner.run
       end
 
-      # Group diagnostics by their file path, keeping only those whose path is an analyzed project file —
-      # run-level streams (the gem-RBS info diagnostic, keyed on `.rigor.yml`) are recomputed fresh every
-      # run and must not be served from the per-file cache.
+      # Group the runner's PER-FILE diagnostics by path, keeping only analyzed project files.
+      #
+      # The argument is `Runner#per_file_diagnostics` — what `PoolCoordinator#analyze_files` returned, already
+      # severity-resolved as the run's stream is (this cache serves reused files without re-stamping, so a
+      # raw row would resurrect an `:off` rule and lose every override) — never the run's full stream. Every
+      # run-level row is regenerated by every run and must not be served
+      # from this cache, and "run-level" is a property of where a row was PRODUCED, not of where it is
+      # positioned: the `.rigor.yml` rows the slice below drops are the common case, but
+      # `effect.annotations-unchecked` sits at the first annotated file and the two `source-rbs-*` rows sit
+      # at the source file that carried the annotation, and all three are produced once per run off the
+      # environment and its reporters. Slicing the full stream cached them, and once a narrowed run's
+      # environment carried the whole project's synthesized RBS (#793) each was regenerated for a file the
+      # recheck did not analyse and met its cached twin in the merge — two rows, `--verify-incremental` red,
+      # on the default configuration with the bundled rbs-inline plugin (#788 rounds 5 and 6; a rule-id
+      # denylist missed the second pair). Feeding only the per-file stream makes the split structural.
       def per_file(diagnostics)
         diagnostics.group_by(&:path).slice(*@analyzed)
       end

data/lib/rigor/analysis/plugin_fact_fingerprint.rb

@@ -151,7 +151,7 @@ module Rigor
       # value actually moves (a new action, a changed sig), which is what a cached diagnostic can depend on;
       # a value-preserving edit keeps the recheck incremental. Returns true when the plugin declared at least
       # one producer (a surface); a producer whose value cannot be digested marks the plugin opaque.
-      # rubocop:disable Naming/PredicateMethod -- reports has-surface AND appends parts (a side-effecting builder)
+      # rubocop:disable-next Naming/PredicateMethod -- reports has-surface AND appends parts (a side-effecting builder)
       def collect_producer_parts(plugin, id, parts, opaque)
         producer_ids = plugin.class.producers.keys
         return false if producer_ids.empty?
@@ -163,7 +163,6 @@ module Rigor
         end
         true
       end
-      # rubocop:enable Naming/PredicateMethod
 
       # Channel (c): the optional {Plugin::Base#incremental_state_fingerprint} hook. Returns true when the
       # plugin defines it (it has a surface).

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

@@ -81,7 +81,8 @@ module Rigor
             next if use.name.nil?
 
             Scan::Reference.new(as_written: use.name.sub(/\A::/, ""), nesting: [].freeze, from: nil,
-                                role: :production, path: use.path, line: use.line)
+                                role: :production, path: use.path, line: use.line,
+                                rooted: use.name.start_with?("::"))
           end
         end
 
@@ -148,7 +149,7 @@ module Rigor
           @references.each do |ref|
             next unless yield(ref)
 
-            target = resolve(ref.as_written, ref.nesting)
+            target = resolve(ref.as_written, ref.nesting, rooted: ref.rooted)
             set << target if target && @owned.include?(target)
           end
           set
@@ -157,7 +158,7 @@ module Rigor
         # `[from_fqn_or_nil, to_fqn, role]` for every reference that resolves to an owned declaration.
         def resolved_edges
           @resolved_edges ||= @references.filter_map do |ref|
-            target = resolve(ref.as_written, ref.nesting)
+            target = resolve(ref.as_written, ref.nesting, rooted: ref.rooted)
             next unless target && @owned.include?(target)
             next if ref.from == target # a declaration referencing itself is not evidence of use
 
@@ -197,8 +198,16 @@ module Rigor
         end
 
         # Ruby's constant lookup at name granularity: `Module.nesting` innermost first, then the ancestors of
-        # the innermost cresting scope (#354), then the bare name.
-        def resolve(as_written, nesting)
+        # the innermost cresting scope (#354), then the bare name. When `rooted: true`, lexical nesting and
+        # ancestors are skipped, answering the top-level declaration directly (#625).
+        def resolve(as_written, nesting, rooted: false)
+          if rooted
+            return as_written if @by_fqn.key?(as_written)
+
+            idx = as_written.rindex("::")
+            return idx ? resolve(as_written[0, idx], nesting, rooted: true) : nil
+          end
+
           walker = nesting.dup
           until walker.empty?
             candidate = (walker + [as_written]).join("::")

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

@@ -28,8 +28,11 @@ module Rigor
 
         # One constant reference. `from` is the fully-qualified name of the innermost enclosing declaration, or
         # nil for a reference written at file level — that is what makes the graph a reachability graph rather
-        # than a reference count (ADR-102 WD2). `role` is the referring FILE's role (WD8).
-        Reference = Data.define(:as_written, :nesting, :from, :role, :path, :line)
+        # than a reference count (ADR-102 WD2). `role` is the referring FILE's role (WD8). `rooted` is true
+        # when the constant was written with a leading `::` (#625).
+        Reference = Data.define(:as_written, :nesting, :from, :role, :path, :line, :rooted) do
+          def initialize(rooted: false, **) = super
+        end
 
         # ADR-102 WD4 — a site where a constant is reached by a mechanism the static reading cannot follow.
         # `name` is the exact constant when the argument is a literal (`"Foo".constantize`), in which case this
@@ -248,7 +251,8 @@ module Rigor
 
             @references << Reference.new(as_written: as_written, nesting: nesting.dup.freeze,
                                          from: nesting.empty? ? nil : nesting.join("::"),
-                                         role: @role, path: @path, line: node.location.start_line)
+                                         role: @role, path: @path, line: node.location.start_line,
+                                         rooted: Source::ConstantPath.rooted?(node))
           end
         end
       end

data/lib/rigor/analysis/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "crash_signature"
+
 module Rigor
   module Analysis
     class Result
@@ -17,6 +19,36 @@ module Rigor
         diagnostics.none?(&:error?)
       end
 
+      # Issue #686 — true when a check rule (or a plugin's node-rule contribution) raised, so
+      # `Runner#analyze_file_body`'s rescue REPLACED the affected file's whole diagnostic list with one
+      # synthetic row. What comes back is then not a weaker account of the code; it is no account of it.
+      #
+      # Any consumer that compares two results, or reads an EMPTY result as "clean", has to ask this first.
+      # A crashed baseline and a crashed mutant carry the same synthetic row, so `==` reports agreement; an
+      # absence assertion holds on the one-diagnostic list the rescue leaves behind. That is how a kill
+      # oracle scored survivors it never measured (#686) and how 1,177 spec examples passed with every check
+      # rule crashing (#674).
+      #
+      # Narrower than "the run reported a failure", deliberately. A raising PLUGIN loses only that plugin's
+      # contribution and a failed RBS definition build loses only a type — in both cases every builtin rule
+      # still ran and its diagnostics are still here, so a consumer that refused those would be discarding a
+      # real measurement. {CrashSignature} carries the full table and the reasoning.
+      #
+      # `success?` is deliberately NOT this question: a crash makes `success?` false (the row is `:error`),
+      # which is why the CLI is loud and CI goes red. It is the callers that read the diagnostic LIST rather
+      # than the exit code which need the predicate.
+      def crashed?
+        diagnostics.any? { |diagnostic| CrashSignature.discards_file_analysis?(diagnostic) }
+      end
+
+      # The diagnostics {#crashed?} answers true for, so a caller can name what it saw rather than only that
+      # it saw something.
+      #
+      # @return [Array<Rigor::Analysis::Diagnostic>]
+      def crash_diagnostics
+        diagnostics.select { |diagnostic| CrashSignature.discards_file_analysis?(diagnostic) }
+      end
+
       def error_count
         diagnostics.count(&:error?)
       end

data/lib/rigor/analysis/run_cache_key.rb

@@ -14,8 +14,13 @@ end
 require_relative "../version"
 require_relative "../cache/descriptor"
 require_relative "../cache/engine_source"
+require_relative "../cache/file_digest"
 require_relative "../cache/rbs_descriptor"
 require_relative "../environment/default_libraries"
+# Both resolvers are leaf files (no requires beyond `yaml`), so the boot-slimming probe reaches the two
+# lockfile paths without loading `rigor/environment` or the RBS machinery.
+require_relative "../environment/lockfile_resolver"
+require_relative "../environment/rbs_collection_discovery"
 
 module Rigor
   module Analysis
@@ -80,7 +85,7 @@ module Rigor
       def descriptor(configuration:, files:, explain:, rbs_config_entries:)
         Cache::Descriptor.new(
           gems: [Cache::RbsDescriptor.rbs_gem_entry],
-          configs: rbs_config_entries + engine_source_entries + [
+          configs: rbs_config_entries + engine_source_entries + lockfile_entries(configuration) + [
             config_entry("configuration", Marshal.dump(configuration.to_h)),
             config_entry("engine",
                          "#{Rigor::VERSION}:#{Cache::Descriptor::SCHEMA_VERSION}:#{explain}"),
@@ -106,6 +111,41 @@ module Rigor
         [config_entry("engine-source", identity)]
       end
 
+      # Issue #564 — the two dependency lockfiles, BY CONTENT. Both are inputs to the run's diagnostics and
+      # neither was represented in the key: the locked gem set decides which bundle-shipped `sig/` dirs and
+      # which `rbs_collection` dirs load, which ADR-72 gem overlays apply, what the ADR-82 WD9 missing-gem
+      # constant index owns, and whether `rbs.coverage.missing-gem` fires at all. Editing a lockfile touches
+      # no analyzed source and no `.rbs` file, so the `paths` slot, the `configuration` slot (which carries
+      # the lockfile PATH, never its bytes) and the recorded dependency descriptor were all unchanged by a
+      # `bundle add` — and a warm run replayed the pre-edit diagnostics in BOTH directions: an
+      # `undefined-method` on `3.minutes` surviving the `bundle add activesupport` that licenses the overlay,
+      # and the same call staying silent after the `bundle remove` that revokes it.
+      #
+      # A KEY slot rather than a dependency entry, because a dependency descriptor can only say "a file I
+      # recorded changed": it cannot express a lockfile that did not exist when the entry was written and
+      # does now, which is the `bundle init` / first-`bundle install` case.
+      #
+      # Content-only — the resolved PATH is deliberately not in the payload, so a checkout that moves (a CI
+      # runner's workspace, a renamed directory) still hits with an identical lockfile.
+      def lockfile_entries(configuration)
+        bundler = Environment::LockfileResolver.resolve_lockfile_path(
+          lockfile_path: configuration.bundler_lockfile, auto_detect: configuration.bundler_auto_detect
+        )
+        collection = Environment::RbsCollectionDiscovery.resolve_lockfile_path(
+          lockfile_path: configuration.rbs_collection_lockfile,
+          auto_detect: configuration.rbs_collection_auto_detect
+        )
+        [lockfile_entry("bundler.lockfile", bundler), lockfile_entry("rbs_collection.lockfile", collection)]
+      end
+
+      # `nil` — no lockfile resolves — is itself part of the identity, so it carries its own sentinel rather
+      # than dropping the slot: "absent" and "present but empty" must not key the same.
+      ABSENT_LOCKFILE = "\0absent"
+
+      def lockfile_entry(key, path)
+        config_entry(key, path.nil? ? ABSENT_LOCKFILE : Cache::FileDigest.hexdigest(path.to_s))
+      end
+
       def config_entry(key, payload)
         Cache::Descriptor::ConfigEntry.new(key: key, value_hash: Digest::SHA256.hexdigest(payload))
       end