rigortype 0.4.6 → 0.4.8

data/lib/rigor/cache/file_digest.rb

@@ -2,6 +2,8 @@
 
 require "digest"
 
+require_relative "../typing_state"
+
 module Rigor
   module Cache
     # Per-run content-digest memo AND the ADR-87 stat-then-digest freshness choke point. Within a single
@@ -20,20 +22,38 @@ module Rigor
     # zero SHA-256 bytes. The SHA-256 digest remains the sole change AUTHORITY — the stat tier only decides
     # whether the digest needs recomputing.
     #
-    # Soundness: the memo + recording-instant + strict flag are process-local (thread-locals, so Ractor-safe
-    # and never crossing a fork boundary), never persisted to disk, and scoped to exactly one run via
-    # {.with_run} (which installs a fresh table and restores the previous one on exit — a second run, or a run
+    # Soundness: the memo + recording-instant + strict flag are process-local (a per-thread {TypingState}
+    # Frame, so Ractor-safe and never crossing a fork boundary), never persisted to disk, and scoped to exactly one
+    # run via {.with_run} (which installs a fresh table and restores the previous one on exit — a second run, or a run
     # that re-reads a file the user edited between runs, gets a clean table). Within a single run the analyzer
     # already assumes the filesystem is stable — {Descriptor#fresh?} validates the whole dependency set against
     # the live tree in one pass and never re-checks mid-run — so caching a coherent per-run snapshot changes
     # nothing about what a run observes. Outside a run scope (no active table) every call digests directly,
     # identical to a bare `Digest::SHA256.file`.
     module FileDigest
-      MEMO_KEY = :rigor_cache_file_digest_memo
-      STAT_KEY = :rigor_cache_file_stat_memo
-      INSTANT_KEY = :rigor_cache_recording_instant
-      STRICT_KEY = :rigor_cache_strict_validation
-      private_constant :MEMO_KEY, :STAT_KEY, :INSTANT_KEY, :STRICT_KEY
+      # One run's state: the digest table, the stat table, the recording instant and the strict flag, installed
+      # together by {.with_run}.
+      Run = Data.define(:digests, :stats, :instant, :strict)
+      private_constant :Run
+
+      # ADR-129 WD1 — a Frame: {.with_run} installs the run and restores the previous one on the way out, and whether
+      # one is installed changes answers (outside a run every call digests or stats directly, the recording instant
+      # is the moment of the call, and validation is not strict). The installed {Run} is frozen; its two tables are
+      # extensional caches its owner fills in place without a touch (Memos by kind, whose entry is fixed once
+      # written): `digests` is keyed on the path and reads the file's bytes, `stats` is keyed on the path and reads
+      # its `File::Stat`, both under the run's premise that the filesystem is stable. The instant and the flag are
+      # read at install time.
+      RUN = TypingState.frame(
+        :file_digest_run,
+        memos: %i[digests stats],
+        reason: "installed per run by with_run; the digest and stat tables are extensional caches keyed on the path, " \
+                "filled in place, both reading the filesystem under the run's stable-filesystem premise, and the " \
+                "recording instant and strict flag are fixed at install",
+        # G1′: the run wraps the typing of every file, but the digest and stat lookups are the cache layer's, made while
+        # the RBS environment is prepared and its producers fetched, before anything types (#2883).
+        typing_never_reads: true
+      )
+      private_constant :RUN
 
       # Set in the environment to force the strict digest-always validation path for a single run, regardless
       # of the `cache.validation` config setting (the env wins). The escape hatch for a filesystem whose stat
@@ -46,21 +66,9 @@ module Rigor
       # captured at run start — a file whose recorded mtime is not strictly older than it is treated as racy
       # (always re-hashed), catching a file edited during the analysis window. `strict:` forces the
       # digest-always path for `cache.validation: digest`.
