rigortype 0.3.8 → 0.4.0

data/lib/rigor/cache/descriptor.rb

@@ -48,7 +48,17 @@ module Rigor
       # added to a schema-less project) invalidates the warm entry. A pre-8 entry carries no absence rows
       # and would validate fresh across exactly that edit, so cached entries must read as misses once and
       # rebuild carrying the rows.
-      SCHEMA_VERSION = 8
+      # v9: #979 — the run-result dependency descriptor now carries a names-only {GlobEntry} directory
+      # listing per RBS signature root, so a `.rbs` file APPEARING under one (a `sig/roles.rbs` declaring the
+      # interface a `conforms-to` names) invalidates the warm entry. A pre-9 entry carries no signature-root
+      # row and would validate fresh across exactly that edit — the #577 reasoning, one slot over — so cached
+      # entries must read as misses once and rebuild carrying the rows.
+      # v10: #1123 — the def-index seed bundles gain the `:prepends` table, the instance-ancestor-ORDER half
+      # of the `include` table (`prepend M`, and `Recv.prepend(M)`), which `Scope#user_def_through_ancestors`
+      # searches ahead of a class's own `def`s. A pre-10 bundle would silently contribute no prepends for an
+      # unchanged file, so that file's consumers would keep answering with the pre-fix MRO — cached bundles
+      # must read as misses once and rebuild carrying the slot.
+      SCHEMA_VERSION = 10
 
       # Per-slot entry value objects. Constructors validate enums / required fields and freeze the resulting
       # struct so no caller can mutate after the entry is in a Descriptor.
@@ -114,7 +124,7 @@ module Rigor
           new(path: path, comparator: :exists, value: PRESENT)
         end
 
-        # @return [Boolean] whether this row records the path as absent (see {.absent}).
+        # @return whether this row records the path as absent (see {.absent}).
         def absent?
           comparator == :exists && value == ABSENT
         end
@@ -235,31 +245,58 @@ module Rigor
         FIELD_SEPARATOR = "\0"
         private_constant :ROW_SEPARATOR, :FIELD_SEPARATOR
 
+        # `:stat` is the ADR-87 WD2 signature above — it answers "did anything under this glob change",
+        # appearance and edit alike. `:names` (#979) answers only "did the SET of matching paths change":
+        # its rows are the sorted relative names, so a file whose bytes are unchanged never moves the
+        # signature however its stat tuple moved. A row exists to catch appearance/disappearance only —
+        # edits to the files it lists are already carried by their own `:stat` {FileEntry} rows — and a
+        # names row must therefore survive what those rows survive. A `:stat` glob over a signature tree
+        # would not: ADR-87 WD1 lets a `:stat` file row fall back to its recorded content digest when the
+        # tuple moves, so a `git checkout`, a `bundle install` or a CI cache restored over a fresh checkout
+        # keeps the file rows fresh while it would move every glob signature, turning every such run into a
+        # full re-analysis. `:names` also reads no stat at all, so it costs a `Dir.glob` and nothing else.
+        VALID_MODES = %i[stat names].freeze
+
         attr_reader :root, :pattern, :value
 
-        value_fields :root, :pattern, :value
+        value_fields :root, :pattern, :mode, :value
+
+        def initialize(root:, pattern:, value:, mode: :stat)
+          raise ArgumentError, "GlobEntry mode must be one of #{VALID_MODES.inspect}, got #{mode.inspect}" \
+            unless VALID_MODES.include?(mode)
 
-        def initialize(root:, pattern:, value:)
           @root = root.to_s.dup.freeze
           @pattern = pattern.to_s.dup.freeze
+          @mode = mode
           @value = value.to_s.dup.freeze
           freeze
         end
 
+        # Defaulted rather than an `attr_reader` because an entry Marshal-loaded from a store written before
+        # the field existed carries no `@mode` ivar; every such entry was recorded under the stat signature.
+        def mode
+          @mode || :stat
+        end
+
         # Builds the entry for the glob's CURRENT filesystem state.
