rigortype 0.4.0 → 0.4.2

data/lib/rigor/cache/store.rb

@@ -25,7 +25,8 @@ module Rigor
       # On-disk byte-layout version. Bumped on incompatible format changes (independent of
       # {Descriptor::SCHEMA_VERSION}, which covers the descriptor schema rather than the byte layout). v2
       # (ADR-54 WD2): the value payload is zlib-deflated on write and inflated on read — Marshal blobs
-      # compress to 13–16 % at an inflate cost an order of magnitude below their `Marshal.load`. v1 entries
+      # compressed to 13–16 % at zlib's default level (now {DEFLATE_LEVEL}) at an inflate cost an order of
+      # magnitude below their `Marshal.load`. v1 entries
       # fail the header check and read as silent misses; the `schema_version.txt` marker additionally carries
       # this version, so the first writable run after a bump clears the root and reclaims the unreadable
       # bytes.
@@ -60,6 +61,14 @@ module Rigor
 
       STALE_TEMP_FILE_AGE_SECONDS = 60 * 60
 
+      # #1507 — the zlib level for everything written under the cache root: these value payloads (ADR-54 WD2),
+      # the incremental snapshot, and `rigor unused`'s scan bundle. The snapshot and the scan bundle are
+      # rewritten whole whenever a run changed anything, so their deflate is on the edit path. On Mastodon the
+      # default level took 122 ms for the snapshot (9.5 MB raw) and 131 ms for `rbs.environment` (22.8 MB raw);
+      # `BEST_SPEED` takes 38 ms and 49 ms, for a cache about a quarter larger. Inflate reads any level, so the
+      # level is not part of the format.
+      DEFLATE_LEVEL = Zlib::BEST_SPEED
+
       # Header literal: 5-byte ASCII magic, 1-byte separator, 1-byte format version.
       HEADER = "RIGOR\x00#{FORMAT_VERSION.chr}".b.freeze
 
@@ -241,8 +250,13 @@ module Rigor
       # validation always re-checks the filesystem — but a single run only looks up once.
       #
       # `generation_cap:` carries the same producer-declared compaction budget as {#fetch_or_compute}.
+      #
+      # `on_hit:` is called with the entry's stored dependency descriptor on a fresh hit, before the value
+      # is returned, and never on a miss. A caller whose own dependency record must carry a served value's
+      # inputs replays them from it (#1558, {Plugin::Base#cache_for}): a hit runs no block, so nothing else
+      # reports what the value was computed from.
       def fetch_or_validate(producer_id:, key_descriptor:, generation_cap:, params: {},
-                            serialize: nil, deserialize: nil)
+                            serialize: nil, deserialize: nil, on_hit: nil)
         validate_producer_id!(producer_id)
         declare_generation_cap(producer_id, generation_cap)
         disk = ensure_schema_version!
@@ -252,6 +266,7 @@ module Rigor
         cached = path && read_entry(path, deserialize: deserialize)
         if (validated = fresh_pair_value(cached))
           @monitor.synchronize { record(:hits, producer_id) }
+          on_hit&.call(validated[1])
           return validated[0]
         end
 
@@ -285,6 +300,51 @@ module Rigor
         validated[0]
       end
 
