rigortype 0.3.8 → 0.3.9

data/lib/rigor/cache/incremental_snapshot.rb

@@ -84,7 +84,29 @@ module Rigor
       # `[]`, deserialises cleanly, and would send every unchanged file's top-level helper back to the peel
       # on a warm run while a cold run resolved at the top level — the `--verify-incremental` divergence 14
       # was bumped for, in the same table.
-      SCHEMA = 17
+      # 18: issue #728 re-keys each seed bundle's `header_nestings` VALUE from one chain per class to one
+      # chain per ancestor NAME the class's sites wrote, plus an unkeyed chain holding the old union. A
+      # pre-18 blob's Array value is not a Hash and the resolver's per-name lookup would raise on it, so the
+      # gate has to reject it — and even a reader that tolerated the old shape would serve the per-class
+      # union for every unchanged file, which is the answer this issue exists to stop giving.
+      # 19: issue #668 re-keys a constant write through a base no name reaches — `k::LIMIT = 7` — from the
+      # bare last segment to the wildcard `*::LIMIT`, in `constant_decls` and in each seed bundle's
+      # `constant_writes` census alike. A pre-19 blob's `LIMIT` key deserialises cleanly and reads as an
+      # ordinary top-level write, so every unchanged file would keep publishing the `Foo::LIMIT` the write
+      # may already have replaced while a cold run made it gradual — the `--verify-incremental` divergence
+      # 14 was bumped for.
+      # 20: issue #722 residue 2 adds each seed bundle's compact-header re-anchor census, without which a
+      # warm fold sees no candidate for an unchanged file and keeps serving the pre-fix `Wrap::Outer::Leaf`
+      # for a `class Outer::Leaf` that reopens `::Outer::Leaf`.
+      # 21: issue #915 widens the seed bundle's `extends` table to a singleton-body `include` / `prepend`;
+      # a pre-21 bundle for an unchanged file would keep the narrower record and still report the
+      # `case Widget when M` arm unreachable.
+      # 22: issues #796 / #794 add `run_level_rows` — the cold run's `definition-build-failed` set and its
+      # HKT-scan outcome, the two rows a narrowed run cannot re-derive from the files it analyses. A pre-22
+      # blob has no such section and would deserialise it as nil, which reads as "nothing cached" and is
+      # therefore not misread — but a snapshot written by an engine that did not yet REPLAY them was also
+      # written by one whose narrowed runs under-reported, so the gate rejects it and the next run is cold.
+      SCHEMA = 22
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -136,11 +158,21 @@ module Rigor
       # collection was off). It is a SEPARATE gate from the global `fingerprint`: the `effects:` block is
       # deliberately absent from `Configuration#to_h`, so turning collection on invalidates no diagnostics,
       # and a vocabulary / catalogue / `effects:` change must invalidate the summaries alone.
+      # Issues #796 / #794 — the run-level rows a narrowed run replays instead of re-deriving; see
+      # docs/internal-spec/cache.md § "Run-level rows the snapshot carries" for why exactly these two are
+      # fresh under the fingerprint and why no other `.rigor.yml`-level row may join them.
       Payload = Data.define(:cache, :sources, :digests, :analyzed,
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
                             :missing, :class_decls, :constant_decls, :seed_bundles, :plugin_fact_digest,
                             :return_summaries, :param_table,
-                            :effect_collections, :effects_identity)
+                            :effect_collections, :effects_identity, :run_level_rows)
+
+      # Issues #796 / #794 — the two run-level rows the snapshot carries. `definition_build_failures` is the
+      # reported per-class detail list ({Environment::RbsLoader#definition_build_failures}); `hkt_scan_failure`
+      # is the `[error_class, first_line, frame, stage]` tuple ({Rigor::Environment#hkt_scan_failure}), nil
+      # when the scan succeeded — which is why the presence of this object, not the tuple, is what says a
+      # replay is available.
+      RunLevelRows = Data.define(:definition_build_failures, :hkt_scan_failure)
 
       # The global fingerprint that gates a snapshot load: a digest of the inputs whose change requires a full
       # rebuild — the engine version + schema, the engine's own SOURCE when the version does not pin it, the
