rigortype 0.2.9 → 0.3.0

data/lib/rigor/analysis/severity_stamp.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "diagnostic"
+require_relative "../configuration/severity_profile"
+
+module Rigor
+  module Analysis
+    # ADR-8 § "Severity profile" — re-stamps each diagnostic's severity from the configured profile + per-rule
+    # overrides and drops any diagnostic resolving to `:off`. Rules emit with their authored severity; the
+    # profile is the final filter.
+    #
+    # Extracted (ADR-87 WD4) so the miss path ({Runner::DiagnosticAggregator}) and the boot-slimming hit path
+    # ({RunCacheProbe}, which never loads the aggregator) apply the IDENTICAL final filter — a warm HIT's
+    # served diagnostics are byte-identical to what a full run would print.
+    module SeverityStamp
+      module_function
+
+      def apply(diagnostics, configuration)
+        diagnostics.filter_map { |diagnostic| stamp(diagnostic, configuration) }
+      end
+
+      def stamp(diagnostic, configuration)
+        return diagnostic if diagnostic.rule.nil?
+
+        resolved = Configuration::SeverityProfile.resolve(
+          rule: diagnostic.rule,
+          authored_severity: diagnostic.severity,
+          profile: configuration.severity_profile,
+          overrides: configuration.severity_overrides,
+          bleeding_edge_overrides: configuration.bleeding_edge_severity_overrides
+        )
+        return nil if resolved == :off
+        return diagnostic if resolved == diagnostic.severity
+
+        Diagnostic.new(
+          path: diagnostic.path, line: diagnostic.line, column: diagnostic.column,
+          message: diagnostic.message, severity: resolved, rule: diagnostic.rule,
+          source_family: diagnostic.source_family
+        )
+      end
+    end
+  end
+end

data/lib/rigor/analysis/worker_session.rb

@@ -13,6 +13,7 @@ require_relative "../inference/coverage_scanner"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/method_dispatcher/file_folding"
 require_relative "check_rules"
+require_relative "dependency_recorder"
 require_relative "dependency_source_inference"
 require_relative "diagnostic"
 require_relative "erb_template_detector"
@@ -78,7 +79,7 @@ module Rigor
       def initialize(configuration:, cache_store: nil, # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists
                      plugin_blueprints: [], explain: false, buffer: nil,
                      synthetic_method_index: nil, project_patched_methods: nil,
-                     project_scope_seed: {}, source_files: [])
+                     project_scope_seed: {}, source_files: [], record_dependencies: false)
         @configuration = configuration
         @cache_store = cache_store
         @explain = explain
@@ -86,6 +87,12 @@ module Rigor
         @synthetic_method_index = synthetic_method_index
         @project_patched_methods = project_patched_methods
         @project_scope_seed = project_scope_seed || {}
+        # ADR-46 — when set (the `--incremental` pool path), each `#analyze` is wrapped in a
+        # `DependencyRecorder.record_for` so the worker captures the file's cross-file reads, and the records
+        # are marshalled back to the coordinator ({#drain_dependencies}). Mirrors `Runner#analyze_file`. A
+        # normal `--workers N` run leaves it false and pays nothing (the recorder's disabled fast path).
+        @record_dependencies = record_dependencies
+        @file_dependencies = {}
         # ADR-32 WD4 — full project file list (frozen Array<String>) for env-build-time invocation of any
         # loaded plugin's `source_rbs_synthesizer` callable.
         @source_files = source_files
@@ -132,8 +139,20 @@ module Rigor
 
       # Equivalent of {Rigor::Analysis::Runner#analyze_file} + `plugin_emitted_diagnostics` +
       # `explain_diagnostics`. Returns a flat `Array<Diagnostic>` for the file. Severity profile re-stamping