-      def self.with_run(strict: false)
-        previous_memo = Thread.current[MEMO_KEY]
-        previous_stat = Thread.current[STAT_KEY]
-        previous_instant = Thread.current[INSTANT_KEY]
-        previous_strict = Thread.current[STRICT_KEY]
-        Thread.current[MEMO_KEY] = {}
-        Thread.current[STAT_KEY] = {}
-        Thread.current[INSTANT_KEY] = now_ns
-        Thread.current[STRICT_KEY] = strict
-        yield
-      ensure
-        Thread.current[MEMO_KEY] = previous_memo
-        Thread.current[STAT_KEY] = previous_stat
-        Thread.current[INSTANT_KEY] = previous_instant
-        Thread.current[STRICT_KEY] = previous_strict
+      def self.with_run(strict: false, &)
+        run = Run.new(digests: {}, stats: {}, instant: now_ns, strict: strict)
+        TypingState.current.with(RUN, run, &)
       end
 
       # The SHA-256 hex digest of `path`'s current content. Served from the active per-run table when one is
@@ -68,10 +76,10 @@ module Rigor
       # read failure (missing / unreadable file) propagates exactly as `Digest::SHA256.file` would and is NOT
       # memoised, so a caller's own rescue path is unchanged.
       def self.hexdigest(path)
-        memo = Thread.current[MEMO_KEY]
-        return Digest::SHA256.file(path).hexdigest if memo.nil?
+        run = TypingState.current[RUN]
+        return Digest::SHA256.file(path).hexdigest if run.nil?
 
-        memo[path] ||= Digest::SHA256.file(path).hexdigest
+        run.digests[path] ||= Digest::SHA256.file(path).hexdigest
       end
 
       # @return whether digest-always validation is forced for this run. The env var wins over the
@@ -79,7 +87,7 @@ module Rigor
       def self.strict_validation?
         return true if ENV[STRICT_ENV] == "1"
 
-        Thread.current[STRICT_KEY] == true
+        TypingState.current[RUN]&.strict == true
       end
 
       # ADR-87 WD1 — packs the `:stat` FileEntry value: `"<digest> <size> <mtime_ns> <ctime_ns> <inode>
@@ -156,14 +164,14 @@ module Rigor
       # describe that moment rather than an earlier probe's. A stat failure propagates un-memoised, exactly
       # as {.hexdigest} treats a read failure.
       def self.validation_stat(path)
-        memo = Thread.current[STAT_KEY]
-        return File.stat(path) if memo.nil?
+        run = TypingState.current[RUN]
+        return File.stat(path) if run.nil?
 
-        memo[path] ||= File.stat(path)
+        run.stats[path] ||= File.stat(path)
       end
 
       def self.recording_instant_ns
-        Thread.current[INSTANT_KEY] || now_ns
+        TypingState.current[RUN]&.instant || now_ns
       end
 
       # value layout: [digest, size, mtime_ns, ctime_ns, inode, recording_instant_ns]

data/lib/rigor/cache/incremental_snapshot.rb

@@ -8,6 +8,7 @@ require_relative "engine_source"
 require_relative "store"
 require_relative "../analysis/shadow_harness"
 require_relative "../analysis/run_cache_key"
+require_relative "../analysis/runner/run_level_facts"
 require_relative "../environment"
 require_relative "../analysis/path_expansion"
 require_relative "../rooted_glob"
@@ -195,20 +196,43 @@ module Rigor
       # 45: issue #1154 — each seed bundle's `global_write_census` also records the ivar writers the declared-parameter
       # credit reads (`[:ivar_set, name]`, `[:ivar_set_class, class]`, `[:own_write, class, name, path]`), which a
       # pre-45 bundle carries none of, so a warm run would credit an ivar write a cold run declines.
