rigortype 0.3.5 → 0.3.7

data/lib/rigor/builtins/hkt_builtins.rb

@@ -52,6 +52,15 @@ module Rigor
         Rigor::Inference::HktBodyParser.parse(CSV_PARSED_BODY, params: [:K])
       end
 
+      # `csv::row[K]` — `Array[K | nil]` (CSV.parse_line's shape:
+      # an Array of optionally-nil cell values for a single row).
+      CSV_ROW_BODY = "Array[K | nil]"
+      private_constant :CSV_ROW_BODY
+
+      def csv_row_body_tree
+        Rigor::Inference::HktBodyParser.parse(CSV_ROW_BODY, params: [:K])
+      end
+
       def json_value_registration
         Rigor::Inference::HktRegistry::Registration.new(
           uri: :"json::value",
@@ -90,6 +99,25 @@ module Rigor
         )
       end
 
+      def csv_row_registration
+        Rigor::Inference::HktRegistry::Registration.new(
+          uri: :"csv::row",
+          arity: 1,
+          variance: [:out],
+          bound: Rigor::Type::Combinator.untyped
+        )
+      end
+
+      def csv_row_definition
+        Rigor::Inference::HktRegistry.definition_with_body_tree(
+          uri: :"csv::row",
+          params: [:K],
+          body_tree: csv_row_body_tree,
+          source_path: __FILE__,
+          source_line: __LINE__ - 5
+        )
+      end
+
       # @return [Rigor::Inference::HktRegistry] frozen registry
       #   pre-seeded with all bundled HKT registrations +
       #   bodies. Allocated fresh each call rather than
@@ -104,8 +132,8 @@ module Rigor
       #   once ADR-15 phase 4b.x covers the dependency graph.
       def registry
         Rigor::Inference::HktRegistry.new(
-          registrations: [json_value_registration, csv_parsed_registration],
-          definitions: [json_value_definition, csv_parsed_definition]
+          registrations: [json_value_registration, csv_parsed_registration, csv_row_registration],
+          definitions: [json_value_definition, csv_parsed_definition, csv_row_definition]
         )
       end
 
@@ -160,6 +188,14 @@ module Rigor
       }.freeze
       private_constant :CSV_PARSED_SPEC
 
+      CSV_ROW_SPEC = {
+        uri: :"csv::row",
+        args: ["String"],
+        discriminator: nil,
+        post_reduce: nil
+      }.freeze
+      private_constant :CSV_ROW_SPEC
+
       METHOD_RETURN_OVERRIDES = {
         # JSON — stdlib's `json` library. Upstream rbs declares
         # `(string, ?options) -> untyped`; the HKT-builtin tier
@@ -190,17 +226,20 @@ module Rigor
         ["YAML",  :safe_load_file, :singleton] => YAML_SAFE_VALUE_SPEC,
         ["Psych", :safe_load,      :singleton] => YAML_SAFE_VALUE_SPEC,
         ["Psych", :safe_load_file, :singleton] => YAML_SAFE_VALUE_SPEC,
-        # CSV.parse / CSV.read — no-headers shape only.
+        # CSV.parse / CSV.read / CSV.readlines / CSV.parse_line — no-headers shape only.
         # Upstream rbs declares broader return shapes but
         # the common case is `Array[Array[String?]]` which
-        # the `csv::parsed[String]` URI matches. The
+        # the `csv::parsed[String]` URI matches, or
+        # `Array[String?]` which `csv::row[String]` matches. The
         # `headers: true` shape (`CSV::Table` of `CSV::Row`)
         # is NOT covered — calls passing the option fall
         # through to the upstream RBS type. CSV.foreach also
         # falls through (it yields rows rather than
         # returning a typed structure).
-        ["CSV", :parse, :singleton] => CSV_PARSED_SPEC,
-        ["CSV", :read,  :singleton] => CSV_PARSED_SPEC
+        ["CSV", :parse,      :singleton] => CSV_PARSED_SPEC,
+        ["CSV", :read,       :singleton] => CSV_PARSED_SPEC,
+        ["CSV", :readlines,  :singleton] => CSV_PARSED_SPEC,
+        ["CSV", :parse_line, :singleton] => CSV_ROW_SPEC
       }.freeze
 
       # @return [Rigor::Type, nil] the reduced HKT type for

