rigortype 0.3.9 → 0.4.1

data/lib/rigor/builtins/static_return_refinements.rb

@@ -93,6 +93,7 @@ module Rigor
         ["IO", :read, :singleton] => IO_READ_NO_LENGTH,
         ["File", :read, :singleton] => IO_READ_NO_LENGTH
       }.freeze
+      Ractor.make_shareable(OVERRIDES)
       private_constant :OVERRIDES
 
       # Looks up a refined return type for the given call.
@@ -124,6 +125,7 @@ module Rigor
         acc[mname] ||= []
         acc[mname] << owner unless acc[mname].include?(owner)
       end.freeze
+      Ractor.make_shareable(OWNERS_BY_METHOD)
       private_constant :OWNERS_BY_METHOD
 
       # @return the candidate owner class names for a bare method-name

data/lib/rigor/cache/descriptor.rb

@@ -53,7 +53,36 @@ module Rigor
       # interface a `conforms-to` names) invalidates the warm entry. A pre-9 entry carries no signature-root
       # row and would validate fresh across exactly that edit — the #577 reasoning, one slot over — so cached
       # entries must read as misses once and rebuild carrying the rows.
-      SCHEMA_VERSION = 9
+      # v10: #1123 — the def-index seed bundles gain the `:prepends` table, the instance-ancestor-ORDER half
+      # of the `include` table (`prepend M`, and `Recv.prepend(M)`), which `Scope#user_def_through_ancestors`
+      # searches ahead of a class's own `def`s. A pre-10 bundle would silently contribute no prepends for an
+      # unchanged file, so that file's consumers would keep answering with the pre-fix MRO — cached bundles
+      # must read as misses once and rebuild carrying the slot.
+      # v11: #1558 — a plugin producer served from its own cache now replays its entry's dependency rows into
+      # the plugin's IoBoundary, so the run-result entry and the entry of any producer computed after it carry
+      # the served value's inputs. A pre-11 entry written while a producer hit lacks those rows and would
+      # validate fresh across exactly the edit they exist to catch. A checkout's source digest already moved
+      # every such key, and a release clears the root through `Store::PAYLOAD_ABI_VERSION`; the bump closes
+      # the remaining window, a same-`VERSION` build installed as `gems/rigortype-<VERSION>`, which
+      # {EngineSource} treats as version-pinned (#285) and so keys on the version alone.
+      # v12: the def-index seed bundles gain the `:unpositioned_mixins` table, the mixin edges whose order is
+      # not a fact, which an ancestor-order reader declines on. A pre-12 bundle would silently contribute no
+      # such edge for an unchanged file, so cached bundles must read as misses once and rebuild carrying it.
+      # v13/v14: #1587 — the prepend table keeps every statement (a repeated `prepend` is no longer collapsed at
+      # the freeze) and a module written to both the include and the prepend table, or a repeated `extend`, is
+      # named unpositioned. A pre-14 bundle would hold the collapsed prepend list and miss the taint for an
+      # unchanged file, so cached bundles must read as misses once and rebuild.
+      # v15: #1592 — an `extend` (or a `class << self` include) written inside a block the walk used to skip is
+      # now recorded and named unpositioned. A pre-15 bundle would hold neither for an unchanged file.
+      # v16: ADR-119 WD1 — the def-index seed bundles gain the `:siblings` Hash (the `possible_*` / `contested_*`
+      # halves of the discovery pairs). A pre-16 bundle would contribute no sibling for an unchanged file, so cached
+      # bundles must read as misses once and rebuild carrying it.
+      # v17: ADR-119 WD3 — the def-contribution producers fill the siblings (a conditional `def`'s name possible, its
+      # def-node slot and envelope contested). A pre-17 bundle carries the empty siblings of the walk before them, so
+      # an unchanged file would fold as "no possible fact" where a cold walk records one.
+      # v18: ADR-119 WD3 — the visibility walk fills `contested_discovered_method_visibilities`; a pre-18 bundle
+      # carries it empty, so an unchanged file's conditional visibility would fold as certain.
+      SCHEMA_VERSION = 18
 
       # 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.
@@ -100,6 +129,21 @@ module Rigor
           new(path: path, comparator: :stat, value: packed)
         end
 