-        def self.compute(root:, pattern:)
-          new(root: root, pattern: pattern, value: signature_for(root: root, pattern: pattern))
+        def self.compute(root:, pattern:, mode: :stat)
+          new(root: root, pattern: pattern, mode: mode,
+              value: signature_for(root: root, pattern: pattern, mode: mode))
         end
 
         # The aggregate signature the entry's `value` carries: SHA-256 over the sorted per-file rows. In the
         # default (`:stat`) mode a row is the file's `(path, size, mtime_ns, ctime_ns, inode)` tuple — NO
         # content read; in strict mode a row is `(path, content-sha256)`, restoring the pre-ADR-87 authority.
+        # In `:names` mode a row is the path alone, stat-free, so only the matching SET moves the signature.
         # Per-file stat failures (a file vanishing between the glob and the stat) drop the row — same race
         # posture as {Descriptor#file_entry_fresh?}. `Dir.glob` returns sorted entries by default so the row
         # order — and therefore the signature — is stable.
-        def self.signature_for(root:, pattern:)
+        def self.signature_for(root:, pattern:, mode: :stat)
+          paths = Dir.glob(File.join(root, pattern))
+          return Digest::SHA256.hexdigest(paths.map { |path| "#{path}#{ROW_SEPARATOR}" }.join) if mode == :names
+
           strict = FileDigest.strict_validation?
-          rows = Dir.glob(File.join(root, pattern)).filter_map do |path|
+          rows = paths.filter_map do |path|
             st = File.stat(path)
             next nil unless st.file?
 
@@ -276,23 +313,30 @@ module Rigor
         end
 
         # ADR-87 WD2 — fresh iff re-globbing + re-stat-ing reproduces the recorded signature. Zero file-content
-        # bytes are read in the default mode. Any failure reads as stale (recompute), never a crash. A stored
-        # signature recorded under the opposite validation mode simply mismatches and recomputes.
+        # bytes are read in the default mode, and no stat at all in `:names`. Any failure reads as stale
+        # (recompute), never a crash. A stored signature recorded under the opposite validation mode simply
+        # mismatches and recomputes.
         def self.fresh?(entry)
-          signature_for(root: entry.root, pattern: entry.pattern) == entry.value
+          signature_for(root: entry.root, pattern: entry.pattern, mode: entry.mode) == entry.value
         rescue StandardError
           false
         end
 
-        # Composition key — {.compose} unions per (root, pattern) slot; two contributions for the same slot
-        # must agree on the value or {Conflict} is raised. Within one run the same glob stat-reads identically,
-        # so contributions never conflict.
+        # Composition key — {.compose} unions per (root, pattern, mode) slot; two contributions for the same
+        # slot must agree on the value or {Conflict} is raised. Within one run the same glob stat-reads
+        # identically, so contributions never conflict. The mode is part of the key because the two signatures
+        # over one (root, pattern) are different questions, not rival answers to the same one.
         def slot_key
-          "#{root}\0#{pattern}"
+          "#{root}\0#{pattern}\0#{mode}"
         end
 
         def to_h
-          { "root" => root, "pattern" => pattern, "value" => value }
+          h = { "root" => root, "pattern" => pattern, "value" => value }
+          # Omitted in the default mode so a descriptor carrying only stat globs keeps its pre-#979 canonical
+          # bytes: this FIELD moves no producer's key. (Every key still moved once with SCHEMA_VERSION 9,
+          # which the storage layer mixes in; that is the #979 migration, not the mode.)
+          h["mode"] = mode.to_s unless mode == :stat
+          h
         end
       end
 
@@ -352,9 +396,8 @@ module Rigor
             dependencies: dependencies, globs: globs)
       end
 