data/lib/rigor/builtins/predefined_constant_refinements.rb

@@ -7,7 +7,9 @@ module Rigor
     # Refined types for predefined Ruby / stdlib constants whose upstream RBS signatures are
     # broader than the constants' documented runtime invariants.
     #
-    # Resolution is two-tiered:
+    # Resolution is two-tiered, and **both tiers are closed tables authored in this file**. A name
+    # taken from the analysed program is never resolved against the analyzer's own object space —
+    # see *Why the table is closed* below.
     #
     # **Tier 1 — exact-value whitelist** (`FOLDED_CONSTANTS`):
     # Constants whose value is bit-for-bit identical across every Ruby version and platform
@@ -23,24 +25,44 @@ module Rigor
     # and as plain `Integer`s they fall through Tier 2 to the RBS type harmlessly.
     # `Complex::I` is deferred (no complex-fold consumer).
     #
-    # **Tier 2 — runtime String inspection**:
-    # For any other constant, the module resolves it via `const_get` against the analyzer's
-    # own Ruby runtime.  Core / stdlib constants (e.g. `RUBY_VERSION`, `RUBY_PLATFORM`) are
-    # always loaded into the analyzer process; project-defined constants are not (they live
-    # only in ASTs), so their `const_get` raises `NameError` and the lookup falls through to
-    # the RBS type tier.
+    # **Tier 2 — String refinements for a closed set of interpreter constants**
+    # (`RUNTIME_STRING_CONSTANTS`): each listed name is read ONCE, at load time, from the analyzer's
+    # own runtime and classified by the value found:
     #
-    # For a successfully resolved `String` value:
-    # - empty string  → no refinement (fall through to RBS `String`)
+    # - not a String, or an empty one  → no entry (the name falls through to the RBS type)
     # - a Ruby numeric literal  → `numeric-string`
     # - non-empty otherwise  → `non-empty-string`
     #
-    # **Exclusion set** (`RUNTIME_INSPECTION_EXCLUDED`):
-    # String constants that appear non-empty in the current runtime but are documented to be
-    # potentially empty in some build configuration or alternative implementation.  Exclusions
-    # are populated by scanning Ruby's C source (version.c, etc.) and RBS comments for any
-    # constant whose documentation says "may be empty" or "platform-specific default".  None
-    # are known today; the set exists as a safety net.
+    # Admission criterion for the list: the constant's value is fixed by the same interpreter choice
+    # that already fixes the core / stdlib RBS the engine reads, and it is non-empty in every build.
+    # A third-party gem's constant does NOT qualify — the analysed project resolves its own copy
+    # through its `Gemfile.lock`, which this layer cannot see. This is the criterion
+    # `Inference::VersionGuard::VERSION_CONSTANTS` already applies to the constants it folds guards on.
+    #
+    # **Why the table is closed** ([#680](https://github.com/rigortype/rigor/issues/680)):
+    # Tier 2 used to resolve ANY name reaching it — a name read out of the analysed source — with
+    # `const_get` against the analyzer's runtime, guarded by `const_defined?(part, false)`. That
+    # guard does not answer the question it was written for: `const_defined?` is true for a
+    # **registered but not yet triggered autoload**, so `const_get` fired the autoload and the target
+    # file was *executed* inside the analyzer. Analysing CRuby's own `lib/prism` reached
+    # `prism/translation/ruby_parser.rb`, which calls `exit` at the top level when `sexp_processor`
+    # is absent; `SystemExit` is not a `StandardError`, so neither the rescue in this file nor the
+    # runner's per-file rescue saw it and the run stopped with no diagnostics and no summary. The
+    # target of an autoload is arbitrary — it may exit, raise, print, mutate global state, or take
+    # unbounded time — and `rigor check` is routinely pointed at code the user did not write.
+    #
+    # Closing the table rather than only guarding the walk is what makes that structural: no name
+    # from the analysed program reaches `const_get` at all. A census of what the open walk actually
+    # bought says the precision cost is nil — over GitLab's `app` + `lib` (11,189 files, 184,965
+    # constant references) it answered for five names and ten references (`RUBY_VERSION`,
+    # `RUBY_PLATFORM`, `RUBY_DESCRIPTION`, `File::SEPARATOR`, `File::PATH_SEPARATOR`, every one of
+    # them listed below), against 17 references that would have autoloaded `ipaddr`; over Mastodon,
+    # three names and five references against 43 such. What it answered for *beyond* the list was
+    # always a constant that happened to live in **Rigor's own** bundle — `Rigor::VERSION` and
+    # `RBS::VERSION` while Rigor checks itself, rubygems and Bundler internals while it checks
+    # CRuby's `lib/` — and that is worse than no answer: identical source would type differently
+    # depending on how the analyzer was installed. Removing an ad hoc `Object.const_get` from an
+    # analysis path is the same move ADR-4 § 330 already made for predicate narrowing.
     #
     # This module is consulted by `Environment#constant_for_name` BEFORE the RBS
     # constant-type table (widest types) but AFTER in-source constant writes (the user's own
