rigortype 0.3.0 → 0.3.2

data/lib/rigor/protection/mutation_cache.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "../analysis/plugin_fact_fingerprint"
+require_relative "../cache/descriptor"
+require_relative "../cache/engine_source"
+require_relative "../cache/file_digest"
+require_relative "../cache/incremental_snapshot"
+require_relative "../cache/store"
+require_relative "../version"
+require_relative "mutation_scanner"
+
+module Rigor
+  module Protection
+    # Issue #134 slice 2 — the per-file cache for an ADR-63 Tier 2 measurement.
+    #
+    # A whole-project `rigor coverage --protection --mutation` run is `Σ(1 + N_f)` single-file analyses (the
+    # investigation on #134: ≈94% of the wall time, and rising with the target set). Every one of them is
+    # recomputed on every invocation, including for files nobody has touched since the last run. This stores
+    # one {MutationScanner::FileResult} per file and serves it back when nothing it could depend on moved.
+    #
+    # ## What "nothing moved" means — the cache key
+    #
+    # The KEY carries the inputs that are known before the measurement and are not files:
+    #
+    # - `Rigor::VERSION` + this class's {SCHEMA} + the {Cache::Descriptor} schema — an engine upgrade is an ABI
+    #   boundary for a Marshal'd `FileResult` and a measurement-semantics boundary for everything else. A
+    #   VERSION pins the engine's bytes only for a RELEASED gem, so a checkout adds {Cache::EngineSource}'s
+    #   source digest alongside it (#285) — without it, editing the analyzer and re-measuring serves the
+    #   pre-edit kill counts back, which is the exact failure a mutation score exists to detect.
+    # - The {Cache::IncrementalSnapshot} fingerprint the dependency edges came from — itself a digest of the
+    #   resolved configuration, the analysis roots, `Gemfile.lock`, `rbs_collection.lock.yaml`, and the
+    #   project's own `sig/` contents. This is how a config or `sig/` edit invalidates the measurement. Since
+    #   #289 that fingerprint carries the engine-source digest too, which makes the slot above redundant on
+    #   paper — keep it anyway: this key states its own soundness rather than inheriting it from how another
+    #   cache happens to compose its key today, and a memoised digest costs nothing to repeat.
+    # - `--limit` / `--seed` / the site selector: the report is already an estimate under a sample, and without
+    #   them a `--limit 20` run would silently serve a `--limit 5` result.
+    # - The sorted set of ADOPTED bleeding-edge feature ids that change this measurement (#255's principle: a
+    #   behaviour feature's id enters the cache identity of everything it changes). `discovery-seeded-mutation-
+    #   sites` moves both the denominator and the kills; `dependent-closure-kill-oracle` moves the kills — and
+    #   that one additionally BYPASSES this cache entirely (see below).
+    # - The whole-project ProjectScan tables (`synthetic_method_index`, `project_patched_methods`) by CONTENT
+    #   DIGEST, plus the ADR-88 plugin fact-surface digest. Any file may contribute a row to those tables, so
+    #   they go in by table diff, never by edge attribution — the same shape and the same reason as ADR-67
+    #   WD6c's `param_seed_invalidation`.
+    # - When the discovery seed is active, the seed's identity (see {.seed_digest}).
+    #
+    # The per-file FILE dependencies ride the ADR-45 record-and-validate side instead: the entry stores a
+    # {Cache::Descriptor} of the measured file plus every `deps[A]` edge the ADR-46 snapshot recorded for it,
+    # and {Cache::Store#peek_validated} re-validates them against the filesystem on the next run. `deps[A]` was
+    # recorded during a full `check` run with cross-file discovery ON, while the Tier-2 oracle re-analyses the
+    # mutant with discovery OFF (or seeded — see the seed slot above), so the recorded set is a strict SUPERSET
+    # of what the oracle reads: over-invalidating, never under.
+    #
+    # ## Degradation — never a silent hit
+    #
+    # The cache disables itself, wholesale, when it cannot prove that much: no reusable snapshot (nobody has
+    # run `rigor check --incremental` for this project / these roots), a plugin with no incremental fingerprint
+    # surface (ADR-88's opaque case), tables it cannot digest, or `--no-cache`. Per file, a path the snapshot
+    # never analysed has no `deps[A]` entry, which means "depends on every project file" — a miss for that file
+    # alone. Every degradation is reported on stderr by the caller, because a measurement that quietly stopped
+    # caching and a measurement that quietly served a stale number look identical from the outside.
+    #
+    # `dependent-closure-kill-oracle` (#254) bypasses the cache rather than keying on it: under that oracle a
+    # file's verdict depends on the diagnostics of its DEPENDENTS, so validity would need the dependencies of
+    # every dependent — a strictly wider edge set than `deps[A]`. The feature is presumptively non-graduating
+    # (#254's closing comments), so a permanent bypass is the honest answer, not the key complexity.
+    class MutationCache
+      # Bumped when the stored value's shape or the key's composition changes, so entries written by an older
+      # Rigor read as misses rather than as a differently-meant number.
+      SCHEMA = 1
+
+      PRODUCER_ID = "protection.mutation-file-result"
+
+      # One live entry per (file, key) at once — the per-file producer shape, so the {Cache::Store#evict!}
+      # generation pass leaves it alone and only the size-based LRU pass can touch it.
+      GENERATION_CAP = Cache::Store::UNBOUNDED_GENERATIONS
+
+      # The sampling knobs that make one measurement incomparable with another (see the class doc).
+      Sampling = Data.define(:limit, :seed, :site_selector)
+
+      # Human-readable reasons the caller prints. Each names something the operator can act on.
+      NO_SNAPSHOT = "no reusable `rigor check --incremental` snapshot"
+      OPAQUE_PLUGIN = "a plugin contributes types with no incremental fingerprint surface"
+      UNDIGESTIBLE = "the project-scan tables could not be digested"
+      UNIDENTIFIED_ENGINE = "the engine's own source tree could not be digested"
+
+      class << self
+        # @param configuration [Rigor::Configuration]
+        # @param roots [Array<String>] the analysis roots to look for a snapshot under, most-specific first
+        #   (the command's own path arguments, then the configured `paths:`).
+        # @param project_scan [Rigor::Analysis::ProjectScan] the prepared whole-project scan.
+        # @param sampling [Sampling]
+        # @param feature_ids [Array<String>] the ADOPTED bleeding-edge ids that change this measurement.
+        # @param seed_inputs [Array<String>, nil] the files the {DiscoverySeed} was built over when it is
+        #   active, nil when it is not. The CLI stays the only place that knows a feature id exists.
+        # @param bypass_reason [String, nil] a caller-side reason to run uncached (`--no-cache`, the closure
+        #   oracle). Reported verbatim.
+        # @return [MutationCache] enabled, or a disabled instance carrying `#reason`.
+        def build(configuration:, roots:, project_scan:, sampling:, feature_ids:, seed_inputs: nil,
+                  bypass_reason: nil)
+          return disabled(bypass_reason) if bypass_reason
+          return disabled(UNIDENTIFIED_ENGINE) unless engine_identifiable?
+
+          matched = load_snapshot(configuration: configuration, roots: roots)
+          return disabled(NO_SNAPSHOT) if matched.nil?
+
+          fingerprint, payload = matched
+          configs = key_configs(fingerprint: fingerprint, project_scan: project_scan, sampling: sampling,
+                                feature_ids: feature_ids, seed_inputs: seed_inputs)
+          return disabled(configs) if configs.is_a?(String)
+
+          new(store: build_store(configuration), sources: payload.sources, key_configs: configs)
+        end
+
+        def disabled(reason)
+          new(store: nil, sources: {}, key_configs: [], reason: reason)
+        end
+
+        def build_store(configuration)
+          Cache::Store.new(root: configuration.cache_path, max_bytes: configuration.cache_max_bytes)
+        end
+
+        # The `[fingerprint, payload]` of the on-disk ADR-46 snapshot under any plausible root set, or nil.
+        #
+        # A snapshot is keyed to the ROOTS its writing run was invoked with, and a measurement has no way to
+        # know which form that was: `rigor check --incremental lib` records `["lib"]`, a bare `rigor check
+        # --incremental` records the configured `paths:` (absolute), and a measurement of a SUBDIRECTORY
+        # shares neither. All four renderings are offered, one blob read (see {IncrementalSnapshot#load_any}).
+        #
+        # Accepting a snapshot whose roots differ from the measured paths is sound rather than lax: the
+        # snapshot contributes per-file dependency edges only, and a file it never analysed simply has no
+        # entry — which this cache already treats as a miss for that file.
+        def load_snapshot(configuration:, roots:)
+          candidates = snapshot_root_candidates(roots, configuration.paths).map do |candidate|
+            Cache::IncrementalSnapshot.fingerprint(configuration: configuration, roots: candidate)
+          end
+          Cache::IncrementalSnapshot.new(root: configuration.cache_path).load_any(fingerprints: candidates)
+        end
+
+        def snapshot_root_candidates(roots, configured)
+          [roots, Array(roots).map { |path| File.expand_path(path) },
+           configured, Array(configured).map { |path| relative_to_pwd(path) }]
+            .compact.reject(&:empty?).uniq
+        end
+
+        # `path` rendered relative to the working directory when it lies underneath it; unchanged otherwise.
+        # Shared by the root-candidate list and the per-file snapshot lookup, which face the same skew.
+        def relative_to_pwd(path)
+          absolute = File.expand_path(path)
+          prefix = "#{File.expand_path(Dir.pwd)}#{File::SEPARATOR}"
+          absolute.start_with?(prefix) ? absolute.delete_prefix(prefix) : path.to_s
+        end
+
+        # The shared (path-independent) key slots, or a String reason when an input cannot be digested.
+        def key_configs(fingerprint:, project_scan:, sampling:, feature_ids:, seed_inputs:)
+          facts = Analysis::PluginFactFingerprint.key_digest(project_scan.plugin_registry)
+          return OPAQUE_PLUGIN if facts.nil?
+
+          tables = table_digest(project_scan)
+          return UNDIGESTIBLE if tables.nil?
+
+          (engine_source_entries + [
+            config_entry("engine", "#{Rigor::VERSION}:#{SCHEMA}:#{Cache::Descriptor::SCHEMA_VERSION}"),
+            config_entry("snapshot", fingerprint),
+            config_entry("sampling", sampling.to_h.sort.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")),
+            config_entry("bleeding-edge", feature_ids.map(&:to_s).sort.join(",")),
+            config_entry("project-tables", tables),
+            config_entry("plugin-facts", facts),
+            config_entry("discovery-seed", seed_digest(seed_inputs))
+          ]).freeze
+        rescue Cache::EngineSource::Unavailable
+          UNIDENTIFIED_ENGINE
+        rescue StandardError
+          UNDIGESTIBLE
+        end
+
+        # Issue #285 — one extra slot pinning the ENGINE'S OWN SOURCE when `Rigor::VERSION` does not (a
+        # checkout rather than a released gem). Empty for a released install, so its key composition is
+        # unchanged and {SCHEMA} needs no bump; an engine that cannot be identified raises through to the
+        # `Unavailable` rescue above and disables the cache, which is the only sound reading of a key slot
+        # that could not be computed.
+        def engine_source_entries
+          identity = Cache::EngineSource.process_identity
+          identity.nil? ? [] : [config_entry("engine-source", identity)]
+        end
+
+        # Probed BEFORE the snapshot load, for the reason string rather than for soundness. Since #289
+        # {Cache::IncrementalSnapshot.fingerprint} folds the same digest in and answers a bare nil when it
+        # cannot, so an unidentifiable engine already reaches the user as a disabled cache — but as
+        # {NO_SNAPSHOT}, which tells them to run `rigor check --incremental`, a fix for a different problem.
+        # The {Cache::EngineSource::Unavailable} rescue in {key_configs} stays as the backstop for a tree
+        # that becomes unreadable between here and there.
+        def engine_identifiable?
+          Cache::EngineSource.process_identity
+          true
+        rescue Cache::EngineSource::Unavailable
+          false
+        end
+
+        def config_entry(key, payload)
+          Cache::Descriptor::ConfigEntry.new(key: key, value_hash: Digest::SHA256.hexdigest(payload))
+        end
+
+        # A stable content digest of the two whole-project pre-pass tables, over their own plain-data
+        # renderings. `nil` when either declines to render (→ the cache disables itself rather than key on a
+        # table it cannot see).
+        def table_digest(project_scan)
+          payload = {
+            "synthetic" => project_scan.synthetic_method_index.to_h,
+            "patched" => patched_rows(project_scan.project_patched_methods)
+          }
+          Digest::SHA256.hexdigest(JSON.generate(payload))
+        rescue StandardError
+          nil
+        end
+
+        # `ProjectPatchedMethods` has no plain-data rendering of its own; each row is flattened here, with the
+        # recorded return type reduced to its short description (the value is a live `Rigor::Type`).
+        def patched_rows(patched)
+          patched.by_key.map do |(class_name, method_name, kind), entry|
+            [class_name.to_s, method_name.to_s, kind.to_s, entry.source_path.to_s, entry.source_line,
+             entry.return_type&.describe(:short).to_s]
+          end.sort
+        end
+
+        # The identity of the cross-file {DiscoverySeed}, as the digest of its INPUTS: the sorted
+        # `(path, content digest)` rows of the files it spans. The seed is a deterministic function of those
+        # contents and of inputs already in the key (the resolved configuration and the plugin fact surface,
+        # which fix the environment the parameter-inference pre-pass runs under), so hashing the inputs is at
+        # least as strong an invalidation signal as hashing the built tables would be — and it never has to
+        # traverse `discovered_def_nodes`, whose values are live `Prism::Node`s with no stable identity.
+        #
+        # Because the seed spans the whole measured path set, ANY measured file's edit invalidates EVERY
+        # file's entry while the feature is adopted. That is the correct reading of "the seed is an input to
+        # every file's measurement", not a defect of this digest.
+        def seed_digest(seed_inputs)
+          return "off" if seed_inputs.nil?
+
+          digest = Digest::SHA256.new
+          seed_inputs.sort.each { |path| digest << path << "\0" << Cache::FileDigest.hexdigest(path) << "\0" }
+          digest.hexdigest
+        end
+      end
+
+      def initialize(store:, sources:, key_configs:, reason: nil)
+        @store = store
+        @sources = sources
+        @key_configs = key_configs
+        @reason = reason
+        @hits = 0
+        @misses = 0
+        @snapshot_keys = {}
+      end
+
+      attr_reader :reason, :hits, :misses
+
+      def enabled?
+        @reason.nil?
+      end
+
+      # The cached result for `path`, or nil on any miss (including "this cache is disabled").
+      # @return [MutationScanner::FileResult, nil]
+      def fetch(path)
+        return nil unless enabled?
+        # A path the snapshot never analysed has no recorded `deps[A]`, which means "depends on every project
+        # file". Answering that from the key alone keeps the read path free of the digesting the WRITE path
+        # does — the stored entry's own dependency descriptor is what a hit is validated against.
+        return miss if snapshot_key(path).nil?
+
+        value = @store.peek_validated(producer_id: PRODUCER_ID, key_descriptor: key_descriptor,
+                                      params: params_for(path))
+        return miss unless value.is_a?(MutationScanner::FileResult)
+
+        @hits += 1
+        value
+      rescue StandardError
+        miss
+      end
+
+      # Persist one measured file. Returns false when nothing was written.
+      #
+      # A result carrying `harness_errors` (#264 — mutants that blew up INSIDE the measurement harness) is
+      # never persisted: that run measured the harness rather than the code, and freezing it into a warm hit
+      # would make a transient failure permanent and invisible.
+      def store(path, result)
+        return false unless enabled?
+        return false unless result.is_a?(MutationScanner::FileResult)
+        return false if result.harness_errors.positive?
+
+        dependency = dependencies(path)
+        return false if dependency.nil?
+
+        @store.fetch_or_validate(producer_id: PRODUCER_ID, key_descriptor: key_descriptor,
+                                 params: params_for(path), generation_cap: GENERATION_CAP) do
+          [result, dependency]
+        end
+        true
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def miss
+        @misses += 1
+        nil
+      end
+
+      # The record-and-validate dependency descriptor for `path`: the file itself plus every `deps[path]` edge
+      # the snapshot recorded. nil when the snapshot never analysed the file (→ "depends on every project
+      # file", the degradation this cache refuses to guess at) or a recorded file has since vanished.
+      def dependencies(path)
+        key = snapshot_key(path)
+        sources = key && @sources[key]
+        return nil if sources.nil?
+
+        entries = ([key] + sources.to_a).uniq.map do |dependency|
+          Cache::Descriptor::FileEntry.stat(path: dependency, digest: Cache::FileDigest.hexdigest(dependency))
+        end
+        Cache::Descriptor.new(files: entries)
+      rescue StandardError
+        nil
+      end
+
+      # The snapshot records project-relative paths; a measurement may have been invoked with an absolute one.
+      def snapshot_key(path)
+        @snapshot_keys.fetch(path) do
+          @snapshot_keys[path] =
+            if @sources.key?(path)
+              path
+            else
+              relative = relative_to_pwd(path)
+              @sources.key?(relative) ? relative : nil
+            end
+        end
+      end
+
+      def relative_to_pwd(path)
+        self.class.relative_to_pwd(path)
+      end
+
+      def key_descriptor
+        @key_descriptor ||= Cache::Descriptor.new(configs: @key_configs)
+      end
+
+      def params_for(path)
+        { "path" => snapshot_key(path) || path }
+      end
+    end
+  end
+end

data/lib/rigor/protection/mutation_scanner.rb

@@ -25,8 +25,17 @@ module Rigor
       # A surviving mutation site — a breakage Rigor did not catch.
       SurvivingSite = Data.define(:line, :receiver, :method_name, :operator)
 
-      FileResult = Data.define(:path, :killed, :survived, :sites) do
-        # Mutations actually analysed (parse-invalid mutants are not counted).
+      # `harness_errors` (#264) — mutants where the harness itself failed (an exception `classify` rescued),
+      # counted separately from a parse-invalid mutant. Defaults to 0 so every existing caller that builds a
+      # `FileResult` without the new keyword — including the early-return-on-empty path below and the fork-scan
+      # `ParseError` branch — keeps constructing one exactly as before.
+      FileResult = Data.define(:path, :killed, :survived, :sites, :harness_errors) do
+        def initialize(path:, killed:, survived:, sites:, harness_errors: 0)
+          super
+        end
+
+        # Mutations actually analysed (parse-invalid mutants are not counted; neither are harness_errors — a
+        # harness-level failure measures the harness, not the code, exactly like a parse-invalid mutant).
         def total = killed + survived
 
         # Effectiveness ratio; a file with no type-relevant mutation is vacuously fully effective (no breakage
@@ -42,7 +51,13 @@ module Rigor
       # "doubly-protected" bucket into `type_killed`: a mutant the type checker already kills never reaches the
       # suite, because the static net already suffices and re-running the suite to learn a test *would also*
       # catch it is wasted work. So the observed buckets are three.
-      FusedFileResult = Data.define(:path, :type_killed, :test_killed, :sites) do
+      # `harness_errors` (#264) — same bucket as {FileResult}, kept out of `total`/`ratio` exactly like a
+      # parse-invalid mutant. Defaults to 0 for the same backward-compatibility reason.
+      FusedFileResult = Data.define(:path, :type_killed, :test_killed, :sites, :harness_errors) do
+        def initialize(path:, type_killed:, test_killed:, sites:, harness_errors: 0)
+          super
+        end
+
         # The unprotected sites (neither a type nor a test caught the breakage).
         def unprotected = sites.size
         def total = type_killed + test_killed + unprotected
@@ -63,14 +78,31 @@ module Rigor
       #   Seam 2). `:biteable` (default) keeps only concrete-type sites Rigor can
       #   bite; `:all` also mutates Dynamic-receiver dispatch sites — use only
       #   with a {TestSuiteOracle} (the fused overlay), never the diagnostic path.
+      # @param base_scope [Rigor::Scope, nil] the scope site selection judges
+      #   anchor types against, built once by the caller (see
+      #   {Mutator#anchor_base_scope}). `nil` — the default — keeps the bare
+      #   single-file empty scope. A caller that seeds cross-file discovery
+      #   passes it here; this class stays free of {Rigor::Configuration} and of
+      #   bleeding-edge feature ids, which live one layer up in the CLI.
+      # @param discovery_seed [Hash, nil] issue #260 — the SAME cross-file table
+      #   set `base_scope` was built from, threaded to the default
+      #   {DiagnosticOracle} so an admitted cross-file site is one the oracle can
+      #   also kill at. Pass both or neither: a `base_scope` without it measures
+      #   sites no mutation can ever break. Ignored when `oracle` is supplied
+      #   (that caller owns its oracle's knowledge).
+      # rubocop:disable Metrics/ParameterLists -- every one is an independently-defaulted collaborator or knob;
+      # bundling them into an options object would only move the list behind a name.
       def initialize(configuration:, environment:, project_scan:, limit: nil, seed: 1, oracle: nil,
-                     site_selector: :biteable)
+                     site_selector: :biteable, base_scope: nil, discovery_seed: nil)
+        # rubocop:enable Metrics/ParameterLists
         @environment = environment
         @limit = limit
         @seed = seed
         @site_selector = site_selector
