rigortype 0.2.8 → 0.3.0

data/lib/rigor/cache/incremental_snapshot.rb

@@ -24,8 +24,22 @@ module Rigor
       # Bump when the on-disk shape changes so stale snapshots are ignored rather than mis-deserialized. 5:
       # the blob is zlib-deflated (ADR-54 WD2 parity with `Store` entries — the snapshot is the one cache
       # artefact that does not go through `Store`); a raw pre-5 blob fails the inflate and loads as nil, the
-      # usual fault-tolerant cold-run path.
-      SCHEMA = 5
+      # usual fault-tolerant cold-run path. 6: adds the ADR-85 WD2 `seed_bundles` section (per-file discovery
+      # contributions with `(node_id, name, fingerprint)` def-node handles); a pre-6 blob mismatches the
+      # SCHEMA gate and loads as nil (a clean cold rebuild — no migration). 7: the seed bundle gains a
+      # `singleton_def_sources` table (ADR-46 slice 4 extended to class/singleton methods) AND `digests`
+      # switches to ADR-87 packed stat entries; a pre-7 blob mismatches the gate and loads as nil (clean cold
+      # rebuild). 8: each seed bundle additionally gains a comment-stripped `code_fingerprint` for the B1
+      # bundle-equality gate; a pre-8 blob mismatches and loads as nil (clean cold rebuild). 9: adds the ADR-88
+      # WD1 `plugin_fact_digest` (a fingerprint of the plugin fact SURFACE — ADR-9 facts, ADR-60 producer
+      # values, and `incremental_state_fingerprint` hooks — that a cached diagnostic can depend on but the
+      # global fingerprint does not capture); a pre-9 blob mismatches the SCHEMA gate and loads as nil (a clean
+      # cold rebuild — no migration). 10: ADR-89 WD1 adds a per-file `declaration_signature` to each seed
+      # 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
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -39,9 +53,25 @@ module Rigor
       # ADR-46 slice 3:
       # `missing` maps a consumer to Set<"kind:name"> it looked up and missed.
       # `class_decls` maps a path to Set<qualified class name> it declares.
+      # ADR-85 WD2:
+      # `seed_bundles` maps an analyzed path to its per-file discovery contribution (plain-data tables +
+      # `(node_id, name, fingerprint)` def-node handles + content digest), so a warm recheck rebuilds the
+      # cross-file index by folding bundles instead of parsing every file.
+      # ADR-88 WD1:
+      # `plugin_fact_digest` is a SHA-256 hex fingerprint of the plugin fact surface at the run that wrote the
+      # snapshot (or nil for a plugin-free project). A warm recheck recomputes it and, on a mismatch, discards
+      # the snapshot and runs a full analysis — the guard for a plugin sig/catalog edit that the global
+      # fingerprint cannot see.
+      # ADR-89 WD2:
+      # `return_summaries` maps a `[path, "Class#method" | "Class.method"]` to the callee's persisted
+      # behavioural surface `{ keys:, returns:, effects: }` — the observed `[receiver, arg_types]` call keys
+      # (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.
       Payload = Data.define(:cache, :sources, :digests, :analyzed,
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
-                            :missing, :class_decls)
+                            :missing, :class_decls, :seed_bundles, :plugin_fact_digest,
+                            :return_summaries)
 
       # 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
@@ -104,7 +134,10 @@ module Rigor
           ancestry_sources: data[:ancestry_sources] || {},
           symbol_fingerprints: data[:symbol_fingerprints] || {},
           missing: data[:missing] || {},
-          class_decls: data[:class_decls] || {}
+          class_decls: data[:class_decls] || {},
+          seed_bundles: data[:seed_bundles] || {},
+          plugin_fact_digest: data[:plugin_fact_digest],
+          return_summaries: data[:return_summaries] || {}
         )
       rescue StandardError
         nil
@@ -122,7 +155,10 @@ module Rigor
           ancestry_sources: payload.ancestry_sources,
           symbol_fingerprints: payload.symbol_fingerprints,
           missing: payload.missing,