+        # A `:stat` row whose recording instant is no later than `limit_ns`: any file whose recorded mtime is at or
+        # after `limit_ns` is then racy, and validation re-hashes it instead of trusting its stat tuple. Any other
+        # row, and one whose instant is already earlier, is returned as is.
+        def with_recording_instant_at_most(limit_ns)
+          return self unless comparator == :stat
+
+          parts = value.split
+          return self unless parts.size == 6 && Integer(parts[5], 10) > limit_ns
+
+          parts[5] = limit_ns.to_s
+          self.class.new(path: path, comparator: comparator, value: parts.join(" "))
+        rescue ArgumentError
+          self
+        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"

data/lib/rigor/cache/engine_source.rb

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

data/lib/rigor/cache/file_digest.rb

@@ -112,6 +112,34 @@ module Rigor
         hexdigest(path) == digest
       end
 
+      # ADR-45 WD2 (#1507) — `packed` re-packed against `path`'s current stat, for a writer about to record it
+      # again: when the tuple moved (a `touch`, a checkout) or the entry is racy, but the file still hashes to the
+      # recorded digest, the new pack carries the current tuple and this run's recording instant, so the next
+      # validation is one `File::Stat` again rather than a re-hash every time.
+      #
+      # The hash is taken fresh, never from the per-run memo: a memoised digest describes the bytes as they were
+      # when change detection read them, and pairing it with a later stat would vouch for bytes written since. And
+      # the re-pack is kept only when the tuple it packed, taken after the hash, is the one taken before it: a
+      # write landing while the file is hashed moves the change time, and leaves `packed` as it was.
+      #
+      # `packed` comes back unchanged when its tuple still matches and it is not racy, and whenever the bytes no
+      # longer match the digest: a row that must stay stale is never refreshed into a fresh one. nil when `packed`
+      # is not a stat pack. A stat failure (the file is gone) returns `packed` unchanged, which then validates as
+      # stale.
+      def self.refresh_stat(path, packed)
+        parsed = parse_stat(packed)
+        return nil if parsed.nil?
+
+        before = File.stat(path)
+        return packed if !racy?(parsed) && tuple_matches?(before, parsed)
+        return packed unless Digest::SHA256.file(path).hexdigest == parsed[0]
+
+        repacked = pack_stat(path, parsed[0])
+        repacked && tuple_matches?(before, parse_stat(repacked)) ? repacked : packed
+      rescue SystemCallError
+        packed
+      end
+
       # The content-digest field of a packed `:stat` entry ({.pack_stat}); nil when the entry is absent or not
       # well-formed. Exposed for the caller that must compare the recorded digest against bytes it hashes
       # itself rather than against the file on disk — the incremental session's editor-mode freshness check,

data/lib/rigor/cache/incremental_snapshot.rb

@@ -5,6 +5,10 @@ require "digest"
 require "zlib"
 
 require_relative "engine_source"
+require_relative "store"
+require_relative "../analysis/shadow_harness"
+require_relative "../analysis/run_cache_key"
+require_relative "../environment"
 
 module Rigor
   module Cache
@@ -106,7 +110,65 @@ module Rigor
       # blob has no such section and would deserialise it as nil, which reads as "nothing cached" and is
       # therefore not misread — but a snapshot written by an engine that did not yet REPLAY them was also
       # written by one whose narrowed runs under-reported, so the gate rejects it and the next run is cold.
