rigortype 0.3.9 → 0.4.1

data/lib/rigor/analysis/dependency_recorder.rb

@@ -22,12 +22,52 @@ module Rigor
       # It is a STACK because captures nest (a memoised callee body evaluating another memo-miss callee): an
       # outer capture must also see the inner window's reads, or its read-set would be non-transitive and a
       # later replay would drop the nested callee's edges.
+      #
+      # Every event reaches every capture open at the time, so an inner capture's sets are always a subset of
+      # each outer one's: the inner capture was pushed after the outer, and everything added since reached both.
+      # {withhold} swaps in a fresh stack and restores this one untouched, so it keeps the property too.
+      # {tee_read} and {tee_missing} rely on it to stop at the first capture that already holds an event.
       CAPTURE_KEY = :__rigor_dependency_capture_stack__
       private_constant :CAPTURE_KEY
 
+      # The read sets an {Accumulator} or {Capture} already holds in full, by identity: replayed into it, or
+      # captured by a window it saw every event of ({capture}). Both only ever grow and a {ReadSet} is frozen,
+      # so replaying such a set into the same target again adds nothing. Recording replays the same stored
+      # read set many times over: on Rigor's own `lib`, 71% of the replays into a consumer repeated one
+      # already made into it, carrying 65% of the replayed events.
+      module ReplayMemory
+        def holds?(read_set)
+          !@held.nil? && @held.key?(read_set)
+        end
+
+        # Called only once every event of `read_set` is in, so a replay that raises part-way leaves the
+        # target unmarked and the next replay adds the rest.
+        def hold!(read_set)
+          (@held ||= {}.compare_by_identity)[read_set] = true
+        end
+      end
+
+      # #1590 — the resolution-chain filings ({file_chain_once}) an {Accumulator} or {Capture} already holds in
+      # full: per chain (by identity; the table holds the chain, so its identity cannot be reused while the target
+      # lives), the starts filed from it and the discovery index each was filed against. A filing is a pure
+      # function of those three, so filing it again into the same target adds nothing.
+      module ChainMemory
+        def chain_filed?(chain, start, discovery)
+          table = @chains&.[](chain)
+          !table.nil? && table.key?(start) && table[start].equal?(discovery)
+        end
+
+        def chain_filed!(chain, start, discovery)
+          ((@chains ||= {}.compare_by_identity)[chain] ||= {})[start] = discovery
+        end
+      end
+
       # Mutable per-consumer accumulator. Frozen into a {Record} snapshot when `record_for` returns.
       class Accumulator
-        attr_reader :consumer, :sources, :missing, :symbol_sources, :ancestry_sources
+        include ReplayMemory
+        include ChainMemory
+
+        attr_reader :consumer, :sources, :missing, :symbol_sources, :ancestry_sources, :suspensions
 
         def initialize(consumer)
           @consumer = consumer
@@ -39,6 +79,15 @@ module Rigor
           # file-granularity by nature (a superclass edge touches the whole class).
           @symbol_sources = Hash.new { |h, k| h[k] = Set.new }
           @ancestry_sources = Set.new
+          @held = nil
+          @chains = nil
+          @suspensions = 0
+        end
+
+        # Counts the {record_for} windows of another consumer opened while this one was recording, which is
+        # when a capture window stops seeing only this consumer's events.
+        def suspend!
+          @suspensions += 1
         end
 
         def snapshot
@@ -65,16 +114,28 @@ module Rigor
       # self-read filter is applied at {replay} time, mirroring {read_site}.
       ReadSet = Data.define(:reads, :missing)
 
+      # What every window that saw nothing closes into: most windows {RbsDispatch}'s recording-mode memos
+      # open see nothing, and they need neither a copy of two empty Sets nor a place in a target's
+      # {ReplayMemory}.
+      EMPTY_READ_SET = Ractor.make_shareable(ReadSet.new(reads: Set.new, missing: Set.new))
+
       # Mutable capture accumulator; snapshot into a frozen {ReadSet} when the capture window closes.
       class Capture
