rigortype 0.3.7 → 0.3.9

data/lib/rigor/analysis/crash_signature.rb

@@ -42,9 +42,16 @@ module Rigor
     #   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`) or all of them
-    #   (`rbs.coverage.environment-build-failed`). A degradation the user causes and the diagnostic itself
-    #   reports; a project can sit on it for a release while it fixes its `sig/`.
+    #   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
@@ -63,10 +70,11 @@ module Rigor
       PLUGIN_SOURCE_FAMILY = :plugin_loader
       PLUGIN_RULE = "runtime-error"
 
-      # The `rbs.coverage.*` rules that mean declared types went missing from this run — an env-wide
-      # collapse and its per-class sibling (#696). Ordered widest consequence last, the way the two rows sit
-      # in `docs/type-specification/diagnostic-policy.md`.
+      # 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
@@ -75,10 +83,55 @@ module Rigor
       # `: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. Both Rigor-measuring harnesses consult it (#790): `tool/mutation`'s fuzz crash detector
+      # and {Protection::AnalysisGuard}, the ADR-69 kill oracles' refusal. Neither reads it alone — the row
+      # is severity-stamped like any other, so `severity_overrides:` can drop it from a run's diagnostics
+      # entirely, and each harness also reads {Rigor::Environment#hkt_scan_failure}, the pre-severity record
+      # the row is derived from. Both also replace their Environment after a defect: the registry build is
+      # memoised and the failure slot is first-write-wins, so an Environment that degraded once stays
+      # degraded for every later mutant.
+      ANALYZER_DEFECT_RULES = %w[
+        rbs.coverage.hkt-scan-failed
+      ].freeze
+
       module_function
 
-      # @param diagnostic [Rigor::Analysis::Diagnostic]
-      # @return [Symbol, nil] `:check_rule`, `:plugin`, `:rbs_build`, or nil for an ordinary diagnostic.
+      # 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.
+      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.
+      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.
+      def relativize_frame(frame)
+        frame&.sub(%r{\A.*/(lib/rigor/)}, '\1')
+      end
+
+      # @return `: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)
@@ -90,17 +143,20 @@ module Rigor
       # 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).
+      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

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

@@ -25,7 +25,7 @@ module Rigor
           @mutex = Mutex.new
         end
 
-        # @return [Array<Entry>] frozen snapshot of the recorded boundary-cross events. Each entry is a Data
+        # @return frozen snapshot of the recorded boundary-cross events. Each entry is a Data
         #   with `class_name` (String), `method_name` (Symbol), `gem_name` (String), and `rbs_display` (String
         #   — the authoritative-side type's human-facing form, embedded into the diagnostic message).
         def entries

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

@@ -17,8 +17,6 @@ module Rigor
       module Builder
         module_function
 
-        # @param dependencies [Rigor::Configuration::Dependencies]
-        # @return [Index]
         def build(dependencies)
           return Index::EMPTY if dependencies.empty?
 

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

@@ -30,8 +30,6 @@ module Rigor
 
         module_function
 
-        # @param entry [Rigor::Configuration::Dependencies::Entry]
-        # @return [Resolved, Unresolvable]
         def resolve(entry)
           spec = locate_gem_spec(entry.gem)
           return Unresolvable.new(gem_name: entry.gem, reason: :not_in_bundle) if spec.nil?

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

@@ -13,19 +13,19 @@ module Rigor
         attr_reader :resolved_gems, :unresolvable, :method_catalog, :budget_exceeded,
                     :class_to_gem, :budget_overrun_strategy, :gem_modes
 
-        # @param method_catalog [Hash{[String, Symbol] => Symbol}] the flat
+        # @param method_catalog — => Symbol}] the flat
         #   `(class_name, method_name) → :instance | :singleton` table produced by {Walker.walk}, aggregated
         #   across every resolved gem in the run. The Index itself stays gem-agnostic — the per-gem
         #   attribution that slice 3's cache descriptor needs lives on `Resolved`, not here.
-        # @param budget_exceeded [Array<String>] gem names whose {Walker} run hit the per-gem catalog cap
+        # @param budget_exceeded — gem names whose {Walker} run hit the per-gem catalog cap
         #   (slice 4). The Runner consumes this list to emit one `dynamic.dependency-source.budget-exceeded`
         #   warning per gem.