-      SCHEMA = 22
+      # 23: issue #992 gives each seed bundle a `parameter_envelopes` table — the joined positional envelope
+      # of every method a file records, plus its module / dynamic-surface marks — which `call.wrong-arity`
+      # reads for a method no signature declares. A pre-23 bundle folds as "no envelopes", which only ever
+      # withholds a check, but a warm run that withholds where a cold run fires is still the
+      # `--verify-incremental` divergence 14 was bumped for.
+      # 24: issue #1097 gives each seed bundle a `deferred_ranges` table — the per-file def / block /
+      # lambda body ranges `Scope#*_def_shadows_call?` orders a project-defined `sig` override
+      # against. A pre-24 bundle would fold as "no ranges", which the predicate reads as "cannot
+      # order → shadow" — a warm run declining the binding where a cold run binds.
+      # 25: issue #1097 extends each `deferred_ranges` row to `[start, end, name, kind, owner]` —
+      # owner-scoped ordering. A 24 bundle folds as "owner = nil", which the predicate reads as
+      # "cannot order", under-shadowing `module_function` defs whose only table evidence is the row
+      # itself.
+      # 26: issue #1123 gives each seed bundle a `prepends` table — the instance-ancestor ORDER of a
+      # class's `prepend`ed modules, which `Scope#user_def_through_ancestors` searches ahead of the
+      # class's own `def`s. A pre-26 bundle would fold as "prepends nothing": the warm run would answer
+      # the pre-fix MRO where a cold run answers the prepended module, exactly the `--verify-incremental`
+      # divergence 14 was bumped for (and a silently WRONG dispatch answer, not a withheld check).
+      # 27: issue #1173 re-MEANs each seed bundle's `includes` VALUES without changing their shape: the
+      # lists now store instance-ancestor SEARCH order (nearest first, prepends ahead of includes)
+      # instead of call order — the same flip 17 made for def-row `nesting`. A pre-27 blob deserialises
+      # cleanly and would serve the old call order on a warm run while a cold run searches nearer-first:
+      # `include A; include B` would resolve A's methods where a cold run resolves B's — the
+      # `--verify-incremental` divergence 14 was bumped for.
+      # 28: issue #1120 gives each seed bundle a `refinements` table — the `def`s of every `refine X do … end`
+      # body, which `call.undefined-method` reads where a `using` of the refining module is in effect. A
+      # pre-28 bundle would fold as "refines nothing", and a warm run would report a refined call a cold run
+      # declines.
+      # 29: issue #1367 gives each seed bundle a `global_write_census` — the globals its `alias` statements name and
+      # the `write` / `to_str` / `to_int` / hatch definitions and top-level mixins it holds, which the `global.*`
+      # write rules decline on project-wide. A pre-29 bundle would fold as "none of those", and a warm run would
+      # report a write a cold run exempts.
+      # 30: issue #1536 gives each seed bundle a `source_rbs_digest` — the digest of what every loaded source-RBS
+      # synthesizer contributes for the file — which ADR-89 WD1 now compares beside `declaration_signature`
+      # in place of switching the gate off whenever `rigor-rbs-inline` is configured. A pre-30 bundle
+      # carries none, which the session reads as "unknown" and so as moved: sound, but every first edit to
+      # each file would re-analyse the whole project, so the gate rejects the blob and the next run is cold.
+      # 31: issue #1574 digests `plugin_fact_digest` and a seed bundle's `source_rbs_digest` with
+      # {ValueDigest} instead of over `Marshal.dump` bytes, so the same value digests alike whether a producer
+      # computed it or its cache entry served it. A pre-31 digest is in the old form and would never match, so
+      # the next run would go cold anyway; the bump makes that a clean miss instead of a "plugin fact surface
+      # changed" note that nothing changed.
+      # 32: each seed bundle gains an `unpositioned_mixins` table — the file's mixin edges whose order is not a
+      # fact (`Scope::DiscoveryIndex#unpositioned_mixins`), which an ancestor-order reader declines on. A pre-32
+      # bundle would fold as "every edge positioned", and a warm run would answer an order a cold run declines.
+      # 33: the mixin producers change what a seed bundle holds (#1587 — the prepend table keeps every statement,
+      # and a both-kind module or a repeated `extend` is named unpositioned), so a pre-33 bundle folds as the
+      # collapsed, positioned table and a warm run would answer an order a cold run declines.
+      # 34: #1592 — an `extend` or a `class << self` include inside a block the extends walk used to skip is now
+      # recorded and named unpositioned, so a pre-34 bundle folds as if the edge did not exist.
+      # 35: ADR-119 WD1 — each seed bundle gains a `siblings` Hash, the `possible_*` / `contested_*` siblings of the
+      # `Scope::DiscoveryIndex` members that may admit a possible fact. Every sibling is empty until a producer
+      # fills one, so a pre-35 bundle folds as "no possible fact", which is what it would hold today; the bump keeps
+      # that true once one does.
+      # 36: ADR-119 WD3 — the def-contribution producers fill those siblings, so a pre-36 bundle folds an unchanged
+      # file's conditional `def` as certain and a warm run would answer a definer a cold run declines.
+      # 37: ADR-119 WD3 — the visibility walk fills `contested_discovered_method_visibilities`, which a pre-37 bundle
+      # carries empty.
+      SCHEMA = 37
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -178,8 +240,13 @@ module Rigor
       # rebuild — the engine version + schema, the engine's own SOURCE when the version does not pin it, the
       # resolved configuration, the analysis **roots** (the path arguments, e.g. `["lib"]`, NOT the expanded
       # file list — so a snapshot is keyed to an invocation's roots but adding / removing a file under them is