-      # @param producer_id [String]
-      # @param params [Hash] inputs the producer was called with
-      # @return [String] hex SHA-256 cache key for the value
+      # @param params — inputs the producer was called with
+      # @return hex SHA-256 cache key for the value
       def cache_key_for(producer_id:, params: {})
         payload = {
           "schema_version" => SCHEMA_VERSION,
@@ -377,7 +420,7 @@ module Rigor
           "dependencies" => sort_entries(dependencies, "gem_name").map(&:to_h),
           "files" => sort_entries(files, "path").map(&:to_h),
           "gems" => sort_entries(gems, "name").map(&:to_h),
-          "globs" => globs.sort_by { |e| [e.root, e.pattern] }.map(&:to_h),
+          "globs" => globs.sort_by { |e| [e.root, e.pattern, e.mode.to_s] }.map(&:to_h),
           "plugins" => sort_entries(plugins, "id").map(&:to_h)
         }
       end

data/lib/rigor/cache/engine_source.rb

@@ -3,6 +3,7 @@
 require "digest"
 
 require_relative "../version"
+require_relative "descriptor"
 
 module Rigor
   module Cache
@@ -63,17 +64,20 @@ module Rigor
       # to whatever else happened to be there, which is exactly the weakening this module forbids.
       REQUIRED_DIRECTORY = "lib"
 
+      # The config-row key every computed-value slot carries the identity under.
+      CONFIG_KEY = "engine-source"
+
       module_function
 
-      # @return [String] the gem root — the directory holding `lib/`, three levels above this file.
+      # @return the gem root — the directory holding `lib/`, three levels above this file.
       def root
         @root ||= File.expand_path("../../..", __dir__)
       end
 
-      # @param root [String] the gem root, defaulted through {.root} so a spec can relocate the tree.
-      # @return [String, nil] a digest identifying the engine's current source, or nil when the tree is
+      # @param root — the gem root, defaulted through {.root} so a spec can relocate the tree.
+      # @return a digest identifying the engine's current source, or nil when the tree is
       #   version-pinned and the caller should add no slot at all.
-      # @raise [Unavailable] when a mutable tree's source cannot be read.
+      # @raise Unavailable — when a mutable tree's source cannot be read.
       def identity(root = self.root)
         return nil if version_pinned?(root)
 
@@ -100,10 +104,34 @@ module Rigor
       # exists at all. The same reading covers the long-running `rigor lsp` process.
       #
       # {Unavailable} propagates and is deliberately NOT memoised: the ivar is only assigned on success.
+      #
+      # The memo is FROZEN because a Ractor-pool worker reads it (#1055): the auto-wired ADR-93
+      # `rigor-rbs-inline` synthesizer reaches `.key_config_entries` from inside
+      # `Environment.for_project`, which is inside `WorkerSession#initialize`, which is inside the worker's
+      # own Ractor — and a non-main Ractor may read a class/module ivar only when its value is shareable.
+      # An unfrozen digest String therefore killed every worker in its constructor on any run with the
+      # synthesizer on, which is every real CLI run (the spec suite pins it off). The worker never WRITES
+      # it: `PoolCoordinator#analyze_files_in_pool` pre-warms this on the main Ractor first, which is where
+      # the argument above already says the value belongs.
       def process_identity
         return @process_identity if defined?(@process_identity)
 
-        @process_identity = identity
+        @process_identity = identity.freeze
+      end
+
+      # The `engine-source` key row for a cache whose value this engine computed, built from
+      # {.process_identity}: empty for a version-pinned tree, so a released gem's keys stay byte-identical.
+      #
+      # Issue #1009 — a slot keyed only on its inputs and a plugin's manifest version outlives the engine
+      # that filled it. The per-file synthesizer slot and every plugin producer were keyed that way, so after
+      # an engine or bundled-plugin edit the run-result key moved and the run re-analysed, but through the
+      # previous build's synthesized RBS and producer values. {Unavailable} propagates, so a caller that
+      # cannot identify the engine bypasses its cache instead of falling back to the weaker key.
+      def key_config_entries
+        identity = process_identity
+        return [] if identity.nil?
+
+        [Descriptor::ConfigEntry.new(key: CONFIG_KEY, value_hash: Digest::SHA256.hexdigest(identity))]
       end
 
       # Discards the {.process_identity} memo; production code MUST NOT call this — a run that recomputed

data/lib/rigor/cache/file_digest.rb

@@ -74,7 +74,7 @@ module Rigor
         memo[path] ||= Digest::SHA256.file(path).hexdigest
       end
 