+        @base_scope = base_scope
         @oracle = oracle || DiagnosticOracle.new(
-          configuration: configuration, environment: environment, project_scan: project_scan
+          configuration: configuration, environment: environment, project_scan: project_scan,
+          discovery_seed: discovery_seed
         )
       end
 
@@ -84,15 +116,17 @@ module Rigor
 
         baseline = @oracle.baseline(source: source, path: path)
         killed = 0
+        harness_errors = 0
         sites = []
         kept.each do |mut|
           case classify(source, path, mut, baseline)
           when :killed then killed += 1
           when :survived then sites << surviving_site(mut)
+          when :harness_error then harness_errors += 1
             # :invalid — a parse-broken mutant; not a measurement, skip it.
           end
         end
-        FileResult.new(path: path, killed: killed, survived: sites.size, sites: sites)
+        FileResult.new(path: path, killed: killed, survived: sites.size, sites: sites, harness_errors: harness_errors)
       end
 
       # ADR-70 — the fused static∪dynamic measurement. Runs the type pass (the {DiagnosticOracle}); for every
@@ -109,6 +143,7 @@ module Rigor
         baseline = @oracle.baseline(source: source, path: path)
         type_killed = 0
         test_killed = 0
+        harness_errors = 0
         sites = []
         kept.each do |mut|
           case classify(source, path, mut, baseline)