-      # handled incrementally by the session, not a full rebuild), the resolved gem set (`Gemfile.lock` /
-      # `rbs_collection`), and the project's own RBS (`signature_paths` file contents). Built WITHOUT
+      # handled incrementally by the session, not a full rebuild), the resolved gem set (the lockfiles
+      # {Analysis::RunCacheKey.resolved_lockfile_paths} resolves — `bundler.lockfile:` / `rbs_collection.lockfile:`,
+      # else `./Gemfile.lock` / `./rbs_collection.lock.yaml` — the same files the run-result key digests), the
+      # project's own RBS (the `sig/` roots the environment actually loads: the explicit
+      # `signature_paths`, or the auto-detected `<root>/sig` when `signature_paths` is nil), and the contents of
+      # every `pre_eval:` file (its PATH is in the configuration, but an edit to a file outside the analysed
+      # paths changes no analysed file, so it needs its own part). Built WITHOUT
       # constructing the RBS environment so the warm path can gate the load cheaply, before the costly env
       # build. The `--verify-incremental` gate is the safety net for any under-capture (it would surface as an
       # incremental-vs-full mismatch). Returns nil on any error → the caller falls back to a non-persisted run.
@@ -193,16 +260,22 @@ module Rigor
       # part, so a released gem's fingerprint is byte-identical to the pre-#289 one and its warm snapshots
       # survive the upgrade untouched.
       def self.fingerprint(configuration:, roots:)
+        bundler_lock, collection_lock = Analysis::RunCacheKey.resolved_lockfile_paths(configuration)
         parts = [
           "engine:#{Rigor::VERSION}:#{SCHEMA}",
           "config:#{Digest::SHA256.hexdigest(Marshal.dump(configuration.to_h))}",
           "roots:#{Array(roots).map(&:to_s).sort.join("\n")}",
-          "gems:#{digest_file_if_present('Gemfile.lock')}",
-          "rbs_collection:#{digest_file_if_present('rbs_collection.lock.yaml')}",
-          "sig:#{digest_signature_paths(configuration.signature_paths)}"
+          "gems:#{digest_file_if_present(bundler_lock)}",
+          "rbs_collection:#{digest_file_if_present(collection_lock)}",
+          "sig:#{digest_signature_paths(project_sig_roots(configuration))}",
+          "pre_eval:#{digest_pre_eval(configuration.pre_eval)}"
         ]
         identity = EngineSource.process_identity
         parts << "engine-source:#{identity}" if identity
+        # ADR-116 WD5 — the snapshot's per-file rows and seed bundles are only as checked as the run that
+        # wrote them ({Inference::DeclarationWalk::Shadow}); nil with the harness off adds no part.
+        shadow = Analysis::ShadowHarness.cache_identity
+        parts << "shadow-harness:#{shadow}" if shadow
         Digest::SHA256.hexdigest(parts.join("\x00"))
       rescue StandardError
         # {EngineSource::Unavailable} lands here too, and nil is the answer it requires rather than one it
@@ -214,10 +287,29 @@ module Rigor
       end
 
       def self.digest_file_if_present(path)
-        File.file?(path) ? Digest::SHA256.file(path).hexdigest : "absent"
+        path = path&.to_s
+        path && File.file?(path) ? Digest::SHA256.file(path).hexdigest : "absent"
       end
       private_class_method :digest_file_if_present
 
+      # Content-digest every `pre_eval:` file in configuration order, so an edit to one invalidates the snapshot
+      # even when it lies outside the analysed paths. A missing file digests as "absent", so creating it counts too.
+      def self.digest_pre_eval(paths)
+        digest = Digest::SHA256.new
+        Array(paths).each do |path|
+          digest << path.to_s << "\0" << digest_file_if_present(path.to_s) << "\0"
+        end
+        digest.hexdigest
+      end
+      private_class_method :digest_pre_eval
+
+      # The `sig/` roots the environment loads for this configuration: the configured `signature_paths`, or the
+      # auto-detected `<root>/sig` when those are nil ({Environment.project_signature_roots}).
+      def self.project_sig_roots(configuration)
+        Environment.project_signature_roots(configuration.signature_paths).map(&:to_s)
+      end
+      private_class_method :project_sig_roots
+
       # Content-digest every `.rbs` under the configured signature paths (sorted for determinism) so a project
       # RBS edit invalidates the snapshot. Sig trees are small; content (not mtime) keeps it stable across
       # checkouts.