@@ -68,70 +90,97 @@ module Rigor
 
       # --- tier 2 -------------------------------------------------------
 
-      # String constants whose runtime value is non-empty in the current Ruby but that should
-      # NOT be narrowed because they are documented to be potentially empty in some build or
-      # implementation.
+      # The closed set of names tier 2 may read, by the admission criterion in the module note.
       #
-      # Methodology: grep Ruby's version.c and similar C sources, and the RBS comment corpus,
-      # for any constant annotated with "may be empty" or "platform-specific default".  Add
-      # the full qualified path (without leading "::") when a genuine risk is found.
-      RUNTIME_INSPECTION_EXCLUDED = Set[].freeze
-      private_constant :RUNTIME_INSPECTION_EXCLUDED
+      # The `RUBY_*` / `Ruby::*` pairs and `Encoding::UNICODE_VERSION` are defined by the interpreter
+      # itself; `File::SEPARATOR` / `Separator` / `PATH_SEPARATOR` / `ALT_SEPARATOR` by its `File`
+      # core class (`Separator` is the capital-S alias of `SEPARATOR`, declared in core RBS and just
+      # as spellable in project code; `ALT_SEPARATOR` is `nil` off Windows and simply gets no entry
+      # there); `Gem::VERSION` by rubygems, which is not the interpreter's to version but IS loaded
+      # in every process that can run `rigor` at all. A name that resolves to something other than a
+      # non-empty String on the running interpreter is skipped, so listing one costs nothing where it
+      # does not exist.
+      RUNTIME_STRING_CONSTANTS = %w[
+        RUBY_VERSION RUBY_RELEASE_DATE RUBY_PLATFORM RUBY_DESCRIPTION RUBY_COPYRIGHT
+        RUBY_ENGINE RUBY_ENGINE_VERSION RUBY_REVISION
+        Ruby::VERSION Ruby::RELEASE_DATE Ruby::PLATFORM Ruby::DESCRIPTION Ruby::COPYRIGHT
+        Ruby::ENGINE Ruby::ENGINE_VERSION Ruby::REVISION
+        File::SEPARATOR File::Separator File::PATH_SEPARATOR File::ALT_SEPARATOR
+        Encoding::UNICODE_VERSION
+        Gem::VERSION
+      ].freeze
+      private_constant :RUNTIME_STRING_CONSTANTS
 
       NON_EMPTY_STRING = Type::Combinator.non_empty_string.freeze
       NUMERIC_STRING   = Type::Combinator.numeric_string.freeze
       private_constant :NON_EMPTY_STRING, :NUMERIC_STRING
 
-      # --- public API ---------------------------------------------------
-
-      # @param name [String] unqualified constant name (e.g. `"Math::PI"`,
-      #   `"RUBY_VERSION"`, `"Ruby::ENGINE"`)
-      # @return [Rigor::Type, nil] refined type, or nil to fall through
-      def self.lookup(name)
-        FOLDED_CONSTANTS[name] || inspect_runtime_string(name)
-      end
-
       # --- private ------------------------------------------------------
 
-      # Resolves `name` via `const_get` in the analyzer's runtime and returns a refined
-      # String carrier, or nil.
-      def self.inspect_runtime_string(name)
-        return nil if RUNTIME_INSPECTION_EXCLUDED.include?(name)
+      # @param value [String] a non-empty string
+      # @return [Rigor::Type]
+      def self.classify_string(value)
+        if Type::Refined.ruby_numeric_literal?(value)
+          NUMERIC_STRING
+        else
+          NON_EMPTY_STRING
+        end
+      end
+      private_class_method :classify_string
 