@@ -119,10 +154,12 @@ module Rigor
             else
               sites << fused_site(mut, :none)
             end
+          when :harness_error then harness_errors += 1
             # :invalid — a parse-broken mutant; not a measurement, skip it.
           end
         end
-        FusedFileResult.new(path: path, type_killed: type_killed, test_killed: test_killed, sites: sites)
+        FusedFileResult.new(path: path, type_killed: type_killed, test_killed: test_killed, sites: sites,
+                            harness_errors: harness_errors)
       end
 
       private
@@ -135,21 +172,28 @@ module Rigor
         muts = mutator.mutations
         kept =
           if @site_selector == :all
-            mutator.dispatch_site_mutations(muts, environment: @environment, path: path)
+            mutator.dispatch_site_mutations(muts, environment: @environment, path: path, base_scope: @base_scope)
           else
-            mutator.filter_by_type(muts, environment: @environment, path: path).first
+            mutator.filter_by_type(muts, environment: @environment, path: path, base_scope: @base_scope).first
           end
         sample(kept)
       end
 
+      # #264 — a parse-invalid mutant (`:invalid`, the mutation itself does not produce parseable Ruby) and a
+      # harness-level failure (`:harness_error`, an exception raised *while measuring* an otherwise-parseable
+      # mutant — e.g. the oracle's re-analysis blowing up) are different failure modes and MUST be told apart:
+      # only the latter is a harness defect worth counting and surfacing. Both stay OUT of `killed + survived`
+      # exactly as before (containment is unchanged) — #264 is about visibility, not about admitting either
+      # bucket into the denominator.
       def classify(source, path, mut, baseline)
         mutant_source = mut.apply(source)
         return :invalid unless Prism.parse(mutant_source).success?
 
         @oracle.killed?(mutant_source: mutant_source, path: path, baseline: baseline) ? :killed : :survived
       rescue StandardError