@@ -319,7 +411,9 @@ module Rigor
           effects_identity: payload.effects_identity,
           run_level_rows: payload.run_level_rows
         )
-        blob = Zlib::Deflate.deflate(raw)
+        # #1507 — every `--incremental` run that analysed anything rewrites this whole blob, so its deflate is
+        # on the edit path; see {Store::DEFLATE_LEVEL}.
+        blob = Zlib::Deflate.deflate(raw, Store::DEFLATE_LEVEL)
         tmp = "#{@path}.#{Process.pid}.tmp"
         File.binwrite(tmp, blob)
         File.rename(tmp, @path)

data/lib/rigor/cache/rbs_cache_producer.rb

@@ -29,6 +29,10 @@ module Rigor
         # files, same libraries), so the loader memoises one build per process instead of re-digesting every
         # .rbs file once per producer.
         descriptor = loader.rbs_cache_descriptor
+        # Issue #1014 — nil is an engine the descriptor could not identify ({EngineSource::Unavailable}).
+        # Compute uncached rather than keying the value without the engine that produced it.
+        return compute(loader) if descriptor.nil?
+
         store.fetch_or_compute(producer_id: self::PRODUCER_ID, params: {}, descriptor: descriptor,
                                generation_cap: generation_cap) do
           compute(loader)

data/lib/rigor/cache/rbs_descriptor.rb

@@ -3,20 +3,47 @@
 require "digest"
 
 require_relative "descriptor"
+require_relative "engine_source"
 require_relative "file_digest"
 
 module Rigor
   module Cache
     # Shared descriptor builder for cache producers that depend on the RBS environment (constant table,
-    # known-class set, future Marshal-clean reflection artefacts). Every consumer attaches the same three
-    # slots, so factoring the construction here keeps the producers small and ensures invalidation behaves
-    # identically across them.
+    # known-class set, future Marshal-clean reflection artefacts). Every consumer attaches the same slots —
+    # the `rbs` gem row, a digest row per signature file, and the `rbs.libraries` / `rbs.virtual_rbs` /
+    # `rbs.deferred_signature_paths` / `engine-source` config rows — so factoring the construction here keeps
+    # the producers small and ensures invalidation behaves identically across them.
     module RbsDescriptor
+      # The key every `rbs.*` producer shares ({RbsCacheProducer#fetch}): `rbs.environment`,
+      # `rbs.constant_type_table`, `rbs.class_ancestor_table`, `rbs.known_class_names`,
+      # `rbs.class_type_param_names`.
+      #
+      # Issue #1014 — the engine-source row is here, not in {.config_entries}, because these are
+      # computed-value slots: what they hold is not the RBS the descriptor digests but what Rigor's own code
+      # made of it. `rbs.constant_type_table` stores `Inference::RbsTypeTranslator.translate` output and
+      # `rbs.class_ancestor_table` the chains `RbsClassAncestorTable.compute` walks out of
+      # `instance_definition`, so an engine edit to either moved the value while the key stood still: the
+      # run-result key moved (#285) and the run re-analysed, then read the previous build's table. Both were
+      # reproduced cross-build on a fixture — a true positive dropped, and a `flow.unreachable-clause` false
+      # positive served — before this row was added.
+      #
+      # {.config_entries} deliberately does NOT get it: that half is what the ADR-45 run cache key reads
+      # ({.build_run}), and `RunCacheKey` already contributes the identical row from
+      # `EngineSource.key_config_entries` itself. Adding it there would duplicate the row in the run key and
+      # would have to be reconstructible by the boot-slimming probe, which builds `config_entries` without a
+      # loader.
+      #
+      # @raise EngineSource::Unavailable — an engine that cannot be identified must not be keyed by its
+      #   inputs alone; {RbsCacheProducer.fetch} turns this into an uncached compute.
       def self.build(loader)