@@ -222,8 +254,8 @@ module Rigor
       # The fingerprint that matched is returned alongside the payload so the caller can mix it into ITS own
       # cache key — the snapshot's identity is exactly what "these dependency edges came from that world" means.
       #
-      # @param fingerprints [Array<String>] candidates, most-specific first.
-      # @return [Array(String, Payload), nil] `[matched fingerprint, payload]`, or nil on any miss.
+      # @param fingerprints — candidates, most-specific first.
+      # @return `[matched fingerprint, payload]`, or nil on any miss.
       def load_any(fingerprints:)
         data = read_data
         return nil if data.nil?
@@ -259,7 +291,8 @@ module Rigor
           return_summaries: data[:return_summaries] || {},
           param_table: data[:param_table] || {},
           effect_collections: data[:effect_collections] || {},
-          effects_identity: data[:effects_identity]
+          effects_identity: data[:effects_identity],
+          run_level_rows: data[:run_level_rows]
         )
       end
       private :payload_from
@@ -283,7 +316,8 @@ module Rigor
           return_summaries: payload.return_summaries,
           param_table: payload.param_table,
           effect_collections: payload.effect_collections,
-          effects_identity: payload.effects_identity
+          effects_identity: payload.effects_identity,
+          run_level_rows: payload.run_level_rows
         )
         blob = Zlib::Deflate.deflate(raw)
         tmp = "#{@path}.#{Process.pid}.tmp"

data/lib/rigor/cache/rbs_class_ancestor_table.rb

@@ -20,9 +20,6 @@ module Rigor
     class RbsClassAncestorTable < RbsCacheProducer
       PRODUCER_ID = "rbs.class_ancestor_table"
 
-      # @param loader [Rigor::Environment::RbsLoader]
-      # @param store [Rigor::Cache::Store]
-      # @return [Hash{String => Array<String>}]
       def self.compute(loader)
         table = {}
         loader.each_known_class_name do |name|

data/lib/rigor/cache/rbs_class_type_param_names.rb

@@ -20,9 +20,6 @@ module Rigor
     class RbsClassTypeParamNames < RbsCacheProducer
       PRODUCER_ID = "rbs.class_type_param_names"
 
-      # @param loader [Rigor::Environment::RbsLoader]
-      # @param store [Rigor::Cache::Store]
-      # @return [Hash{String => Array<Symbol>}]
       def self.compute(loader)
         table = {}
         loader.each_known_class_name do |name|

data/lib/rigor/cache/rbs_constant_table.rb

@@ -15,9 +15,6 @@ module Rigor
     class RbsConstantTable < RbsCacheProducer
       PRODUCER_ID = "rbs.constant_type_table"
 
-      # @param loader [Rigor::Environment::RbsLoader]
-      # @param store [Rigor::Cache::Store]
-      # @return [Hash{String => Rigor::Type}]
       def self.compute(loader)
         table = {}
         loader.each_constant_decl do |name, entry|

data/lib/rigor/cache/rbs_descriptor.rb

@@ -12,13 +12,11 @@ module Rigor
     # slots, so factoring the construction here keeps the producers small and ensures invalidation behaves
     # identically across them.
     module RbsDescriptor
-      # @param loader [Rigor::Environment::RbsLoader]
-      # @return [Rigor::Cache::Descriptor]
       def self.build(loader)
         Descriptor.new(
           gems: [rbs_gem_entry],
           files: file_entries(loader),
-          configs: config_entries(loader)
+          configs: config_entries(loader) + env_only_config_entries(loader)
         )
       end
 
@@ -26,8 +24,9 @@ module Rigor
       # `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).
+      # or `==`'d, only its four readers are consulted — so deferring `files` costs no soundness, and `gems`
+      # / `configs` match {.build}'s shared slots (the key is unchanged; the one slot the env key adds on
+      # top, {.env_only_config_entries}, is never read here).
       def self.build_run(loader)
         RunDescriptor.new(loader: loader, gems: [rbs_gem_entry], configs: config_entries(loader))
       end
@@ -38,19 +37,47 @@ module Rigor
         [libraries_entry(loader.libraries), virtual_rbs_entry(loader)].compact
       end
 