+        include ReplayMemory
+        include ChainMemory
+
         attr_reader :reads, :missing
 
         def initialize
           @reads = Set.new
           @missing = Set.new
+          @held = nil
+          @chains = nil
         end
 
         def snapshot
+          return EMPTY_READ_SET if reads.empty? && missing.empty?
+
           ReadSet.new(reads: reads.dup.freeze, missing: missing.dup.freeze)
         end
       end
@@ -94,6 +155,7 @@ module Rigor
       # the previous recorder on exit.
       def record_for(consumer)
         previous = Thread.current[KEY]
+        previous&.suspend!
         accumulator = Accumulator.new(consumer.to_s)
         Thread.current[KEY] = accumulator
         @mutex.synchronize { @active_count += 1 }
@@ -109,6 +171,13 @@ module Rigor
         @active_count.positive?
       end
 
+      # Whether THIS thread's reads reach an accumulator: inside {record_for}, including a {withhold}
+      # window. {active?} answers for the process and is the cheap gate; this is the exact one, for a caller
+      # that must know whether an empty {capture} means "nothing to record" or "nothing was watching".
+      def recording?
+        !Thread.current[KEY].nil?
+      end
+
       # ADR-84 WD2 — runs the block under an observe-and-forward capture window and returns
       # `[block_result, read_set]`. Reads recorded during the window reach the current consumer's accumulator
       # unchanged (forwarding) and are additionally collected into the returned frozen {ReadSet} (observing),
@@ -116,6 +185,8 @@ module Rigor
       # {active?}; opening a capture with no accumulator active would collect reads no run is recording.
       def capture
         captures = (Thread.current[CAPTURE_KEY] ||= [])
+        accumulator = Thread.current[KEY]
+        suspensions = accumulator&.suspensions
         capture = Capture.new
         captures.push(capture)
         begin
@@ -123,6 +194,48 @@ module Rigor
         ensure
           captures.pop
         end
+        read_set = capture.snapshot
+        note_captured(read_set, captures, accumulator, suspensions)
+        [result, read_set]
+      end
+
+      # Every event a window saw also reached the window outside it, and was filed for the consumer that was
+      # recording at the time, except the consumer's own self-reads, which a replay into that consumer drops
+      # anyway. So the enclosing window holds the closed window's read set in full, and so does the consumer's
+      # accumulator when no other consumer recorded in between. Noting that lets a later replay of the set
+      # there skip a pass that could add nothing: on Rigor's own `lib`, two thirds of the first replays into a
+      # consumer were of a set captured while that consumer was recording.
+      def note_captured(read_set, captures, accumulator, suspensions)
+        return if read_set.equal?(EMPTY_READ_SET)
+
+        captures.last&.hold!(read_set)
+        return unless accumulator && Thread.current[KEY].equal?(accumulator)
+        return unless accumulator.suspensions == suspensions
+
+        accumulator.hold!(read_set)
+      end
+      private_class_method :note_captured
+
+      # Issue #992 — runs the block with its reads DETACHED from the current consumer (and from any enclosing
+      # capture) and returns `[block_result, read_set]`, so a caller that learns only afterwards whether its
+      # answer depended on those reads can {replay} them or drop them. `call.wrong-arity` reads a class's whole
+      # envelope bucket to decide a call that turns out to fit, and recording that as a file-level ancestry
+      # edge would make every correct call on a project class re-check on any edit to the class's files.
+      # Returns a nil read set when no recording is active.
+      def withhold
+        previous = Thread.current[KEY]
+        return [yield, nil] if previous.nil?
+
+        previous_captures = Thread.current[CAPTURE_KEY]
+        capture = Capture.new
+        Thread.current[KEY] = Accumulator.new(previous.consumer)
+        Thread.current[CAPTURE_KEY] = [capture]
+        begin
+          result = yield
+        ensure
+          Thread.current[KEY] = previous
+          Thread.current[CAPTURE_KEY] = previous_captures
+        end
         [result, capture.snapshot]
       end
 