-          class_decls: payload.class_decls
+          class_decls: payload.class_decls,
+          seed_bundles: payload.seed_bundles,
+          plugin_fact_digest: payload.plugin_fact_digest,
+          return_summaries: payload.return_summaries
         )
         blob = Zlib::Deflate.deflate(raw)
         tmp = "#{@path}.#{Process.pid}.tmp"

data/lib/rigor/cache/rbs_descriptor.rb

@@ -3,6 +3,7 @@
 require "digest"
 
 require_relative "descriptor"
+require_relative "file_digest"
 
 module Rigor
   module Cache
@@ -17,15 +18,36 @@ module Rigor
         Descriptor.new(
           gems: [rbs_gem_entry],
           files: file_entries(loader),
-          configs: [libraries_entry(loader), virtual_rbs_entry(loader)].compact
+          configs: config_entries(loader)
         )
       end
 
+      # Lazy-files variant for the ADR-45 run-diagnostics record-and-validate cache. The cache KEY reads only
+      # `gems` + `configs` ({Runner#run_key_descriptor}); the RBS signature-tree `files` are read solely on a
+      # MISS, by the dependency descriptor ({Runner#run_dependency_descriptor}). So a warm HIT never digests
+      # the (large, vendored) RBS tree. {RunDescriptor} is NOT a {Descriptor} — it is never composed, hashed,
+      # or `==`'d, only its three readers are consulted — so deferring `files` costs no soundness, and `gems`
+      # / `configs` are byte-identical to {.build} (the key is unchanged).
+      def self.build_run(loader)
+        RunDescriptor.new(loader: loader, gems: [rbs_gem_entry], configs: config_entries(loader))
+      end
+
+      # The `gems` + `configs` slots the run cache key reads. Cheap — no RBS env load, no file digesting
+      # (only the configured library names + any plugin-synthesised virtual RBS are hashed).
+      def self.config_entries(loader)
+        [libraries_entry(loader.libraries), virtual_rbs_entry(loader)].compact
+      end
+
+      # Public (ADR-87 WD4) so the boot-slimming run-cache probe reconstructs the identical `gems` +
+      # `rbs.libraries` key slots the runner writes, from the config-derived library list, without a loader.
       def self.rbs_gem_entry
         Descriptor::GemEntry.new(name: "rbs", requirement: ">= 0", locked: ::RBS::VERSION.to_s)
       end
 
-      def self.file_entries(loader)
+      # @param comparator [Symbol] `:digest` (default) for the env-cache KEY descriptor ({.build}), where the
+      #   value must be deterministic; `:stat` (ADR-87 WD1) for the validation-only run-dependency descriptor
+      #   ({RunDescriptor#files}), where the stat tier short-circuits the SHA-256 on an unmoved file.
+      def self.file_entries(loader, comparator: :digest)
         roots = loader.signature_paths +
                 Rigor::Environment::RbsLoader.vendored_gem_sig_paths +
                 Rigor::Environment::RbsLoader.core_overlay_sig_paths
@@ -33,17 +55,20 @@ module Rigor
           next [] unless root.directory?
 
           Dir.glob(root.join("**", "*.rbs")).map do |path|
-            Descriptor::FileEntry.new(
-              path: path,
-              comparator: :digest,
-              value: Digest::SHA256.file(path).hexdigest
-            )
+            digest = FileDigest.hexdigest(path)
+            if comparator == :stat
+              Descriptor::FileEntry.stat(path: path, digest: digest)
+            else
+              Descriptor::FileEntry.new(path: path, comparator: :digest, value: digest)
+            end
           end
         end
       end
 
-      def self.libraries_entry(loader)
-        sorted = loader.libraries.map(&:to_s).sort
+      # @param library_names [Array<String, Symbol>] the loader's merged library list (or, on the WD4 probe
+      #   path, `Environment::DEFAULT_LIBRARIES + config.libraries` reconstructed without a loader).
+      def self.libraries_entry(library_names)
+        sorted = library_names.map(&:to_s).sort
         Descriptor::ConfigEntry.new(
           key: "rbs.libraries",
           value_hash: Digest::SHA256.hexdigest(sorted.join("\n"))
@@ -66,7 +91,28 @@ module Rigor
         )
       end
 