-      # @return [Boolean] whether digest-always validation is forced for this run. The env var wins over the
+      # @return whether digest-always validation is forced for this run. The env var wins over the
       #   run-scoped config flag so an operator can bypass the stat tier without editing `.rigor.yml`.
       def self.strict_validation?
         return true if ENV[STRICT_ENV] == "1"
@@ -112,6 +112,14 @@ module Rigor
         hexdigest(path) == digest
       end
 
+      # The content-digest field of a packed `:stat` entry ({.pack_stat}); nil when the entry is absent or not
+      # well-formed. Exposed for the caller that must compare the recorded digest against bytes it hashes
+      # itself rather than against the file on disk — the incremental session's editor-mode freshness check,
+      # whose authority is the editor's buffer.
+      def self.content_digest(packed)
+        parse_stat(packed)&.first
+      end
+
       # The VALIDATION-side stat, served from the per-run table when one is installed — a collecting run
       # validates the effects entry and the diagnostics entry against the same ~thousands-of-files
       # dependency descriptor, and the second pass is pure repetition under the run's own stable-filesystem

data/lib/rigor/cache/incremental_snapshot.rb

@@ -84,7 +84,61 @@ 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.
+      # 23: issue #992 gives each seed bundle a `parameter_envelopes` table — the joined positional envelope
+      # of every method a file records, plus its module / dynamic-surface marks — which `call.wrong-arity`
+      # reads for a method no signature declares. A pre-23 bundle folds as "no envelopes", which only ever
+      # withholds a check, but a warm run that withholds where a cold run fires is still the
+      # `--verify-incremental` divergence 14 was bumped for.
+      # 24: issue #1097 gives each seed bundle a `deferred_ranges` table — the per-file def / block /
+      # lambda body ranges `Scope#*_def_shadows_call?` orders a project-defined `sig` override
+      # against. A pre-24 bundle would fold as "no ranges", which the predicate reads as "cannot
+      # order → shadow" — a warm run declining the binding where a cold run binds.
+      # 25: issue #1097 extends each `deferred_ranges` row to `[start, end, name, kind, owner]` —
+      # owner-scoped ordering. A 24 bundle folds as "owner = nil", which the predicate reads as
+      # "cannot order", under-shadowing `module_function` defs whose only table evidence is the row
+      # itself.
+      # 26: issue #1123 gives each seed bundle a `prepends` table — the instance-ancestor ORDER of a
+      # class's `prepend`ed modules, which `Scope#user_def_through_ancestors` searches ahead of the
+      # class's own `def`s. A pre-26 bundle would fold as "prepends nothing": the warm run would answer
+      # the pre-fix MRO where a cold run answers the prepended module, exactly the `--verify-incremental`
+      # divergence 14 was bumped for (and a silently WRONG dispatch answer, not a withheld check).
+      # 27: issue #1173 re-MEANs each seed bundle's `includes` VALUES without changing their shape: the
+      # lists now store instance-ancestor SEARCH order (nearest first, prepends ahead of includes)
+      # instead of call order — the same flip 17 made for def-row `nesting`. A pre-27 blob deserialises
+      # cleanly and would serve the old call order on a warm run while a cold run searches nearer-first:
+      # `include A; include B` would resolve A's methods where a cold run resolves B's — the
+      # `--verify-incremental` divergence 14 was bumped for.
+      # 28: issue #1120 gives each seed bundle a `refinements` table — the `def`s of every `refine X do … end`
+      # body, which `call.undefined-method` reads where a `using` of the refining module is in effect. A
+      # pre-28 bundle would fold as "refines nothing", and a warm run would report a refined call a cold run
+      # declines.
+      # 29: issue #1367 gives each seed bundle a `global_write_census` — the globals its `alias` statements name and
+      # the `write` / `to_str` / `to_int` / hatch definitions and top-level mixins it holds, which the `global.*`
+      # write rules decline on project-wide. A pre-29 bundle would fold as "none of those", and a warm run would
+      # report a write a cold run exempts.
+      SCHEMA = 29
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -136,11 +190,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 +286,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 +323,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 +348,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_cache_producer.rb