+      # Reads `name` in the analyzer's runtime, returning its value when that is a non-empty String.
+      #
+      # Called ONLY with the names in {RUNTIME_STRING_CONSTANTS} — Rigor's own source — and only
+      # while this file is being loaded. It is never handed a name from the analysed program.
+      #
+      # @param name [String] a qualified constant path without a leading "::"
+      # @return [String, nil]
+      def self.runtime_string_value(name)
         mod = ::Object
         name.split("::").each do |part|
-          # Resolve only constants already present — never let analysing a reference drive
-          # the analyzer's own runtime to autoload or run a `const_missing` hook. A
-          # `Digest::UUID` reference in project code otherwise makes `const_get` trigger
-          # `Digest.const_missing` → `require "digest/uuid"`, and a missing optional library
-          # raises `LoadError` (a `ScriptError`, not the `NameError` the const_get walk
-          # expects), which would abort the whole run rather than fall through to the RBS
-          # tier. `const_defined?(part, false)` answers the same "is this resolvable here"
-          # question without the side effect — a project-defined constant (the common case)
-          # is simply absent and returns nil, no exception raised.
           return nil unless mod.is_a?(::Module) && mod.const_defined?(part, false)
+          # `const_defined?` is true for a REGISTERED-BUT-NOT-YET-TRIGGERED autoload, so on its own
+          # it does not mean "already in memory" and `const_get` would EXECUTE the target file. Only
+          # `Module#autoload?` separates the two: it returns the registered path while the autoload
+          # is pending and nil once it has run, so declining on it declines exactly the dangerous
+          # case and still resolves a constant genuinely loaded ([#680]).
+          return nil if mod.autoload?(part)
 
           mod = mod.const_get(part, false)
         end
 
-        return nil unless mod.is_a?(::String) && !mod.empty?
-
-        classify_string(mod)
-      rescue ::NameError, ::TypeError, ::LoadError
+        mod.is_a?(::String) && !mod.empty? ? mod : nil
+      rescue ::StandardError, ::ScriptError, ::SystemExit
+        # Deliberately wider than the `NameError` / `TypeError` / `LoadError` this used to name.
+        # Refining a constant is an optimisation and nothing it can hit justifies stopping the
+        # process; `SystemExit` is the one that actually did ([#680]) and is not a `StandardError`,
+        # and `ScriptError` covers the `LoadError` family for the same reason. `Interrupt`,
+        # `SignalException` and `NoMemoryError` are deliberately NOT caught — a Ctrl-C must keep
+        # reaching the user, and an out-of-memory process is not one to keep analysing in.
         nil
       end
-      private_class_method :inspect_runtime_string
+      private_class_method :runtime_string_value
+
+      # @return [Hash{String => Rigor::Type}] frozen, built once at load time.
+      def self.build_runtime_string_refinements
+        RUNTIME_STRING_CONSTANTS.each_with_object({}) do |name, table|
+          value = runtime_string_value(name)
+          table[name] = classify_string(value) if value
+        end.freeze
+      end
+      private_class_method :build_runtime_string_refinements
 
-      # @param value [String] a non-empty string
-      # @return [Rigor::Type]
-      def self.classify_string(value)
-        if Type::Refined.ruby_numeric_literal?(value)
-          NUMERIC_STRING
-        else
-          NON_EMPTY_STRING
-        end
+      RUNTIME_STRING_REFINEMENTS = build_runtime_string_refinements
+      private_constant :RUNTIME_STRING_REFINEMENTS
+
+      # --- public API ---------------------------------------------------
+
+      # @param name [String] unqualified constant name (e.g. `"Math::PI"`,
+      #   `"RUBY_VERSION"`, `"Ruby::ENGINE"`)
+      # @return [Rigor::Type, nil] refined type, or nil to fall through
+      def self.lookup(name)
+        FOLDED_CONSTANTS[name] || RUNTIME_STRING_REFINEMENTS[name]
       end
-      private_class_method :classify_string
     end
   end
 end

data/lib/rigor/builtins/static_return_refinements.rb