-      private_class_method :rbs_gem_entry, :file_entries, :libraries_entry, :virtual_rbs_entry
+      private_class_method :virtual_rbs_entry
+
+      # The lazy-files run descriptor {RbsDescriptor.build_run} returns. Exposes the three readers the
+      # run-diagnostics cache consults — `gems` + `configs` are supplied eagerly (they feed the cache KEY,
+      # and are cheap); `files` (the RBS signature-tree digests, read only on a MISS) is computed once on
+      # first access and memoised, so a warm HIT never pays for it.
+      class RunDescriptor
+        attr_reader :gems, :configs
+
+        def initialize(loader:, gems:, configs:)
+          @loader = loader
+          @gems = gems
+          @configs = configs
+        end
+
+        def files
+          # ADR-87 WD1 — this descriptor is validated (never a cache key), so the RBS signature tree rides the
+          # stat-then-digest `:stat` tier: a warm run stat-checks the (large, vendored) tree instead of
+          # re-hashing it.
+          @files ||= RbsDescriptor.file_entries(@loader, comparator: :stat)
+        end
+      end
     end
   end
 end

data/lib/rigor/cache/store.rb

@@ -7,6 +7,7 @@ require "monitor"
 require "securerandom"
 require "zlib"
 
+require_relative "../version"
 require_relative "descriptor"
 
 module Rigor
@@ -30,6 +31,27 @@ module Rigor
       # bytes.
       FORMAT_VERSION = 2
 
+      # Payload ABI version. Store values are mostly Marshal blobs of Rigor/RBS objects, so a Rigor release
+      # upgrade is an ABI boundary even when the byte layout and descriptor schema are unchanged. Folding the
+      # gem version into the root marker makes installed-version upgrades rebuild rather than silently reuse a
+      # 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
+
+      STALE_TEMP_FILE_AGE_SECONDS = 60 * 60
+
       # Header literal: 5-byte ASCII magic, 1-byte separator, 1-byte format version.
       HEADER = "RIGOR\x00#{FORMAT_VERSION.chr}".b.freeze
 
@@ -37,17 +59,19 @@ module Rigor
 
       # @param root [String] cache root directory.
       # @param read_only [Boolean] when true, every disk-side side-effect is suppressed: `fetch_or_compute`
-      #   still reads existing entries (hits) and still runs the producer block on miss, but it does NOT
-      #   write the produced value to disk, does NOT update the `schema_version.txt` marker, and does NOT
-      #   touch the on-disk root directory. The in-process memo is still populated so repeated lookups within
-      #   the same run stay cheap. Used by editor mode so multiple buffer-mode invocations can read from the
-      #   same cache concurrently without churning it. See `docs/design/20260516-editor-mode.md` § "Cache
-      #   behaviour".
+      #   still reads existing entries (hits, gated on a current `schema_version.txt` marker — see
+      #   {#ensure_schema_version!}) and still runs the producer block on miss, but it does NOT write the
+      #   produced value to disk, does NOT update the marker, and does NOT touch the on-disk root directory.
+      #   The in-process memo is still populated so repeated lookups within the same run stay cheap. Used by
+      #   editor mode so multiple buffer-mode invocations can read from the same cache concurrently without
+      #   churning it. See `docs/design/20260516-editor-mode.md` § "Cache behaviour".
       def initialize(root:, read_only: false, max_bytes: nil)
         @root = root.to_s.dup.freeze
         @read_only = read_only
         @max_bytes = max_bytes&.then { |n| Integer(n) }
-        @schema_version_ensured = false
+        # Tri-state: nil = not yet checked, true/false = the disk tier's availability for this Store's
+        # lifetime (see {#ensure_schema_version!}).
+        @disk_available = nil
         @hits = 0
         @misses = 0
         @writes = 0
@@ -100,7 +124,7 @@ module Rigor
       # the eviction cap forever. Folding the format version into the marker routes the bump through the
       # established clear-the-root path instead.
       def self.schema_marker_value
-        "#{Descriptor::SCHEMA_VERSION}.#{FORMAT_VERSION}"
+        "#{PAYLOAD_ABI_VERSION}.#{Descriptor::SCHEMA_VERSION}.#{FORMAT_VERSION}"
       end
 
       def self.disk_inventory(root:)
