rigortype 0.3.6 → 0.3.7

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

data/lib/rigor/cli/coverage_command.rb

@@ -217,24 +217,23 @@ module Rigor
       # class. Tier 1 seeds unconditionally because it only reclassifies sites it already counted; Tier 2 adds
       # sites to a denominator `--threshold` gates CI on, which is why only the latter is gated on a feature id.
       def scope_with_inferred_params(paths, configuration, environment, workers)
-        base = Scope.empty(environment: environment)
-        seed = {}
-
-        discovered = Inference::ScopeIndexer.discovered_classes_for_paths(paths)
-        seed[:discovered_classes] = discovered unless discovered.empty?
-
-        table = Inference::ParameterInferenceCollector.collect(
-          files: paths, environment: environment, target_ruby: configuration.target_ruby, workers: workers
+        CoverageScan.discovery_seeded_scope(
+          files: paths, configuration: configuration, environment: environment,
+          parameter_inference: true, workers: workers
         )
-        seed[:param_inferred_types] = table unless table.empty?
-
-        return base if seed.empty?
-
-        base.with_discovery(base.discovery.with(**seed))
       end
 
+      # Issue #686 — an unmeasured file fails the build the way a parse error already does, and for the same
+      # reason: the command could not measure part of what it was asked about, so its ratio is an answer to
+      # a smaller question than the user asked. Deliberately NOT routed through `--threshold`, which the
+      # line below applies to a ratio: a crashed file's mutants leave `killed + survived` at zero, the
+      # project ratio is then computed over the files that DID work, and a run that measured nothing at all
+      # came out at 1.0 and passed every threshold. It is also deliberately not the `harness_errors` count,
+      # which #264 keeps out of the exit code on purpose — a few rescued mutants are the transient that
+      # bucket exists to make visible, while a wholly unmeasured FILE is not a transient.
       def determine_protection_exit(report, options)
         return 1 unless report.parse_errors.empty?
+        return 1 if unmeasured_files_in(report).positive?
 
         threshold = options[:threshold]
         return 0 if threshold.nil?
@@ -242,6 +241,12 @@ module Rigor
         report.ratio < threshold ? 1 : 0
       end
 
+      # Issue #686 — the one reader of the count, shared with the stderr warning. The Tier-1 protection
+      # report has no such notion, so a report without the field reads as zero rather than erroring.
+      def unmeasured_files_in(report)
+        report.respond_to?(:unmeasured_files) ? report.unmeasured_files : 0
+      end
+
       def usage_error
         @err.puts("coverage: at least one path is required")
         @err.puts(USAGE)
@@ -254,11 +259,11 @@ module Rigor
 
       # The protection scan must see the same receiver types `rigor check` does — including plugin-contributed
       # `dynamic_return` types (a controller's `params` → `ActionController::Parameters`, a `Model.where` →
-      # `ActiveRecord::Relation[Model]`). The bare `CoverageScan.project_environment` carries only the RBS environment
-      # (no plugin registry), so every plugin-typed receiver reads `Dynamic` and its dispatch site is miscounted as
-      # *unprotected* — a systematic undercount of what Rigor actually types on a plugin-using project.
-      # `ProjectContext` builds the plugin-aware environment (registry materialised + the per-run prepare pass that
-      # primes producers like the controller / model index) exactly as the LSP and the runner do.
+      # `ActiveRecord::Relation[Model]`). A bare RBS environment carries no plugin registry, so every plugin-typed
+      # receiver reads `Dynamic` and its dispatch site is miscounted as *unprotected* — a systematic undercount of
+      # what Rigor actually types on a plugin-using project. `ProjectContext` builds the plugin-aware environment
+      # (registry materialised + the per-run prepare pass that primes producers like the controller / model index)
+      # exactly as the LSP, the runner, and — since #513 — the precision path all do.
       def plugin_aware_environment(configuration)
         LanguageServer::ProjectContext.new(configuration: configuration).environment
       end

data/lib/rigor/cli/coverage_mutation.rb

@@ -9,6 +9,8 @@ require_relative "../protection/dependency_closure"
 require_relative "../protection/discovery_seed"
 require_relative "../protection/mutation_cache"
 
+require_relative "measurement_integrity_warning"
+
 module Rigor
   class CLI
     # ADR-63 Tier 2 + ADR-70 — the mutation-effectiveness and fused static∪dynamic protection paths, factored out of
@@ -43,17 +45,13 @@ module Rigor
 
       private
 
-      # @param report [MutationProtectionReport, FusedProtectionReport] — both expose `total_harness_errors`.
+      # Both measurement-integrity warnings, and the escalation rule between them, live in
+      # {MeasurementIntegrityWarning}. Only the floor stays here: it is this command's policy, and
+      # `coverage_command_spec` reads it off this module.
+      #
+      # @param report [MutationProtectionReport, FusedProtectionReport]
       def warn_harness_errors(report)
-        count = report.total_harness_errors
-        return if count < HARNESS_ERROR_WARN_FLOOR
-
-        @err.puts(
-          "coverage: #{count} mutants failed inside the measurement harness (\"harness_errors\", " \
-          "at/above the #{HARNESS_ERROR_WARN_FLOOR}-mutant floor) — excluded from the ratio like a " \
-          "parse-invalid mutant, but this many suggests a harness defect rather than one-off noise. " \
-          "Investigate before trusting --threshold on this run."
-        )
+        MeasurementIntegrityWarning.emit(report, err: @err, floor: HARNESS_ERROR_WARN_FLOOR)
       end
 
       # The cross-file knowledge Tier 2 measures with — the #253 gate, and the ONLY place in this feature that
@@ -262,13 +260,11 @@ module Rigor
       # the two sets were assembled.
       #
       # The two cache phases each get their OWN {Cache::FileDigest.with_run} scope and the MEASUREMENT sits
-      # between them, deliberately: that scope installs a per-path digest memo, and {Protection::ClosureKillOracle}
-      # rewrites one process-private temp file per mutant and digests it through a buffer binding. A memo
-      # spanning the measurement would hand every mutant after the first the FIRST one's digest, the mutated
-      # file's discovery bundle would never be re-walked, and the run would report zero cross-file kills — a
-      # plausible-looking number rather than an error. The oracle's own comment states the same invariant from
-      # the other side. The cost of two scopes is one extra SHA-256 per cached file, against a measurement
-      # that is hundreds of analyses.
+      # between them, deliberately: that scope installs a per-path digest memo. {Protection::ClosureKillOracle}
+      # now writes each mutant to a fresh block-scoped path, so a memo spanning the measurement could no
+      # longer serve one mutant another's digest — but keeping the measurement outside any memo scope stays
+      # correct by construction rather than by the oracle's path discipline, and costs only one extra
+      # SHA-256 per cached file against a measurement that is hundreds of analyses.
       def measure_mutation_files(paths, cache:, scanner:, context:, configuration:, workers:)
         cached = with_digest_run(configuration) { paths.to_h { |path| [path, cache.fetch(path)] }.compact }
         pending = paths - cached.keys