rigortype 0.2.9 → 0.3.1

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_cache_producer.rb

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

data/lib/rigor/cache/rbs_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/rbs_environment_marshal_patch.rb

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

data/lib/rigor/cache/store.rb

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

data/lib/rigor/ci_detector.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Rigor
+  # Runtime CI-environment detection (ADR-51 WD7), modelled on `OndraM/ci-detector` (the library PHPStan uses). Reads
+  # the well-known environment variables a CI provider sets and returns the matching {Platform}, classifying it into a
+  # **tier** that decides how `rigor check` surfaces diagnostics there:
+  #
+  #   :native_stdout   — Rigor has a native format that renders purely from
+  #                      stdout, so it is auto-emitted on top of the human
+  #                      output (GitHub Actions → `github`, TeamCity →
+  #                      `teamcity`). These are the first-class platforms.
+  #   :native_artifact — Rigor has a native format but it needs a CI-wired
+  #                      report artifact, not stdout (GitLab CI → `gitlab`).
+  #                      First-class, but Rigor only *hints* the format.
+  #   :reviewdog       — no native Rigor format; second-class, routed through
+  #                      reviewdog (`checkstyle`/`sarif`) or `junit`. Hint
+  #                      only.
+  #
+  # Lives outside the CLI namespace because it is a pure function of the environment hash with no CLI dependency, and
+  # non-CLI consumers exist: {Configuration#cache_validation_strict?} resolves the `auto` cache-validation default
+  # through it (a fresh CI checkout regenerates every stat tuple, so ADR-87's stat tier cannot work there).
+  # Detection is fully testable; callers pass `ENV`.
+  # `RIGOR_CI_DETECT=0` (or `false`/`no`) disables it globally — the seam the spec suite uses for determinism.
+  module CiDetector
+    Platform = Struct.new(:id, :name, :format, :tier, keyword_init: true) do
+      def native_stdout? = tier == :native_stdout
+      def native_artifact? = tier == :native_artifact
+      def reviewdog? = tier == :reviewdog
+    end
+
+    # The detection table, ordered most-specific first so the generic `CI=true` catch-all is last (a provider that
+    # also sets `CI` is still recognised by its own variable). `match` is `:truthy` (value in 1/true/yes/on),
+    # `:present` (variable set non-empty), or `:equals`.
+    PROVIDERS = [
+      { id: "github-actions", name: "GitHub Actions", format: "github", tier: :native_stdout,
+        var: "GITHUB_ACTIONS", match: :truthy },
+      { id: "gitlab", name: "GitLab CI", format: "gitlab", tier: :native_artifact,
+        var: "GITLAB_CI", match: :truthy },
+      { id: "teamcity", name: "TeamCity", format: "teamcity", tier: :native_stdout,
+        var: "TEAMCITY_VERSION", match: :present },
+      { id: "circleci", name: "CircleCI", format: nil, tier: :reviewdog,
+        var: "CIRCLECI", match: :truthy },
+      { id: "jenkins", name: "Jenkins", format: nil, tier: :reviewdog,
+        var: "JENKINS_URL", match: :present },
+      { id: "travis", name: "Travis CI", format: nil, tier: :reviewdog,
+        var: "TRAVIS", match: :truthy },
+      { id: "appveyor", name: "AppVeyor", format: nil, tier: :reviewdog,
+        var: "APPVEYOR", match: :truthy },
+      { id: "azure-pipelines", name: "Azure Pipelines", format: nil, tier: :reviewdog,
+        var: "TF_BUILD", match: :present },
+      { id: "bitbucket", name: "Bitbucket Pipelines", format: nil, tier: :reviewdog,
+        var: "BITBUCKET_BUILD_NUMBER", match: :present },
+      { id: "buildkite", name: "Buildkite", format: nil, tier: :reviewdog,
+        var: "BUILDKITE", match: :truthy },
+      { id: "drone", name: "Drone CI", format: nil, tier: :reviewdog,
+        var: "DRONE", match: :truthy },
+      { id: "semaphore", name: "Semaphore", format: nil, tier: :reviewdog,
+        var: "SEMAPHORE", match: :truthy },
+      { id: "codeship", name: "Codeship", format: nil, tier: :reviewdog,
+        var: "CI_NAME", match: :equals, value: "codeship" },
+      { id: "ci", name: "CI", format: nil, tier: :reviewdog,
+        var: "CI", match: :truthy }
+    ].freeze
+
+    module_function
+
+    # Returns the detected {Platform}, or nil when no CI is recognised or detection is disabled via `RIGOR_CI_DETECT`.
+    def detect(env = ENV)
+      return nil if disabled?(env)
+
+      row = PROVIDERS.find { |provider| matches?(env, provider) }
+      return nil if row.nil?
+
+      Platform.new(id: row[:id], name: row[:name], format: row[:format], tier: row[:tier])
+    end
+
+    def disabled?(env)
+      %w[0 false no off].include?(env["RIGOR_CI_DETECT"].to_s.strip.downcase)
+    end
+
+    def matches?(env, provider)
+      value = env[provider[:var]].to_s.strip
+      case provider[:match]
+      when :truthy then %w[1 true yes on].include?(value.downcase)
+      when :present then !value.empty?
+      when :equals then value.downcase == provider[:value]
+      end
+    end
+  end
+end