-      SCHEMA = 45
+      # 46: issue #2314 — each seed bundle's `global_write_census` also records the global writers
+      # (`[:global_writer, name, method]`) the statement walk reads past a call; a pre-46 bundle carries none, so a
+      # warm run would keep a global's binding a cold run forgets.
+      # 47: issues #2079 / #2170 — each seed bundle's `global_write_census` also records each instance-side ivar
+      # write's coarse value (`[:own_write_type, class, name, value, path]`), which the class-ivar census joins across
+      # files and along the chain; a pre-47 bundle carries none, so a warm run would keep a seed a cold run widens.
+      # 48: issue #1237 — a `return_summaries` key may carry a third element, `true`, for a call key a splat call
+      # observed, which the gate re-drives with no positional correspondence. A pre-48 summary holds such a call under a
+      # positional key the engine bound as one argument, so a warm run would re-drive it the old way.
+      # 49: issue #3116 — a `return_summaries` entry for a def observed under more keys than the per-def cap is
+      # `{ keys: [], returns: [], effects:, overflow: true }`. A pre-49 summary holds the first eight keys of such a
+      # def with no marker, so a warm run would skip the reader of a key it never recorded.
+      # 50: issue #3160 — a `return_summaries` entry holds every key under which a current reader observes the def,
+      # merged across the runs that observed them, and a def whose keys cannot all be listed has no entry (the
+      # `overflow` form of 49 is gone). A pre-50 summary holds only what the last run that analysed the def's file
+      # saw, so a warm run would skip a reader added, or left out of that run, since.
+      # 51: issue #3180 — a reader the ADR-89 WD2 gate skipped holds the dependency edges the gate's probe recorded
+      # for the def it passed, and the summaries hold the keys that probe observed. A pre-51 snapshot's skipped
+      # readers lack the edges and keys of whatever a gate-passed def came to reach, so a warm run would skip them.
+      # 52: issues #3186 / #3187 — a `return_summaries` entry also holds `guard_constants`, the published-constant
+      # spellings the truthiness rule's one hop reads in the def's body, and a gate-skipped reader holds the plugin
+      # reads and run-scoped registrations the gate's probe made. A pre-52 snapshot's skipped readers lack those
+      # plugin rows, so a warm run would serve them past an edit of what the plugin read.
+      SCHEMA = 52
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
-      # `sources` maps a consumer to the Set of source files it read from.
+      # `sources` maps a consumer to the source files it read from.
       # `digests` maps a file to its content digest at analysis time.
       # `analyzed` is the ordered analyzed-file list.
       # ADR-46 slice 4:
-      # `symbol_sources` maps a consumer to { source_path → Set<"ClassName#method"> }.
-      # `ancestry_sources` maps a consumer to Set<source_path> (class-ancestry deps).
+      # `symbol_sources` maps a consumer to { source_path → the "ClassName#method" names it read }.
+      # `ancestry_sources` maps a consumer to the source paths it read for class ancestry.
       # `symbol_fingerprints` maps a path to { "ClassName#method" => sha256_hex }.
       # 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.
+      # `missing` maps a consumer to the "kind:name" keys it looked up and missed.
+      # `class_decls` maps a path to the qualified class names it declares.
       # Issue #644:
       # `constant_decls` maps a path to that file's constant PUBLICATION CENSUS,
       # `{qualified name => [literal] | :unpublishable}`. The descriptor is what the recheck diffs: a name's
@@ -226,10 +250,15 @@ module Rigor
       # 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.
+      # behavioural surface `{ keys:, returns:, effects:, guard_constants: }` — the observed `[receiver, arg_types]`
+      # call keys (issue #1237: `[receiver, arg_types, true]` for a key a splat call observed)
+      # (Marshal-clean type tuples), their `describe(:short)` return descriptors, the content-mutated
+      # parameter positions, and (issue #3186) the published-constant spellings the body reads.
+      # A recheck re-evaluates a declaration-stable changed callee at these keys and,
+      # when every return, the effects and the spellings are unchanged, skips its symbol dependents.
+      # Issues #3116 / #3160 — an entry
+      # holds every key under which a current symbol dependent observes the def; a def whose keys cannot all be
+      # listed (more than the per-def cap, among others) has no entry, and the recheck never skips its dependents.
       # ADR-67 WD6c lift:
       # `param_table` is the `parameter_inference:` seed table (`[class, method, kind] => {param => Type}`)
       # the run that wrote the snapshot seeded its analysis from — `{}` when the gate is off. A recheck
@@ -279,12 +308,14 @@ module Rigor
         end
       end
 