+      # Issue #610 — the slots only the env-cache KEY reads, on top of {.config_entries}. Which of the
+      # loader's `signature_paths:` are DEFERRED (a bundled plugin's `sig/`, loaded last and allowed to
+      # stand down against a colliding generic arity) changes the env built from byte-identical files, so
+      # the partition belongs in the key: moving a plugin's `sig/` between `plugins:` and an explicit
+      # `signature_paths:` entry changes no file, and an env cached before the producer honoured the
+      # partition must read as a miss once. Kept OUT of {.config_entries} deliberately — the run-result
+      # key already digests the whole resolved configuration (`RunCacheKey`), and its boot-slimming probe
+      # reconstructs {.config_entries} without loading a plugin, so an entry there that it cannot rebuild
+      # would turn the warm fast lane into a permanent miss on every project that enables a bundled plugin.
+      def self.env_only_config_entries(loader)
+        [deferred_signature_paths_entry(loader)].compact
+      end
+
+      def self.deferred_signature_paths_entry(loader)
+        return nil unless loader.respond_to?(:deferred_signature_paths)
+
+        deferred = Array(loader.deferred_signature_paths).map(&:to_s).sort
+        return nil if deferred.empty?
+
+        Descriptor::ConfigEntry.new(
+          key: "rbs.deferred_signature_paths",
+          value_hash: Digest::SHA256.hexdigest(deferred.join("\n"))
+        )
+      end
+
+      private_class_method :deferred_signature_paths_entry
+
       # 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
 
-      # @param comparator [Symbol] `:digest` (default) for the env-cache KEY descriptor ({.build}), where the
+      # @param comparator — `: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
+                Rigor::Environment::RbsLoader.core_overlay_sig_paths +
+                Rigor::Environment::RbsLoader.capability_role_sig_paths
         roots.flat_map do |root|
           next [] unless root.directory?
 
@@ -65,7 +92,40 @@ module Rigor
         end
       end
 
-      # @param library_names [Array<String, Symbol>] the loader's merged library list (or, on the WD4 probe
+      # Issue #979 — the directory-LISTING rows for the signature roots, one {Descriptor::GlobEntry} per
+      # root over `**/*.rbs`. {.file_entries} answers "did any signature file I read change", which is a
+      # question only about files that existed when the run recorded its dependencies; a `sig/roles.rbs`
+      # written afterwards is in no row, so the ADR-45 run-result slot validated fresh and the warm run kept
+      # serving diagnostics computed without it. A glob row is the same edge {Plugin::IoBoundary} records
+      # for a listed directory (#954): re-globbing on the next run sees the appearance, and one row per root
+      # (not per file) keeps the cost a single `Dir.glob`.
+      #
+      # The rows are `:names` mode, not the default `:stat`: the question they add is which signature files
+      # EXIST, and every edit to one of them is already carried by that file's own ADR-87 WD1 `:stat` row —
+      # which survives a moved stat tuple by falling back to its recorded content digest. A stat-mode glob
+      # would not, so a `git checkout`, a `bundle install`, or a CI run with a restored cache over a fresh
+      # checkout — none of which changes a byte of RBS — would turn every warm run into a full re-analysis.
+      # Names mode also reads no stat, so it neither pays for nor perturbs the per-run validation-stat memo.
+      #
+      # Scoped to the loader's own roots — the project's `signature_paths:` (including the auto-detected
+      # `sig/`), the bundled-plugin `sig/` trees (ADR-25), the bundle walk, `rbs collection`, the ADR-72
+      # overlays. Rigor's own `data/` trees ({RbsLoader.vendored_gem_sig_paths}, `.core_overlay_sig_paths`,
+      # `.capability_role_sig_paths`) are engine-owned: a file appears under one only when the engine tree is
+      # edited, which normally arrives with the `lib/` change that reads it and so re-keys every
+      # computed-value slot through {EngineSource}. They get file rows and no glob — a glob there would cost
+      # every project a stat walk of the vendored gem-signature tree per warm run to catch an
+      # engine-development edit.
+      def self.glob_entries(loader)
+        # Deduplicated by path: a root reachable twice (an explicit `signature_paths:` entry that is also a
+        # bundled plugin's `sig/`, #610) would otherwise contribute two rows whose stat signatures race.
+        loader.signature_paths.uniq(&:to_s).filter_map do |root|
+          next unless root.directory?
+
+          Descriptor::GlobEntry.compute(root: root.to_s, pattern: File.join("**", "*.rbs"), mode: :names)
+        end
+      end
+
+      # @param library_names — 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
@@ -93,10 +153,11 @@ module Rigor
 
       private_class_method :virtual_rbs_entry
 
