rigortype 0.3.0 → 0.3.2

data/lib/rigor/cache/incremental_snapshot.rb

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

data/lib/rigor/cache/rbs_cache_producer.rb

@@ -15,12 +15,22 @@ module Rigor
     # `self::PRODUCER_ID` resolves the constant on the concrete subclass, and `compute(loader)` dispatches to
     # its private class method. See the `_CacheProducer` RBS interface for the structural contract.
     class RbsCacheProducer
+      # Every RBS producer is whole-project and content-keyed: one entry is live and any older generation is
+      # unreachable, so `Cache::Store#evict!` keeps a small number of them (one spare for the still-warm
+      # previous signature state — the RBS environment blob alone runs to ~1.8 MB, ADR-54 WD3). Declared on
+      # the base, so a producer added by subclassing inherits a cap instead of being silently uncapped; a
+      # subclass with different economics overrides this method.
+      def self.generation_cap
+        2
+      end
+
       def self.fetch(loader:, store:)
         # ADR-54 WD4 — the descriptor is identical for every producer consulting the same loader (same sig
         # files, same libraries), so the loader memoises one build per process instead of re-digesting every
         # .rbs file once per producer.
         descriptor = loader.rbs_cache_descriptor
-        store.fetch_or_compute(producer_id: self::PRODUCER_ID, params: {}, descriptor: descriptor) do
+        store.fetch_or_compute(producer_id: self::PRODUCER_ID, params: {}, descriptor: descriptor,
+                               generation_cap: generation_cap) do
           compute(loader)
         end
       end

data/lib/rigor/cache/rbs_environment_marshal_patch.rb

@@ -17,6 +17,20 @@ require "rbs"
 #
 # Idempotent: the guard checks `method_defined?(:_dump)` so requiring this file twice (or against an upstream
 # rbs that adds Marshal hooks itself) is a no-op.
+#
+# `RBS::TypeName` / `RBS::Namespace` carry a second, subtler Marshal hazard, introduced by rbs 4.1's
+# flyweight interning (ruby/rbs#2957): both memoise their `#hash` into an `@hash` ivar, and that value is
+# derived from `Array#hash` / `Symbol#hash`, which Ruby seeds PER PROCESS. Marshal round-trips the ivar
+# verbatim, so a cached `TypeName` loaded in a later process answers `hash` with the *writing* process's
+# value while a freshly parsed `TypeName.parse("::String")` answers with this process's. The two are still
+# `eql?`, so nothing raises — every Hash keyed by a TypeName simply misses. `RBS::Environment#class_decls`
+# is exactly such a Hash, so a warm cache silently reported every core class as unknown.
+#
+# `_dump` / `_load` on both classes fixes it at the representation: the name is dumped as its source string
+# and reconstructed through `.parse`, which routes back through the flyweight interner. That drops the stale
+# `@hash` (it is re-memoised on demand, under this process's seed), and restores the flyweight identity the
+# interner exists to provide — a cached env now shares one object per distinct name rather than one per
+# reference. Both classes are value objects fully described by `to_s`, so the round-trip is lossless.
 module RBS
   class Location
     unless method_defined?(:_dump)
@@ -29,4 +43,28 @@ module RBS
       end
     end
   end
+
+  class Namespace
+    unless method_defined?(:_dump)
+      def _dump(_)
+        to_s
+      end
+
+      def self._load(string)
+        parse(string)
+      end
+    end
+  end
+
+  class TypeName
+    unless method_defined?(:_dump)
+      def _dump(_)
+        to_s
+      end
+
+      def self._load(string)
+        parse(string)
+      end
+    end
+  end
 end

data/lib/rigor/cache/store.rb

@@ -37,18 +37,10 @@ module Rigor
       # blob whose class layout still happens to unmarshal.
       PAYLOAD_ABI_VERSION = Rigor::VERSION
 