@@ -131,22 +244,75 @@ module Rigor
       # capture so an enclosing capture window stays transitive when a memo hit substitutes for a body walk.
       def replay(read_set)
         accumulator = Thread.current[KEY]
-        return if accumulator.nil? || read_set.nil?
+        return if accumulator.nil? || read_set.nil? || read_set.equal?(EMPTY_READ_SET)
 
         captures = Thread.current[CAPTURE_KEY]
+        tee_read_set(captures, read_set) if captures && !captures.empty?
+        # Each set keeps its own insertion order whichever target is filled first, and a skipped replay is one
+        # that could only have re-added what the target already holds.
+        return if accumulator.holds?(read_set)
+
+        consumer = accumulator.consumer
         read_set.reads.each do |pair|
-          captures&.each { |c| c.reads.add(pair) }
           path, symbol = pair
-          next if path == accumulator.consumer
-
-          accumulate_read(accumulator, path, symbol)
+          accumulate_read(accumulator, path, symbol) unless path == consumer
         end
-        read_set.missing.each do |entry|
-          captures&.each { |c| c.missing.add(entry) }
-          accumulator.missing << entry
+        missing = accumulator.missing
+        read_set.missing.each { |entry| missing << entry }
+        accumulator.hold!(read_set)
+      end
+
+      # #1590 — runs the block, which files a resolution chain's edges from entry `start` (nil: the root and the
+      # whole chain) against `discovery`, unless the current consumer's accumulator AND the innermost open capture
+      # already hold that filing; the block files the same edges every time, so skipping it there changes nothing.
+      # Every event reaches every capture open at the time (see CAPTURE_KEY), so the innermost capture holding the
+      # filing means every open capture does. A filing the accumulator holds but a capture opened since does not is
+      # filed again, so that capture's read set, replayed elsewhere, still carries it; and {withhold} starts a fresh
+      # accumulator and capture, which hold nothing. The marks are made only once the block has run, as {hold!}'s are.
+      def file_chain_once(chain, start, discovery)
+        accumulator = Thread.current[KEY]
+        return if accumulator.nil?
+
+        captures = Thread.current[CAPTURE_KEY]
+        open = captures && !captures.empty?
+        if accumulator.chain_filed?(chain, start, discovery) &&
+           (!open || captures.last.chain_filed?(chain, start, discovery))
+          return
         end
+
+        yield
+        accumulator.chain_filed!(chain, start, discovery)
+        captures.each { |capture| capture.chain_filed!(chain, start, discovery) } if open
       end
 
+      # {replay}'s share for the open captures. The innermost capture having seen `read_set` already means every
+      # open capture holds all of it (see CAPTURE_KEY).
+      def tee_read_set(captures, read_set)
+        innermost = captures.last
+        return if innermost.holds?(read_set)
+
+        read_set.reads.each { |pair| tee_read(captures, pair) }
+        read_set.missing.each { |entry| tee_missing(captures, entry) }
+        innermost.hold!(read_set)
+      end
+      private_class_method :tee_read_set
+
+      # Adds a read pair to the open captures, innermost first, and stops at the first capture that already holds
+      # it: every capture outside that one holds it too (see CAPTURE_KEY). The capture sets end up exactly as
+      # adding it to every capture would leave them, in the same insertion order.
+      def tee_read(captures, pair)
+        index = captures.size - 1
+        index -= 1 while index >= 0 && captures[index].reads.add?(pair)
+      end
+      private_class_method :tee_read
+
+      # {tee_read} for a name-keyed `missing` entry.
+      def tee_missing(captures, entry)
+        index = captures.size - 1
+        index -= 1 while index >= 0 && captures[index].missing.add?(entry)
+      end
+      private_class_method :tee_missing
+
       # Records that the current consumer read a declaration / body whose definition site is `path_line` (a
       # `"path:line"` String, or nil). When `symbol` is given (a `"ClassName#method"` String), the read is a
       # method-call edge and is recorded at symbol granularity in `symbol_sources` in addition to the coarse