-        # A harness-level failure on one mutant must not abort the file.
-        :invalid
+        # A harness-level failure on one mutant must not abort the file — but it must not vanish either
+        # (#264): the caller counts this bucket separately and the CLI surfaces it.
+        :harness_error
       end
 
       def sample(mutations)

data/lib/rigor/protection/mutator.rb

@@ -75,8 +75,11 @@ module Rigor
       # unresolved/probe-failed type KEEPS the mutation, so the filter never hides a kill it is unsure about — it
       # only removes provably-Dynamic sites. Returns [kept, dropped_count]. Builds the scope index from THIS
       # mutator's parse so anchor node identity matches the keys.
-      def filter_by_type(mutations, environment:, path:)
-        base = Rigor::Scope.empty(environment: environment, source_path: path)
+      #
+      # @param base_scope [Rigor::Scope, nil] a pre-seeded scope to judge anchors against (see
+      #   {#anchor_base_scope}); nil builds the bare empty scope, which is the shipped default.
+      def filter_by_type(mutations, environment:, path:, base_scope: nil)
+        base = anchor_base_scope(environment, path, base_scope)
         index = Rigor::Inference::ScopeIndexer.index(@parse.value, default_scope: base)
         cache = {}
         kept = mutations.select do |mut|
@@ -93,8 +96,8 @@ module Rigor
       # {#filter_by_type} hides exactly the Dynamic sites a test-suite consumer most wants to probe: where Rigor
       # cannot bite, a test is the only protection. Use only with a {TestSuiteOracle} — at a Dynamic site the
       # type pass can never kill, so without the test axis these are all noise.