-      # 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)
+      # Issues #796 / #794 — the run-level rows the snapshot carries: one member per run-level fact declared
+      # `replay` ({Analysis::Runner::RunLevelFacts}, ADR-116 WD3). Today that is `definition_build_failures`,
+      # the reported per-class detail list ({Environment::RbsLoader#definition_build_failures}), and
+      # `hkt_scan_failure`, 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. Declaring another fact `replay`
+      # changes this shape, so it bumps {SCHEMA}.
+      RunLevelRows = Data.define(*Analysis::Runner::RunLevelFacts.replayable_names)
 
       # 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
@@ -324,7 +355,7 @@ module Rigor
           "sig:#{digest_signature_paths(project_sig_roots(configuration))}",
           "pre_eval:#{digest_pre_eval(configuration.pre_eval)}"
         ]
-        parts.concat(dependency_source_parts(configuration))
+        parts.concat(project_input_parts(configuration))
         identity = EngineSource.process_identity
         parts << "engine-source:#{identity}" if identity
         # Issue #1700 — the gated vendored signatures the run's source activates. A file that gains or drops a
@@ -347,6 +378,37 @@ module Rigor
         nil
       end
 
+      # Issue #2517 — a selected core is read like the project's own `sig/`, so an edit in place to one of its files
+      # must drop the snapshot (and the language server's session, which keys on this fingerprint). No part for the
+      # default core, so every other project's fingerprint is as it was.
+      def self.extra_signature_parts(configuration)
+        core_root_parts(configuration) + bundle_sig_parts(configuration)
+      end
+      private_class_method :extra_signature_parts
+
+      def self.core_root_parts(configuration)
+        core_root = configuration.core_root
+        core_root.nil? ? [] : ["core:#{digest_signature_paths([core_root])}"]
+      end
+      private_class_method :core_root_parts
+
+      # Issue #2987 — the bundle gems' own `sig/` directories the environment loads: which gems have one and what
+      # their `.rbs` files hold. The lockfile digest above covers a gem's version, not a `sig/` appearing under an
+      # unchanged version, nor an edit in place to one. Shared with the language server's session key. No part for a
+      # project whose bundle holds none, so its fingerprint is as it was.
+      def self.bundle_sig_parts(configuration)
+        locked = Environment::LockfileResolver.locked_gems(
+          lockfile_path: configuration.bundler_lockfile, project_root: Dir.pwd,
+          auto_detect: configuration.bundler_auto_detect
+        )
+        dirs = Environment::BundleSigDiscovery.discover(
+          bundle_path: configuration.bundler_bundle_path, project_root: Dir.pwd,
+          auto_detect: configuration.bundler_auto_detect, locked_gems: locked.empty? ? nil : locked
+        ).map(&:to_s).sort
+        dirs.empty? ? [] : ["bundle-sig:#{dirs.join("\n")}:#{digest_signature_paths(dirs)}"]
+      end
+      private_class_method :bundle_sig_parts
+
       def self.required_features(configuration, roots)
         files = Analysis::PathExpansion.ruby_files(roots, configuration.exclude_patterns,
                                                    base: configuration.exclude_base)
@@ -364,6 +426,22 @@ module Rigor
       end
       private_class_method :dependency_source_parts
 
+      # The parts read off the project beside its configuration, in the order the fingerprint has always joined them:
+      # the extra signature roots, the `dependencies.source_inference` gems, and (#3030) the collection setup hint.
+      def self.project_input_parts(configuration)
+        extra_signature_parts(configuration) + dependency_source_parts(configuration) +
+          collection_setup_hint_parts(configuration)
+      end
+      private_class_method :project_input_parts
+
+      # Issue #3030 — the `rbs.coverage.collection-not-installed` hint, a run-level row read off the working directory
+      # that no other part covers. No part without a hint, so every other project's fingerprint is as it was.
+      def self.collection_setup_hint_parts(configuration)
+        hint = Analysis::RunCacheKey.collection_setup_hint(configuration)
+        hint ? ["rbs-collection-hint:#{hint}"] : []
+      end
+      private_class_method :collection_setup_hint_parts
+
       def self.digest_file_if_present(path)
         path = path&.to_s
         path && File.file?(path) ? Digest::SHA256.file(path).hexdigest : "absent"