+      # ADR-45 WD2 (#1507) — a record-and-validate entry's value WITHOUT validating its dependencies. The
+      # `--incremental` session reads the previous run-result slot to carry forward the rows a narrowed run
+      # cannot re-derive, and that slot is expected to be stale: the edit that started this run is in it. So
+      # the answer here is never served — only rows are taken from it, and they are validated again, with
+      # everything else, the next time the slot is read. nil on a miss, a malformed entry or an unavailable
+      # disk tier. Records neither a hit nor a miss, since nothing was looked up to be served.
+      def peek_unvalidated(producer_id:, key_descriptor:, params: {})
+        validate_producer_id!(producer_id)
+        return nil unless ensure_schema_version!
+
+        key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
+        pair = read_entry(entry_path(producer_id, key))&.value
+        return nil unless pair.is_a?(Array) && pair.size == 2 && pair[1].is_a?(Descriptor)
+
+        pair[0]
+      end
+
+      # ADR-45 WD2 (#1507) — the write half of {#fetch_or_validate} on its own, and unconditional. That method
+      # writes only after it failed to validate what is there; a writer that has just computed an answer of its
+      # own must store THAT answer even when the entry already on disk still validates, because it is the one
+      # the run printed. Same entry format and the same failure contract as {#fetch_or_validate}'s write: a
+      # disk-side failure is swallowed, a value `Marshal` cannot dump raises. Returns whether it wrote.
+      def store_validated(producer_id:, key_descriptor:, generation_cap:, value:, dependencies:, params: {})
+        validate_producer_id!(producer_id)
+        declare_generation_cap(producer_id, generation_cap)
+        return false unless ensure_schema_version!
+
+        key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
+        wrote = try_write_entry(entry_path(producer_id, key), key_descriptor, [value, dependencies])
+        @monitor.synchronize { record(:writes, producer_id) } if wrote
+        wrote
+      end
+
+      # ADR-45 WD2 (#1507) — removes one entry, for a writer that has just superseded it under another key and
+      # knows nothing will ask for it again. Best-effort like every other unlink here; a no-op on a read-only
+      # store.
+      def discard(producer_id:, key_descriptor:, params: {})
+        validate_producer_id!(producer_id)
+        return if @read_only || !ensure_schema_version!
+
+        path = entry_path(producer_id, key_descriptor.cache_key_for(producer_id: producer_id, params: params))
+        unlink_entry_and_shard?(path) if File.file?(path)
+        nil
+      end
+
       # 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
@@ -469,7 +529,7 @@ module Rigor
         FileUtils.mkdir_p(File.dirname(path))
 
         descriptor_bytes = descriptor.to_canonical_bytes
-        value_bytes = Zlib::Deflate.deflate(serialize_value(value, serialize))
+        value_bytes = Zlib::Deflate.deflate(serialize_value(value, serialize), DEFLATE_LEVEL)
 
         body = +"".b
         body << HEADER