-        # @param class_to_gem [Hash<String, String>] reverse lookup `class_name → gem_name` (slice 5b). Built
+        # @param class_to_gem — reverse lookup `class_name → gem_name` (slice 5b). Built
         #   first-write-wins: when two opt-in gems re-open the same class, the first gem owns it. The
         #   dispatcher consults this map under the `:dependency_silence` budget overrun strategy so call
         #   sites on a budget-exceeded gem's classes degrade to `Dynamic[top]` instead of falling through to
         #   the user-class fallback.
-        # @param gem_modes [Hash<String, Symbol>] per-gem mode table (`gem_name → :disabled | :when_missing |
+        # @param gem_modes — per-gem mode table (`gem_name → :disabled | :when_missing |
         #   :full`). ADR-10 slice 5c consults this through {#mode_for} to identify call sites where
         #   gem-source and RBS both contribute under `mode: :full`. The map is keyed on `gem_name` (not
         #   class) because re-opened classes belong to the first gem they appeared in per `class_to_gem`;
@@ -56,7 +56,7 @@ module Rigor
         end
         private :normalize_catalog
 
-        # @return [String, nil] the gem that owns `class_name` (first-write-wins); `nil` when the class isn't
+        # @return the gem that owns `class_name` (first-write-wins); `nil` when the class isn't
         #   in any opt-in gem's catalog.
         def gem_for(class_name)
           @class_to_gem[class_name]

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

@@ -28,8 +28,7 @@ module Rigor
       module ReturnTypeHeuristic
         module_function
 
-        # @param def_node [Prism::DefNode]
-        # @return [Rigor::Type, nil] heuristic return type, or `nil` when the body's tail expression doesn't
+        # @return heuristic return type, or `nil` when the body's tail expression doesn't
         #   match any of the recognised shapes.
         def extract(def_node)
           body = def_node.body

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

@@ -55,12 +55,12 @@ module Rigor
 
         module_function
 
-        # @param gem_dir [String, Pathname] absolute path to the gem's installation directory.
-        # @param roots [Array<String>] subdirectory names within the gem to walk (defaults to `["lib"]` per
+        # @param gem_dir — absolute path to the gem's installation directory.
+        # @param roots — subdirectory names within the gem to walk (defaults to `["lib"]` per
         #   `Configuration::Dependencies::Entry`).
-        # @param budget [Integer, Float] per-gem catalog cap (method-definition count). When unset, defaults
+        # @param budget — per-gem catalog cap (method-definition count). When unset, defaults
         #   to `UNBOUNDED` for backwards-compatible test paths.
-        # @return [Outcome] frozen wrapper carrying the catalog (`Hash{[class_name, method_name] =>
+        # @return frozen wrapper carrying the catalog (`Hash{[class_name, method_name] =>
         #   :instance | :singleton}`) and a `truncated?` flag set when the walker stopped harvesting because
         #   the budget was reached. Methods of identical name on the same class with different kinds (rare;
         #   private API mostly) carry the kind that wins the per-class first walk.

data/lib/rigor/analysis/effects_cache_probe.rb

@@ -52,17 +52,16 @@ module Rigor
       # otherwise rebuild (the probe loaded the plugins to key the entry, so it already knows it).
       Served = Data.define(:table, :sources, :registry, :plugin_facts)
 
-      # @param configuration [Rigor::Configuration] with effects already enabled by the caller.
-      # @param cache_root [String, nil]
+      # @param configuration — with effects already enabled by the caller.
       def initialize(configuration:, cache_root:)
         @configuration = configuration
         @cache_root = cache_root
       end
 
-      # @param paths [Array<String>] the analysed set — `configuration.paths` unioned with any path
+      # @param paths — the analysed set — `configuration.paths` unioned with any path
       #   arguments, exactly what {CLI::EffectsCommand#analyze} hands the runner, because the analysed
       #   set is part of the diagnostics key.
-      # @return [Served, nil] nil to decline, on any failure whatsoever.
+      # @return nil to decline, on any failure whatsoever.
       def serve(paths)
         return nil if @cache_root.nil? || !@configuration.effects_check?
 

data/lib/rigor/analysis/erb_template_detector.rb

@@ -19,8 +19,7 @@ module Rigor
 
       module_function
 