-      # Whole-project producers are content-keyed, so dependency / signature churn writes a new entry and leaves
-      # the old generation unreachable. The global 256 MB cap is intentionally generous and often never fires on
-      # one project, so these producers get a small generation cap as a second compaction axis. Per-file / plugin
-      # producers are deliberately absent from this table: many current entries under one producer id can be live.
-      GENERATION_CAP_BY_PRODUCER = {
-        "analysis.run-diagnostics" => 16,
-        "rbs.class_ancestor_table" => 2,
-        "rbs.class_type_param_names" => 2,
-        "rbs.constant_type_table" => 2,
-        "rbs.environment" => 2,
-        "rbs.known_class_names" => 2
-      }.freeze
+      # The `generation_cap:` value declaring that a producer keeps MANY live entries under one id at once
+      # (per-file and per-plugin producers): a generation count is not a staleness proxy there, so the
+      # compaction pass in {#evict!} leaves the producer alone and only the size-based LRU pass can touch it.
+      UNBOUNDED_GENERATIONS = :unbounded
 
       STALE_TEMP_FILE_AGE_SECONDS = 60 * 60
 
@@ -76,6 +68,14 @@ module Rigor
         @misses = 0
         @writes = 0
         @by_producer = Hash.new { |h, k| h[k] = { hits: 0, misses: 0, writes: 0 } }
+        # `producer_id => generation cap`, populated from the `generation_cap:` every fetch call declares (see
+        # {#declare_generation_cap}). This is the bridge between the id STRINGS the fetch API takes and the
+        # directory names {#evict!} walks: a producer id the Store never saw declared stays uncapped, which
+        # errs toward under-evicting. Per-instance rather than process-global on purpose — a global mutable
+        # registry would be a `Ractor` shareability hazard for pool mode, and the Store instance that wrote a
+        # generation is the one whose `evict!` compacts it (`CLI::CheckCommand` calls
+        # `runner.cache_store&.evict!`).
+        @generation_caps = {}
         # Process-level in-memory layer keyed by `(producer_id, cache_key)`. Avoids the disk read +
         # `Marshal.load` cost (the dominant share of repeated cache-hit calls per stackprof) when many
         # short-lived `Analysis::Runner` instances share one `Store` — the spec process, the LSP daemon's
@@ -161,6 +161,12 @@ module Rigor
       private_class_method :collect_producers
 
       # @param producer_id [String] stable cache namespace; only `[a-z][a-z0-9._-]*` is accepted.
+      # @param generation_cap [Integer, Symbol] how many generations of this producer survive a compaction
+      #   pass — a positive `Integer` for a whole-project producer (one live entry, older ones unreachable),
+      #   or {UNBOUNDED_GENERATIONS} for a producer with many simultaneously-live entries. REQUIRED, and
+      #   sourced from the producer's own declaration (`RbsCacheProducer.generation_cap`,
+      #   `RunCacheKey::GENERATION_CAP`, `Plugin::Base.producer generation_cap:`) rather than invented at the
+      #   call site. See {#evict!}.
       # @param params [Hash] producer inputs; mixed into the cache key via {Descriptor#cache_key_for}.
       # @param descriptor [Rigor::Cache::Descriptor] the invalidation descriptor for the value being cached.
       # @param serialize [#call, nil] optional callable that turns the producer's return value into a binary
@@ -175,9 +181,10 @@ module Rigor
       #   path.
       # @yieldreturn the value to cache.
       # @return the cached value (loaded from disk on hit; produced by the block on miss).