@@ -66,13 +66,32 @@ module Rigor
       FILE_NON_EMPTY = ->(_arg_types) { NON_EMPTY_STRING }
       private_constant :FILE_NON_EMPTY
 
+      STRING_NOMINAL = Type::Combinator.nominal_of("String").freeze
+      private_constant :STRING_NOMINAL
+
+      # `IO.read(name)` / `File.read(name)` return nil ONLY when a `length` argument is given
+      # and the stream is at EOF; the no-length form always returns a String (it raises on
+      # error). Upstream RBS declares one row with an optional length — `-> String?` for every
+      # call shape — so the whole-file idiom `File.read(path, mode: 'rb')` read as nilable and
+      # fired `possible-nil-receiver` on working code (redmine's Import#read_file_head, three
+      # sites). The refinement drops the nil exactly when no positional length is present; a
+      # keyword-only trailing hash (`mode:`, `encoding:`) is not a length. Same family as the
+      # staged upstream signature fixes (#159).
+      IO_READ_NO_LENGTH = lambda do |arg_types|
+        positional = arg_types.grep_v(Type::HashShape)
+        positional.size <= 1 ? STRING_NOMINAL : nil
+      end
+      private_constant :IO_READ_NO_LENGTH
+
       # Frozen ((owner_class_name, method_name, kind) => handler) table. The kind tag is
       # `:both`, `:singleton`, or `:instance`. New entries SHOULD prefer `:both` unless the
       # singleton- and instance-side shapes genuinely differ.
       OVERRIDES = {
         ["Kernel", :__dir__, :both] => KERNEL_DIR,
         ["File", :expand_path, :singleton] => FILE_NON_EMPTY,
-        ["File", :dirname, :singleton] => FILE_NON_EMPTY
+        ["File", :dirname, :singleton] => FILE_NON_EMPTY,
+        ["IO", :read, :singleton] => IO_READ_NO_LENGTH,
+        ["File", :read, :singleton] => IO_READ_NO_LENGTH
       }.freeze
       private_constant :OVERRIDES
 

data/lib/rigor/cache/descriptor.rb

@@ -38,7 +38,17 @@ module Rigor
       # whose RBS dangles an interface or type-alias reference gets stubs where an older Rigor discarded the
       # whole batch and cached an env in which those signatures are inert. Same reasoning as v3: the
       # marshalled env is the cached value, so it MUST be rebuilt for the fix to take effect.
-      SCHEMA_VERSION = 6
+      # v7: #526 — the def-index seed bundles gain the `:extends` table (`extend M` / `extend self` /
+      # bare `module_function`), which `finalize_def_index` folds into the singleton-side method tables. A
+      # pre-7 bundle would silently contribute no extends for an unchanged file, so cached bundles must
+      # read as misses once and rebuild carrying the slot.
+      # v8: #577 / ADR-45 WD1 — a plugin {Plugin::IoBoundary} read that finds its path MISSING now records
+      # an absence row ({FileEntry.absent}: `:exists` / `"false"`) into the run-result and plugin-producer
+      # dependency descriptors, so a file that appears after a run which probed for it (a `db/schema.rb`
+      # 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
 
       # 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.
@@ -54,6 +64,11 @@ module Rigor
         # `:digest`, while the {Runner} run-dependency descriptor and plugin {IoBoundary} reads use `:stat`.
         VALID_COMPARATORS = %i[digest stat mtime exists].freeze
 
+        # The two `:exists` values — `File.exist?`'s answer rendered with `to_s`, which is what
+        # {Descriptor#file_entry_fresh?} compares the live answer against.
+        PRESENT = "true"
+        ABSENT = "false"
+
         attr_reader :path, :comparator, :value
 
         value_fields :path, :comparator, :value
@@ -80,6 +95,30 @@ module Rigor
           new(path: path, comparator: :stat, value: packed)
         end
 