data/lib/rigor/cache/rbs_cache_producer.rb

@@ -6,8 +6,8 @@ module Rigor
   module Cache
     # Base for the RBS-derived cache producers.
     #
-    # Every producer (`RbsKnownClassNames`, `RbsConstantTable`, `RbsEnvironment`, the ancestor / type-param /
-    # definition tables, …) repeated the identical `fetch` wiring: build the RBS descriptor, then
+    # Every producer (`RbsKnownClassNames`, `RbsConstantTable`, `RbsEnvironment`, the ancestor / type-param
+    # tables, …) repeated the identical `fetch` wiring: build the RBS descriptor, then
     # `store.fetch_or_compute` under the producer's id, yielding to the producer's `compute`. Only the
     # `PRODUCER_ID` constant and the `compute(loader)` body actually differ between producers.
     #

data/lib/rigor/cache/rbs_class_ancestor_table.rb

@@ -6,7 +6,7 @@ require_relative "rbs_cache_producer"
 module Rigor
   module Cache
     # Cache producer that materialises the RBS-declared ancestor chain of every loaded class / module into a
-    # Marshal-clean `Hash<String, Array<String>>`. Ancestor names are top-level-stripped (e.g. `"Integer"` not
+    # Marshal-clean table. Ancestor names are top-level-stripped (e.g. `"Integer"` not
     # `"::Integer"`) to match `Environment::RbsHierarchy#normalize_name`.
     #
     # The hierarchy is the substrate behind every `class_ordering` query, which is itself a hot path on the

data/lib/rigor/cache/rbs_class_type_param_names.rb

@@ -6,8 +6,8 @@ require_relative "rbs_cache_producer"
 module Rigor
   module Cache
     # Cache producer that materialises every loaded class's RBS-declared type-parameter names as a
-    # Marshal-clean `Hash<String, Array<Symbol>>` keyed by top-level-stripped class name (e.g. `"Array"` →
-    # `[:Elem]`, `"Hash"` → `[:K, :V]`). Producer id `"rbs.class_type_param_names"`.
+    # Marshal-clean table keyed by top-level-stripped class name (e.g. `"Array"` →
+    # `[:Elem]`, `"Hash"` → `[:K, :V]`).
     #
     # The dispatcher reads type-parameter names every time it builds a substitution map from a receiver's
     # `type_args` into a method's return type — it is one of the hottest reflection lookups during analysis.

data/lib/rigor/cache/rbs_constant_table.rb

@@ -6,7 +6,7 @@ require_relative "rbs_cache_producer"
 module Rigor
   module Cache
     # Cache producer that materialises every RBS-declared constant to its translated `Rigor::Type` form and
-    # stores the result as a `Hash<String, Rigor::Type>` keyed by canonical constant name. This is the v0.0.8
+    # stores the result as a table keyed by canonical constant name. This is the v0.0.8
     # first cached producer per ADR-6 § 7; it caches a post-translation artefact so the cache value is
     # `Marshal`-clean (RBS-native objects carry `RBS::Location`, which lacks `_dump_data`).
     #

data/lib/rigor/cache/rbs_descriptor.rb

@@ -77,9 +77,58 @@ module Rigor
       # 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
+        [deferred_signature_paths_entry(loader), project_signature_paths_entry(loader), core_root_entry(loader),
+         subordinate_signature_paths_entry(loader), collection_signature_paths_entry(loader)].compact
       end
 