+        # FIRST, before {.file_entries} digests the whole signature tree: the {EngineSource::Unavailable}
+        # path discards this descriptor entirely, and a SHA-256 of every `.rbs` under every signature root is
+        # the expensive way to reach that conclusion.
+        engine = EngineSource.key_config_entries
         Descriptor.new(
           gems: [rbs_gem_entry],
           files: file_entries(loader),
-          configs: config_entries(loader) + env_only_config_entries(loader)
+          configs: config_entries(loader) + env_only_config_entries(loader) + engine
         )
       end
 
@@ -25,8 +52,10 @@ module Rigor
       # MISS, by the dependency descriptor ({Runner#run_dependency_descriptor}). So a warm HIT never digests
       # the (large, vendored) RBS tree. {RunDescriptor} is NOT a {Descriptor} — it is never composed, hashed,
       # or `==`'d, only its four readers are consulted — so deferring `files` costs no soundness, and `gems`
-      # / `configs` match {.build}'s shared slots (the key is unchanged; the one slot the env key adds on
-      # top, {.env_only_config_entries}, is never read here).
+      # / `configs` match {.build}'s shared slots (the key is unchanged; the slots the env key adds on top,
+      # {.env_only_config_entries} and the #1014 `engine-source` row, are never read here — `RunCacheKey`
+      # contributes the identical engine-source row itself, from the same
+      # `EngineSource.key_config_entries`).
       def self.build_run(loader)
         RunDescriptor.new(loader: loader, gems: [rbs_gem_entry], configs: config_entries(loader))
       end
@@ -112,7 +141,8 @@ module Rigor
       # overlays. Rigor's own `data/` trees ({RbsLoader.vendored_gem_sig_paths}, `.core_overlay_sig_paths`,
       # `.capability_role_sig_paths`) are engine-owned: a file appears under one only when the engine tree is
       # edited, which normally arrives with the `lib/` change that reads it and so re-keys every
-      # computed-value slot through {EngineSource}. They get file rows and no glob — a glob there would cost
+      # computed-value slot through {EngineSource} — including, since #1014, this descriptor itself, which
+      # until then carried no such row. They get file rows and no glob — a glob there would cost
       # every project a stat walk of the vendored gem-signature tree per warm run to catch an
       # engine-development edit.
       def self.glob_entries(loader)

data/lib/rigor/cache/store.rb

@@ -25,7 +25,8 @@ module Rigor
       # On-disk byte-layout version. Bumped on incompatible format changes (independent of
       # {Descriptor::SCHEMA_VERSION}, which covers the descriptor schema rather than the byte layout). v2
       # (ADR-54 WD2): the value payload is zlib-deflated on write and inflated on read — Marshal blobs
-      # compress to 13–16 % at an inflate cost an order of magnitude below their `Marshal.load`. v1 entries
+      # compressed to 13–16 % at zlib's default level (now {DEFLATE_LEVEL}) at an inflate cost an order of
+      # magnitude below their `Marshal.load`. v1 entries
       # 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.
@@ -60,12 +61,19 @@ module Rigor
 
       STALE_TEMP_FILE_AGE_SECONDS = 60 * 60
 
+      # #1507 — the zlib level for everything written under the cache root: these value payloads (ADR-54 WD2),
+      # the incremental snapshot, and `rigor unused`'s scan bundle. The snapshot and the scan bundle are
+      # rewritten whole whenever a run changed anything, so their deflate is on the edit path. On Mastodon the
+      # default level took 122 ms for the snapshot (9.5 MB raw) and 131 ms for `rbs.environment` (22.8 MB raw);
+      # `BEST_SPEED` takes 38 ms and 49 ms, for a cache about a quarter larger. Inflate reads any level, so the
+      # level is not part of the format.
+      DEFLATE_LEVEL = Zlib::BEST_SPEED
+
       # Header literal: 5-byte ASCII magic, 1-byte separator, 1-byte format version.
       HEADER = "RIGOR\x00#{FORMAT_VERSION.chr}".b.freeze
 
       VALID_PRODUCER_ID = /\A[a-z][a-z0-9._-]*\z/
 
-      # @param root — cache root directory.
       # @param read_only — when true, every disk-side side-effect is suppressed: `fetch_or_compute`
       #   still reads existing entries (hits, gated on a current `schema_version.txt` marker — see
       #   {#ensure_schema_version!}) and still runs the producer block on miss, but it does NOT write the