+        # ADR-45 WD1 (#577) — the absence row: fresh while `path` does not exist, stale the moment anything
+        # (a file, a directory, a symlink) comes into existence there. {Plugin::IoBoundary#read_file}
+        # records one when a read fails because the path is missing, so a value computed on "X is absent"
+        # invalidates when X appears. Validation is a single `File.exist?` — no stat tuple, no digest,
+        # nothing that can move on an unchanged tree — so an absence row never costs a warm run its hit.
+        def self.absent(path:)
+          new(path: path, comparator: :exists, value: ABSENT)
+        end
+
+        # ADR-45 WD1b (#613) — {.absent}'s positive twin: fresh while `path` exists, stale once it is gone.
+        # {Plugin::IoBoundary#file?} / `#directory?` record one when an existence probe found what it asked
+        # for and the plugin never read the bytes (a discovery root it globbed, a config file whose mere
+        # presence switched a mode). It is the weakest file row — a rewrite in place leaves it fresh — so it
+        # is only ever the row for a dependency that really is on existence alone; a read records the `:stat`
+        # row over it.
+        def self.present(path:)
+          new(path: path, comparator: :exists, value: PRESENT)
+        end
+
+        # @return [Boolean] whether this row records the path as absent (see {.absent}).
+        def absent?
+          comparator == :exists && value == ABSENT
+        end
+
         def to_h
           { "path" => path, "comparator" => comparator.to_s, "value" => value }
         end
@@ -280,7 +319,8 @@ module Rigor
       # version) belong in the cache *key*, not the validated dependency set — so a descriptor carrying any
       # non-file slot is never considered fresh (it was built wrong for this use). ADR-60 WD3 adds `globs`
       # alongside `files` as a re-validatable slot: a {GlobEntry} is fresh when re-globbing + re-digesting
-      # reproduces its recorded value.
+      # reproduces its recorded value. ADR-45 WD1 (#577): an absence row ({FileEntry.absent}) is fresh
+      # while its path is still missing — the negative half of the dependency set.
       def fresh?
         return false unless gems.empty? && plugins.empty? && configs.empty? && dependencies.empty?
 

data/lib/rigor/cache/file_digest.rb

@@ -30,9 +30,10 @@ module Rigor
     # 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, :INSTANT_KEY, :STRICT_KEY
+      private_constant :MEMO_KEY, :STAT_KEY, :INSTANT_KEY, :STRICT_KEY
 
       # 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
@@ -47,14 +48,17 @@ module Rigor
       # 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
       end
@@ -102,12 +106,26 @@ module Rigor
         digest = parsed[0]
         return hexdigest(path) == digest if strict_validation?
 
-        st = File.stat(path)
+        st = validation_stat(path)
         return true if !racy?(parsed) && tuple_matches?(st, parsed)
 
         hexdigest(path) == digest
       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
+      # premise (see the module doc). The RECORDING side ({.pack_stat}) deliberately keeps its direct
+      # `File.stat`: it packs the tuple a *future* run validates, after the content was read, and must
+      # 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?
+
+        memo[path] ||= File.stat(path)
+      end
+
       def self.recording_instant_ns
         Thread.current[INSTANT_KEY] || now_ns
       end

data/lib/rigor/cache/incremental_snapshot.rb

@@ -54,8 +54,37 @@ module Rigor
       # loads as nil (a clean cold rebuild — no migration). 12: ADR-103 WD13 / issue #382 adds the effects
       # sidecar — `effect_collections` (the per-file {Rigor::Effects::FileCollection}s a collecting run
       # produced) and the `effects_identity` they were produced under; a pre-12 blob mismatches the SCHEMA