+      # Issue #2517 — which directory the env loaded core from. The selected core's files are digested by
+      # {.file_entries} too, so this row is the identity of the choice and those rows its contents: switching
+      # between two roots with byte-identical files still re-keys. Absent for the default core, whose identity
+      # is the `rbs` gem row, so every project without the setting keeps its key.
+      def self.core_root_entry(loader)
+        core_root = selected_core_root(loader)
+        return nil if core_root.nil?
+
+        Descriptor::ConfigEntry.new(key: "rbs.core_root", value_hash: Digest::SHA256.hexdigest(core_root.to_s))
+      end
+
+      private_class_method :core_root_entry
+
+      # The loader's issue #2517 core root as a Pathname, or nil for the default core.
+      def self.selected_core_root(loader)
+        core_root = loader.respond_to?(:core_root) ? loader.core_root : nil
+        core_root.nil? ? nil : Pathname(core_root)
+      end
+
+      private_class_method :selected_core_root
+
+      # {.selected_core_root} as the signature roots it adds: none for the default core.
+      def self.core_root_dirs(loader)
+        core_root = selected_core_root(loader)
+        core_root.nil? ? [] : [core_root]
+      end
+
+      private_class_method :core_root_dirs
+
+      # Issue #2422 — which of the loader's `signature_paths:` are the project's own changes the env built from
+      # byte-identical files: a bundled plugin's method composes with another source's as an overload, but stands
+      # down to the project's own. Only read when a plugin defers signatures, so a project without one keeps its
+      # key.
+      def self.project_signature_paths_entry(loader)
+        return nil unless loader.respond_to?(:project_signature_paths) && loader.respond_to?(:deferred_signature_paths)
+        return nil if Array(loader.deferred_signature_paths).empty?
+
+        own = Array(loader.project_signature_paths).map(&:to_s).sort
+        return nil if own.empty?
+
+        Descriptor::ConfigEntry.new(
+          key: "rbs.project_signature_paths",
+          value_hash: Digest::SHA256.hexdigest(own.join("\n"))
+        )
+      end
+
+      private_class_method :project_signature_paths_entry
+
       def self.deferred_signature_paths_entry(loader)
         return nil unless loader.respond_to?(:deferred_signature_paths)
 
@@ -94,6 +143,40 @@ module Rigor
 
       private_class_method :deferred_signature_paths_entry
 
+      # Issue #2978 — which of the loader's `signature_paths:` stand down member by member to the rest (a bundle gem's
+      # collection copy behind its own `sig/`) changes the env built from byte-identical files, as the deferred
+      # partition does. Absent when there is none, so every other project keeps its key.
+      def self.subordinate_signature_paths_entry(loader)
+        return nil unless loader.respond_to?(:subordinate_signature_paths)
+
+        subordinate = Array(loader.subordinate_signature_paths).map(&:to_s).sort
+        return nil if subordinate.empty?
+
+        Descriptor::ConfigEntry.new(
+          key: "rbs.subordinate_signature_paths",
+          value_hash: Digest::SHA256.hexdigest(subordinate.join("\n"))
+        )
+      end
+
+      private_class_method :subordinate_signature_paths_entry
+
+      # Issue #3030 — which of the loader's `signature_paths:` are `rbs collection` gem directories decides whether
+      # their `_`-prefixed directories load, so it changes the env built from byte-identical files. Absent when
+      # there is none, so every project without a collection lockfile keeps its key.
+      def self.collection_signature_paths_entry(loader)
+        return nil unless loader.respond_to?(:collection_signature_paths)
+
+        collection = Array(loader.collection_signature_paths).map(&:to_s).sort
+        return nil if collection.empty?
+
+        Descriptor::ConfigEntry.new(
+          key: "rbs.collection_signature_paths",
+          value_hash: Digest::SHA256.hexdigest(collection.join("\n"))
+        )
+      end
+
+      private_class_method :collection_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
@@ -104,7 +187,9 @@ module Rigor
       #   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 +
+        # Issue #2517 — a selected core is project input like `signature_paths:`, not the engine-versioned `rbs`
+        # gem tree, so an edit in place must move the key.
+        roots = core_root_dirs(loader) + loader.signature_paths +
                 Rigor::Environment::RbsLoader.vendored_gem_sig_paths +
                 Rigor::Environment::RbsLoader.core_overlay_sig_paths +
                 Rigor::Environment::RbsLoader.capability_role_sig_paths
@@ -149,7 +234,8 @@ module Rigor
       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|