-      def dispatch_site_mutations(mutations, environment:, path:)
-        base = Rigor::Scope.empty(environment: environment, source_path: path)
+      def dispatch_site_mutations(mutations, environment:, path:, base_scope: nil)
+        base = anchor_base_scope(environment, path, base_scope)
         index = Rigor::Inference::ScopeIndexer.index(@parse.value, default_scope: base)
         cache = {}
         mutations.select do |mut|
@@ -108,6 +111,25 @@ module Rigor
 
       private
 
+      # The scope the anchor types are judged against.
+      #
+      # `base_scope` is nil on the shipped path, and the result is then the bare empty scope this file has always
+      # used: a single-file view in which a constant receiver declared in a *sibling* file reads `Dynamic`, so its
+      # dispatch site is dropped from the Tier-2 denominator. The caller may instead hand down a scope already
+      # carrying the cross-file discovery Tier 1 seeds (`discovered_classes` + `param_inferred_types`), in which
+      # case the same site resolves to the type it really has and is measured — `coverage --protection --mutation`
+      # does that behind the `discovery-seeded-mutation-sites` bleeding-edge feature (#253).
+      #
+      # Deliberately a plain parameter: this class knows nothing about {Rigor::Configuration} or feature ids. The
+      # gate lives in the CLI layer, which is the only layer that has a Configuration to ask.
+      #
+      # `source_path` is per-file, so a shared base scope is re-stamped here rather than rebuilt per path.
+      def anchor_base_scope(environment, path, base_scope)
+        return Rigor::Scope.empty(environment: environment, source_path: path) if base_scope.nil?
+
+        base_scope.with_source_path(path)
+      end
+
       def walk(node, &blk)
         return if node.nil?
 