-      # gate and loads as nil (a clean cold rebuild — no migration).
-      SCHEMA = 12
+      # gate and loads as nil (a clean cold rebuild — no migration). 13: issue #644 adds `constant_decls`
+      # (the per-file constant PUBLICATION CENSUS — `{qualified name => [literal] | :unpublishable}` — whose
+      # diff drives the new `constant:` edge's producer) and grows each seed bundle's row grammar by its own
+      # `constant_writes` census; a pre-13 blob mismatches the SCHEMA gate and loads as nil (a clean cold
+      # rebuild — no migration). 14: issue #707 widens each seed-bundle def row from `[node_id, name,
+      # fingerprint]` to `[node_id, name, fingerprint, nesting]`, carrying issue #681's recorded
+      # `Module.nesting` so a bundle-served callee resolves its constants under the declaration that owns it
+      # instead of a peel of the receiver's name; a pre-14 blob mismatches the SCHEMA gate and loads as nil (a
+      # clean cold rebuild — no migration). The bump is what keeps a pre-14 blob REJECTED rather than MISREAD:
+      # a three-element row destructures with `nesting` nil, which is indistinguishable from a top-level def,
+      # so every unchanged file would silently keep the pre-fix peel. 15: issue #682 gives each seed bundle a
+      # `header_nestings` table — the `Module.nesting` each class / module DECLARATION HEADER is written in —
+      # so a bundle-served class resolves its superclass and include names in the cref Ruby resolves them in
+      # rather than by peeling its own qualified name; a pre-15 blob mismatches the SCHEMA gate and loads as
+      # nil (a clean cold rebuild — no migration). Absence here is gradual rather than misread (the resolver
+      # falls back to the peel), but a warm run that peels where a cold run does not is exactly the
+      # `--verify-incremental` divergence 14 was bumped for.
+      # 16: issue #722 residue 1 gives each seed bundle's `superclasses` values a ROOTED MARKER — a leading
+      # `::` on an ancestor name the site wrote rooted (`class X < ::Base`, `Class.new(::Parent)`) — so the
+      # resolvers anchor it at the top level instead of walking the enclosing nesting. The value stays a
+      # String, so a pre-16 blob deserialises cleanly and is exactly why the gate has to reject it: an
+      # un-rooted value is indistinguishable from "not rooted", and every unchanged file would keep the
+      # pre-fix answer on a warm run while a cold run gave the right one.
+      # 17: issue #716 changes what a seed-bundle def row's `nesting` MEANS without changing its shape. A
+      # top-level def now records the EMPTY chain (Ruby's `Module.nesting` there is `[]`), so the resolver
+      # anchors its constants at the top level instead of peeling the caller's namespace; `nil` narrows to
+      # "no chain recorded at all". A pre-17 blob stored `nil` for exactly the top-level defs that now store
+      # `[]`, 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
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -69,6 +98,12 @@ module Rigor
       # ADR-46 slice 3:
       # `missing` maps a consumer to Set<"kind:name"> it looked up and missed.
       # `class_decls` maps a path to Set<qualified class name> it declares.
+      # 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
+      # published answer is a function of the whole project's write set for it, so a value edit, a write
+      # becoming unpublishable, or a second declarer appearing / going away all move the answer without
+      # moving the name set.
       # ADR-85 WD2:
       # `seed_bundles` maps an analyzed path to its per-file discovery contribution (plain-data tables +
       # `(node_id, name, fingerprint)` def-node handles + content digest), so a warm recheck rebuilds the
@@ -103,7 +138,7 @@ module Rigor
       # and a vocabulary / catalogue / `effects:` change must invalidate the summaries alone.
       Payload = Data.define(:cache, :sources, :digests, :analyzed,
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
-                            :missing, :class_decls, :seed_bundles, :plugin_fact_digest,
+                            :missing, :class_decls, :constant_decls, :seed_bundles, :plugin_fact_digest,
                             :return_summaries, :param_table,
                             :effect_collections, :effects_identity)
 
@@ -218,6 +253,7 @@ module Rigor
           symbol_fingerprints: data[:symbol_fingerprints] || {},
           missing: data[:missing] || {},
           class_decls: data[:class_decls] || {},
+          constant_decls: data[:constant_decls] || {},
           seed_bundles: data[:seed_bundles] || {},
           plugin_fact_digest: data[:plugin_fact_digest],
           return_summaries: data[:return_summaries] || {},
@@ -241,6 +277,7 @@ module Rigor
           symbol_fingerprints: payload.symbol_fingerprints,
           missing: payload.missing,
           class_decls: payload.class_decls,
+          constant_decls: payload.constant_decls,
           seed_bundles: payload.seed_bundles,
           plugin_fact_digest: payload.plugin_fact_digest,
           return_summaries: payload.return_summaries,

data/lib/rigor/cache/rbs_environment_marshal_patch.rb

@@ -9,11 +9,28 @@ require "rbs"
 #
 # Patch policy (purely additive):
 #