data/lib/rigor/cache/value_digest.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Rigor
+  module Cache
+    # Issue #1574 — a digest of a Ruby VALUE, not of its object graph. The same value digests to the same hex
+    # string whether a producer computed it in this process or a cache entry served it from disk, whatever
+    # Strings, Arrays or Hashes happen to share one object.
+    #
+    # `Marshal.dump` is not that function. It writes an object reached twice once and back-references it after,
+    # and a Marshal round trip does not keep that sharing: `Marshal.load` rebuilds a String unfrozen, and
+    # `Hash#[]=` then stores a frozen copy of it as the key rather than the String itself. A frozen String used
+    # both as a row's field and as the key of an index Hash (rigor-sidekiq's `worker_index`, rigor-rails-i18n's
+    # `locale_index`) therefore dumps to one set of bytes when computed and another when served, and a digest of
+    # those bytes flipped the ADR-88 fact-surface fingerprint on every run that switched between the two.
+    #
+    # The encoding below walks the value as a tree. Each node is written as a type tag plus its content, and
+    # sizes are length-prefixed, so the encoding is unambiguous and two values encode alike only when they are
+    # alike. Nothing in it reads identity or frozenness. An object (a Data, a Struct, or any other non-core
+    # object) is always written as its class name and the SHA-256 of its own encoding. That digest is taken once
+    # per object and reused wherever the object is reached again, so a row shared between an index's list and
+    # its by-name Hash is walked once, and the encoding is the same whether an object is shared or not.
+    #
+    # What it keeps, so a changed value still changes the digest:
+    #
+    # - every class distinction Marshal keeps: Integer vs Float, String vs Symbol, a subclass of String / Array /
+    #   Hash / Set vs the base class, and the class name of every Data, Struct and plain object;
+    # - Hash and Set iteration ORDER. Two Hashes equal under `==` but built in another order digest differently.
+    #   A consumer may iterate a fact in order (the first matching row wins), and Marshal keeps the order, so the
+    #   computed and served forms agree on it; digesting the order is the direction that can only over-invalidate;
+    # - a Hash's `default` value, the `compare_by_identity` flag of a Hash or Set, a Range's `exclude_end?`, a
+    #   Regexp's options, and a non-ASCII String's encoding. ASCII-only Strings digest alike in every encoding, as
+    #   `==` has it.
+    #
+    # What it leaves out, although Marshal keeps it:
+    #
+    # - instance variables set on a String, Array, Hash or Set, which `==` ignores too;
+    # - modules an object was `extend`ed with (Marshal refuses singleton methods, and this does not look);
+    # - the hidden fields a core exception subclass keeps beside its message, backtrace and cause
+    #   (`NameError#name`, `SystemCallError#errno`), which reach the digest only through the message, and the
+    #   hidden fields any other C-implemented class keeps outside `instance_variables`.
+    #
+    # A plain object digests as its instance variables, sorted by name; a Data or Struct as its members and its
+    # instance variables; an Exception as its message, backtrace, cause and instance variables. Each is read
+    # through the core class's own method, so a subclass that overrides `to_h`, `each_pair`, `message` or
+    # `backtrace` cannot hide a field. An object that defines `marshal_dump` or `_dump` digests as what that
+    # returns, which is what Marshal keeps of it.
+    #
+    # A value that cannot be digested this way raises {Uncanonicalisable}: an object whose state lives outside
+    # its instance variables (a Proc, an IO, a Mutex: what `Marshal.dump` refuses), a Hash with a default proc, an
+    # anonymous class, or a structure nested more than {MAX_DEPTH} deep, which is what a cycle becomes. A caller
+    # must treat that as "unknown", never as "unchanged".
+    module ValueDigest
+      # The value has no canonical encoding. Fail closed: treat the value as moved.
+      class Uncanonicalisable < StandardError; end
+
+      # Containers nested deeper than this are refused. No fact is this deep; a cyclic structure is infinitely
+      # deep, so this is also the cycle check, and it fires well before the Ruby stack would.
+      MAX_DEPTH = 256
+
+      module_function
+
+      # The hex SHA-256 of `value`'s canonical encoding.
+      def hexdigest(value)
+        Encoder.new.hexdigest(value)
+      rescue SystemStackError
+        raise Uncanonicalisable, "#{value.class} is nested too deeply to digest"
+      end
+
+      # One walk of one value. The canonical bytes are fed to the SHA-256 in chunks, so a multi-megabyte fact
+      # never has its whole encoding in memory at once.
+      class Encoder
+        FLUSH_AT = 64 * 1024
+        private_constant :FLUSH_AT
+
+        def initialize
+          @sha = Digest::SHA256.new
+          @out = String.new(capacity: FLUSH_AT * 2, encoding: Encoding::BINARY)
+          @depth = 0
+          @objects = {}.compare_by_identity # object => the SHA-256 of its encoding
+          @symbols = {} # Symbol => its encoding
+          @plain = {}.compare_by_identity # class => whether Marshal writes its instances as their ivars
+          # The core readers, taken unbound so an override on the value's class cannot change what is read. Held
+          # per walk rather than in constants, which must stay Ractor-shareable (#1064).
+          @data_to_h = Data.instance_method(:to_h)
+          @struct_each_pair = Struct.instance_method(:each_pair)
+          @exception_readers = %i[to_s backtrace cause].map { |name| Exception.instance_method(name) }
+          @instance_variables = Kernel.instance_method(:instance_variables)
+          @instance_variable_get = Kernel.instance_method(:instance_variable_get)
+        end
+
+        def hexdigest(value)
+          write(value)
+          @sha.update(@out)
+          @sha.hexdigest
+        end
+
+        private
+
+        def write(value)
+          case value
+          when String then write_string(value)
+          when Symbol then @out.append_as_bytes(@symbols[value] ||= encoded("y", value.name))
+          when Hash then enter { write_hash(value) }
+          when Array then enter { write_array(value) }
+          when Set then enter { write_set(value) }
+          when Integer then @out.append_as_bytes("i", value.to_s, ";")
+          when nil then @out.append_as_bytes("n")
+          when true then @out.append_as_bytes("t")
+          when false then @out.append_as_bytes("f")
+          else write_other(value)
+          end
+        end
+
+        def write_other(value)
+          case value
+          when Float then @out.append_as_bytes("d", value.to_s, ";")
+          when Range then enter { write_range(value) }
+          when Regexp then write_regexp(value)
+          when Rational then @out.append_as_bytes("q", value.numerator.to_s, "/", value.denominator.to_s, ";")
+          when Complex then enter { write_pair("c", value.real, value.imaginary) }
+          when Module then write_bytes(value.is_a?(Class) ? "k" : "m", class_name(value))
+          else write_object(value)
+          end
+        end
+
+        # The common case, an ASCII-only plain String, is written inline: it is most of the nodes of a large fact.
+        def write_string(value)
+          if value.ascii_only? && value.instance_of?(String)
+            @out.append_as_bytes("s:", value.bytesize.to_s, ":", value)
+          else
+            write_subclass(value, String)
+            write_bytes("s", value)
+          end
+          flush if @out.bytesize >= FLUSH_AT
+        end
+
+        # A tag and a String's bytes, length-prefixed. The encoding is written only for a String with non-ASCII
+        # bytes: ASCII-only Strings compare equal whatever their encoding, and one built from a Symbol is
+        # US-ASCII.
+        def write_bytes(tag, string)
+          @out.append_as_bytes(encoded(tag, string))
+        end
+
+        def encoded(tag, string)
+          encoding = string.ascii_only? ? "" : string.encoding.name
+          "#{tag}#{encoding}:#{string.bytesize}:".b.append_as_bytes(string)
+        end
+
+        def write_hash(value)
+          raise Uncanonicalisable, "a Hash with a default proc" if value.default_proc
+
+          write_subclass(value, Hash)
+          default = value.default
+          @out.append_as_bytes("h", value.compare_by_identity? ? "I" : "", default.nil? ? "" : "D",
+                               value.size.to_s, ":")
+          write(default) unless default.nil?
+          value.each_pair do |key, entry|
+            write(key)
+            write(entry)
+          end
+        end
+
+        def write_array(value)
+          write_subclass(value, Array)
+          @out.append_as_bytes("a", value.size.to_s, ":")
+          value.each { |element| write(element) }
+        end
+
+        def write_set(value)
+          write_subclass(value, Set)
+          @out.append_as_bytes("e", value.compare_by_identity? ? "I" : "", value.size.to_s, ":")
+          value.each { |element| write(element) }
+        end
+
+        def write_range(value)
+          write_pair(value.exclude_end? ? "rx" : "ri", value.begin, value.end)
+        end
+
+        def write_pair(tag, first, second)
+          @out.append_as_bytes(tag)
+          write(first)
+          write(second)
+        end
+
+        def write_regexp(value)
+          @out.append_as_bytes("g", value.options.to_s, ";")
+          write_bytes("s", value.source)
+        end
+
+        # Every object that is not a core value: its class name and the digest of its content, taken once per
+        # object however often the value reaches it.
+        def write_object(value)
+          digest = @objects[value] ||= enter { object_digest(value) }
+          write_bytes("o", class_name(value.class))
+          @out.append_as_bytes(digest)
+        end
+
+        # The object's content, walked into a SHA-256 of its own. A `marshal_dump` / `_dump` hook decides what
+        # Marshal keeps of an object, so it decides the digest too; otherwise the object is its members (a Data or
+        # Struct) or its message, backtrace and cause (an Exception), then its instance variables.
+        def object_digest(value)
+          outer_sha = @sha
+          outer_out = @out
+          @sha = Digest::SHA256.new
+          @out = +"".b
+          write_content(value)
+          @sha.update(@out)
+          @sha.digest
+        ensure
+          @sha = outer_sha
+          @out = outer_out
+        end
+
+        def write_content(value)
+          if value.respond_to?(:marshal_dump, true)
+            @out.append_as_bytes("U")
+            write(value.send(:marshal_dump))
+          elsif value.is_a?(Time)
+            # `Time#_dump` keeps the offset and zone as instance variables on the String it returns, which the
+            # String encoding leaves out.
+            @out.append_as_bytes("z")
+            [value.to_r, value.utc_offset, value.zone].each { |part| write(part) }
+          elsif value.respond_to?(:_dump, true)
+            @out.append_as_bytes("u")
+            write(value.send(:_dump, -1))
+          else
+            write_members(value)
+          end
+        end
+
+        def write_members(value)
+          case value
+          when Data then write_fields("D", @data_to_h.bind_call(value))
+          when Struct then write_fields("T", struct_members(value))
+          when Exception then write_exception(value)
+          else
+            assert_plain(value)
+            @out.append_as_bytes("V")
+          end
+          write_fields("@", instance_variables(value))
+        end
+
+        def struct_members(value)
+          members = []
+          @struct_each_pair.bind_call(value) { |name, field| members << [name, field] }
+          members
+        end
+
+        # Marshal keeps an exception's message, backtrace and cause in hidden instance variables, which
+        # `instance_variables` does not list: two exceptions that differ only in their message would otherwise
+        # digest alike. A plugin that records parse errors as exceptions depends on the message moving the digest.
+        def write_exception(value)
+          @out.append_as_bytes("X")
+          @exception_readers.each { |reader| write(reader.bind_call(value)) }
+        end
+
+        def instance_variables(value)
+          @instance_variables.bind_call(value).sort.map { |name| [name, @instance_variable_get.bind_call(value, name)] }
+        end
+
+        def write_fields(tag, pairs)
+          fields = pairs.to_a
+          @out.append_as_bytes(tag, fields.size.to_s, ":")
+          fields.each do |name, field|
+            write(name.to_sym)
+            write(field)
+          end
+        end
+
+        # An object's instance variables are all of its state only when Marshal writes it that way. `Marshal.dump`
+        # refuses a Proc, an IO, a Mutex or a Thread (C-level state and no `_dump_data`), and so does this. The
+        # depth limit of 1 makes the check cost one object: Marshal decides whether it can write the object
+        # before it writes any instance variable, and raises `ArgumentError` on reaching the first one. It is
+        # asked once per class, since whether a class keeps state outside Ruby does not vary by instance.
+        #
+        # The `ArgumentError` cannot tell a listed instance variable from a hidden one that a C-implemented class
+        # keeps, so an Exception, whose message and backtrace are hidden, is read explicitly above instead.
+        def assert_plain(value)
+          klass = value.class
+          plain = @plain.fetch(klass) do
+            @plain[klass] = begin
+              Marshal.dump(value, 1)
+              true
+            rescue ArgumentError # "exceed depth limit": the object itself was written
+              true
+            rescue TypeError
+              false
+            end
+          end
+          raise Uncanonicalisable, "#{klass} keeps its state outside its instance variables" unless plain
+        end
+
+        # A subclass of a core value keeps its class through Marshal, so the class is part of the value.
+        def write_subclass(value, base)
+          klass = value.class
+          write_bytes("C", class_name(klass)) unless klass.equal?(base)
+        end
+
+        def class_name(klass)
+          klass.name || raise(Uncanonicalisable, "an anonymous #{klass.class.name.downcase} has no name to digest")
+        end
+
+        def enter
+          raise Uncanonicalisable, "a value nested deeper than #{MAX_DEPTH} (a cycle?)" if @depth >= MAX_DEPTH
+
+          @depth += 1
+          begin
+            result = yield
+          ensure
+            @depth -= 1
+          end
+          flush if @out.bytesize >= FLUSH_AT
+          result
+        end
+
+        def flush
+          @sha.update(@out)
+          @out.clear
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/annotate_command.rb