-      # The lazy-files run descriptor {RbsDescriptor.build_run} returns. Exposes the three readers the
+      # The lazy-files run descriptor {RbsDescriptor.build_run} returns. Exposes the four 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.
+      # and are cheap); `files` (the RBS signature-tree digests) and `globs` (#979, the per-root listing
+      # rows) are read only on a MISS, computed once on first access and memoised, so a warm HIT pays for
+      # neither.
       class RunDescriptor
         attr_reader :gems, :configs
 
@@ -106,6 +167,13 @@ module Rigor
           @configs = configs
         end
 
+        # Issue #979 — one directory-listing row per signature root, so a `.rbs` file APPEARING under one
+        # (or vanishing from it) invalidates the run-result slot. Memoised for the same reason `files` is:
+        # a collecting run asks twice about the same post-run world.
+        def globs
+          @globs ||= RbsDescriptor.glob_entries(@loader)
+        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

data/lib/rigor/cache/rbs_environment.rb

@@ -22,14 +22,18 @@ module Rigor
     class RbsEnvironment < RbsCacheProducer
       PRODUCER_ID = "rbs.environment"
 
-      # @param loader [Rigor::Environment::RbsLoader]
-      # @param store [Rigor::Cache::Store]
-      # @return [::RBS::Environment]
+      # Issue #610 — the deferred (plugin-contributed) subset rides through too. This is the build path every
+      # cached run takes: a cache store is the CLI default and only `--no-cache` reaches the loader's own
+      # `build_env`, so a list threaded through the loader but not through here ran the arity stand-down on
+      # no real `rigor check` at all — 0.3.8 shipped exactly that, behind a green gate built over a
+      # store-less loader. Any input `build_env_for` takes MUST be passed from here as well.
       def self.compute(loader)
         Rigor::Environment::RbsLoader.build_env_for(
           libraries: loader.libraries,
           signature_paths: loader.signature_paths,
-          virtual_rbs: loader.respond_to?(:virtual_rbs) ? loader.virtual_rbs : []
+          virtual_rbs: loader.respond_to?(:virtual_rbs) ? loader.virtual_rbs : [],
+          deferred_signature_paths:
+            loader.respond_to?(:deferred_signature_paths) ? loader.deferred_signature_paths : []
         )
       end
 

data/lib/rigor/cache/rbs_known_class_names.rb

@@ -18,9 +18,6 @@ module Rigor
     class RbsKnownClassNames < RbsCacheProducer
       PRODUCER_ID = "rbs.known_class_names"
 
-      # @param loader [Rigor::Environment::RbsLoader]
-      # @param store [Rigor::Cache::Store]
-      # @return [Set<String>]
       def self.compute(loader)
         names = Set.new
         loader.each_known_class_name { |name| names << name }

data/lib/rigor/cache/store.rb

@@ -65,8 +65,8 @@ module Rigor
 
       VALID_PRODUCER_ID = /\A[a-z][a-z0-9._-]*\z/
 
-      # @param root [String] cache root directory.
-      # @param read_only [Boolean] when true, every disk-side side-effect is suppressed: `fetch_or_compute`
+      # @param root — cache root directory.
+      # @param read_only — when true, every disk-side side-effect is suppressed: `fetch_or_compute`
       #   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.
@@ -107,7 +107,7 @@ module Rigor
 
       attr_reader :root
 
-      # @return [Boolean] whether this Store suppresses disk writes (`schema_version.txt`, entry creation).
+      # @return whether this Store suppresses disk writes (`schema_version.txt`, entry creation).
       #   Reads are unaffected.
       def read_only?
         @read_only