-      # is intentionally NOT applied — that is a per-run aggregate concern handled by the caller.
+      # is intentionally NOT applied — that is a per-run aggregate concern handled by the caller. When
+      # `record_dependencies:` was set, wraps the analysis in a {DependencyRecorder} window (ADR-46) so the
+      # worker captures the file's cross-file reads for {#drain_dependencies}; the recorder's own disabled
+      # fast path makes the unwrapped case free.
       def analyze(path)
+        return analyze_body(path) unless @record_dependencies
+
+        diagnostics = nil
+        record = DependencyRecorder.record_for(path) { diagnostics = analyze_body(path) }
+        @file_dependencies[path] = record
+        diagnostics
+      end
+
+      def analyze_body(path)
         parse_result = parse_source(path)
         unless parse_result.errors.empty?
           return [] if ErbTemplateDetector.template?(parse_result)
@@ -161,6 +180,7 @@ module Rigor
       rescue StandardError => e
         [analyzer_error(path, "internal analyzer error: #{e.class}: #{e.message}")]
       end
+      private :analyze_body
 
       # Read-once snapshot of the per-worker reporters so the caller (or the eventual Phase 4b pool
       # aggregator) can merge into a single coordinator-side reporter. Both reporters dedupe at write time,
@@ -176,6 +196,14 @@ module Rigor
         }
       end
 
+      # ADR-46 — the per-file {DependencyRecorder::Record}s captured by this session's `#analyze` calls (empty
+      # unless `record_dependencies:` was set). Marshal-clean (Data of frozen Sets / String Hashes), so the
+      # fork pool ships them back to the coordinator, which folds them into the runner's `file_dependencies`
+      # exactly as the sequential recording path would.
+      def drain_dependencies
+        @file_dependencies
+      end
+
       private
 
       # Mirrors {Runner#seed_project_scope}: applies the cross-file pre-pass discovery tables the

data/lib/rigor/bleeding_edge.rb

@@ -9,11 +9,10 @@ module Rigor
   # *today's* rules are) and is versioned with the gem, NOT a user-supplied file: the
   # inspectable counterpart to PHPStan's `bleedingEdge` include.
   #
-  # The overlay is **empty today** — no discipline has yet been queued for the next major.
-  # This module is the WD2 *foundation* (the v0.1.19 slice): the surface (`bleeding_edge:`
-  # config, the `rigor show-bleedingedge` command, the severity-composition hook in
-  # {Configuration::SeverityProfile.resolve}) exists and is wired end-to-end, so the first
-  # real feature lands as a single {FEATURES} entry with no engine plumbing.
+  # The WD2 foundation slice wired the surface end-to-end (`bleeding_edge:` config, the
+  # `rigor show-bleedingedge` command, the severity-composition hook in
+  # {Configuration::SeverityProfile.resolve}), so a discipline lands as a single {FEATURES}
+  # entry with no engine plumbing — as the first one, `reject-unparseable-signatures`, does.
   #
   # Each feature carries a **stable feature id** — part of the ADR-50 WD1 contract
   # vocabulary: the config, the `show` command, and the eventual CHANGELOG migration note all
@@ -40,9 +39,39 @@ module Rigor
       end
     end
 
-    # The overlay. Empty until the first next-major discipline is queued; add a {Feature}
-    # here (with a stable id) when one is.
-    FEATURES = [].freeze
+    # The overlay.
+    #
+    # Feature ids are **kebab-case, and name the discipline rather than the rule** it happens to
+    # promote (`reject-unparseable-signatures`, not `rbs-quarantine-error`): a discipline may grow
+    # to cover more rules without its id going stale, and the id is contract vocabulary that
+    # outlives the rule set it started with.
+    FEATURES = [
+      Feature.new(
+        id: "reject-unparseable-signatures",
+        summary: "A broken `signature_paths:` RBS set fails the run instead of degrading it silently. An " \
+                 "unparseable `.rbs` is otherwise skipped with a warning, and a duplicate-declaration " \
+                 "conflict (a file that parses fine but collides on resolve — typically against Rigor's " \
+                 "own bundled RBS) collapses the whole env with a warning; either way the run gets quieter " \
+                 "rather than cleaner. This treats both as a build error, the way a broken source file " \
+                 "already is.",
+        severity_overrides: {
+          "rbs.coverage.quarantined-signature" => :error,
+          "rbs.coverage.environment-build-failed" => :error
+        }.freeze
+      ),
+      Feature.new(
+        id: "use-of-void-value",
+        summary: "Using a value recovered from an author-declared `-> void` return in value context (an " \
+                 "assignment right-hand side, a call receiver, or an argument) becomes a `:warning`. An " \
+                 "explicit `-> void` is the strongest possible \"do not rely on this return\" signal, so " \
+                 "the direct-dispatch case is FP-narrow; a bare-statement `void` result and a legitimate " \
+                 "`top` value both stay silent. Off by default because a new required diagnostic is an " \
+                 "ADR-50 WD1 compatibility change (ADR-100 WD2).",
+        severity_overrides: {
+          "static.value-use.void" => :warning
+        }.freeze
+      )
+    ].freeze
 
     module_function
 