-      # @param parse_result [Prism::ParseResult]
-      # @return [Boolean] true when the parsed source looks like an ERB template (parse errors expected;
+      # @return true when the parsed source looks like an ERB template (parse errors expected;
       #   analysis should skip).
       def template?(parse_result)
         source = parse_result.source.source

data/lib/rigor/analysis/fact_store.rb

@@ -18,9 +18,14 @@ module Rigor
       ].freeze
 
       class Target < Data.define(:kind, :name)
+        # #775 — a target is an immutable value keyed by its name, and the local target is built on every
+        # binding (`Scope#with_local` invalidates through it) and every local-fact read: ~350k times on
+        # the lib self-check for a few thousand distinct names. One shared instance per name.
         def self.local(name)
-          new(kind: :local, name: name.to_sym)
+          name = name.to_sym
+          @local_targets[name] ||= new(kind: :local, name: name)
         end
+        @local_targets = {}
 
         def initialize(kind:, name:)
           super(kind: kind.to_sym, name: name)

data/lib/rigor/analysis/incremental.rb

@@ -120,6 +120,22 @@ module Rigor
         appeared.freeze
       end
 
+      # Issue #639 — the SYMMETRIC reading of {appeared_classes}: the names whose declaration in a file
+      # appeared OR VANISHED. Appearance alone answered the miss side, which was the only side recording a
+      # `class:` edge; a bare reference that RESOLVED now records one too, and what invalidates it is the
+      # declaration going away. `paths` MUST therefore include REMOVED files — a removed file has no
+      # after-state, so its whole before-set vanished — which is the same reason
+      # {changed_constant_publications} diffs over `changed + removed`.
+      def changed_class_declarations(paths, decls_before, decls_after)
+        moved = Set.new
+        paths.each do |path|
+          before = decls_before[path] || Set.new
+          after  = decls_after[path]  || Set.new
+          moved.merge(after ^ before)
+        end
+        moved.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

data/lib/rigor/analysis/incremental_session.rb

@@ -42,22 +42,22 @@ module Rigor
         end
       end
 
-      # @param paths [Array<String>, nil] explicit analysis roots; nil (the default) uses the configuration's
+      # @param paths — explicit analysis roots; nil (the default) uses the configuration's
       #   `paths:`.
-      # @param environment [Rigor::Environment, nil] optional shared environment to thread into each internal
+      # @param environment — optional shared environment to thread into each internal
       #   Runner. Long-lived callers and specs can use this to avoid rebuilding the same RBS universe for
       #   every baseline / recheck / oracle run.
-      # @param cache_store [Rigor::Cache::Store, nil] ADR-85 WD1 — the persistent cache each internal Runner
+      # @param cache_store — ADR-85 WD1 — the persistent cache each internal Runner
       #   exposes to the RBS-env and plugin-producer tiers. A cross-process `--incremental` recheck otherwise
       #   rebuilt a fresh runner with no store, so every plugin `#prepare` producer (the ADR-9/#74/ADR-60 WD3
       #   record-and-validate caches) recomputed per invocation — 86% of a Rails warm incremental. Threading
       #   the store lets those producers serve from disk. `nil` (the default) preserves the pre-#85 behaviour
       #   the specs assert; the whole-run ADR-45 result cache stays disabled on these runs
       #   (`Runner#run_result_cacheable?` excludes `record_dependencies` / `analyze_only`).
-      # @param plugin_requirer [#call, nil] optional gem-require hook threaded into each internal Runner
+      # @param plugin_requirer — optional gem-require hook threaded into each internal Runner
       #   (mirrors {Runner}'s parameter). nil (the default, and what the CLI passes) uses `Kernel.require`;
       #   embedders and specs inject a fake so a test plugin registers without touching the real load path.
-      # @param workers [Integer] ADR-46 — the resolved fork-pool worker count threaded into every internal
+      # @param workers — ADR-46 — the resolved fork-pool worker count threaded into every internal
       #   analyzer, so a `--incremental` recheck's closure re-analysis parallelises exactly like the standard
       #   `check` path (the recon's audit: `--workers` / `RIGOR_RACTOR_WORKERS` / `parallel.workers:` were
       #   silently ignored because `build_runner` passed no `workers:`). 0 (the default, and what the specs and
@@ -112,7 +112,7 @@ module Rigor
         # and a missing invalidation edge is impossible by construction — the reason this is a table diff
         # and not the caller→callee edge recording #204 first sketched.
         @param_table = {}