data/lib/rigor/runtime/jit.rb

@@ -28,7 +28,14 @@ module Rigor
     # Opt-out: `RIGOR_DISABLE_YJIT=1` makes every entry point a no-op (the pin
     # the byte-identical-diagnostics gate uses). If YJIT is already enabled (the
     # user passed `--yjit` / `RUBY_YJIT_ENABLE=1`) or is unavailable (a build
-    # without YJIT, or a non-MRI Ruby), both entry points are no-ops too.
+    # without YJIT, or a non-MRI Ruby), every entry point is a no-op too.
+    #
+    # `fork` copies only the calling thread, so the {enable_after} sleeper dies
+    # in every child of a fork pool — a worker would run its whole slice
+    # interpreted while the parent JITs work it no longer does. {rearm_after_fork}
+    # is the child-side entry point that repairs this, and it carries the
+    # *remaining* deadline rather than restarting the window; see its own
+    # comment for why that distinction is worth the bookkeeping.
     module Jit
       # Opt-out switch: `RIGOR_DISABLE_YJIT=1` disables both entry points.
       DISABLE_ENV = "RIGOR_DISABLE_YJIT"
@@ -90,6 +97,18 @@ module Rigor
         return nil if disabled?
         return nil if RubyVM::YJIT.enabled?
 