-      def fetch_or_compute(producer_id:, params:, descriptor:,
+      def fetch_or_compute(producer_id:, params:, descriptor:, generation_cap:,
                            serialize: nil, deserialize: nil, &block)
         validate_producer_id!(producer_id)
+        declare_generation_cap(producer_id, generation_cap)
         disk = ensure_schema_version!
 
         key = descriptor.cache_key_for(producer_id: producer_id, params: params)
@@ -217,8 +224,12 @@ module Rigor
       #
       # The block MUST return `[value, dependency_descriptor]`. Disk reads are not in-process-memoised —
       # validation always re-checks the filesystem — but a single run only looks up once.
-      def fetch_or_validate(producer_id:, key_descriptor:, params: {}, serialize: nil, deserialize: nil)
+      #
+      # `generation_cap:` carries the same producer-declared compaction budget as {#fetch_or_compute}.
+      def fetch_or_validate(producer_id:, key_descriptor:, generation_cap:, params: {},
+                            serialize: nil, deserialize: nil)
         validate_producer_id!(producer_id)
+        declare_generation_cap(producer_id, generation_cap)
         disk = ensure_schema_version!
 
         key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
@@ -243,6 +254,9 @@ module Rigor
       # to serve a run's diagnostics WITHOUT loading the inference engine — it never runs a producer block, so
       # there is nothing to write. Records a hit (for `--cache-stats` parity) but never a miss (a probe miss
       # hands off to the full path, which records its own).
+      #
+      # Takes no `generation_cap:`: a pure read creates no generation, so a run that only ever peeks has
+      # nothing to compact. The write path for the same producer declares the cap.
       def peek_validated(producer_id:, key_descriptor:, params: {}, deserialize: nil)
         validate_producer_id!(producer_id)
         return nil unless ensure_schema_version!
@@ -256,8 +270,15 @@ module Rigor
         validated[0]
       end
 
-      # ADR-6 § "Eviction" — compaction pass over the on-disk cache. No-op when the store is read-only. Stale
-      # temp file cleanup and the whole-project generation cap run regardless of `max_bytes:` — they reclaim
+      # ADR-6 § "Eviction" — compaction pass over the on-disk cache. No-op when the store is read-only.
+      #
+      # The generation cap of pass 2 comes from what the producers themselves declared through this Store's
+      # fetch calls (`generation_cap:`), NOT from a maintained table of producer ids: a producer id this
+      # Store never saw is left alone. That is deliberately the safe direction — a producer that was not
+      # consulted this run also wrote no new generation, so the only entries this can skip are ones that were
+      # already sitting there.
+      #
+      # Stale temp file cleanup and the generation cap run regardless of `max_bytes:` — they reclaim
       # provably-dead bytes (leaked temp files, unreachable content-keyed generations) rather than enforcing a
       # size budget, so an explicitly unbounded store (`max_bytes: nil`) still benefits from them. The
       # size-based LRU pass below stays gated on `max_bytes:` being configured: it walks all remaining
@@ -279,7 +300,7 @@ module Rigor
         entries.each do |entry|
           break if total <= @max_bytes
 
-          total -= entry[:bytes] if unlink_entry(entry[:path])
+          total -= entry[:bytes] if unlink_entry_and_shard?(entry[:path])
         end
         nil
       rescue StandardError
@@ -320,6 +341,37 @@ module Rigor
               "producer_id must match #{VALID_PRODUCER_ID.inspect}, got #{producer_id.inspect}"
       end
 
+      # Records the producer's declared compaction budget for {#evict!}. Every fetch call carries it, so a
+      # producer cannot reach disk without stating one — the failure mode the previous hardcoded id table
+      # had (a new whole-project producer silently uncapped) is not expressible.
+      #
+      # Two DIFFERENT caps for one producer id in one process is a producer bug, not a policy: whichever the
+      # compaction pass picked would be arbitrary. It raises, consistent with the serializer-contract
+      # violations {#try_write_entry} deliberately lets through.
+      def declare_generation_cap(producer_id, generation_cap)
+        validate_generation_cap!(producer_id, generation_cap)
+        @monitor.synchronize do
+          previous = @generation_caps[producer_id]
+          if !previous.nil? && previous != generation_cap
+            raise ArgumentError,
+                  "producer #{producer_id.inspect} declared generation_cap #{generation_cap.inspect} after " \
+                  "#{previous.inspect}; one producer id must declare one cap"
+          end
+
+          @generation_caps[producer_id] = generation_cap
+        end
+      end
+
+      def validate_generation_cap!(producer_id, generation_cap)
+        return if generation_cap == UNBOUNDED_GENERATIONS
+        return if generation_cap.is_a?(Integer) && generation_cap.positive?
+
+        raise ArgumentError,
+              "producer #{producer_id.inspect} must declare generation_cap as a positive Integer (a " \
+              "whole-project producer: how many generations survive compaction) or " \
+              "#{UNBOUNDED_GENERATIONS.inspect} (many entries live at once), got #{generation_cap.inspect}"
+      end
+
       def entry_path(producer_id, key)
         File.join(@root, producer_id, key[0, 2], "#{key[2..]}.entry")
       end
@@ -541,7 +593,7 @@ module Rigor
           next unless File.file?(path)
           next if File.mtime(path) > cutoff
 
-          unlink_entry(path)
+          unlink_entry_and_shard?(path)
         rescue StandardError
           next
         end
@@ -550,16 +602,16 @@ module Rigor
       end
 
       def evict_excess_generations(entries)
+        caps = @monitor.synchronize { @generation_caps.dup }
         removed = {}
         entries.group_by { |entry| entry[:producer] }.each do |producer, producer_entries|
-          cap = GENERATION_CAP_BY_PRODUCER[producer]
+          cap = caps[producer]
+          cap = nil if cap == UNBOUNDED_GENERATIONS
           next if cap.nil? || producer_entries.size <= cap
 
-          producer_entries.sort_by { |entry| [entry[:mtime], entry[:path]] }
-                          .first(producer_entries.size - cap)
-                          .each do |entry|
-            removed[entry[:path]] = true if unlink_entry(entry[:path])
-          end
+          excess = producer_entries.sort_by { |entry| [entry[:mtime], entry[:path]] }
+                                   .first(producer_entries.size - cap)
+          excess.each { |entry| removed[entry[:path]] = true if unlink_entry_and_shard?(entry[:path]) }
         end
         return entries if removed.empty?
 
@@ -573,6 +625,29 @@ module Rigor
         false
       end
 
+      # {#unlink_entry} plus a best-effort {#rmdir_if_empty} of the shard directory the unlinked file left
+      # behind. Shared by every eviction/sweep pass so an emptied shard is cleaned up wherever an entry (or
+      # stale temp file) is removed, per the issue #216 fossil fix.
+      def unlink_entry_and_shard?(path)
+        return false unless unlink_entry(path)
+
+        rmdir_if_empty(File.dirname(path))
+        true
+      end
+
+      # Removes `dir` — a shard directory (`entry_path`'s `key[0, 2]` component) — when the unlink that
+      # just preceded this call was the one to empty it. Best-effort and rescued the same way
+      # {#unlink_entry} is: a concurrent writer's `FileUtils.mkdir_p` recreating the shard between the
+      # unlink and this call (`Errno::ENOTEMPTY`) or another pass already having removed it
+      # (`Errno::ENOENT`) are both benign outcomes, never a reason to break the eviction/sweep pass. This
+      # is purely cosmetic (inode reclaim) — it never decides which ENTRIES are evicted, only tidies the
+      # directory left behind once they are gone.
+      def rmdir_if_empty(dir)
+        Dir.rmdir(dir)
+      rescue StandardError
+        nil
+      end
+
       # Returns an array of `{ path:, producer:, mtime:, bytes: }` hashes for every `.entry` file under the
       # cache root, skipping unreadable entries.
       def collect_entry_stats

data/lib/rigor/cli/check_command.rb

@@ -48,9 +48,6 @@ module Rigor
 
         configuration = load_check_configuration(options)
         configuration = apply_bleeding_edge_override(configuration, options)
-        conflict = parameter_inference_incremental_conflict(configuration, options)
-        return conflict unless conflict.nil?
-
         config_warnings = warn_unresolved_config(configuration)
         cache_root = configuration.cache_path
         handle_clear_cache(cache_root) if options.fetch(:clear_cache)
@@ -62,14 +59,15 @@ module Rigor
         return finalize_cache_hit(probed, configuration, options, config_warnings) unless probed.nil?
 
         load_check_dependencies
-        special = dispatch_special_check_mode(configuration, options, cache_root)
+        special = dispatch_special_check_mode(configuration, options, cache_root, buffer)
         return special unless special.nil?
 
-        runner = build_check_runner(
+        invocation = invoke_check(
           configuration: configuration, options: options,
           buffer: buffer, cache_root: cache_root
         )
-        raw_result = runner.run(@argv.empty? ? configuration.paths : @argv)
+        runner = invocation.runner
+        raw_result = invocation.result
         result = apply_baseline_filter(raw_result, configuration, options)
 
         coverage = compute_coverage(runner, configuration, options)
@@ -142,30 +140,24 @@ module Rigor
         exit_code
       end
 
-      # ADR-67 WD6c — `parameter_inference:` and the ADR-46 incremental modes are mutually exclusive in slice 1.
-      # The parameter table introduces cross-file edges (a caller's argument types drive a callee's body
-      # diagnostics) that the per-file dependency recorder does not yet carry, so a cached file whose parameter
-      # seeds changed would serve a stale result. Refuse with a message naming the ADR-46 gap rather than
-      # silently producing unsound incremental diagnostics; the edge wiring is the named follow-up. Returns the
-      # usage exit code on a conflict, or nil to proceed. `--verify-incremental` (the acceptance gate that runs
-      # incremental analysis) is caught here too.
-      def parameter_inference_incremental_conflict(configuration, options)
-        return nil unless configuration.parameter_inference
-        return nil unless options.fetch(:incremental) || options.fetch(:verify_incremental)
-
-        flag = options.fetch(:incremental) ? "--incremental" : "--verify-incremental"
-        @err.puts("rigor: parameter_inference: cannot combine with #{flag} — the call-site parameter table " \
-                  "introduces cross-file caller→callee edges the ADR-46 incremental dependency graph does not " \
-                  "yet record, so a cached file could serve a stale diagnostic. Run a full check (drop " \
-                  "#{flag}), or disable parameter_inference: for this run.")
-        CLI::EXIT_USAGE
-      end
-
       # ADR-46 — the two incremental-analysis check modes both fully handle the run and return an exit code (so `run`
       # short-circuits); returns nil for an ordinary check.
-      def dispatch_special_check_mode(configuration, options, cache_root)
-        return run_verify_incremental(configuration, options, cache_root) if options.fetch(:verify_incremental)
-        return run_incremental_check(configuration, options, cache_root) if options.fetch(:incremental)
+      # A nil return means "not a special mode" — `run` continues with the ordinary check. Editor mode option B
+      # also returns nil when it declines (no reusable snapshot), so the run falls back to single-file scope.
+      def dispatch_special_check_mode(configuration, options, cache_root, buffer)
+        if options.fetch(:verify_incremental)
+          # The gate compares an incremental recheck against a full-run oracle, and a buffer makes the two
+          # disagree by construction (the oracle reads the file on disk). Refusing beats the silent wrong
+          # answer both incremental modes gave a buffer before #146.
+          if buffer
+            @err.puts("rigor: --verify-incremental cannot run against an editor buffer " \
+                      "(--tmp-file / --instead-of); it compares against a full analysis of the files on disk.")
+            return CLI::EXIT_USAGE
+          end
+
+          return run_verify_incremental(configuration, options, cache_root)
+        end
+        return run_incremental_check(configuration, options, cache_root, buffer) if options.fetch(:incremental)
 
         nil
       end
@@ -211,7 +203,7 @@ module Rigor
       # run (plus their dependents), serving the rest from the snapshot; on a miss runs a full baseline. Persists the
       # updated snapshot for the next invocation. Diagnostics are identical to a full run (the `--verify-incremental`
       # gate enforces this); the win is skipping per-file inference for unchanged files.
-      def run_incremental_check(configuration, options, cache_root)
+      def run_incremental_check(configuration, options, cache_root, buffer = nil)
         require_relative "check_runner_factory"
         paths = @argv.empty? ? nil : @argv
         fingerprint = Cache::IncrementalSnapshot.fingerprint(
@@ -225,9 +217,12 @@ module Rigor
           # ADR-46 — thread the same worker-count precedence the standard `check` path uses
           # (CLI `--workers` > `RIGOR_RACTOR_WORKERS` > `parallel.workers:` > 0) so the recheck's closure
           # re-analysis parallelises; the fork pool marshals dependency records back so the graph is sound.
-          workers: CheckRunnerFactory.resolve_workers(options, configuration)
+          workers: CheckRunnerFactory.resolve_workers(options, configuration),
+          buffer: buffer
         )
 
+        return run_editor_mode_option_b(session, snapshot, fingerprint, configuration, options) if buffer
+
         diagnostics, warm = session.run_incremental(snapshot: snapshot, fingerprint: fingerprint)
         # The banner's file count comes from the session's analyzed set (cold analyses all; a warm recheck's
         # `@analyzed` advances to the current file set), so a dedicated probe Runner + `Dir.glob` is no longer
@@ -243,6 +238,33 @@ module Rigor
         result.success? ? 0 : 1
       end
 
+      # Editor mode option B (#146) — `--incremental` plus an editor buffer. The whole project is in scope with
+      # the buffer substituted for one file: the buffer's logical path and its dependents re-analyse, every
+      # other file is served from the snapshot. Before this, the two flags together silently ignored the
+      # buffer and analysed the file on disk, which is a wrong answer rather than a missing feature.
+      #
+      # The session never saves — the buffer's bytes exist only in the editor — so there is no warm state to
+      # build up. That is why a snapshot it cannot reuse means falling back to option A (single-file scope,
+      # the pre-#146 behaviour) instead of running a baseline that would repeat on the next keystroke. The
+      # note tells the user how to get option B: warm the snapshot with a plain `rigor check --incremental`.
+      def run_editor_mode_option_b(session, snapshot, fingerprint, configuration, options)
+        result = session.run_buffer_recheck(snapshot: snapshot, fingerprint: fingerprint)
+        if result.nil?
+          @err.puts("rigor: --incremental has no reusable snapshot for this project; analysing the buffer " \
+                    "alone (run `rigor check --incremental` once to enable whole-project editor mode).")
+          return nil
+        end
+
+        @err.puts("rigor: --incremental editor mode — re-analysed #{result.affected.size} file(s), " \
+                  "#{result.reused.size} served from cache")
+        emit_incremental_fact_surface_notes(session)
+        filtered = apply_baseline_filter(
+          Analysis::Result.new(diagnostics: result.diagnostics, stats: nil), configuration, options
+        )
+        write_result(filtered, options.fetch(:format))
+        filtered.success? ? 0 : 1
+      end
+
       # ADR-88 WD1 — a one-line stderr note when the plugin fact surface (an ADR-9 fact, an ADR-60 producer
       # value, or an `incremental_state_fingerprint` hook) forced a full run: either it CHANGED since the
       # snapshot (a Sorbet sig edit, a schema change) or a contributing plugin declares NO fingerprint surface
@@ -383,11 +405,16 @@ module Rigor
         @err.puts("rigor: #{silenced_count} diagnostic(s) silenced by baseline #{baseline_path}")
       end
 
-      def build_check_runner(configuration:, options:, buffer:, cache_root:)
-        require_relative "check_runner_factory"
-        CheckRunnerFactory.build(
+      # The primary check run, routed through the shared {CheckInvocation} entry point so `rigor doctor` and
+      # `rigor skill describe --deep` reach a result through this exact path rather than re-deriving it (#148).
+      # Required lazily for the reason the old inline `CheckRunnerFactory.build` was: it pulls the inference engine,
+      # and ADR-87 WD4's cache-hit fast path must reach its verdict without it.
+      def invoke_check(configuration:, options:, buffer:, cache_root:)
+        require_relative "check_invocation"
+        CheckInvocation.run(
           configuration: configuration, options: options,
-          buffer: buffer, cache_root: cache_root
+          buffer: buffer, cache_root: cache_root,
+          paths: @argv.empty? ? nil : @argv
         )
       end