data/lib/rigor/builtins/regex_refinement.rb

@@ -19,7 +19,7 @@ module Rigor
     # Recognised body shapes (each row admits the `+` quantifier and the bounded `{n}` /
     # `{n,m}` forms with `n >= 1`):
     #
-    #   - `\d`                     -> decimal-int-string
+    #   - `\d`, `[0-9]`            -> decimal-int-string
     #   - `\h`                     -> hex-int-string
     #   - `[0-9a-fA-F]`            -> hex-int-string
     #   - `[0-9a-f]`, `[0-9A-F]`   -> hex-int-string
@@ -45,6 +45,7 @@ module Rigor
       # `Ractor::IsolationError` on the first row access.
       RULES = Ractor.make_shareable([
                                       [/\A\\d#{QUANTIFIER_SOURCE}\z/, :decimal_int_string],
+                                      [/\A\[0-9\]#{QUANTIFIER_SOURCE}\z/, :decimal_int_string],
                                       [/\A\\h#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
                                       [/\A\[0-9a-fA-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
                                       [/\A\[0-9a-f\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
@@ -77,6 +78,40 @@ module Rigor
         Type::Combinator.public_send(rule.last)
       end
 
+      # Whole-receiver regime (#164). Where {for_capture_body} narrows a named-capture body —
+      # sound *without* anchors because the capture boundary is itself the anchor — this maps a
+      # WHOLE regex `source` (as from `Regexp#source` or a literal `RegularExpressionNode`)
+      # matched against an entire string via `String#match?` / `=~`. The predicate proves a
+      # property of the whole string only when the pattern is fully anchored, so a required
+      # leading `\A` **and** trailing `\z` are load-bearing: both must be present, and the inner
+      # body must be one of the curated single-char-class shapes {for_capture_body} already
+      # audits.
+      #
+      # Deliberately rejected (each admits a string the carrier would misdescribe):
+      #
+      #   - bare / one-sided anchoring (`\d+`, `\A\d+`, `\d+\z`) — matches a substring, not the
+      #     whole string;
+      #   - `\Z` (capital) — anchors before an optional trailing newline, so `"12\n"` matches
+      #     `/\A\d+\Z/` yet is not a decimal-int-string;
+      #   - line anchors `^` / `$` — match per-line, so `"12\nabc"` matches `/^\d+$/`;
+      #   - any inner body outside the curated table (`\w+`, alternation, multi-class).
+      #
+      # Extended (`//x`) mode is the caller's concern — the char-class table cannot see the
+      # free-whitespace/`#`-comment flag from the `source` alone, so consumers bail on it before
+      # calling here.
+      #
+      # @param source [String, nil] the full regex source string.
+      # @return [Rigor::Type, nil] the matching imported refinement carrier, or `nil`.
+      def for_whole_pattern(source)
+        return nil if source.nil?
+        return nil unless source.start_with?('\A') && source.end_with?('\z')
+
+        inner = source[2...-2]
+        return nil if inner.nil? || inner.empty?
+
+        for_capture_body(inner)
+      end
+
       # Filters the bounded-quantifier forms to ones whose lower bound is at least 1 and
       # whose upper bound (if any) is at least the lower bound. Without this, `\d{0,5}` would
       # be accepted even though it admits the empty string, which is not a valid

data/lib/rigor/cache/descriptor.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "json"
 require_relative "../value_semantics"
+require_relative "file_digest"
 
 module Rigor
   module Cache
@@ -26,7 +27,13 @@ module Rigor
       # v4: ADR-60 WD3 added the `globs` slot ({GlobEntry}) for the record-and-validate plugin-producer cache;
       # the new slot changes `#to_canonical_hash` (and is Marshal-dumped inside `fetch_or_validate` entry
       # pairs), so entries written by an older Rigor must read as misses.
-      SCHEMA_VERSION = 4
+      # v5: ADR-87 WD1/WD2 changed the dependency-side freshness format — {FileEntry} gains the `:stat`
+      # comparator (a packed `digest + size + mtime_ns + ctime_ns + inode + recording_instant` tuple) and
+      # {GlobEntry}'s aggregate signature is now a SHA-256 over per-file STAT tuples rather than per-file
+      # content digests. Old entries must read as misses so the first writable run rebuilds them in the new
+      # format for a clean one-shot migration (the #57 marker discipline: the bump clears the root and
+      # reclaims the unreadable bytes).
+      SCHEMA_VERSION = 5
 
       # 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.
@@ -34,7 +41,13 @@ module Rigor
       class FileEntry
         include Rigor::ValueSemantics
 
-        VALID_COMPARATORS = %i[digest mtime exists].freeze
+        # `:stat` (ADR-87 WD1) is the stat-then-digest comparator for the validation-only dependency
+        # descriptor; its `value` packs the content digest PLUS a `(size, mtime_ns, ctime_ns, inode)` stat
+        # tuple and the run's recording instant, so validation can skip the SHA-256 when the stat is unmoved.
+        # It MUST NOT be placed in a descriptor used as a cache KEY (its value carries machine-local,
+        # per-run-nondeterministic stat data); {RbsDescriptor.build}'s env-cache `files` therefore stay
+        # `:digest`, while the {Runner} run-dependency descriptor and plugin {IoBoundary} reads use `:stat`.
+        VALID_COMPARATORS = %i[digest stat mtime exists].freeze
 
         attr_reader :path, :comparator, :value
 
@@ -52,6 +65,16 @@ module Rigor
           freeze
         end
 
+        # ADR-87 WD1 — builds a `:stat` entry, packing the supplied content `digest` with the file's live stat
+        # tuple. Falls back to a plain `:digest` entry when the file cannot be stat-ed (a race between the
+        # digest and the stat), so the resulting entry is always valid to re-validate.
+        def self.stat(path:, digest:)
+          packed = FileDigest.pack_stat(path, digest)
+          return new(path: path, comparator: :digest, value: digest) if packed.nil?
+
+          new(path: path, comparator: :stat, value: packed)
+        end
+
         def to_h
           { "path" => path, "comparator" => comparator.to_s, "value" => value }
         end
@@ -147,14 +170,27 @@ module Rigor
         end
       end
 
-      # ADR-60 WD3 — one glob's-worth of watched files, digested as a single value so the entry covers content
-      # change, addition, AND removal in one row: the digest is the SHA-256 over the sorted
-      # `"<path>\0<sha256-of-content>\n"` rows of every file matching `File.join(root, pattern)`. A new file
-      # adds a row, a deleted file drops one, an edit changes one — all three move the digest.
-      # {Descriptor#fresh?} re-runs the same computation and compares.
+      # ADR-60 WD3 / ADR-87 WD2 — one glob's-worth of watched files, covering content change, addition, AND
+      # removal in a single aggregate `value`. Pre-ADR-87 the value was a SHA-256 over sorted
+      # `"<path>\0<content-sha256>\n"` rows — sound but it re-READ + re-hashed every file's CONTENT on every
+      # validation (the ~40 MB gitlab plugin-prepass tax). ADR-87 WD2 keeps the identical one-hash shape (small
+      # to Marshal, deterministic, composition-safe) but hashes STAT TUPLES instead of content: the value is a
+      # SHA-256 over sorted `"<path>\0<size>\0<mtime_ns>\0<ctime_ns>\0<inode>\n"` rows. {.fresh?} re-globs +
+      # re-stats and compares — reading ZERO file-content bytes on an unchanged tree — while any content edit
+      # (which moves mtime + ctime) still moves the signature. `RIGOR_STRICT_VALIDATION` / `cache.validation:
+      # digest` restores the content-hash signature for a filesystem whose stat cannot be trusted. A single
+      # aggregate hash is the right granularity here: a watched dependency is all-or-nothing (one changed file
+      # invalidates the producer's cache regardless), so per-file partial re-hashing bought nothing but a heavy
+      # per-file table to Marshal. The trade vs the old content signature is that a bare `touch` (moved stat,
+      # identical content) now invalidates the glob — rare, and only forces the same recompute the old form
+      # paid on EVERY run.
       class GlobEntry
         include Rigor::ValueSemantics
 
+        ROW_SEPARATOR = "\n"
+        FIELD_SEPARATOR = "\0"
+        private_constant :ROW_SEPARATOR, :FIELD_SEPARATOR
+
         attr_reader :root, :pattern, :value
 
         value_fields :root, :pattern, :value
@@ -168,27 +204,45 @@ module Rigor
 
         # Builds the entry for the glob's CURRENT filesystem state.
         def self.compute(root:, pattern:)
-          new(root: root, pattern: pattern, value: digest_for(root: root, pattern: pattern))
+          new(root: root, pattern: pattern, value: signature_for(root: root, pattern: pattern))
         end
 
-        # The digest the entry's `value` carries. Per-file read failures (a file vanishing between the glob and
-        # the digest) are treated as the file being absent — same race posture as
-        # {Descriptor#file_entry_fresh?}.
-        def self.digest_for(root:, pattern:)
-          # Dir.glob returns sorted entries by default (sort: true), so the row order — and therefore the
-          # digest — is stable.
+        # The aggregate signature the entry's `value` carries: SHA-256 over the sorted per-file rows. In the
+        # default (`:stat`) mode a row is the file's `(path, size, mtime_ns, ctime_ns, inode)` tuple — NO
+        # content read; in strict mode a row is `(path, content-sha256)`, restoring the pre-ADR-87 authority.
+        # Per-file stat failures (a file vanishing between the glob and the stat) drop the row — same race
+        # posture as {Descriptor#file_entry_fresh?}. `Dir.glob` returns sorted entries by default so the row
+        # order — and therefore the signature — is stable.
+        def self.signature_for(root:, pattern:)
+          strict = FileDigest.strict_validation?
           rows = Dir.glob(File.join(root, pattern)).filter_map do |path|
-            next nil unless File.file?(path)
-
-            "#{path}\0#{Digest::SHA256.file(path).hexdigest}\n"
+            st = File.stat(path)
+            next nil unless st.file?
+
+            if strict
+              "#{path}#{FIELD_SEPARATOR}#{FileDigest.hexdigest(path)}#{ROW_SEPARATOR}"
+            else
+              "#{path}#{FIELD_SEPARATOR}#{st.size}#{FIELD_SEPARATOR}#{FileDigest.ns_of(st.mtime)}" \
+                "#{FIELD_SEPARATOR}#{FileDigest.ns_of(st.ctime)}#{FIELD_SEPARATOR}#{st.ino}#{ROW_SEPARATOR}"
+            end
           rescue StandardError
             nil
           end
           Digest::SHA256.hexdigest(rows.join)
         end
 
+        # ADR-87 WD2 — fresh iff re-globbing + re-stat-ing reproduces the recorded signature. Zero file-content
+        # bytes are read in the default mode. Any failure reads as stale (recompute), never a crash. A stored
+        # signature recorded under the opposite validation mode simply mismatches and recomputes.
+        def self.fresh?(entry)
+          signature_for(root: entry.root, pattern: entry.pattern) == entry.value
+        rescue StandardError
+          false
+        end
+
         # Composition key — {.compose} unions per (root, pattern) slot; two contributions for the same slot
-        # must agree on the digest or {Conflict} is raised.
+        # must agree on the value or {Conflict} is raised. Within one run the same glob stat-reads identically,
+        # so contributions never conflict.
         def slot_key
           "#{root}\0#{pattern}"
         end
@@ -229,10 +283,12 @@ module Rigor
           globs.all? { |entry| glob_entry_fresh?(entry) }
       end
 
-      # File-comparator strictness ordering. `:digest` is strictest (deterministic across machines); `:mtime`
-      # is cheaper but local; `:exists` is the weakest signal. When two contributors disagree on the
-      # comparator for the same `path`, the stricter one wins.
-      COMPARATOR_STRICTNESS = { digest: 2, mtime: 1, exists: 0 }.freeze
+      # File-comparator strictness ordering. `:stat` is strictest (it carries the content digest AND a stat
+      # tuple, so it validates content-authoritatively while short-circuiting on an unmoved stat); `:digest` is
+      # deterministic across machines; `:mtime` is cheaper but local; `:exists` is the weakest signal. Ranking
+      # `:stat` and `:digest` apart guarantees a path contributed under both never raises a value {Conflict}
+      # (their `value` strings differ by construction) — the stricter one wins and its value is used.
+      COMPARATOR_STRICTNESS = { stat: 3, digest: 2, mtime: 1, exists: 0 }.freeze
       private_constant :COMPARATOR_STRICTNESS
 
       # Composes any number of descriptors into a single descriptor whose slots are the union of the inputs'
@@ -313,7 +369,13 @@ module Rigor
       def file_entry_fresh?(entry)
         case entry.comparator
         when :digest
-          File.file?(entry.path) && Digest::SHA256.file(entry.path).hexdigest == entry.value
+          # `FileDigest` serves a per-run memo when a run is active (validation digests overlap the
+          # dependency descriptor's), and falls back to a direct digest otherwise — same value either way.
+          File.file?(entry.path) && FileDigest.hexdigest(entry.path) == entry.value
+        when :stat
+          # ADR-87 WD1 — stat-then-digest: stat first, re-hash only when the tuple moved (or the racy window
+          # fires, or strict mode forces it). A stat failure raises and the outer rescue reads it as stale.
+          FileDigest.stat_fresh?(entry.path, entry.value)
         when :mtime
           File.exist?(entry.path) && File.mtime(entry.path).to_i.to_s == entry.value
         when :exists
@@ -325,12 +387,10 @@ module Rigor
         false
       end
 
-      # ADR-60 WD3 — re-runs the entry's glob + digest and compares against the recorded value. Any failure
-      # reads as stale (recompute), never a crash.
+      # ADR-60 WD3 / ADR-87 WD2 — stat-validates the entry's per-file table against the live tree, re-hashing
+      # only stat-moved files. Any failure reads as stale (recompute), never a crash.
       def glob_entry_fresh?(entry)
-        GlobEntry.digest_for(root: entry.root, pattern: entry.pattern) == entry.value
-      rescue StandardError
-        false
+        GlobEntry.fresh?(entry)
       end
 
       def sort_entries(entries, key)

data/lib/rigor/cache/file_digest.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Rigor
+  module Cache
+    # Per-run content-digest memo AND the ADR-87 stat-then-digest freshness choke point. Within a single
+    # `Rigor::Analysis::Runner#run`, the same absolute path is SHA-256'd at most once — across every descriptor
+    # that digests files: the run-diagnostics dependency descriptor ({Runner#analyzed_file_entries}), the
+    # ADR-45 {Descriptor#fresh?} validation of that descriptor, the RBS signature tree
+    # ({RbsDescriptor.file_entries}), and every plugin producer's `watch:`-glob validation
+    # ({Descriptor::GlobEntry}). Those sets overlap heavily (an analyzed file is often also inside a plugin's
+    # watch glob; the RBS tree is digested by both the runner and the RBS producers), so the memo removes the
+    # redundant re-hashing that dominates warm-hit validation.
+    #
+    # ADR-87 WD1 layers a stat tier ON TOP of the memo: a `:stat` {Descriptor::FileEntry} packs a
+    # `(digest, size, mtime_ns, ctime_ns, inode)` tuple plus the run's recording instant, and {.stat_fresh?}
+    # validates it by stat-ing the file first and only falling back to {.hexdigest} (this memo) when the tuple
+    # moved or the racy window fires. On a true null build an unchanged file is a single `File::Stat` call and
+    # zero SHA-256 bytes. The SHA-256 digest remains the sole change AUTHORITY — the stat tier only decides
+    # whether the digest needs recomputing.
+    #
+    # Soundness: the memo + recording-instant + strict flag are process-local (thread-locals, so Ractor-safe
+    # and never crossing a fork boundary), never persisted to disk, and scoped to exactly one run via
+    # {.with_run} (which installs a fresh table and restores the previous one on exit — a second run, or a run
+    # that re-reads a file the user edited between runs, gets a clean table). Within a single run the analyzer
+    # already assumes the filesystem is stable — {Descriptor#fresh?} validates the whole dependency set against
+    # the live tree in one pass and never re-checks mid-run — so caching a coherent per-run snapshot changes
+    # nothing about what a run observes. Outside a run scope (no active table) every call digests directly,
+    # identical to a bare `Digest::SHA256.file`.
+    module FileDigest
+      MEMO_KEY = :rigor_cache_file_digest_memo
+      INSTANT_KEY = :rigor_cache_recording_instant
+      STRICT_KEY = :rigor_cache_strict_validation
+      private_constant :MEMO_KEY, :INSTANT_KEY, :STRICT_KEY
+
+      # Set in the environment to force the strict digest-always validation path for a single run, regardless
+      # of the `cache.validation` config setting (the env wins). The escape hatch for a filesystem whose stat
+      # tuples cannot be trusted (a coarse-timestamp mount, a restored-from-backup tree).
+      STRICT_ENV = "RIGOR_STRICT_VALIDATION"
+
+      # Runs `block` with a fresh per-run digest table installed, restoring whatever table was active before
+      # (nil on the normal top-level run; a parent table only if a run were somehow nested). Always restores,
+      # even on a raise, so a failed run never leaks its table into the next one. The recording instant is
+      # captured at run start — a file whose recorded mtime is not strictly older than it is treated as racy
+      # (always re-hashed), catching a file edited during the analysis window. `strict:` forces the
+      # digest-always path for `cache.validation: digest`.
+      def self.with_run(strict: false)
+        previous_memo = Thread.current[MEMO_KEY]
+        previous_instant = Thread.current[INSTANT_KEY]
+        previous_strict = Thread.current[STRICT_KEY]
+        Thread.current[MEMO_KEY] = {}
+        Thread.current[INSTANT_KEY] = now_ns
+        Thread.current[STRICT_KEY] = strict
+        yield
+      ensure
+        Thread.current[MEMO_KEY] = previous_memo
+        Thread.current[INSTANT_KEY] = previous_instant
+        Thread.current[STRICT_KEY] = previous_strict
+      end
+
+      # The SHA-256 hex digest of `path`'s current content. Served from the active per-run table when one is
+      # installed (computing + storing it on first request for that path), otherwise computed directly. A
+      # read failure (missing / unreadable file) propagates exactly as `Digest::SHA256.file` would and is NOT
+      # memoised, so a caller's own rescue path is unchanged.
+      def self.hexdigest(path)
+        memo = Thread.current[MEMO_KEY]
+        return Digest::SHA256.file(path).hexdigest if memo.nil?
+
+        memo[path] ||= Digest::SHA256.file(path).hexdigest
+      end
+
+      # @return [Boolean] whether digest-always validation is forced for this run. The env var wins over the
+      #   run-scoped config flag so an operator can bypass the stat tier without editing `.rigor.yml`.
+      def self.strict_validation?
+        return true if ENV[STRICT_ENV] == "1"
+
+        Thread.current[STRICT_KEY] == true
+      end
+
+      # ADR-87 WD1 — packs the `:stat` FileEntry value: `"<digest> <size> <mtime_ns> <ctime_ns> <inode>
+      # <recording_instant_ns>"`. The digest is supplied by the caller (already computed via {.hexdigest} or
+      # from in-memory content). Returns nil when the file cannot be stat-ed (a race between the digest and the
+      # stat), so the caller can fall back to a plain `:digest` entry.
+      def self.pack_stat(path, digest)
+        st = File.stat(path)
+        "#{digest} #{st.size} #{ns(st.mtime)} #{ns(st.ctime)} #{st.ino} #{recording_instant_ns}"
+      rescue SystemCallError
+        nil
+      end
+
+      # ADR-87 WD1 — validates a `:stat` FileEntry value against the live filesystem. Stats the file first;
+      # when the `(size, mtime_ns, ctime_ns, inode)` tuple is unchanged AND the entry is not racy, the file is
+      # fresh with zero bytes hashed. When the tuple moved or the entry is racy, the recorded digest is the
+      # authority: the file is re-hashed and fresh iff the digest still matches (a touch — a moved stat over
+      # identical content — therefore validates as fresh). Any stat failure (missing / unreadable file) raises
+      # and the caller reads it as stale. In strict mode the stat tier is skipped entirely.
+      def self.stat_fresh?(path, packed)
+        parsed = parse_stat(packed)
+        return false if parsed.nil?
+
+        digest = parsed[0]
+        return hexdigest(path) == digest if strict_validation?
+
+        st = File.stat(path)
+        return true if !racy?(parsed) && tuple_matches?(st, parsed)
+
+        hexdigest(path) == digest
+      end
+
+      def self.recording_instant_ns
+        Thread.current[INSTANT_KEY] || now_ns
+      end
+
+      # value layout: [digest, size, mtime_ns, ctime_ns, inode, recording_instant_ns]
+      def self.parse_stat(packed)
+        parts = packed.to_s.split
+        return nil unless parts.size == 6
+
+        [parts[0], *parts[1..].map { |n| Integer(n, 10) }]
+      rescue ArgumentError
+        nil
+      end
+      private_class_method :parse_stat
+
+      def self.tuple_matches?(stat, parsed)
+        stat.size == parsed[1] && ns(stat.mtime) == parsed[2] &&
+          ns(stat.ctime) == parsed[3] && stat.ino == parsed[4]
+      end
+      private_class_method :tuple_matches?
+
+      # An entry is racy when its recorded mtime is not strictly older than the run's recording instant — the
+      # file was (or may have been) modified within the recording window, so its stat tuple cannot be trusted
+      # to have settled. Such an entry always re-hashes. On a nanosecond-resolution filesystem this fires only
+      # for a file edited during the analysis run itself.
+      def self.racy?(parsed)
+        parsed[2] >= parsed[5]
+      end
+      private_class_method :racy?
+
+      # Full-nanosecond integer for a `Time` (from `File::Stat#mtime`/`#ctime`). Public so {GlobEntry} packs
+      # its per-file rows with the identical resolution the FileEntry tuple uses.
+      def self.ns_of(time)
+        (time.tv_sec * 1_000_000_000) + time.tv_nsec
+      end
+
+      def self.ns(time)
+        ns_of(time)
+      end
+      private_class_method :ns
+
+      def self.now_ns
+        Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+      end
+      private_class_method :now_ns
+    end
+  end
+end