-# - `_dump` returns an empty string. The cached env loses per-node source-position info, but Rigor does not
-#   consult `RBS::Location` from any analysis code path (every diagnostic uses Prism's own location), so the
-#   loss is inert in practice.
-# - `_load` reconstructs a sentinel Location backed by an empty `<cached>` Buffer. Code paths that DID consult
-#   Location after a cache hit see a benign zero-range value rather than crashing.
+# - `_dump` returns the buffer's NAME and nothing else. Per-node source POSITIONS are still dropped (Rigor
+#   does not consult them from any analysis path — every diagnostic uses Prism's own location), but the
+#   file a declaration came from is cheap to keep and is not inert: `rbs.coverage.definition-build-failed`
+#   names the conflicting signature files, and dropping the name made a warm run omit that clause while a
+#   cold run printed it, so the same project said different things by cache state (issue #696 review,
+#   second pass). It costs cache SIZE: a `_dump` payload is raw bytes, not a linkable object graph, so the
+#   path is written once per Location rather than once per buffer. Memoising the coerced name per buffer was
+#   tried and changes nothing for exactly that reason. Measured +6.6% on a realistic project (Rigor's own
+#   349-file `lib`: 4,332K to 4,616K) and +12.3% on a one-file project (1,672K to 1,876K), both stable
+#   across reps — the env blob is fixed overhead, so the ratio falls as a project's own cached data grows
+#   and the realistic figure is the lower one. That is the price of a diagnostic that reads the same warm
+#   and cold; positions, which are far more numerous and which nothing reads, stay dropped.
+# - `_load` reconstructs a zero-range Location over that name, falling back to a `<cached>` sentinel when
+#   the dump carried none. Code paths that DID consult Location after a cache hit see a benign value rather
+#   than crashing, and one that reads `buffer.name` now sees the real path.
+# - Both directions were exercised rather than assumed. A NEW blob read by an OLDER `_load` — which ignored
+#   its argument — loads and behaves exactly as before; that direction is clean. An OLD blob read by THIS
+#   `_load` also loads without raising, and the sentinel fallback keeps it from ever naming `<cached>` as a
+#   path — but the conflicting-files clause then goes missing, so a warm run off a pre-change blob says less
+#   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.
 #
 # 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.
@@ -33,13 +50,19 @@ require "rbs"
 # reference. Both classes are value objects fully described by `to_s`, so the round-trip is lossless.
 module RBS
   class Location
+    # The name a Location gets back when the dump carried none — an old blob, or a buffer that never had
+    # one. Never a real path, so a consumer that reports file names must filter it
+    # ({Rigor::Environment::RbsLoader::CACHED_LOCATION_BUFFER_NAME}).
+    CACHED_BUFFER_NAME = "<cached>"
+
     unless method_defined?(:_dump)
       def _dump(_)
-        ""
+        buffer&.name.to_s
       end
 
-      def self._load(_)
-        new(buffer: ::RBS::Buffer.new(name: "<cached>", content: ""), start_pos: 0, end_pos: 0)
+      def self._load(name)
+        name = CACHED_BUFFER_NAME if name.nil? || name.empty?
+        new(buffer: ::RBS::Buffer.new(name: name, content: ""), start_pos: 0, end_pos: 0)
       end
     end
   end

data/lib/rigor/cache/store.rb

@@ -29,7 +29,16 @@ module Rigor
       # fail the header check and read as silent misses; the `schema_version.txt` marker additionally carries
       # this version, so the first writable run after a bump clears the root and reclaims the unreadable
       # bytes.
-      FORMAT_VERSION = 2
+      #
+      # v3 (issue #696 review, second pass): `RBS::Location#_dump` now carries the buffer NAME rather than an
+      # empty string, so an env blob written before this change reconstructs every location behind the
+      # `<cached>` sentinel. That degrades gracefully — the sentinel is filtered, never printed as a path —
+      # but `rbs.coverage.definition-build-failed` then omits its conflicting-files clause, so a warm run off
+      # a pre-change blob says less than a cold run does, indefinitely: ADR-6's store never evicts.
+      # `PAYLOAD_ABI_VERSION` already rebuilds across a RELEASE, so the exposure is a same-version tree; this
+      # closes that window too, because "the same project reports differently depending on how you ran it" is
+      # the defect the diagnostic exists to end and a stale blob reintroduces it.
+      FORMAT_VERSION = 3
 
       # Payload ABI version. Store values are mostly Marshal blobs of Rigor/RBS objects, so a Rigor release
       # upgrade is an ABI boundary even when the byte layout and descriptor schema are unchanged. Folding the