@@ -158,16 +324,26 @@ module Rigor
         accumulator = Thread.current[KEY]
         return if accumulator.nil? || path_line.nil?
 
-        path = path_line.split(":", 2).first
+        path = site_path(path_line)
         return unless path
 
         captures = Thread.current[CAPTURE_KEY]
-        captures&.each { |c| c.reads.add([path, symbol].freeze) }
+        tee_read(captures, [path, symbol].freeze) if captures && !captures.empty?
         return if path == accumulator.consumer
 
         accumulate_read(accumulator, path, symbol)
       end
 
+      # The path part of a `"path:line"` site: what `path_line.split(":", 2).first` answers, without the Array
+      # and the discarded line String.
+      def site_path(path_line)
+        colon = path_line.byteindex(":")
+        return path_line.byteslice(0, colon) if colon
+
+        path_line.empty? ? nil : path_line.dup
+      end
+      private_class_method :site_path
+
       # Records a NAME-KEYED cross-file dependency: this consumer's answer depends on what the project makes
       # of `name` under `kind`, so a recheck must re-analyze it when that changes. The recorded key is
       # inverted into `negative_dependents` and matched against the producer for its kind.
@@ -183,10 +359,38 @@ module Rigor
         return if accumulator.nil?
 
         entry = "#{kind}:#{name}"
-        Thread.current[CAPTURE_KEY]&.each { |c| c.missing.add(entry) }
+        captures = Thread.current[CAPTURE_KEY]
+        tee_missing(captures, entry) if captures && !captures.empty?
         accumulator.missing.add(entry)
       end
 
+      # {read_name} keyed on the LAST SEGMENT of a constant path, `name.delete_prefix("::").split("::").last`,
+      # which is the key the `class:` and `constant:` name edges use. The segment is found by scanning for the
+      # last separator rather than by building every segment: on Rigor's own `lib` that split cost about seven
+      # objects a call over half a million calls. A name the scan could read differently from `split` (one
+      # that is not ASCII, or carries a run of colons or a trailing one) takes `split`'s answer.
+      def read_last_segment(kind, name)
+        return if Thread.current[KEY].nil?
+
+        segment = last_segment(name)
+        read_name(kind, segment) if segment
+      end
+
+      def last_segment(name)
+        return name.delete_prefix("::").split("::").last unless plain_constant_path?(name)
+
+        start = name.start_with?("::") ? 2 : 0
+        separator = name.rindex("::")
+        cut = separator && separator >= start ? separator + 2 : start
+        cut == name.bytesize ? nil : name.byteslice(cut, name.bytesize - cut)
+      end
+      private_class_method :last_segment
+
+      def plain_constant_path?(name)
+        name.ascii_only? && !name.end_with?(":") && !name.include?(":::")
+      end
+      private_class_method :plain_constant_path?
+
       # The miss-only spelling of {read_name}: a cross-file lookup of `name` (kind `:method` / `:class` /
       # `:toplevel` / …) that resolved to nothing. Kept as the name the internal spec's negative-edge
       # contract uses.
@@ -194,13 +398,14 @@ module Rigor
         read_name(kind, name)
       end
 
-      # The positive-edge aggregation shared by {read_site} and {replay}.
+      # The positive-edge aggregation shared by {read_site} and {replay}. `sources` is the union of the other
+      # two tables' paths, and this is the only writer of all three, so a read the finer table already holds is
+      # already in `sources` and costs one Set probe instead of two.
       def accumulate_read(accumulator, path, symbol)
