rigortype 0.3.7 → 0.3.9

data/lib/rigor/cache/annotation_location.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+module Rigor
+  module Cache
+    # The `RBS::AST::Annotation` location carry (issue #799): the two halves of the `marshal_dump` /
+    # `marshal_load` pair {file:lib/rigor/cache/rbs_environment_marshal_patch.rb the env-cache Marshal patch}
+    # installs on `RBS::AST::Annotation`, plus the buffer a reconstructed location points at. That file's
+    # header carries the why; this one is the how.
+    #
+    # Nothing here reconstructs the annotation's SOURCE — the cached env has no file contents, and a
+    # consumer that wants the text already has `Annotation#string`. What it reconstructs is the pair of
+    # `(line, column)` answers `RBS::Location` gives, so a diagnostic positioned on the directive reads the
+    # same line warm as it does cold.
+    module AnnotationLocation
+      # The two positions {Buffer} distinguishes. `RBS::Location` addresses its buffer by character
+      # offset, and the reconstruction has no content to offset into, so the offsets are used as tags:
+      # 0 is "the start pair", 1 is "the end pair".
+      START_POS = 0
+      END_POS = 1
+
+      # A content-less `RBS::Buffer` that answers `pos_to_loc` from the pairs the cold parse had.
+      #
+      # Answering there is all it takes: `RBS::Location#start_line` and its three siblings are C methods
+      # that resolve the offset through `buffer.pos_to_loc`, so the reconstructed Location reports the real
+      # position without the buffer having to hold (or synthesize) the file it came from. The alternative —
+      # a synthetic content string of `line - 1` newlines — is exact only while an annotation stays on one
+      # line, and `%a{...}` may span two.
+      class Buffer < ::RBS::Buffer
+        def initialize(name:, start_loc:, end_loc:)
+          super(name: name, content: "")
+          @start_loc = start_loc
+          @end_loc = end_loc
+        end
+
+        def pos_to_loc(pos)
+          pos == START_POS ? @start_loc : @end_loc
+        end
+      end
+
+      module_function
+
+      # @return `[name, start_line, start_column, end_line, end_column]`, or nil when there is
+      #   no location to carry. Fail-soft: a location whose buffer cannot answer is dumped as nil rather
+      #   than failing the whole environment's dump.
+      def dump(location)
+        return nil if location.nil?
+
+        buffer = location.buffer
+        name = buffer.respond_to?(:name) ? buffer.name.to_s : nil
+        [name, location.start_line, location.start_column, location.end_line, location.end_column]
+      rescue StandardError
+        nil
+      end
+
+      # @param payload — what {dump} produced.
+      def load(payload)
+        return nil if payload.nil?
+
+        name, start_line, start_column, end_line, end_column = payload
+        name = ::RBS::Location::CACHED_BUFFER_NAME if name.nil? || name.empty?
+        buffer = Buffer.new(name: name, start_loc: [start_line, start_column], end_loc: [end_line, end_column])
+        ::RBS::Location.new(buffer: buffer, start_pos: START_POS, end_pos: END_POS)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rigor/cache/descriptor.rb

@@ -48,7 +48,12 @@ 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.
+      SCHEMA_VERSION = 9
 
       # 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 +119,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 +240,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 +308,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 +391,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 +415,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

@@ -65,15 +65,15 @@ module Rigor
 
       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)
 

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,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_environment_marshal_patch.rb

@@ -2,6 +2,8 @@
 
 require "rbs"
 
+require_relative "annotation_location"
+
 # Adds `_dump` / `_load` to {RBS::Location} so an `RBS::Environment` (and its transitive AST nodes, all of
 # which carry Locations) round-trips through `Marshal`. The rbs gem's C-extension `RBS::Location` ships
 # without the Marshal hooks; until rbs grows them upstream this patch is the minimal monkey-patch the v0.0.9
@@ -31,6 +33,25 @@ require "rbs"
 #   than a cold run does. ADR-6's store never evicts, so that would persist. `Cache::Store::FORMAT_VERSION`
 #   is therefore bumped to 3: `PAYLOAD_ABI_VERSION` already rebuilds across a release, and the bump closes
 #   the same-version window too.
+# - `RBS::AST::Annotation` carries its own `marshal_dump` / `marshal_load`, which keep the annotation's
+#   POSITION as well as its file (issue #799). "Nothing reads positions" was never quite true: the two
+#   `conforms-to` rows — `rbs_extended.unsatisfied-conformance` and `dynamic.rbs-extended.unresolved` —
+#   are reported AT the directive, because there is no Ruby `def` a missing interface method could be
+#   reported at, so both read `start_line` / `start_column` off an annotation's location. (They are the
+#   only readers: {Rigor::RbsExtended::EnvelopeScanner} positions `effect.unknown-label` at an annotation
+#   too, but reaches it by parsing the project's own `.rbs` rather than the built env — refusing this very
+#   loss is one of the two reasons it does.) Cold the row is `sig/buffer.rbs:6:1`; through a `_dump`ed
+#   location it collapsed to `1:1`, which made `--verify-incremental` fail outright on any project carrying
+#   an unsatisfied directive (the replica normalises rows by position, and only one side of the comparison
+#   runs against the cached env) and made a warm `--incremental` run move a row on a tree that had not
+#   changed. The carry is scoped to annotations rather than done in `_dump` for the reason the paragraph
+#   above gives: a Location hangs off every AST node, and carrying its position measured +2.9% on Rigor's
+#   own env (9,941K to 10,229K) on top of the names. An annotation is rare by comparison — 18 of them in
+#   that same env — so the same carry costs +1.4K there, which is the whole argument for scoping it here
+#   rather than widening `_dump`. `Cache::Store::FORMAT_VERSION` is bumped to 4 for the same reason it was
+#   bumped to 3: a pre-change blob still loads (Marshal encodes an ivar dump and a `marshal_dump` payload
+#   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.
@@ -67,6 +88,24 @@ module RBS
     end
   end
 
+  module AST
+    class Annotation
+      # Carries the annotation's POSITION across the cache, not just its file. See the header's fourth
+      # bullet for why this one AST node opts out of the position-dropping `RBS::Location#_dump` above.
+      unless method_defined?(:marshal_dump)
+        def marshal_dump
+          [string, Rigor::Cache::AnnotationLocation.dump(location)]
+        end
+
+        def marshal_load(payload)
+          dumped_string, dumped_location = payload
+          @string = dumped_string
+          @location = Rigor::Cache::AnnotationLocation.load(dumped_location)
+        end
+      end
+    end
+  end
+
   class Namespace
     unless method_defined?(:_dump)
       def _dump(_)

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 }