@@ -100,7 +100,12 @@ module Rigor
         # in `#annotate` raise `invalid byte sequence in US-ASCII`. Ruby source is UTF-8 by convention (the parser's own
         # assumption absent a magic comment).
         source = File.read(file, mode: "r:bom|utf-8")
+        # Prism parses the ORIGINAL bytes, so a `# -*- coding: -*-` file is read in its own encoding. Only the text the
+        # line-wise regexps below see is scrubbed: a byte invalid in UTF-8 (a comment, `__END__` data, a non-UTF-8
+        # file) would make them raise.
+        # Scrubbing is byte-for-byte (`?` per bad byte), so Prism's positions still address it.
         parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
+        source = source.scrub { |bytes| "?" * bytes.bytesize } unless source.valid_encoding?
         return 1 if parse_errors?(parse_result, file)
 
         # `converged_loop_recording` re-records fixpoint-tracked loop bodies from their converged (post-writeback)

data/lib/rigor/cli/baseline_command.rb

@@ -126,8 +126,10 @@ module Rigor
 
       def collect_diagnostics(configuration, _options)
         cache_store = Cache::Store.new(root: configuration.cache_path)
-        # IMPORTANT: do NOT activate the existing baseline when generating a fresh one — otherwise the new file records
-        # the post-filter (silenced) diagnostic set, which is empty after a successful first run.
+        # The generating run is the loaded configuration with `baseline:` off (#1777): every other key shapes the
+        # diagnostic set `rigor check` reports, so it must shape the recorded one too. The baseline filter itself is
+        # applied CLI-side by `check` (`CheckCommand#apply_baseline_filter`), never by the runner; clearing it here is
+        # defensive.
         configuration_for_generation = override_configuration_baseline_off(configuration)
         runner = Analysis::Runner.new(
           configuration: configuration_for_generation,
@@ -137,23 +139,10 @@ module Rigor
         runner.run(configuration_for_generation.paths).diagnostics
       end
 
+      # The loaded configuration with only `baseline` disabled (#1777): any other key can change the
+      # diagnostic set, and the baseline must record the set `rigor check` will then report.
       def override_configuration_baseline_off(configuration)
-        # Synthesise a new Configuration with `baseline` explicitly disabled. The original Configuration is frozen-ish
-        # so we round-trip through the constructor with an override hash.
-        defaults = Configuration::DEFAULTS.merge(
-          "paths" => configuration.paths,
-          "exclude" => configuration.exclude_patterns,
-          "plugins" => configuration.plugins,
-          "disable" => configuration.disabled_rules,
-          "libraries" => configuration.libraries,
-          "signature_paths" => configuration.signature_paths,
-          "pre_eval" => configuration.pre_eval,
-          "severity_profile" => configuration.severity_profile.to_s,
-          "severity_overrides" => configuration.severity_overrides,
-          "baseline" => false,
-          "cache" => { "path" => configuration.cache_path }
-        )
-        Configuration.new(defaults)
+        configuration.without_baseline
       end
 
       # ---- dump --------------------------------------------------

data/lib/rigor/cli/check_command.rb

@@ -59,8 +59,8 @@ module Rigor
         # ADR-87 WD4 — try to serve the whole run from the ADR-45 cache before booting the engine. A hit boots
         # only CLI + config + cache + digest code (no `rigor/inference`), skipping the plugin prepass + env
         # build entirely.
-        probed = try_run_cache_hit(configuration, options, buffer, cache_root)
-        return finalize_cache_hit(probed, configuration, options, config_warnings) unless probed.nil?
+        served = serve_from_run_cache(configuration, options, buffer, cache_root, config_warnings)
+        return served unless served.nil?
 
         load_check_dependencies
         special = dispatch_special_check_mode(configuration, options, cache_root, buffer)
@@ -113,6 +113,16 @@ module Rigor
         false
       end
 
+      # The exit code of a run served whole from a run-result slot, engine-free, or nil to run the engine: the
+      # plain slot for an ordinary check (ADR-87 WD4), the incremental session's for `--incremental` (ADR-45 WD2).
+      def serve_from_run_cache(configuration, options, buffer, cache_root, config_warnings)
+        probed = try_run_cache_hit(configuration, options, buffer, cache_root)
+        return finalize_cache_hit(probed, configuration, options, config_warnings) unless probed.nil?
+
+        hit = try_incremental_run_hit(configuration, options, buffer, cache_root)
+        hit && finalize_incremental_hit(hit, configuration, options)
+      end
+
       # ADR-87 WD4 — attempt the boot-slimming run-cache hit. Returns the cached {Analysis::Result} (severity
       # profile applied, no stats — matching a cache-served `Runner#run`) on a hit, or nil to fall through to
       # the full engine path. Only an ordinary sequential check whose result IS cache-served the same way is
@@ -141,8 +151,9 @@ module Rigor
 
       # Any signal that per-file analysis would run in a worker pool (CLI `--workers`, the env override, or the
       # config default). Deliberately over-declines (a false positive only forgoes the fast lane); mirrors
-      # {CheckRunnerFactory.resolve_workers} without requiring it (that pulls in the engine).
-      def pool_workers_configured?(options, configuration)
+      # {CheckRunnerFactory.resolve_workers} without requiring it (that pulls in the engine). `unreadable` is the
+      # answer for a count that does not parse, which the full path's resolver raises on.
+      def pool_workers_configured?(options, configuration, unreadable: false)
         cli = options[:workers]
         return Integer(cli).positive? if cli
 
@@ -151,7 +162,41 @@ module Rigor
 
         configuration.parallel_workers.positive?
       rescue ArgumentError
-        false
+        unreadable
+      end
+
+      # ADR-45 WD2 (#1507) — `rigor check --incremental`'s engine-free null run: serve the run-result slot the
+      # incremental session wrote after its last run, when every row of it still validates. Returns an
+      # {Analysis::IncrementalRunSlot::Hit}, or nil to run the full incremental path.
+      def try_incremental_run_hit(configuration, options, buffer, cache_root)
+        return nil unless incremental_run_hit_eligible?(configuration, options, buffer)
+
+        require_relative "../analysis/incremental_run_slot"
+        Analysis::IncrementalRunSlot.serve(
+          configuration: configuration, cache_root: cache_root, paths: @argv.empty? ? configuration.paths : @argv
+        )
+      end
+
+      # A plain `--incremental` run the session would answer as a warm recheck and write a slot for. Every other
+      # shape declines, and the full path handles it exactly as before: an editor buffer (never saved), `--no-cache`
+      # (no store to hold a slot), `--verify-incremental`, a worker pool (the session writes no slot for one: a
+      # worker's plugin reads never reach the process that records them), and `--explain`, which the session
+      # ignores today (#1533) — the slot is keyed without it, so the probe declines rather than answer for a flag
+      # its writer never saw. The rest mirror the plain probe: `--coverage`, `--cache-stats` and the
+      # `RIGOR_*_TRACE` probes each want the full path's own output.
+      def incremental_run_hit_eligible?(configuration, options, buffer)
+        options.fetch(:incremental) && buffer.nil? &&
+          !options.fetch(:no_cache) && !options.fetch(:explain) && !options.fetch(:coverage) &&
+          !options.fetch(:cache_stats) && !options.fetch(:verify_incremental) &&
+          !pool_workers_configured?(options, configuration, unreadable: true) &&
+          ENV["RIGOR_BUDGET_TRACE"].to_s.empty? && ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+      end
+
+      # The tail {#run_incremental_check} gives a warm run, from the slot's answer: the same banner, baseline
+      # filter, output and exit code. No fact-surface note, since a warm run never has one.
+      def finalize_incremental_hit(hit, configuration, options)
+        report_incremental_run(true, hit.file_count)
+        write_incremental_result(hit.result.diagnostics, configuration, options)
       end
 
       # ADR-87 WD4 — the engine-free tail for a cache-served hit: baseline filter + output + exit code,
@@ -237,9 +282,15 @@ module Rigor
       def run_incremental_check(configuration, options, cache_root, buffer = nil)
         require_relative "check_runner_factory"
         paths = @argv.empty? ? nil : @argv
-        fingerprint = Cache::IncrementalSnapshot.fingerprint(
-          configuration: configuration, roots: paths || configuration.paths
-        )
+        # `--no-cache` is a cold run that touches no persistent state: a nil fingerprint is the session's "uncomputable
+        # inputs" signal, so it neither loads the snapshot, nor saves it, nor writes the run-result slot.
+        fingerprint = if options.fetch(:no_cache)
+                        nil
+                      else
+                        Cache::IncrementalSnapshot.fingerprint(
+                          configuration: configuration, roots: paths || configuration.paths
+                        )
+                      end
         snapshot = Cache::IncrementalSnapshot.new(root: cache_root)
         store = incremental_cache_store(configuration, options, cache_root)
         session = Analysis::IncrementalSession.new(
@@ -258,12 +309,23 @@ module Rigor
         # 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
         # built just to size the banner (recon §3 — the analysis tree was expanded three times per recheck).
-        @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
-                  "(#{session.analyzed_files.size} files)")
+        report_incremental_run(warm, session.analyzed_files.size)
         emit_incremental_fact_surface_notes(session)
         write_incremental_cache_stats(session, cache_root, store, options.fetch(:format)) if
           options.fetch(:cache_stats)
 
+        write_incremental_result(diagnostics, configuration, options)
+      end
+
+      def report_incremental_run(warm, file_count)
+        @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
+                  "(#{file_count} files)")
+      end
+
+      # The incremental tail, shared by the full path and the ADR-45 WD2 slot hit so a served run prints exactly
+      # what the full path would. It is not the ordinary check's tail — no `config_warnings` block in the JSON,
+      # no CI-detected annotations, no `--baseline-strict` verdict — which is why the hit cannot reuse that one.
+      def write_incremental_result(diagnostics, configuration, options)
         result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration,
                                        options)
         write_result(result, options.fetch(:format), fail_on: options.fetch(:fail_on))