@@ -118,7 +118,7 @@ module Rigor
       # specific instance rather than the on-disk cache state. Disk-level state is reported separately by
       # {.disk_inventory}.
       #
-      # @return [Hash] `{ hits:, misses:, writes:, by_producer: { id => { hits:, misses:, writes: } } }`
+      # @return `{ hits:, misses:, writes:, by_producer: { id => { hits:, misses:, writes: } } }`
       def stats
         @monitor.synchronize do
           per_producer = @by_producer.transform_values { |counts| counts.dup.freeze }.freeze
@@ -130,7 +130,7 @@ module Rigor
       # `rigor check --cache-stats` to surface cache size and per-producer entry counts without depending on
       # in-process counters (which only reflect the current run).
       #
-      # @return [Hash] `{ root:, schema_version:, total_entries:, total_bytes:, producers: [{ id:, entries:,
+      # @return `{ root:, schema_version:, total_entries:, total_bytes:, producers: [{ id:, entries:,
       #   bytes: }, ...] }`. When the root does not exist or has no schema-version marker, `schema_version` is
       #   nil and the producer list is empty.
       #
@@ -176,21 +176,21 @@ module Rigor
       end
       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
+      # @param producer_id — stable cache namespace; only `[a-z][a-z0-9._-]*` is accepted.
+      # @param generation_cap — 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
+      # @param params — producer inputs; mixed into the cache key via {Descriptor#cache_key_for}.
+      # @param descriptor — the invalidation descriptor for the value being cached.
+      # @param serialize — optional callable that turns the producer's return value into a binary
       #   `String`. Defaults to `Marshal.dump(value).b`. Producers whose return values are not
       #   `Marshal`-clean (RBS-native objects with `RBS::Location` members, raw `IO`, …) MUST provide a
       #   serialiser. The pair `(serialize, deserialize)` MUST round-trip — a producer that reads with one
       #   strategy and writes with another corrupts its own cache slice.
-      # @param deserialize [#call, nil] optional callable that turns bytes back into the producer's value.
+      # @param deserialize — optional callable that turns bytes back into the producer's value.
       #   Defaults to `Marshal.load`. Any exception (`StandardError`) raised by the deserialiser is treated as
       #   a cache miss — the entry is considered corrupt, the producer block reruns, and the next write
       #   overwrites it. This is consistent with the fault-tolerance contract for the default `Marshal.load`
@@ -394,10 +394,22 @@ module Rigor
 
       # Reads and validates one entry file. Any failure (missing, short, bad magic, bad version, bad
       # checksum, unmarshal-able) returns nil so the caller treats it as a cache miss.
+      #
+      # The `ENOENT` rescue covers the gap between the existence check and the open: a concurrent process
+      # compacting or clearing the root can unlink the file in between, and a file that is gone reads as the
+      # same miss the existence check above already reports for one that was never there (issue #807). It is
+      # deliberately narrow — every other `SystemCallError` (a permission error, an I/O error) still raises,
+      # so a genuinely broken filesystem stays visible instead of degrading into an endless recompute. A
+      # present-but-corrupt file is not touched by this either: it still goes through the envelope and
+      # payload checks below.
       def read_entry(path, deserialize: nil)
         return nil unless File.file?(path)
 
-        bytes = File.binread(path)
+        begin
+          bytes = File.binread(path)
+        rescue Errno::ENOENT
+          return nil
+        end
         return nil unless envelope_valid?(bytes)
 
         body = bytes.byteslice(HEADER.bytesize, bytes.bytesize - HEADER.bytesize - 32)
@@ -486,22 +498,34 @@ module Rigor
       def atomically_replace(path, body)
         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)}"
-          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
+          publish_by_rename(path, body)
           fsync_directory(File.dirname(path))
         end
       end
 