+        # Issue #2517 — and the selected core's root, where a file appearing is as much a new input.
+        (core_root_dirs(loader) + 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)
@@ -157,7 +243,7 @@ module Rigor
       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).
+      #   path, `Environment::BaseLibraries.resolve` reconstructed without a loader).
       def self.libraries_entry(library_names)
         sorted = library_names.map(&:to_s).sort
         Descriptor::ConfigEntry.new(

data/lib/rigor/cache/rbs_environment.rb

@@ -33,7 +33,14 @@ module Rigor
           signature_paths: loader.signature_paths,
           virtual_rbs: loader.respond_to?(:virtual_rbs) ? loader.virtual_rbs : [],
           deferred_signature_paths:
-            loader.respond_to?(:deferred_signature_paths) ? loader.deferred_signature_paths : []
+            loader.respond_to?(:deferred_signature_paths) ? loader.deferred_signature_paths : [],
+          project_signature_paths:
+            loader.respond_to?(:project_signature_paths) ? loader.project_signature_paths : [],
+          core_root: loader.respond_to?(:core_root) ? loader.core_root : nil,
+          subordinate_signature_paths:
+            loader.respond_to?(:subordinate_signature_paths) ? loader.subordinate_signature_paths : [],
+          collection_signature_paths:
+            loader.respond_to?(:collection_signature_paths) ? loader.collection_signature_paths : []
         )
       end
 

data/lib/rigor/cache/rbs_environment_marshal_patch.rb

@@ -53,8 +53,8 @@ require_relative "annotation_location"
 #   differently, and only the latter reaches `marshal_load`), so without the bump a stale blob would keep
 #   reporting the moved position indefinitely.
 #
-# 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.
+# Idempotent: each hook is defined only when `method_defined?` reports it missing, 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

data/lib/rigor/cache/rbs_known_class_names.rb

@@ -7,7 +7,7 @@ module Rigor
   module Cache
     # Cache producer that materialises the set of every RBS-declared class / module / alias name (top-level
     # prefixed, e.g. `"::Math"`) currently loaded into the environment. Marshal-clean — the cache value is a
-    # `Set<String>`.
+    # Set of names.
     #
     # The set lets `RbsLoader#class_known?` answer point lookups in O(1) without re-parsing the name on each
     # call, and lets a warm process skip the env walk entirely (the env still has to be built to enumerate

data/lib/rigor/cache/store.rb

@@ -135,14 +135,6 @@ module Rigor
         end
       end
 
-      # Walks the on-disk cache rooted at `root` and reports a producer-level inventory. Used by
-      # `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 `{ 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.
-      #
       # The `schema_version.txt` marker content. Covers BOTH invalidation axes: the descriptor schema and the
       # on-disk byte layout ({FORMAT_VERSION}, ADR-54). A format bump leaves the old entries permanently
       # unreadable (header mismatch → miss) but, alone, would never reclaim their bytes — they can sit below
@@ -152,6 +144,13 @@ module Rigor
         "#{PAYLOAD_ABI_VERSION}.#{Descriptor::SCHEMA_VERSION}.#{FORMAT_VERSION}"
       end
 
+      # Walks the on-disk cache rooted at `root` and reports a producer-level inventory. Used by
+      # `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 `{ 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.
       def self.disk_inventory(root:)
         root_s = root.to_s
         marker = File.join(root_s, "schema_version.txt")
@@ -360,7 +359,8 @@ module Rigor
       # 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
+      # signal: a disk hit (not an in-process-memo hit) updates the mtime when `max_bytes:` is set, so
+      # recently-read entries survive
       # the eviction pass. Any FS error is swallowed — eviction must never break a run.
       def evict!
         return if @read_only
@@ -591,7 +591,8 @@ module Rigor
       # — 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
+      # A writable store clears the cache root and rewrites the marker on a stale marker (a missing or empty
+      # one is rewritten without clearing), 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

data/lib/rigor/ci_detector.rb

@@ -20,7 +20,7 @@ module Rigor
   # 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.
+  # `RIGOR_CI_DETECT=0` (or `false`/`no`/`off`) 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