@@ -154,7 +178,7 @@ module Rigor
       def fetch_or_compute(producer_id:, params:, descriptor:,
                            serialize: nil, deserialize: nil, &block)
         validate_producer_id!(producer_id)
-        ensure_schema_version!
+        disk = ensure_schema_version!
 
         key = descriptor.cache_key_for(producer_id: producer_id, params: params)
         memo_key = [producer_id, key].freeze
@@ -164,8 +188,8 @@ module Rigor
           return memoed
         end
 
-        path = entry_path(producer_id, key)
-        cached = read_entry(path, deserialize: deserialize)
+        path = disk ? entry_path(producer_id, key) : nil
+        cached = path && read_entry(path, deserialize: deserialize)
         unless cached.nil?
           @monitor.synchronize do
             record(:hits, producer_id)
@@ -175,10 +199,10 @@ module Rigor
         end
 
         value = block.call
-        write_entry(path, descriptor, value, serialize: serialize) unless @read_only
+        wrote = path && try_write_entry(path, descriptor, value, serialize: serialize)
         @monitor.synchronize do
           record(:misses, producer_id)
-          record(:writes, producer_id) unless @read_only
+          record(:writes, producer_id) if wrote
           @memo[memo_key] = value
         end
         value
@@ -195,29 +219,18 @@ module Rigor
       # 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)
         validate_producer_id!(producer_id)
-        ensure_schema_version!
+        disk = ensure_schema_version!
 
         key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
-        path = entry_path(producer_id, key)
-        cached = read_entry(path, deserialize: deserialize)
-        if cached && (pair = cached.value).is_a?(Array) && pair.size == 2 &&
-           pair[1].is_a?(Descriptor) && pair[1].fresh?
+        path = disk ? entry_path(producer_id, key) : nil
+        cached = path && read_entry(path, deserialize: deserialize)
+        if (validated = fresh_pair_value(cached))
           @monitor.synchronize { record(:hits, producer_id) }
-          return pair[0]
+          return validated[0]
         end
 
         value, dependency_descriptor = block_given? ? yield : [nil, Descriptor.new]
-        wrote = false
-        unless @read_only
-          # A cache write must never break the run. If the value is not Marshal-clean (or any disk error
-          # occurs) skip caching and return the freshly-computed value — the next run recomputes.
-          begin
-            write_entry(path, key_descriptor, [value, dependency_descriptor], serialize: serialize)
-            wrote = true
-          rescue StandardError
-            wrote = false
-          end
-        end
+        wrote = path && try_write_entry(path, key_descriptor, [value, dependency_descriptor], serialize: serialize)
         @monitor.synchronize do
           record(:misses, producer_id)
           record(:writes, producer_id) if wrote
@@ -225,27 +238,48 @@ module Rigor
         value
       end
 
-      # ADR-6 § "Eviction" — LRU pass over the on-disk cache. No-op when `max_bytes:` was not configured or
-      # the store is read-only. Walks all `.entry` files, sorts by mtime ascending (oldest = least recently
-      # used), and unlinks from the oldest until the total is at or below the cap. Touch-on-disk-read
-      # ({read_entry}) is the cross-process LRU signal: every disk hit (not in-process-memo hit) updates the
-      # mtime so recently-read entries survive the eviction pass. Any FS error is swallowed — eviction must
-      # never break a run.
+      # ADR-87 WD4 — the READ half of {#fetch_or_validate} with no compute and no write: returns the cached
+      # value on a fresh hit, nil on a miss / stale / unavailable-disk. The boot-slimming hit probe calls this
+      # 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).
+      def peek_validated(producer_id:, key_descriptor:, params: {}, deserialize: nil)
+        validate_producer_id!(producer_id)
+        return nil unless ensure_schema_version!
+
+        key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
+        cached = read_entry(entry_path(producer_id, key), deserialize: deserialize)
+        validated = fresh_pair_value(cached)
+        return nil if validated.nil?
+
+        @monitor.synchronize { record(:hits, producer_id) }
+        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
+      # 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
+      # `.entry` files, sorts by mtime ascending (oldest = least recently used), and unlinks from the oldest
+      # until the total is at or below the cap. Touch-on-disk-read ({read_entry}) is the cross-process LRU
+      # signal: every disk hit (not in-process-memo hit) updates the mtime so recently-read entries survive
+      # the eviction pass. Any FS error is swallowed — eviction must never break a run.
       def evict!