@@ -29,6 +29,10 @@ module Rigor
         # 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
+        # Issue #1014 — nil is an engine the descriptor could not identify ({EngineSource::Unavailable}).
+        # Compute uncached rather than keying the value without the engine that produced it.
+        return compute(loader) if descriptor.nil?
+
         store.fetch_or_compute(producer_id: self::PRODUCER_ID, params: {}, descriptor: descriptor,
                                generation_cap: generation_cap) do
           compute(loader)

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

@@ -3,22 +3,47 @@
 require "digest"
 
 require_relative "descriptor"
+require_relative "engine_source"
 require_relative "file_digest"
 
 module Rigor
   module Cache
     # Shared descriptor builder for cache producers that depend on the RBS environment (constant table,
-    # known-class set, future Marshal-clean reflection artefacts). Every consumer attaches the same three
-    # slots, so factoring the construction here keeps the producers small and ensures invalidation behaves
-    # identically across them.
+    # known-class set, future Marshal-clean reflection artefacts). Every consumer attaches the same slots —
+    # the `rbs` gem row, a digest row per signature file, and the `rbs.libraries` / `rbs.virtual_rbs` /
+    # `rbs.deferred_signature_paths` / `engine-source` config rows — 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]
+      # The key every `rbs.*` producer shares ({RbsCacheProducer#fetch}): `rbs.environment`,
+      # `rbs.constant_type_table`, `rbs.class_ancestor_table`, `rbs.known_class_names`,
+      # `rbs.class_type_param_names`.
+      #
+      # Issue #1014 — the engine-source row is here, not in {.config_entries}, because these are
+      # computed-value slots: what they hold is not the RBS the descriptor digests but what Rigor's own code
+      # made of it. `rbs.constant_type_table` stores `Inference::RbsTypeTranslator.translate` output and
+      # `rbs.class_ancestor_table` the chains `RbsClassAncestorTable.compute` walks out of
+      # `instance_definition`, so an engine edit to either moved the value while the key stood still: the
+      # run-result key moved (#285) and the run re-analysed, then read the previous build's table. Both were
+      # reproduced cross-build on a fixture — a true positive dropped, and a `flow.unreachable-clause` false
+      # positive served — before this row was added.
+      #
+      # {.config_entries} deliberately does NOT get it: that half is what the ADR-45 run cache key reads
+      # ({.build_run}), and `RunCacheKey` already contributes the identical row from
+      # `EngineSource.key_config_entries` itself. Adding it there would duplicate the row in the run key and
+      # would have to be reconstructible by the boot-slimming probe, which builds `config_entries` without a
+      # loader.
+      #
+      # @raise EngineSource::Unavailable — an engine that cannot be identified must not be keyed by its
+      #   inputs alone; {RbsCacheProducer.fetch} turns this into an uncached compute.
       def self.build(loader)
+        # FIRST, before {.file_entries} digests the whole signature tree: the {EngineSource::Unavailable}
+        # path discards this descriptor entirely, and a SHA-256 of every `.rbs` under every signature root is
+        # the expensive way to reach that conclusion.
+        engine = EngineSource.key_config_entries
         Descriptor.new(
           gems: [rbs_gem_entry],
           files: file_entries(loader),
-          configs: config_entries(loader)
+          configs: config_entries(loader) + env_only_config_entries(loader) + engine
         )
       end
 
@@ -26,8 +51,11 @@ 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 slots the env key adds on top,
+      # {.env_only_config_entries} and the #1014 `engine-source` row, are never read here — `RunCacheKey`
+      # contributes the identical engine-source row itself, from the same
+      # `EngineSource.key_config_entries`).
       def self.build_run(loader)
         RunDescriptor.new(loader: loader, gems: [rbs_gem_entry], configs: config_entries(loader))
       end
@@ -38,19 +66,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 +121,41 @@ 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} — including, since #1014, this descriptor itself, which
+      # until then carried no such row. 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 +183,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 +197,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 }