rigortype 0.3.6 → 0.3.8

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/annotation_location.rb

@@ -0,0 +1,72 @@
+# 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
+
+      # @param location [RBS::Location, nil]
+      # @return [Array, nil] `[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 [Array, nil] what {dump} produced.
+      # @return [RBS::Location, nil]
+      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

@@ -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/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

@@ -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
@@ -9,11 +11,47 @@ 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.
+# - `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.
@@ -33,13 +71,37 @@ 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(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
+
+  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 self._load(_)
-        new(buffer: ::RBS::Buffer.new(name: "<cached>", content: ""), start_pos: 0, end_pos: 0)
+        def marshal_load(payload)
+          dumped_string, dumped_location = payload
+          @string = dumped_string
+          @location = Rigor::Cache::AnnotationLocation.load(dumped_location)
+        end
       end
     end
   end

data/lib/rigor/cache/store.rb

@@ -29,7 +29,23 @@ 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.
+      #
+      # v4 (issue #799): `RBS::AST::Annotation` now carries its own `marshal_dump` / `marshal_load`, which
+      # keep the annotation's POSITION as well as its file, so `rbs_extended.unsatisfied-conformance` points
+      # at the `%a{rigor:v1:conforms-to …}` line warm as well as cold. A pre-change blob loads perfectly well
+      # — Marshal encodes an ivar dump and a `marshal_dump` payload differently, and only the latter reaches
+      # `marshal_load` — which is exactly the problem: without a bump it would keep reporting the row at
+      # `1:1` forever, and `--verify-incremental` would keep failing on that project.
+      FORMAT_VERSION = 4
 
       # 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