-        reset_effect_state
+        reset_carried_state
         # ADR-88 WD1 — the plugin fact-surface digest computed for THIS invocation (nil until a
         # `#run_incremental` pass runs / a plugin-free project) and the reporting flags a caller (the CLI
         # banner + `--cache-stats`) reads after `#run_incremental`. `@last_runner` is the analysis runner the
@@ -172,8 +172,9 @@ 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)] }
+        @run_level_rows = runner.run_level_rows
         diagnostics
       end
 
@@ -197,12 +198,13 @@ module Rigor
         # The freshly collected table is handed to the runner so the run seeds from the SAME table the diff
         # was decided on (and the collector runs once per recheck, not twice).
         runner = build_runner(analyze_only: analyze_set, record_dependencies: true,
-                              param_inferred_types: fresh_params)
+                              param_inferred_types: fresh_params,
+                              restored_run_level_rows: @run_level_rows)
         fresh = run_runner(runner).diagnostics
         @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)
@@ -407,10 +409,13 @@ module Rigor
       end
 
       # The current project file set (cheap directory expansion, no analysis), used to detect files added /
-      # removed since the last run.
+      # removed since the last run. Also where an editor buffer's binding is re-spelled onto the set, since
+      # this is where the run first learns how it spells its own members.
       def current_files
         runner = build_runner
-        @paths ? runner.analysis_file_set(@paths) : runner.analysis_file_set
+        files = @paths ? runner.analysis_file_set(@paths) : runner.analysis_file_set
+        rebind_buffer(files)
+        files
       end
 
       # Verification engine (the `--verify-incremental` gate): with NO source edit, re-analyze `subset` fresh
@@ -422,7 +427,8 @@ module Rigor
         affected = subset.to_set
         # ADR-67 WD6c lift — seed the subset run from the baseline's own table so the verification engine
         # exercises the exact seeds the served cache entries were computed under (and skips a re-collect).
-        runner = build_runner(analyze_only: affected, param_inferred_types: @param_table)
+        runner = build_runner(analyze_only: affected, param_inferred_types: @param_table,
+                              restored_run_level_rows: @run_level_rows)
         fresh = run_runner(runner).diagnostics
         reused = @analyzed - affected.to_a
         fresh + reused.flat_map { |path| @cache[path] || [] }
@@ -559,6 +565,9 @@ module Rigor
         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.
+        # Issues #796 / #794 — absent (nil) in a snapshot written before schema 22 is impossible (the SCHEMA
+        # gate rejects one), so nil here means the writing run genuinely had nothing to say.
+        @run_level_rows    = payload.run_level_rows
         # ADR-103 WD13 / #382 — the effects sidecar rides its own identity, so a snapshot whose summaries
         # were collected under a different vocabulary / catalogue / `effects:` block restores as EMPTY
         # rather than as stale rows. {#run_incremental} turns that emptiness into a full baseline, because
@@ -592,7 +601,8 @@ module Rigor
           return_summaries: marshal_safe_return_summaries,
           param_table: marshal_safe_param_table,
           effect_collections: marshal_safe_effect_collections,
-          effects_identity: @effects_identity
+          effects_identity: @effects_identity,
+          run_level_rows: @run_level_rows
         )
       end
 
@@ -606,6 +616,15 @@ module Rigor
         @effects_identity = nil
       end
 
+      # The state this session carries ACROSS processes in the snapshot rather than deriving each run: the
+      # effects sidecar above, and (issues #796 / #794) the run-level rows the last FULL run answered — the
+      # `definition-build-failed` set and the HKT-scan outcome, nil until a full run has produced them, and
+      # handed to every narrowed run this session builds, none of which can derive them from its own files.
+      def reset_carried_state
+        reset_effect_state
+        @run_level_rows = nil
+      end
+
       # Whether the effects half of a restored snapshot permits reuse. Collection off is vacuously true —
       # the session keeps no collections, writes none, and the pre-#382 reuse decision stands unchanged.
       def effects_reuse_permitted?(payload)
@@ -684,18 +703,21 @@ 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)
         end
         absorb_dependency_graph(runner)
+        # Issues #796 / #794 — the recheck's own snapshots already carry the replayed rows folded together
+        # with anything its closure demanded for itself, so this is the same union the next run replays.
+        @run_level_rows = runner.run_level_rows
         refresh_return_summaries(runner, analyze_set)
         refresh_effect_collections(runner, analyze_set)
       end