@@ -282,8 +344,13 @@ module Rigor
       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).")
+          if options.fetch(:no_cache)
+            @err.puts("rigor: --no-cache skips the incremental snapshot, so the buffer is analysed on its own " \
+                      "(no whole-project editor mode).")
+          else
+            @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).")
+          end
           return nil
         end
 
@@ -523,7 +590,10 @@ module Rigor
             options[:coverage] = true
           end
           opts.on("--clear-cache", "Remove the .rigor/cache directory before running") { options[:clear_cache] = true }
-          opts.on("--no-cache", "Disable the persistent cache for this run") { options[:no_cache] = true }
+          opts.on("--no-cache",
+                  "Disable the persistent cache for this run (with --incremental: no snapshot is read or written)") do
+            options[:no_cache] = true
+          end
           opts.on("--[no-]stats",
                   "Print run summary (files, classes, memory, wall time) to stderr (default: on)") do |value|
             options[:stats] = value
@@ -615,9 +685,10 @@ module Rigor
         # ADR-103 WD15 — captured before `DEFAULTS.merge` below folds "no `effects:` key" and "`effects:
         # false`" into the same value; see `Configuration.load`'s identical capture.
         effects_key_present = data.key?("effects")
+        target_ruby_key_present = data.key?("target_ruby")
         data = data.dup
         data["plugins"] = inject_treat_all_as_inline_rbs(Array(data["plugins"]))
-        Configuration.new(Configuration::DEFAULTS.merge(data), effects_key_present)
+        Configuration.new(Configuration::DEFAULTS.merge(data), effects_key_present, target_ruby_key_present)
       end
 
       # ADR-50 § WD2 — applies the `--bleeding-edge[=ids]` / `--no-bleeding-edge` CLI selection over the configured

data/lib/rigor/cli/doctor_command.rb

@@ -246,7 +246,7 @@ module Rigor
       def real_or_expanded(path)
         File.realpath(path)
       rescue StandardError
-        File.expand_path(path)
+        File.absolute_path(path)
       end
 
       # ADR-25 carry-over — the plain `bundle install` layout. {Environment::BundleSigDiscovery} detects a