@@ -242,8 +250,13 @@ module Rigor
       # validation always re-checks the filesystem — but a single run only looks up once.
       #
       # `generation_cap:` carries the same producer-declared compaction budget as {#fetch_or_compute}.
+      #
+      # `on_hit:` is called with the entry's stored dependency descriptor on a fresh hit, before the value
+      # is returned, and never on a miss. A caller whose own dependency record must carry a served value's
+      # inputs replays them from it (#1558, {Plugin::Base#cache_for}): a hit runs no block, so nothing else
+      # reports what the value was computed from.
       def fetch_or_validate(producer_id:, key_descriptor:, generation_cap:, params: {},
-                            serialize: nil, deserialize: nil)
+                            serialize: nil, deserialize: nil, on_hit: nil)
         validate_producer_id!(producer_id)
         declare_generation_cap(producer_id, generation_cap)
         disk = ensure_schema_version!
@@ -253,6 +266,7 @@ module Rigor
         cached = path && read_entry(path, deserialize: deserialize)
         if (validated = fresh_pair_value(cached))
           @monitor.synchronize { record(:hits, producer_id) }
+          on_hit&.call(validated[1])
           return validated[0]
         end
 
@@ -286,6 +300,51 @@ module Rigor
         validated[0]
       end
 
+      # ADR-45 WD2 (#1507) — a record-and-validate entry's value WITHOUT validating its dependencies. The
+      # `--incremental` session reads the previous run-result slot to carry forward the rows a narrowed run
+      # cannot re-derive, and that slot is expected to be stale: the edit that started this run is in it. So
+      # the answer here is never served — only rows are taken from it, and they are validated again, with
+      # everything else, the next time the slot is read. nil on a miss, a malformed entry or an unavailable
+      # disk tier. Records neither a hit nor a miss, since nothing was looked up to be served.
+      def peek_unvalidated(producer_id:, key_descriptor:, params: {})
+        validate_producer_id!(producer_id)
+        return nil unless ensure_schema_version!
+
+        key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
+        pair = read_entry(entry_path(producer_id, key))&.value
+        return nil unless pair.is_a?(Array) && pair.size == 2 && pair[1].is_a?(Descriptor)
+
+        pair[0]
+      end
+
+      # ADR-45 WD2 (#1507) — the write half of {#fetch_or_validate} on its own, and unconditional. That method
+      # writes only after it failed to validate what is there; a writer that has just computed an answer of its
+      # own must store THAT answer even when the entry already on disk still validates, because it is the one
+      # the run printed. Same entry format and the same failure contract as {#fetch_or_validate}'s write: a
+      # disk-side failure is swallowed, a value `Marshal` cannot dump raises. Returns whether it wrote.
+      def store_validated(producer_id:, key_descriptor:, generation_cap:, value:, dependencies:, params: {})
+        validate_producer_id!(producer_id)
+        declare_generation_cap(producer_id, generation_cap)
+        return false unless ensure_schema_version!
+
+        key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
+        wrote = try_write_entry(entry_path(producer_id, key), key_descriptor, [value, dependencies])
+        @monitor.synchronize { record(:writes, producer_id) } if wrote
+        wrote
+      end
+
+      # ADR-45 WD2 (#1507) — removes one entry, for a writer that has just superseded it under another key and
+      # knows nothing will ask for it again. Best-effort like every other unlink here; a no-op on a read-only
+      # store.
+      def discard(producer_id:, key_descriptor:, params: {})
+        validate_producer_id!(producer_id)
+        return if @read_only || !ensure_schema_version!
+
+        path = entry_path(producer_id, key_descriptor.cache_key_for(producer_id: producer_id, params: params))
+        unlink_entry_and_shard?(path) if File.file?(path)
+        nil
+      end
+
       # ADR-6 § "Eviction" — compaction pass over the on-disk cache. No-op when the store is read-only.
       #
       # The generation cap of pass 2 comes from what the producers themselves declared through this Store's
@@ -470,7 +529,7 @@ module Rigor
         FileUtils.mkdir_p(File.dirname(path))
 
         descriptor_bytes = descriptor.to_canonical_bytes
-        value_bytes = Zlib::Deflate.deflate(serialize_value(value, serialize))
+        value_bytes = Zlib::Deflate.deflate(serialize_value(value, serialize), DEFLATE_LEVEL)
 
         body = +"".b
         body << HEADER