@@ -803,20 +825,24 @@ module Rigor
       end
 
       # ADR-46 slice 3 — the consumers to re-check because a symbol that appeared in a changed file resolves
-      # 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.
+      # a prior missed lookup, and (issue #639) because a class DECLARATION appeared or vanished. 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, 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 #639 — a class DISAPPEARING satisfies the `class:` kind too, now that a resolved bare
+        # reference records the edge and not only a failed one; removed files join the diff for it.
+        moved_classes = Incremental.changed_class_declarations(
+          changed + removed, @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.
+        # last segment the consumer recorded. Removed files join this diff (as they do the class one above):
+        # 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_classes.map { |klass| "class:#{klass.split('::').last}" })
         keys.concat(moved_constants.map { |name| "constant:#{name.split('::').last}" })
         Incremental.negative_closure(keys, @negative_dependents)
       end
@@ -984,9 +1010,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
@@ -1001,18 +1039,51 @@ module Rigor
         candidates.reject { |path| stat_fresh?(path) }
       end
 
-      # A bound buffer's logical path is never fresh: the bytes to analyse live in the editor's temp file, and
-      # the recorded entry describes the file on disk. Re-analysing it when the two happen to agree costs one
-      # file; trusting the stat tuple would serve the editor its own stale diagnostics.
       def buffer_path?(path)
         !@buffer.nil? && path == @buffer.logical_path
       end
 
+      # Editor mode (#146) — the bound buffer's logical path is fresh exactly when the EDITOR's bytes still
+      # hash to the digest the snapshot recorded for the file they stand in for. The recorded stat tuple
+      # describes the file on disk, which an edit in the editor never moves, so validating through it serves
+      # the editor its own pre-buffer answers (#960); hashing the buffer makes the substituted file changed
+      # whenever it differs, and keeps an untouched buffer out of the closure. Anything unreadable or
+      # unrecorded reads as changed, the conservative direction the rest of this tier takes.
+      def buffer_fresh?(path)
+        recorded = Cache::FileDigest.content_digest(@digests[path])
+        return false if recorded.nil?
+
+        Cache::FileDigest.hexdigest(@buffer.resolve(path)) == recorded
+      rescue StandardError
+        false
+      end
+
+      # Editor mode (#146 / #960) — `--instead-of` is spelled the way the editor spells it (absolute, or
+      # `./`-prefixed), while the analysed set is spelled the way the run's path arguments produce. A binding
+      # whose logical path matches no member of that set substitutes nothing at all: every reader keeps
+      # reading the file on disk and the run answers as if no buffer had been passed. Re-spell the binding
+      # onto the set's own member, identified by real path, once the set is known.
+      def rebind_buffer(files)
+        return if @buffer.nil? || files.include?(@buffer.logical_path)
+
+        target = real_path(@buffer.logical_path)
+        return if target.nil?
+
+        match = files.find { |path| real_path(path) == target }
+        @buffer = BufferBinding.new(logical_path: match, physical_path: @buffer.physical_path) if match
+      end
+
+      def real_path(path)
+        File.realpath(path)
+      rescue StandardError
+        nil
+      end
+
       # True when `path`'s recorded stat entry proves it unchanged since the last analysis. Any stat / parse
       # failure (missing entry, unreadable / vanished file) reads as NOT fresh (→ re-analyse), preserving the
       # prior `digest(path) != recorded` "changed" semantics for a file that cannot be validated.
       def stat_fresh?(path)
-        return false if buffer_path?(path)
+        return buffer_fresh?(path) if buffer_path?(path)
 
         entry = @digests[path]
         return false if entry.nil?

data/lib/rigor/analysis/plugin_fact_fingerprint.rb

@@ -79,7 +79,6 @@ module Rigor
       #
       # Keeping the opaque decision here, rather than at each cache's call site, means a new consumer cannot
       # key on `digest` while forgetting that an opaque surface makes it meaningless.
-      # @return [String, nil]
       def self.key_digest(registry)
         result = from_registry(registry)
         result.opaque? ? nil : result.digest.to_s

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

@@ -29,13 +29,11 @@ module Rigor
         # bucket on trust.
         Undecidable = Data.define(:fqn, :path, :line, :reason)
 
-        # @param declarations [Array<Scan::Declaration>]
-        # @param references [Array<Scan::Reference>]
-        # @param root_fqns [Enumerable<String>] declarations that are entry points regardless of who references
+        # @param root_fqns — declarations that are entry points regardless of who references
         #   them (config-declared globs in this slice; plugin-supplied roots are #349).
-        # @param foreign [#call] predicate answering "is this FQN owned by something outside the project?" —
+        # @param foreign — predicate answering "is this FQN owned by something outside the project?" —
         #   a reopened gem or stdlib class must never be a candidate (WD6). Defaults to "nothing is foreign".
-        # @param dynamic_uses [Array<Scan::DynamicUse>] sites where a constant is reached by name at runtime.
+        # @param dynamic_uses — sites where a constant is reached by name at runtime.
         #   A literal-argument site contributes a real reference; a dynamic one taints a namespace (WD4).
         def initialize(declarations:, references:, root_fqns: [], dynamic_uses: [], foreign: ->(_fqn) { false })
           @declarations = declarations

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

@@ -83,14 +83,15 @@ module Rigor
         # Loads the project's configured plugins, runs every `#prepare`, and returns the union of every
         # published `:reachability_roots` and `:reachability_references` fact.
         #
-        # @param configuration [Rigor::Configuration] the loaded project configuration.
-        # @param plugin_requirer [#call] how a plugin gem is brought into the process. The same seam
-        #   `Analysis::Runner` exposes, so a spec can register a plugin class without publishing a gem.
-        # @param cache_store [Rigor::Cache::Store, nil] when given, each plugin's `#prepare` producers read
+        # @param configuration — the loaded project configuration.
+        # @param plugin_requirer — how a plugin gem is brought into the process, called with the gem name. The
+        #   same seam `Analysis::Runner` exposes, so a spec can register a plugin class without publishing a
+        #   gem.
+        # @param cache_store — when given, each plugin's `#prepare` producers read
         #   and write the same ADR-60 record-and-validate slots they use under `rigor check`, instead of
         #   recomputing from scratch — a routes parse or a factory discovery is a validated cache read on
         #   every invocation after the first. Nil keeps the historical recompute-always behaviour.
-        # @return [Contribution] sorted and de-duplicated. Empty whenever the project declares no plugins, no
+        # @return sorted and de-duplicated. Empty whenever the project declares no plugins, no
         #   plugin contributes anything, or anything at all goes wrong.
         def collect(configuration:, plugin_requirer: ->(name) { require name }, cache_store: nil)
           return Contribution.empty if configuration.plugins.empty?

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

@@ -46,8 +46,8 @@ module Rigor
           File.fnmatch?(pattern, path, File::FNM_PATHNAME)
         end
 
-        # @param relative_paths [Array<String>] paths relative to `root`.
-        # @return [Array<String>] those that belong to the project itself.
+        # @param relative_paths — paths relative to `root`.
+        # @return those that belong to the project itself.
         def own(relative_paths, root)
           prefixes = submodule_prefixes(root)
           relative_paths.grep_v(VENDOR_DIRS).reject { |rel| prefixes.any? { |prefix| rel.start_with?(prefix) } }

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

@@ -70,11 +70,6 @@ module Rigor
           end
         end
 
-        # @param path [String] the file's path, as the report should render it.
-        # @param source [String] the file's bytes.
-        # @param target_ruby [String, nil] Prism version string, threaded from the project configuration.
-        # @return [Result, nil] nil when the file does not parse (a parse error is the analyzer's business, not
-        #   this scan's — it simply contributes nothing rather than half a file).
         # A constant name is ASCII by construction, so a byte sequence that is not valid UTF-8 cannot be one.
         # Dropping it is both correct and the only safe answer: carrying it forward crashed the whole run on
         # the first `String#sub` downstream, which is how this surfaced — `rigor unused` on Rigor's own
@@ -86,6 +81,11 @@ module Rigor
           name.valid_encoding? ? name : nil
         end
 
+        # @param path — the file's path, as the report should render it.
+        # @param source — the file's bytes.
+        # @param target_ruby — Prism version string, threaded from the project configuration.
+        # @return nil when the file does not parse (a parse error is the analyzer's business, not
+        #   this scan's — it simply contributes nothing rather than half a file).
         def self.call(path:, source:, target_ruby: nil)
           parsed = if target_ruby
                      Prism.parse(source, filepath: path,