-        accumulator.sources << path
         if symbol
-          accumulator.symbol_sources[path] << symbol
-        else
-          accumulator.ancestry_sources << path
+          accumulator.sources << path if accumulator.symbol_sources[path].add?(symbol)
+        elsif accumulator.ancestry_sources.add?(path)
+          accumulator.sources << path
         end
       end
       private_class_method :accumulate_read

data/lib/rigor/analysis/fact_store.rb

@@ -21,8 +21,17 @@ module Rigor
         # #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.
+        #
+        # #1055 — the table is a class ivar holding an unshareable Hash, and a non-main Ractor may neither
+        # write one nor read one. A pool worker therefore pays the allocation instead of sharing the
+        # instance: the interning is a per-process ALLOCATION saving, never an identity contract (`Target`
+        # is a `Data` value and compares by value), so declining it changes nothing a caller can observe.
+        # The guard is a C-level predicate on the hot path, which is what keeps the sequential run's
+        # saving intact.
         def self.local(name)
           name = name.to_sym
+          return new(kind: :local, name: name) unless Ractor.main?
+
           @local_targets[name] ||= new(kind: :local, name: name)
         end
         @local_targets = {}

data/lib/rigor/analysis/incremental.rb

@@ -120,6 +120,32 @@ module Rigor
         appeared.freeze
       end
 
+      # Issue #1120 — the method names whose refinements moved in this edit: a `[refined class, method, refining
+      # module]` entry that appeared in, or vanished from, any file in `paths`. A consumer whose
+      # `call.undefined-method` answer consulted the refinement table recorded a `refinement:<method>` edge
+      # whichever way it answered, because the answer is a function of the whole project's refinements of that
+      # name. `paths` MUST include removed files, whose whole before-table vanished. `before` / `after` map a
+      # path to that file's `{refined class => {method => [modules]}}` table (nil when it refines nothing).
+      def changed_refinement_names(paths, before, after)
+        moved = Set.new
+        paths.each do |path|
+          entries_before = refinement_entries(before[path])
+          entries_after = refinement_entries(after[path])
+          (entries_before ^ entries_after).each { |(_refined, method_name, _module)| moved << method_name }
+        end
+        moved.freeze
+      end
+
+      def refinement_entries(table)
+        entries = Set.new
+        table&.each do |refined, methods|
+          methods.each do |method_name, modules|
+            modules.each { |refining| entries << [refined, method_name, refining] }
+          end
+        end
+        entries
+      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