+        # Record when the window actually closes, so a child forked partway
+        # through it can re-arm with what is LEFT ({rearm_after_fork}) instead
+        # of restarting the wait. Monotonic, so a wall-clock adjustment mid-run
+        # cannot move the deadline; and monotonic time survives `fork`, so the
+        # value stays comparable in a child.
+        #
+        # Thread-safety: this is written on the arming thread before any `fork`
+        # and read only in children *after* the fork, each of which sees a
+        # private copy of the parent's memory. No reader and writer ever share a
+        # process, so the plain attribute needs no lock.
+        @deadline_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+
         thread = Thread.new do
           sleep(seconds)
           enable_now
@@ -102,6 +121,49 @@ module Rigor
         thread
       end
 
+      # Re-arms the deferred-YJIT deadline inside a freshly forked child,
+      # carrying the *remaining* window rather than restarting it.
+      #
+      # `fork` copies only the calling thread, so the parent's {enable_after}
+      # sleeper never fires in a child: without re-arming, a worker runs its
+      # entire slice interpreted however long that takes, and a fork pool can be
+      # slower than sequential (measured: `coverage --protection --mutation
+      # lib/rigor/analysis` at 37s sequential against 67s at eight workers).
+      # Re-arming with a *fresh full* deadline fixes that but overshoots the
+      # other way — the parent has normally already burned part of the window
+      # before it forks, so every child sits out the whole window again. That is
+      # pure warm-up loss, and it is paid once per worker, so it grows with the
+      # worker count exactly where a pool is supposed to pay off.
+      #
+      # The remaining window is what the amortization contract actually says:
+      # the deadline exists to keep short *runs* off the JIT, and a child is a
+      # continuation of the parent's run, not a new one. When the deadline has
+      # already passed, the run has proven itself long — enable straight away.
+      #
+      # Re-arming goes through {enable_after}, so the child records the same
+      # absolute deadline it inherited and a grandchild fork carries it too.
+      #
+      # @return [Thread, nil] the child's deadline thread; nil when YJIT was
+      #   enabled immediately, and nil when the call is a no-op up front
+      #   (unavailable / opted out / already enabled — a child forked after the
+      #   parent enabled inherits the enabled state and has nothing to do).
+      def rearm_after_fork
+        return nil unless available?
+        return nil if disabled?
+        return nil if RubyVM::YJIT.enabled?
+
+        # No recorded deadline means nothing in this process ever armed one — a
+        # caller that forks without going through a CLI entry point, or a spec.
+        # Degrade to a fresh full window, never to no YJIT at all.
+        return enable_after(deadline_seconds) if @deadline_at.nil?
+
+        remaining = @deadline_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return enable_after(remaining) if remaining.positive?
+
+        enable_now
+        nil
+      end
+
       # The resolved {enable_after} deadline: {DEADLINE_ENV} when it parses to a
       # non-negative float, else {DEFAULT_DEADLINE_SECONDS}.
       #

data/lib/rigor/scope/discovery_index.rb

@@ -37,6 +37,15 @@ module Rigor
       EMPTY_TABLE = {}.freeze
       private_constant :EMPTY_NODE_TABLE, :EMPTY_TABLE
 
+      # The third value a `discovered_methods` entry can hold, beside `:instance` and `:singleton`. One name may
+      # legitimately be defined on both sides of the same class (`def helper` plus a `class << self` twin), and the
+      # table is keyed by name alone — so before this existed the second `def` overwrote the first's kind and
+      # `Scope#discovered_method?` answered false for a method that is right there in the source. That is a false
+      # `call.undefined-method` on ordinary Ruby (#239), which outranks any worst-case reading (AGENTS.md
+      # § "Implementation Guidelines"). Writers promote to this instead of clobbering; readers treat it as matching
+      # either kind.
+      METHOD_KIND_BOTH = :both
+
       # The shared all-empty index `Scope.empty` (and every scope that never sees a seeding pass) points at — one
       # allocation per process.
       EMPTY = new(