-        return if @max_bytes.nil? || @read_only
+        return if @read_only
 
-        entries = collect_entry_stats
-        total   = entries.sum { |e| e[:bytes] }
+        cleanup_stale_temp_files
+        entries = evict_excess_generations(collect_entry_stats)
+        return if @max_bytes.nil?
+
+        total = entries.sum { |e| e[:bytes] }
         return if total <= @max_bytes
 
         entries.sort_by! { |e| e[:mtime] }
         entries.each do |entry|
           break if total <= @max_bytes
 
-          File.unlink(entry[:path])
-          total -= entry[:bytes]
-        rescue StandardError
-          next
+          total -= entry[:bytes] if unlink_entry(entry[:path])
         end
         nil
       rescue StandardError
@@ -257,6 +291,19 @@ module Rigor
       Entry = Data.define(:descriptor_bytes, :value)
       private_constant :Entry
 
+      # A record-and-validate entry is a fresh hit iff it deserialised to a `[value, dependency_descriptor]`
+      # pair whose descriptor still validates against the filesystem. Returns the pair on a fresh hit, nil
+      # otherwise. Shared by {#fetch_or_validate} and {#peek_validated} so both apply identical hit criteria.
+      def fresh_pair_value(cached)
+        return nil if cached.nil?
+
+        pair = cached.value
+        return nil unless pair.is_a?(Array) && pair.size == 2 &&
+                          pair[1].is_a?(Descriptor) && pair[1].fresh?
+
+        pair
+      end
+
       def record(counter, producer_id)
         case counter
         when :hits then @hits += 1
@@ -372,38 +419,68 @@ module Rigor
         File.open(path, File::RDWR | File::CREAT, 0o644) do |lock_fd|
           lock_fd.flock(File::LOCK_EX)
           tmp = "#{path}.tmp.#{Process.pid}.#{SecureRandom.hex(4)}"
-          File.open(tmp, "wb") do |f|
-            f.write(body)
-            f.fsync
+          begin
+            File.open(tmp, "wb") do |f|
+              f.write(body)
+              f.fsync
+            end
+            File.rename(tmp, path)
+          ensure
+            # A failed write/rename must not leak its temp file — rely on the 1-hour `cleanup_stale_temp_files`
+            # sweep only as a backstop for crashes that skip this ensure entirely.
+            unlink_entry(tmp) if File.exist?(tmp)
           end
-          File.rename(tmp, path)
+          fsync_directory(File.dirname(path))
         end
       end
 
+      # Checks (and, for a writable store, repairs) the `schema_version.txt` marker, and reports whether the
+      # disk tier is usable for the rest of this Store's lifetime. The result is memoized in `@disk_available`
+      # — one check per Store is enough; a benign double-check under a thread race would just repeat
+      # idempotent work.
+      #
+      # A writable store clears the cache root and rewrites the marker on a stale/missing marker, then reports
+      # available. A read-only store never touches the root — no mkdir, no marker write, no destructive clear
+      # — so it reports available ONLY when the on-disk marker already matches current exactly; a stale or
+      # missing marker (e.g. a Rigor upgrade with no writable run yet, as in LSP / editor mode) reports
+      # unavailable rather than risk unmarshalling a payload from a different ABI. Any filesystem failure
+      # (permission, disk full, deleted root) also reports unavailable, degrading this Store instance to
+      # in-memory-memo-only for the rest of its lifetime — the producer block still runs, its result still
+      # lands in `@memo`, and disk reads/writes are simply skipped.
+      #
+      # @return [Boolean]
       def ensure_schema_version!