data/lib/rigor/analysis/incremental_run_slot/write_guard.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "securerandom"
+
+require_relative "../incremental_run_slot"
+require_relative "../../cache/file_digest"
+require_relative "../../cache/incremental_snapshot"
+
+module Rigor
+  module Analysis
+    module IncrementalRunSlot
+      # ADR-45 WD2 (#1507) — whether a run may record its answer at all. Some of a slot's rows are built when the
+      # run ENDS rather than when it reads, and each of those must still describe the tree the run analysed: a
+      # save that lands while the run reads — an editor's, a `bundle install`'s, a `mkdir` — would otherwise leave
+      # the slot vouching for a tree the analysis never saw, and the probe would serve the pre-save answer against
+      # the post-save tree.
+      #
+      # So the session takes a mark before the run reads anything ({.start}) and asks {#admits?} about those rows
+      # before it writes. A row recorded as the run read (a plugin's read, a listing it took) needs no guard: a
+      # later save leaves it stale, and validation says so.
+      #
+      # The mark is the filesystem's own clock, read off the change time of a file written for the purpose: a
+      # timestamp compared across clocks misses an edit that lands inside a coarse filesystem's tick, and change
+      # times (unlike modification times) cannot be set back by `cp -p` or `touch -d`. One clock means one
+      # filesystem, so the mark is taken only when the store is on the project's filesystem, and a row the key
+      # does not pin refuses the write when it is on any other. Declining to write is always safe; it leaves the
+      # next null run on the full path.
+      #
+      # A filesystem's change times tick coarsely (a millisecond or more on ext4 and tmpfs), so a file saved just
+      # before the stamp can carry the stamp's own change time. {#admits?} refuses a change time at or after the
+      # mark, since a save after the stamp in the same tick reads the same; taking the first stamp as the mark
+      # would therefore refuse every save that landed shortly before the run, and no slot would be written. So the
+      # mark is taken on a tick boundary: stamps are written until one carries a later change time than the first,
+      # and that later change time is the mark. Everything saved before the run started carries a change time no
+      # later than the first stamp, hence before the mark; everything saved after the mark carries at least the
+      # mark. The wait is bounded ({TICK_WAIT_LIMIT}); a filesystem that does not tick within it takes no mark,
+      # which is the safe answer. A filesystem whose first stamp lands on a whole second (HFS+, FAT, ext3) ticks too
+      # coarsely to wait out and takes no mark at once.
+      #
+      # Where the change time is not the time of the write, the mark says nothing, and the guard takes none or
+      # cannot tell: native Windows, where a change time is the creation time, takes no mark; a network or FUSE
+      # filesystem (NFS with its attribute cache, virtiofs, sshfs) may report a change time from before a save,
+      # which nothing here detects. A clock that steps backwards (an NTP correction) inside the run would date a
+      # save before the mark, so {#admits?} takes one more stamp and refuses when it reads earlier than the mark.
+      # A step undone before the run ends is not seen.
+      class WriteGuard
+        STAMP_DIR = "incremental"
+        private_constant :STAMP_DIR
+
+        # How long to wait, in seconds, for the filesystem's change time to tick past the first stamp.
+        TICK_WAIT_LIMIT = 0.05
+        # The pause between stamps.
+        TICK_RETRY_DELAY = 0.0005
+        private_constant :TICK_RETRY_DELAY
+
+        # Takes the mark, or nil when the slot must not be written: no stamp can be written, it is not on the
+        # project's filesystem, or the snapshot fingerprint the run was given no longer describes the tree.
+        #
+        # The fingerprint is recomputed AFTER the stamp: the caller computed it earlier, and a lockfile or a
+        # signature file under the configured or auto-detected `sig/` roots, or a `pre_eval:` file, changed in
+        # between would leave the snapshot the run restores keyed by one tree
+        # and the run reading another. From the stamp on, the lockfiles are the guard's to watch ({#admits?}), which
+        # is also what lets the slot's key, whose only file inputs they are, be computed when the run ends.
+        #
+        # The mark also records which of the paths an existence row can name are present: the lockfiles, the
+        # analysis roots, the `pre_eval:` entries and the signature roots.
+        def self.start(configuration:, roots:, cache_root:, fingerprint:)
+          return nil if Gem.win_platform?
+
+          started_ns, device = stamp(cache_root)
+          return nil if started_ns.nil? || device_of(Dir.pwd) != device
+          return nil unless Cache::IncrementalSnapshot.fingerprint(configuration: configuration, roots: roots) ==
+                            fingerprint
+
+          lockfiles = lockfile_paths(configuration)
+          named = Array(roots) + configuration.pre_eval + (configuration.signature_paths || ["sig"])
+          presence = (lockfiles + named.map { |path| File.absolute_path(path.to_s) }).to_h do |path|
+            [path, File.exist?(path)]
+          end
+          new(started_ns: started_ns, device: device, lockfiles: lockfiles, presence: presence,
+              stamp_dir: stamp_dir(cache_root))
+        end
+
+        # The mark: the change time and device of the first stamp whose change time is later than that of a
+        # stamp taken before it, on the same device; nil when none is written within {TICK_WAIT_LIMIT}.
+        def self.stamp(cache_root)
+          dir = stamp_dir(cache_root)
+          FileUtils.mkdir_p(dir)
+          first_ns, device = write_stamp(dir)
+          # A change time on a whole second is a filesystem that ticks by the second: waiting for it would burn the
+          # whole bound. One that ticks finer lands there once in a billion stamps, and declining is safe.
+          return nil if first_ns.nil? || (first_ns % 1_000_000_000).zero?
+
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + TICK_WAIT_LIMIT
+          loop do
+            ns, dev = write_stamp(dir)
+            return nil if ns.nil? || dev != device
+            return [ns, device] if ns > first_ns
+            return nil if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+            sleep(TICK_RETRY_DELAY)
+          end
+        rescue SystemCallError, IOError
+          nil
+        end
+        private_class_method :stamp
+
+        def self.stamp_dir(cache_root)
+          File.join(cache_root.to_s, STAMP_DIR)
+        end
+        private_class_method :stamp_dir
+
+        # One stamp's change time and device; the file is removed again.
+        def self.write_stamp(dir)
+          path = File.join(dir, "run-#{Process.pid}-#{SecureRandom.hex(4)}.stamp")
+          File.write(path, "")
+          stat = File.stat(path)
+          [Cache::FileDigest.ns_of(stat.ctime), stat.dev]
+        rescue SystemCallError, IOError
+          nil
+        ensure
+          FileUtils.rm_f(path) if path
+        end
+        private_class_method :write_stamp
+
+        def self.device_of(path)
+          File.stat(path).dev
+        rescue SystemCallError
+          nil
+        end
+        private_class_method :device_of
+
+        # Every lockfile the key or the snapshot fingerprint may digest, present or not: a lockfile that appears
+        # while the run reads moves the key as surely as one rewritten, and one rewritten and restored digests as it
+        # did while the run may have read the other bytes.
+        def self.lockfile_paths(configuration)
+          configured = [
+            [configuration.bundler_lockfile, Environment::LockfileResolver],
+            [configuration.rbs_collection_lockfile, Environment::RbsCollectionDiscovery]
+          ].filter_map { |path, resolver| resolver.configured_lockfile_path(path) if path }
+          (configured + %w[Gemfile.lock rbs_collection.lock.yaml].map { |path| File.absolute_path(path) }).uniq
+        end
+        private_class_method :lockfile_paths
+
+        def initialize(started_ns:, device:, lockfiles:, presence: {}, stamp_dir: nil)
+          @stamp_dir = stamp_dir
+          @started_ns = started_ns
+          @device = device
+          @lockfiles = lockfiles
+          @presence = presence
+        end
+
+        # True when nothing the guard watches moved since the mark:
+        #
+        # - no lockfile the key or the fingerprint digests was written, created or removed;
+        # - no file `rows` or `pinned` names changed. A content row's file changed if its change time moved. An
+        #   existence row asks only whether its path is there, so a path the mark recorded changed if it came or
+        #   went, and an editor's lock file created and removed beside it, which moves its directory's change
+        #   time, does not count. That needs no clock, so it holds on any filesystem; it cannot see a path that
+        #   comes and goes again within the run. Any other existence row falls back to change times: its own when
+        #   present, its nearest existing ancestor's when absent;
+        # - no directory a glob row lists gained or lost an entry, nor, for a stat-mode glob, did any file it
+        #   matches change.
+        #
+        # A path on another filesystem than the mark refuses the write when it is one of `rows`, and is passed
+        # over when it is one of `pinned`: the rows the key pins (the engine's own signature files, a gem's
+        # signatures, which the engine slot and the lockfiles identify) live wherever the engine and the gems are
+        # installed — a container image's layer, a Nix store — and refusing them would turn the fast path off for
+        # every such installation. On the mark's filesystem they are checked like any other row.
+        #
+        # A content row whose file is gone passes: the row is stale already, and validation says so.
+        #
+        # @param rows — a {Cache::Descriptor} of the rows the key does not pin
+        # @param pinned — a {Cache::Descriptor} of the rows it does
+        def admits?(rows, pinned: Cache::Descriptor.new)
+          !clock_stepped_back? && @lockfiles.none? { |path| lockfile_changed?(path) } &&
+            files_unchanged?(rows.files, strict: true) && globs_unchanged?(rows.globs, strict: true) &&
+            files_unchanged?(pinned.files, strict: false) && globs_unchanged?(pinned.globs, strict: false)
+        rescue StandardError
+          false
+        end
+
+        # `descriptor` with every `:stat` row's recording instant no later than the mark. A row recorded as the run
+        # read carries the instant the run began, and validation trusts a stat tuple whose mtime is before it. On a
+        # coarse clock a save that lands after the read, in the tick the file's mtime already has and with the same
+        # size, leaves the tuple unmoved, so it would be trusted. With the instant at the mark, every row whose mtime is
+        # at or after the mark is racy, and validation re-hashes it.
+        def mark_racy(descriptor)
+          Cache::Descriptor.new(
+            files: descriptor.files.map { |entry| entry.with_recording_instant_at_most(@started_ns) },
+            gems: descriptor.gems, plugins: descriptor.plugins, configs: descriptor.configs,
+            dependencies: descriptor.dependencies, globs: descriptor.globs
+          )
+        end
+
+        private
+
+        # One more stamp: a change time earlier than the mark means the clock stepped back since it was taken, so
+        # a save since then may carry a change time the guard reads as before it. A stamp that cannot be written,
+        # or lands on another device, cannot vouch for the clock either.
+        def clock_stepped_back?
+          return false if @stamp_dir.nil?
+
+          ns, device = self.class.__send__(:write_stamp, @stamp_dir)
+          ns.nil? || device != @device || ns < @started_ns
+        end
+
+        # An existence row and a content row for one path are different questions (the first asks only whether it
+        # is there, the second whether it changed), so the row that comes first must not hide the other.
+        def files_unchanged?(entries, strict:)
+          seen = Set.new
+          entries.none? do |entry|
+            next false unless seen.add?([entry.path, entry.comparator == :exists])
+
+            if entry.comparator == :exists
+              existence_changed?(entry.path, strict: strict)
+            else
+              changed?(entry.path, strict: strict)
+            end
+          end
+        end
+
+        def globs_unchanged?(entries, strict:)
+          entries.none? do |entry|
+            listed = Dir.glob(File.join(entry.root, File.dirname(entry.pattern), ""))
+            matched = entry.mode == :stat ? Dir.glob(File.join(entry.root, entry.pattern)) : []
+            (listed + matched).any? { |path| changed?(path, strict: strict) }
+          end
+        end
+
+        # A lockfile is read for its bytes: one absent at the mark must still be absent, one present must still be
+        # there with its change time before the mark.
+        def lockfile_changed?(path)
+          return File.exist?(path) unless @presence[path]
+
+          changed?(path, strict: true, missing: true)
+        end
+
+        def existence_changed?(path, strict:)
+          absolute = File.absolute_path(path)
+          return File.exist?(absolute) != @presence[absolute] if @presence.key?(absolute)
+
+          nearest = absolute
+          nearest = File.dirname(nearest) until File.exist?(nearest) || File.dirname(nearest) == nearest
+          moved?(File.stat(nearest), strict: strict)
+        rescue SystemCallError
+          true
+        end
+
+        def changed?(path, strict:, missing: false)
+          moved?(File.stat(path), strict: strict)
+        rescue SystemCallError
+          missing
+        end
+
+        # A change time is comparable with the mark only on the stamp's filesystem.
+        def moved?(stat, strict:)
+          return strict if stat.dev != @device
+
+          Cache::FileDigest.ns_of(stat.ctime) >= @started_ns
+        end
+      end
+    end
+  end
+end