+      # The rename-into-place half of {#atomically_replace}, without the destination lock: writes `body` to a
+      # sibling temp file, fsyncs it, and renames it over `path`. POSIX makes the rename atomic within one
+      # filesystem, so an unlocked concurrent reader sees either the previous contents in full or the new
+      # ones in full — never a truncated or half-written file.
+      #
+      # {#repair_writable_marker!} uses this half alone. It needs the atomicity (its reader is another
+      # process's constructor, which does not lock) but not the ordering a lock would buy: every writer of
+      # `schema_version.txt` writes the same value, so there is no last-writer-wins question to settle.
+      def publish_by_rename(path, body)
+        tmp = "#{path}.tmp.#{Process.pid}.#{SecureRandom.hex(4)}"
+        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
+      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
@@ -515,8 +539,6 @@ module Rigor
       # (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!
         return @disk_available unless @disk_available.nil?
 
@@ -532,25 +554,48 @@ module Rigor
         false
       end
 
+      # The marker is PUBLISHED BY RENAME rather than written in place. Its reader is another process's
+      # constructor, which takes no lock, so an `O_TRUNC`-then-write would expose a window in which the file
+      # exists and is empty; a reader landing there concludes the marker disagrees and clears the whole cache
+      # root — under, among others, a sibling that is between its own `File.file?` and `File.binread`, which
+      # is the `Errno::ENOENT` of issue #807. Two `rigor check` processes over one fresh `.rigor/cache` are
+      # enough to hit it.
+      #
+      # An EMPTY marker is treated as an ABSENT one — rewritten, never cleared on. Emptiness carries no
+      # information: it is what a torn write by an older Rigor looks like, what a crash between the create
+      # and the write leaves, and what this method's own clear-then-rewrite passes through. Answering an
+      # ambiguous signal by destroying a cache root is the wrong trade, and declining grants the entries
+      # below no trust they did not already have — a marker that is simply MISSING over existing entries is
+      # already kept and served (see the spec's writable-store rules), and `clear_cache_root!` removes the
+      # marker before rewriting it, so it produces that state itself.
       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 true if on_disk == current
+        on_disk = read_marker(marker)
+        return true if on_disk == current
 
-          clear_cache_root!
-        end
+        clear_cache_root! unless on_disk.nil? || on_disk.empty?
 
         FileUtils.mkdir_p(@root)
-        File.write(marker, "#{current}\n")
+        publish_by_rename(marker, "#{current}\n")
+        fsync_directory(@root)
         true
       rescue StandardError
         false
       end
 
+      # @return the marker's content, or nil when there is none to read — including the case of a concurrent
+      #   {#clear_cache_root!} removing it between the check and the open.
+      def read_marker(path)
+        return nil unless File.file?(path)
+
+        File.read(path).strip
+      rescue Errno::ENOENT
+        nil
+      end
+
       def clear_cache_root!
         Dir.children(@root).each do |entry|
           FileUtils.rm_rf(File.join(@root, entry))

data/lib/rigor/cli/annotate_command.rb

@@ -15,7 +15,7 @@ require_relative "../inference/scope_indexer"
 require_relative "../inference/statement_evaluator"
 require_relative "prism_colorizer"
 require_relative "command"
-require_relative "probe_environment"
+require_relative "../project_environment"
 
 module Rigor
   class CLI
@@ -43,7 +43,7 @@ module Rigor
       # paging stays off because the CLI may itself sit in a pipeline.
       BAT_ARGS = %w[--language=ruby --style=plain --paging=never --color=always].freeze
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         file = @argv.shift
@@ -132,10 +132,10 @@ module Rigor
 
       # The plugin-aware environment for the annotated file, so a `#=> <type>` matches what `rigor check`
       # infers on that line — including types synthesized from the file's own inline RBS annotations (the file
-      # is threaded as the synthesizer's `source_files:`; see {ProbeEnvironment}).
+      # is threaded as the synthesizer's `source_files:`; see {ProjectEnvironment}).
       def base_scope(configuration, file)
         Scope.empty(
-          environment: ProbeEnvironment.build(configuration: configuration, source_files: [file])
+          environment: ProjectEnvironment.build(configuration: configuration, source_files: [file])
         )
       end
 
@@ -220,8 +220,7 @@ module Rigor
         @scope_index = scope_index
       end
 
-      # @param program [Prism::ProgramNode]
-      # @return [Hash{Integer => Rigor::Type}] 1-indexed line => type.
+      # @return 1-indexed line => type.
       def collect(program)
         by_line = {}
         each_statement(program) do |statement|