-        # Read-only stores never touch the cache root — no mkdir, no marker write, no destructive clear on
-        # schema mismatch. A stale or wrong-schema marker simply yields nothing back (entries read through
-        # the version check are content-keyed, so a write under the new schema never collides with a read
-        # under the old). The next writable run will repair the cache.
-        return if @read_only
-        # The marker is process-stable; one check per Store is enough (a benign double-check under a thread
-        # race just repeats idempotent work).
-        return if @schema_version_ensured
+        return @disk_available unless @disk_available.nil?
+
+        @disk_available = @read_only ? read_only_marker_current? : repair_writable_marker!
+      end
+
+      def read_only_marker_current?
+        marker = File.join(@root, "schema_version.txt")
+        return false unless File.file?(marker)
+
+        File.read(marker).strip == self.class.schema_marker_value
+      rescue StandardError
+        false
+      end
 
-        @schema_version_ensured = true
+      def repair_writable_marker!
         FileUtils.mkdir_p(@root)
         marker = File.join(@root, "schema_version.txt")
         current = self.class.schema_marker_value
 
         if File.file?(marker)
           on_disk = File.read(marker).strip
-          return if on_disk == current
+          return true if on_disk == current
 
           clear_cache_root!
         end
 
         FileUtils.mkdir_p(@root)
         File.write(marker, "#{current}\n")
+        true
+      rescue StandardError
+        false
       end
 
       def clear_cache_root!
@@ -412,6 +489,27 @@ module Rigor
         end
       end
 
+      # Shared write path for both {#fetch_or_compute} and {#fetch_or_validate}. A cache write must never
+      # break the run: filesystem-side failures (permission, disk full, deleted root, read-only mount) are
+      # swallowed and read as "did not write". Programmer errors — a custom serializer that doesn't return a
+      # `String`, or any other producer contract violation — still raise so the bug is visible.
+      def try_write_entry(path, descriptor, value, serialize: nil)
+        return false if @read_only
+
+        write_entry(path, descriptor, value, serialize: serialize)
+        true
+      rescue SystemCallError, IOError
+        false
+      end
+
+      # Best-effort durability for the rename itself. Some platforms cannot fsync directories (or do not need to),
+      # so failures are ignored; the entry envelope still turns any lost/partial write into a miss.
+      def fsync_directory(dir)
+        File.open(dir, File::RDONLY, &:fsync)
+      rescue StandardError
+        nil
+      end
+
       # LEB128 unsigned varint encoder/decoder. Lengths fit easily in five bytes (cap at 2^35); the cache
       # layer never writes a value larger than that in practice.
       def write_varint(bytes, value)
@@ -437,17 +535,66 @@ module Rigor
         nil
       end
 
-      # Returns an array of `{ path:, mtime:, bytes: }` hashes for every `.entry` file under the cache root,
-      # skipping unreadable entries.
+      def cleanup_stale_temp_files
+        cutoff = Time.now - STALE_TEMP_FILE_AGE_SECONDS
+        Dir.glob(File.join(@root, "**", "*.tmp.*")).each do |path|
+          next unless File.file?(path)
+          next if File.mtime(path) > cutoff
+
+          unlink_entry(path)
+        rescue StandardError
+          next
+        end
+      rescue StandardError
+        nil
+      end
+
+      def evict_excess_generations(entries)
+        removed = {}
+        entries.group_by { |entry| entry[:producer] }.each do |producer, producer_entries|
+          cap = GENERATION_CAP_BY_PRODUCER[producer]
+          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
+        end
+        return entries if removed.empty?
+
+        entries.reject { |entry| removed[entry[:path]] }
+      end
+
+      def unlink_entry(path)
+        File.unlink(path)
+        true
+      rescue StandardError
+        false
+      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
         Dir.glob(File.join(@root, "**", "*.entry")).filter_map do |path|
           stat = File.stat(path)
-          { path: path, mtime: stat.mtime, bytes: stat.size }
+          producer = producer_id_for_entry(path)
+          next nil if producer.nil?
+
+          { path: path, producer: producer, mtime: stat.mtime, bytes: stat.size }
         rescue StandardError
           nil
         end
       end
 
+      def producer_id_for_entry(path)
+        root_prefix = @root.end_with?(File::SEPARATOR) ? @root : "#{@root}#{File::SEPARATOR}"
+        return nil unless path.start_with?(root_prefix)
+
+        producer = path.delete_prefix(root_prefix).split(File::SEPARATOR, 2).first
+        producer.empty? ? nil : producer
+      end
+
       def read_varint(bytes, offset)
         result = 0
         shift = 0