rigortype 0.3.1 → 0.3.2

data/lib/rigor/cli/check_command.rb

@@ -48,9 +48,6 @@ module Rigor
 
         configuration = load_check_configuration(options)
         configuration = apply_bleeding_edge_override(configuration, options)
-        conflict = parameter_inference_incremental_conflict(configuration, options)
-        return conflict unless conflict.nil?
-
         config_warnings = warn_unresolved_config(configuration)
         cache_root = configuration.cache_path
         handle_clear_cache(cache_root) if options.fetch(:clear_cache)
@@ -62,7 +59,7 @@ module Rigor
         return finalize_cache_hit(probed, configuration, options, config_warnings) unless probed.nil?
 
         load_check_dependencies
-        special = dispatch_special_check_mode(configuration, options, cache_root)
+        special = dispatch_special_check_mode(configuration, options, cache_root, buffer)
         return special unless special.nil?
 
         invocation = invoke_check(
@@ -143,30 +140,24 @@ module Rigor
         exit_code
       end
 
-      # ADR-67 WD6c — `parameter_inference:` and the ADR-46 incremental modes are mutually exclusive in slice 1.
-      # The parameter table introduces cross-file edges (a caller's argument types drive a callee's body
-      # diagnostics) that the per-file dependency recorder does not yet carry, so a cached file whose parameter
-      # seeds changed would serve a stale result. Refuse with a message naming the ADR-46 gap rather than
-      # silently producing unsound incremental diagnostics; the edge wiring is the named follow-up. Returns the
-      # usage exit code on a conflict, or nil to proceed. `--verify-incremental` (the acceptance gate that runs
-      # incremental analysis) is caught here too.
-      def parameter_inference_incremental_conflict(configuration, options)
-        return nil unless configuration.parameter_inference
-        return nil unless options.fetch(:incremental) || options.fetch(:verify_incremental)
-
-        flag = options.fetch(:incremental) ? "--incremental" : "--verify-incremental"
-        @err.puts("rigor: parameter_inference: cannot combine with #{flag} — the call-site parameter table " \
-                  "introduces cross-file caller→callee edges the ADR-46 incremental dependency graph does not " \
-                  "yet record, so a cached file could serve a stale diagnostic. Run a full check (drop " \
-                  "#{flag}), or disable parameter_inference: for this run.")
-        CLI::EXIT_USAGE
-      end
-
       # ADR-46 — the two incremental-analysis check modes both fully handle the run and return an exit code (so `run`
       # short-circuits); returns nil for an ordinary check.
-      def dispatch_special_check_mode(configuration, options, cache_root)
-        return run_verify_incremental(configuration, options, cache_root) if options.fetch(:verify_incremental)
-        return run_incremental_check(configuration, options, cache_root) if options.fetch(:incremental)
+      # A nil return means "not a special mode" — `run` continues with the ordinary check. Editor mode option B
+      # also returns nil when it declines (no reusable snapshot), so the run falls back to single-file scope.
+      def dispatch_special_check_mode(configuration, options, cache_root, buffer)
+        if options.fetch(:verify_incremental)
+          # The gate compares an incremental recheck against a full-run oracle, and a buffer makes the two
+          # disagree by construction (the oracle reads the file on disk). Refusing beats the silent wrong
+          # answer both incremental modes gave a buffer before #146.
+          if buffer
+            @err.puts("rigor: --verify-incremental cannot run against an editor buffer " \
+                      "(--tmp-file / --instead-of); it compares against a full analysis of the files on disk.")
+            return CLI::EXIT_USAGE
+          end
+
+          return run_verify_incremental(configuration, options, cache_root)
+        end
+        return run_incremental_check(configuration, options, cache_root, buffer) if options.fetch(:incremental)
 
         nil
       end
@@ -212,7 +203,7 @@ module Rigor
       # run (plus their dependents), serving the rest from the snapshot; on a miss runs a full baseline. Persists the
       # updated snapshot for the next invocation. Diagnostics are identical to a full run (the `--verify-incremental`
       # gate enforces this); the win is skipping per-file inference for unchanged files.
-      def run_incremental_check(configuration, options, cache_root)
+      def run_incremental_check(configuration, options, cache_root, buffer = nil)
         require_relative "check_runner_factory"
         paths = @argv.empty? ? nil : @argv
         fingerprint = Cache::IncrementalSnapshot.fingerprint(
@@ -226,9 +217,12 @@ module Rigor
           # ADR-46 — thread the same worker-count precedence the standard `check` path uses
           # (CLI `--workers` > `RIGOR_RACTOR_WORKERS` > `parallel.workers:` > 0) so the recheck's closure
           # re-analysis parallelises; the fork pool marshals dependency records back so the graph is sound.
-          workers: CheckRunnerFactory.resolve_workers(options, configuration)
+          workers: CheckRunnerFactory.resolve_workers(options, configuration),
+          buffer: buffer
         )
 
+        return run_editor_mode_option_b(session, snapshot, fingerprint, configuration, options) if buffer
+
         diagnostics, warm = session.run_incremental(snapshot: snapshot, fingerprint: fingerprint)
         # The banner's file count comes from the session's analyzed set (cold analyses all; a warm recheck's
         # `@analyzed` advances to the current file set), so a dedicated probe Runner + `Dir.glob` is no longer
@@ -244,6 +238,33 @@ module Rigor
         result.success? ? 0 : 1
       end
 
+      # Editor mode option B (#146) — `--incremental` plus an editor buffer. The whole project is in scope with
+      # the buffer substituted for one file: the buffer's logical path and its dependents re-analyse, every
+      # other file is served from the snapshot. Before this, the two flags together silently ignored the
+      # buffer and analysed the file on disk, which is a wrong answer rather than a missing feature.
+      #
+      # The session never saves — the buffer's bytes exist only in the editor — so there is no warm state to
+      # build up. That is why a snapshot it cannot reuse means falling back to option A (single-file scope,
+      # the pre-#146 behaviour) instead of running a baseline that would repeat on the next keystroke. The
+      # note tells the user how to get option B: warm the snapshot with a plain `rigor check --incremental`.
+      def run_editor_mode_option_b(session, snapshot, fingerprint, configuration, options)
+        result = session.run_buffer_recheck(snapshot: snapshot, fingerprint: fingerprint)
+        if result.nil?
+          @err.puts("rigor: --incremental has no reusable snapshot for this project; analysing the buffer " \
+                    "alone (run `rigor check --incremental` once to enable whole-project editor mode).")
+          return nil
+        end
+
+        @err.puts("rigor: --incremental editor mode — re-analysed #{result.affected.size} file(s), " \
+                  "#{result.reused.size} served from cache")
+        emit_incremental_fact_surface_notes(session)
+        filtered = apply_baseline_filter(
+          Analysis::Result.new(diagnostics: result.diagnostics, stats: nil), configuration, options
+        )
+        write_result(filtered, options.fetch(:format))
+        filtered.success? ? 0 : 1
+      end
+
       # ADR-88 WD1 — a one-line stderr note when the plugin fact surface (an ADR-9 fact, an ADR-60 producer
       # value, or an `incremental_state_fingerprint` hook) forced a full run: either it CHANGED since the
       # snapshot (a Sorbet sig edit, a schema change) or a contributing plugin declares NO fingerprint surface

data/lib/rigor/cli/coverage_command.rb

@@ -27,6 +27,7 @@ require_relative "fused_protection_report"
 require_relative "fused_protection_renderer"
 require_relative "coverage_mutation"
 require_relative "protection_fork_scan"
+require_relative "mutation_fork_scan"
 require_relative "check_runner_factory"
 require_relative "command"
 
@@ -90,7 +91,7 @@ module Rigor
       def parse_options
         options = { format: "text", threshold: nil, config: nil, protection: false, mutation: false,
                     with_tests: false, test_command: DEFAULT_TEST_COMMAND, include_dynamic: false,
-                    limit: nil, seed: 1, workers: nil }
+                    limit: nil, seed: 1, workers: nil, no_cache: false }
         OptionParser.new { |opts| define_options(opts, options) }.parse!(@argv)
         options
       end
@@ -103,7 +104,8 @@ module Rigor
           options[:protection] = true
         end
         define_mutation_options(opts, options)
-        opts.on("--workers=N", Integer, "With --protection: fork N workers over the scanned files " \
+        opts.on("--workers=N", Integer, "With --protection (with or without --mutation, but not --with-tests, " \
+                                        "which must stay sequential): fork N workers over the scanned files " \
                                         "(default: config parallel.workers / RIGOR_RACTOR_WORKERS / 0)") do |v|
           options[:workers] = v
         end
@@ -135,6 +137,12 @@ module Rigor
           options[:limit] = v
         end
         opts.on("--seed=N", Integer, "RNG seed for --limit sampling (default 1)") { |v| options[:seed] = v }
+        opts.on("--no-cache", "With --mutation: measure every file from scratch, neither reading nor writing " \
+                              "the per-file mutation-result cache (#134 slice 2). The cold arm of the " \
+                              "warm==cold gate; unrelated caches (RBS environment, plugin producers) are " \
+                              "untouched.") do
+          options[:no_cache] = true
+        end
       end
 
       def mutation_misuse_error
@@ -204,6 +212,11 @@ module Rigor
       #
       # Both span the scanned `paths` only (no whole-project pre-pass) — a site that gains neither is classified exactly
       # as before.
+      #
+      # Tier 2's analogue is {Protection::DiscoverySeed} (#253, #260): the same idea over a *fuller* table set,
+      # because Tier 2 must also let its kill oracle resolve the method on the receiver, not merely name its
+      # class. Tier 1 seeds unconditionally because it only reclassifies sites it already counted; Tier 2 adds
+      # sites to a denominator `--threshold` gates CI on, which is why only the latter is gated on a feature id.
       def scope_with_inferred_params(paths, configuration, environment, workers)
         base = Scope.empty(environment: environment)
         seed = {}

data/lib/rigor/cli/coverage_mutation.rb

@@ -3,6 +3,12 @@
 require "English"
 require "prism"
 
+require_relative "../cache/file_digest"
+require_relative "../protection/closure_kill_oracle"
+require_relative "../protection/dependency_closure"
+require_relative "../protection/discovery_seed"
+require_relative "../protection/mutation_cache"
+
 module Rigor
   class CLI
     # ADR-63 Tier 2 + ADR-70 — the mutation-effectiveness and fused static∪dynamic protection paths, factored out of
@@ -10,8 +16,118 @@ module Rigor
     # (using `@out` / `@err` / `@argv` / `collect_paths` / `determine_protection_exit` and the Protection +
     # LanguageServer collaborators the command requires).
     module CoverageMutation
+      # ADR-50 § WD2 — the bleeding-edge feature id gating the Tier-2 discovery seed (#253). Named here rather
+      # than inlined at the call site: {Configuration#bleeding_edge_active?} raises on an id absent from the
+      # registry, so the constant is the single place a rename has to reach.
+      DISCOVERY_SEEDED_MUTATION_SITES = "discovery-seeded-mutation-sites"
+
+      # ADR-50 § WD2 — the bleeding-edge feature id gating the Tier-2 dependent-closure kill oracle (#254).
+      # Same reason as above for naming it here rather than inlining the string.
+      DEPENDENT_CLOSURE_KILL_ORACLE = "dependent-closure-kill-oracle"
+
+      # #264 — the "loud" threshold for a rescued-harness-failure count. Below it, a rescued mutant reads as
+      # the occasional transient this issue's `harness_errors` bucket exists to make VISIBLE, not to eliminate
+      # (see {Protection::MutationScanner#classify}); at or above it, the pattern looks less like noise and
+      # more like a harness defect worth stopping to investigate before trusting the ratio. Deliberately NOT
+      # the `determine_protection_exit` gate: a `--threshold` build is pinned to the killed/survived ratio
+      # today, and turning a harness-side symptom into a new way for that same command to exit non-zero would
+      # silently change semantics CI already depends on. A loud stderr warning (plus the unconditional JSON
+      # field) is the visibility this issue asks for without redefining what "the build is red" means.
+      HARNESS_ERROR_WARN_FLOOR = 3
+
+      # Issue #134 slice 2 — the bleeding-edge ids whose adoption changes what a Tier-2 measurement REPORTS,
+      # and which therefore enter the identity of anything cached about it (#255: a behaviour feature's id is
+      # part of the cache identity of everything it changes). Both are named above; this is the ordered set the
+      # cache key reads, so a feature added to Tier 2 later has exactly one place to register.
+      MUTATION_BEHAVIOUR_FEATURES = [DISCOVERY_SEEDED_MUTATION_SITES, DEPENDENT_CLOSURE_KILL_ORACLE].freeze
+
       private
 
+      # @param report [MutationProtectionReport, FusedProtectionReport] — both expose `total_harness_errors`.
+      def warn_harness_errors(report)
+        count = report.total_harness_errors
+        return if count < HARNESS_ERROR_WARN_FLOOR
+
+        @err.puts(
+          "coverage: #{count} mutants failed inside the measurement harness (\"harness_errors\", " \
+          "at/above the #{HARNESS_ERROR_WARN_FLOOR}-mutant floor) — excluded from the ratio like a " \
+          "parse-invalid mutant, but this many suggests a harness defect rather than one-off noise. " \
+          "Investigate before trusting --threshold on this run."
+        )
+      end
+
+      # The cross-file knowledge Tier 2 measures with — the #253 gate, and the ONLY place in this feature that
+      # knows a feature id exists.
+      #
+      # Returns nil (today's behaviour: an unseeded per-file view on both halves of the measurement) unless the
+      # project has adopted `discovery-seeded-mutation-sites`. With it adopted, returns the table set
+      # {Protection::DiscoverySeed} builds over the scanned `paths` — class identity so a receiver whose class
+      # is declared in a *sibling* file resolves instead of reading `Dynamic`, the def / ancestry index so the
+      # method on it resolves too, and `param_inferred_types` (ADR-67 WD3) for an inferred-parameter receiver.
+      #
+      # One table set, two consumers, deliberately (issue #260): site selection admits a site and the kill
+      # oracle can act on it. Seeding only the first admitted sites no mutation could ever break.
+      #
+      # Why the feature is off by default: an unseeded Tier 2 drops those sites from the denominator entirely,
+      # so seeding ADDS sites and the effectiveness ratio moves on unchanged code — and `--threshold=RATIO`
+      # exits 1 below a ratio users pin in CI. Turning it on by default would turn their build red with no
+      # change on their side.
+      #
+      # Built ONCE here, on the parent, so {MutationForkScan}'s children copy-on-write inherit it inside the
+      # scanner. Nothing crosses the marshal boundary: only the per-file results are marshaled back, and
+      # neither a Scope nor a `Prism::Node` is among them.
+      def mutation_discovery_seed(paths, configuration, environment, workers)
+        return nil unless configuration.bleeding_edge_active?(DISCOVERY_SEEDED_MUTATION_SITES)
+
+        seed = Protection::DiscoverySeed.build(
+          paths: paths, environment: environment, target_ruby: configuration.target_ruby, workers: workers
+        )
+        seed.empty? ? nil : seed
+      end
+
+      # The kill oracle Tier 2 measures with — the #254 gate, and the only place that feature id is read.
+      #
+      # Returns nil (today's behaviour: {Protection::DiagnosticOracle}, which re-analyses the mutated file
+      # alone) unless the project has adopted `dependent-closure-kill-oracle`. With it adopted, returns the
+      # {Protection::ClosureKillOracle}, which counts a kill when a new diagnostic appears anywhere in the
+      # mutated file's dependent closure — so a mutation whose damage lands in a CALLER is scored as the
+      # catch it is.
+      #
+      # Why the feature is off by default: it moves the reported effectiveness ratio UP on unchanged code
+      # (kills rise, the denominator does not), so a number recorded under it is not comparable with one
+      # recorded without it — the ADR-50 WD2/WD7 reason for the overlay, even though the direction cannot
+      # turn a `--threshold` build red.
+      #
+      # Both of its inputs are built HERE, once, on the parent — the ADR-46 dependents map (one recording
+      # pass) and the per-file discovery bundles — so {MutationForkScan}'s children copy-on-write inherit
+      # them and no per-mutant work is repeated per worker. `seed` composes the two features: it is handed
+      # to the closure oracle's delegated {Protection::DiagnosticOracle} verbatim, so the mutated file's
+      # verdict stays exactly the verdict the other feature's state produces, and this feature only ever
+      # ADDS the kills that land in a dependent.
+      def mutation_kill_oracle(paths, configuration, context, seed, workers)
+        return nil unless configuration.bleeding_edge_active?(DEPENDENT_CLOSURE_KILL_ORACLE)
+
+        Protection::ClosureKillOracle.new(
+          configuration: configuration, environment: context.environment, project_scan: context.project_scan,
+          paths: paths,
+          dependents: Protection::DependencyClosure.build(
+            paths: paths, configuration: configuration, environment: context.environment,
+            cache_store: context.cache_store, workers: workers
+          ),
+          seed_bundles: Protection::DiscoverySeed.bundles(paths: paths),
+          discovery_seed: seed
+        )
+      end
+
+      # The scope {Protection::Mutator} judges a mutation site's receiver against, derived from the same seed
+      # the oracle gets. nil (the gate off, or an empty seed) keeps the bare `Scope.empty` per file.
+      def mutation_base_scope(seed, environment)
+        return nil if seed.nil?
+
+        base = Scope.empty(environment: environment)
+        base.with_discovery(base.discovery.with(**seed))
+      end
+
       # ADR-63 Tier 2 — the mutation-effectiveness deep dive. Builds the RBS environment + project pre-pass once (the
       # warm loop), then re-analyses each target file's mutants against its clean baseline. Defaults to the git-changed
       # `.rb` files; explicit paths override (and enable the whole-project opt-in, which is minutes).
@@ -26,9 +142,12 @@ module Rigor
         end
 
         note_sampling(options)
+        # `--with-tests` deliberately does NOT take the fork path below: {Protection::TestSuiteOracle} shells
+        # out to the project's test runner, and concurrent suite invocations would race over one working tree.
         return run_fused_protection(target_files, options) if options[:with_tests]
 
         report = scan_mutation_protection(target_files, options)
+        warn_harness_errors(report)
         MutationProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
         determine_protection_exit(report, options)
       end
@@ -49,22 +168,47 @@ module Rigor
       # mutant survived" is meaningless — abort with a clear message if not.
       def run_fused_protection(paths, options)
         configuration = Configuration.load(options.fetch(:config))
+        warn_workers_ignored_under_tests(options)
         test_oracle = Protection::TestSuiteOracle.new(command: options.fetch(:test_command))
         return suite_not_green_error(options) unless test_oracle.green?
 
         context = LanguageServer::ProjectContext.new(configuration: configuration)
+        # The fused path stays sequential end to end (`--workers` is warned about above), so the seed's own
+        # parameter-inference pre-pass runs sequentially too rather than quietly re-enabling the forking the
+        # warning just said was ignored. It is otherwise the same seed, threaded to the same two consumers, so
+        # `--with-tests` measures the same site set as the plain path.
+        seed = mutation_discovery_seed(paths, configuration, context.environment, 0)
         scanner = Protection::MutationScanner.new(
           configuration: configuration, environment: context.environment, project_scan: context.project_scan,
           limit: options[:limit], seed: options[:seed],
-          site_selector: options[:include_dynamic] ? :all : :biteable
+          site_selector: options[:include_dynamic] ? :all : :biteable,
+          base_scope: mutation_base_scope(seed, context.environment), discovery_seed: seed,
+          # #254 — the type half of the fused measurement is the same measurement, so the closure oracle
+          # applies here too when adopted: a `--with-tests` run must not disagree with the plain run about
+          # which mutants the TYPE axis caught, or the "add a type OR a test" verdict would depend on which
+          # command you ran. Sequential like the rest of this path (`--workers` is warned about above).
+          oracle: mutation_kill_oracle(paths, configuration, context, seed, 0)
         )
         accumulator = FusedProtectionAccumulator.new
         paths.each { |path| scan_fused_one(path, scanner, accumulator, test_oracle, configuration) }
         report = accumulator.to_report
+        warn_harness_errors(report)
         FusedProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
         determine_protection_exit(report, options)
       end
 
+      # An explicit `--workers=N` on the fused path cannot be honoured, so say so rather than repeat the bug
+      # this slice fixed (a flag accepted and silently dropped). Only the explicit flag warns — a project-wide
+      # `parallel.workers:` or `RIGOR_RACTOR_WORKERS` default is not a request about *this* run.
+      def warn_workers_ignored_under_tests(options)
+        return unless options[:workers].to_i > 1
+
+        @err.puts(
+          "coverage: --workers is ignored with --with-tests — the test-suite oracle shells out to " \
+          "#{options.fetch(:test_command).join(' ')}, and parallel runs would race."
+        )
+      end
+
       def scan_fused_one(path, scanner, accumulator, test_oracle, configuration)
         source = File.read(path)
         parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
@@ -89,28 +233,115 @@ module Rigor
         1
       end
 
+      # Builds the RBS environment + whole-project pre-pass ONCE (≈6% of a 45-file run), then fork-maps the
+      # per-file measurement — the ≈94% that is `Σ(1 + N_f)` single-file analyses — across the resolved worker
+      # count (#134 slice 1). {MutationForkScan} returns `{path => result}` and the parent absorbs in `paths`
+      # order, so the report is byte-identical to a sequential run whatever order the workers finished in.
+      #
+      # #134 slice 2 — the files whose measurement is still valid are served from {Protection::MutationCache}
+      # and never reach a worker at all; only the rest are forked over, and their fresh results are written
+      # back. The cache read + write both happen on the parent, so the workers stay the pure-read, store-free
+      # processes {MutationForkScan} documents.
       def scan_mutation_protection(paths, options)
         configuration = Configuration.load(options.fetch(:config))
         context = LanguageServer::ProjectContext.new(configuration: configuration)
+        workers = CheckRunnerFactory.resolve_workers(options, configuration)
+        seed = mutation_discovery_seed(paths, configuration, context.environment, workers)
         scanner = Protection::MutationScanner.new(
           configuration: configuration, environment: context.environment, project_scan: context.project_scan,
-          limit: options[:limit], seed: options[:seed]
+          limit: options[:limit], seed: options[:seed],
+          base_scope: mutation_base_scope(seed, context.environment), discovery_seed: seed,
+          oracle: mutation_kill_oracle(paths, configuration, context, seed, workers)
         )
-        accumulator = MutationProtectionAccumulator.new
+        cache = mutation_result_cache(paths, options, configuration, context, seed)
+        measure_mutation_files(paths, cache: cache, scanner: scanner, context: context,
+                                      configuration: configuration, workers: workers)
+      end
+
+      # The cached / freshly-measured split, absorbed in `paths` order so the report is byte-identical however
+      # the two sets were assembled.
+      #
+      # The two cache phases each get their OWN {Cache::FileDigest.with_run} scope and the MEASUREMENT sits
+      # between them, deliberately: that scope installs a per-path digest memo, and {Protection::ClosureKillOracle}
+      # rewrites one process-private temp file per mutant and digests it through a buffer binding. A memo
+      # spanning the measurement would hand every mutant after the first the FIRST one's digest, the mutated
+      # file's discovery bundle would never be re-walked, and the run would report zero cross-file kills — a
+      # plausible-looking number rather than an error. The oracle's own comment states the same invariant from
+      # the other side. The cost of two scopes is one extra SHA-256 per cached file, against a measurement
+      # that is hundreds of analyses.
+      def measure_mutation_files(paths, cache:, scanner:, context:, configuration:, workers:)
+        cached = with_digest_run(configuration) { paths.to_h { |path| [path, cache.fetch(path)] }.compact }
+        pending = paths - cached.keys
+        fresh = if pending.empty?
+                  {}
+                else
+                  MutationForkScan.run(paths: pending, scanner: scanner, environment: context.environment,
+                                       configuration: configuration, workers: workers)
+                end
+        # `fetch`, never `[]`: a worker that died mid-slice must abort the run rather than quietly drop files
+        # out of a ratio that `--threshold` gates CI on.
+        with_digest_run(configuration) { pending.each { |path| cache.store(path, fresh.fetch(path)) } }
+        report_mutation_cache(cache, measured: pending.size, served: cached.size)
+        absorb_measured_files(paths, cached, fresh)
+      end
 
-        paths.each { |path| scan_mutation_one(path, scanner, accumulator, configuration) }
+      def absorb_measured_files(paths, cached, fresh)
+        accumulator = MutationProtectionAccumulator.new
+        paths.each do |path|
+          absorb_mutation_result(accumulator, path, cached.fetch(path) { fresh.fetch(path) })
+        end
         accumulator.to_report
       end
 
-      def scan_mutation_one(path, scanner, accumulator, configuration)
-        source = File.read(path)
-        parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
-        if parse_result.errors.any?
-          accumulator.record_parse_error(path, parse_result.errors)
-          return
+      # ADR-87 WD1's per-run digest scope, so the cache's own freshness checks honour `cache.validation:`
+      # (and `RIGOR_STRICT_VALIDATION`) exactly as every other record-and-validate cache does.
+      def with_digest_run(configuration, &)
+        Cache::FileDigest.with_run(strict: configuration.cache_validation_strict?, &)
+      end
+
+      # The per-file result cache (#134 slice 2), or a disabled one. Two callers-side bypasses are decided
+      # here rather than inside the cache: `--no-cache`, and the `dependent-closure-kill-oracle` overlay —
+      # under that oracle a file's verdict depends on its DEPENDENTS' diagnostics, so validity would need the
+      # dependencies of every dependent rather than `deps[A]`, and the feature is presumptively non-graduating
+      # (#254). A bypass is sound and honest; a key that pretended otherwise would not be.
+      def mutation_result_cache(paths, options, configuration, context, seed)
+        Protection::MutationCache.build(
+          configuration: configuration, roots: @argv, project_scan: context.project_scan,
+          sampling: Protection::MutationCache::Sampling.new(
+            limit: options[:limit], seed: options[:seed],
+            site_selector: options[:include_dynamic] ? :all : :biteable
+          ),
+          feature_ids: MUTATION_BEHAVIOUR_FEATURES.select { |id| configuration.bleeding_edge_active?(id) },
+          seed_inputs: seed.nil? ? nil : paths,
+          bypass_reason: mutation_cache_bypass(options, configuration)
+        )
+      end
+
+      def mutation_cache_bypass(options, configuration)
+        return "--no-cache" if options[:no_cache]
+        return DEPENDENT_CLOSURE_KILL_ORACLE if configuration.bleeding_edge_active?(DEPENDENT_CLOSURE_KILL_ORACLE)
+
+        nil
+      end
+
+      # One stderr line saying what the cache did — stdout stays clean for JSON. Always printed, because "the
+      # cache quietly stopped working" and "the cache quietly served a stale number" are indistinguishable
+      # from the outside otherwise; the slice-3 gate reads this line to prove itself non-vacuous.
+      def report_mutation_cache(cache, measured:, served:)
+        if cache.enabled?
+          @err.puts("coverage: mutation cache — re-measured #{measured} file(s), #{served} served from cache.")
+        else
+          @err.puts("coverage: mutation cache disabled (#{cache.reason}) — " \
+                    "re-measured #{measured} file(s).")
         end
+      end
 
-        accumulator.absorb(scanner.scan_file(path, source: source))
+      def absorb_mutation_result(accumulator, path, result)
+        if result.is_a?(MutationForkScan::ParseError)
+          accumulator.record_parse_error_count(path, result.count)
+        else
+          accumulator.absorb(result)
+        end
       end
 
       # The git-changed (modified / added / untracked) `.rb` files that exist on disk — the default Tier 2 scope.

data/lib/rigor/cli/fused_protection_renderer.rb

@@ -33,10 +33,20 @@ module Rigor
         @out.puts "    by type:  #{report.total_type_killed}"
         @out.puts "    by test:  #{report.total_test_killed}  (type-survivors a test caught)"
         @out.puts "  unprotected: #{report.total_unprotected}  (neither — add a type or a test)"
+        render_harness_errors(report)
         render_unprotected(report)
         render_files(report)
       end
 
+      # #264 — see {MutationProtectionRenderer#render_harness_errors}; surfaced only when non-zero.
+      def render_harness_errors(report)
+        count = report.total_harness_errors
+        return if count.zero?
+
+        @out.puts "  harness errors: #{count} mutant(s) failed inside the measurement harness " \
+                  "(excluded from the ratio — see --format=json's \"harness_errors\")"
+      end
+
       def render_unprotected(report)
         unprotected = report.unprotected
         return if unprotected.empty?

data/lib/rigor/cli/fused_protection_report.rb

@@ -9,7 +9,12 @@ module Rigor
     #
     # Framing (ADR-63 / ADR-62 Criterion A, extended): the payload is the **attribution** — which protection axis is
     # missing — never raw survival. An unprotected site is "add protection here", never "your code is broken".
-    FusedFileProtection = Data.define(:path, :type_killed, :test_killed, :unprotected, :ratio)
+    # `harness_errors` (#264) — see {Rigor::CLI::FileEffectiveness}; defaults to 0 for the same reason.
+    FusedFileProtection = Data.define(:path, :type_killed, :test_killed, :unprotected, :ratio, :harness_errors) do
+      def initialize(path:, type_killed:, test_killed:, unprotected:, ratio:, harness_errors: 0)
+        super
+      end
+    end
     UnprotectedBreakage = Data.define(:method_name, :count, :examples)
 
     FusedProtectionReport = Data.define(:files, :unprotected, :parse_errors) do
@@ -20,6 +25,9 @@ module Rigor
       def protected_total = total_type_killed + total_test_killed
       def ratio = grand_total.zero? ? 1.0 : protected_total.to_f / grand_total
 
+      # #264 — stays OUT of `grand_total`/`ratio`, exactly like the plain mutation report.
+      def total_harness_errors = files.sum(&:harness_errors)
+
       def to_h
         {
           "mode" => "protection-fused",
@@ -27,9 +35,10 @@ module Rigor
           "test_killed" => total_test_killed,
           "unprotected" => total_unprotected,
           "protected_ratio" => ratio.round(4),
+          "harness_errors" => total_harness_errors,
           "files" => files.map do |f|
             { "path" => f.path, "type_killed" => f.type_killed, "test_killed" => f.test_killed,
-              "unprotected" => f.unprotected, "ratio" => f.ratio.round(4) }
+              "unprotected" => f.unprotected, "ratio" => f.ratio.round(4), "harness_errors" => f.harness_errors }
           end,
           "add_protection_here" => unprotected.map do |m|
             { "method" => m.method_name, "count" => m.count, "examples" => m.examples }
@@ -50,7 +59,7 @@ module Rigor
         @files << FusedFileProtection.new(
           path: file_result.path, type_killed: file_result.type_killed,
           test_killed: file_result.test_killed, unprotected: file_result.unprotected,
-          ratio: file_result.ratio
+          ratio: file_result.ratio, harness_errors: file_result.harness_errors
         )
         file_result.sites.each do |site|
           bucket = @unprotected[site.method_name]

data/lib/rigor/cli/mutation_fork_scan.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../inference/fork_map"
+
+module Rigor
+  class CLI
+    # Fork-pool for the `rigor coverage --protection --mutation` scan (#134 slice 1) — the Tier-2 analogue of
+    # {ProtectionForkScan}. The expensive shared state is built ONCE on the parent (the RBS environment, the
+    # plugin registry, and the whole-project pre-pass {Analysis::ProjectScan}, all held by the
+    # {Protection::MutationScanner}'s oracle) and children copy-on-write inherit it via {Inference::ForkMap},
+    # each measuring a contiguous slice of paths.
+    #
+    # Why this is safe to parallelise where Tier 1 already is: a Tier-2 per-file measurement is pure-read
+    # against that shared state — every mutant is analysed through `Runner.new(prebuilt:)#run_source`, an
+    # in-memory overlay that writes nothing to disk and, because `prebuilt:` disables the run-result cache, has
+    # no cache store to race on. The returned {Protection::MutationScanner::FileResult} is a Data of primitives
+    # (and `SurvivingSite` likewise), so it marshals back verbatim.
+    #
+    # Determinism: {MutationProtectionAccumulator#absorb} is order-dependent (the per-file list and the
+    # "add a type here" example paths follow absorption order), so the parent MUST iterate the original `paths`
+    # and `fetch` each result rather than consume completion order. A missing key then raises instead of
+    # silently under-reporting an effectiveness ratio a `--threshold` gate reads.
+    #
+    # NOT used by the fused `--with-tests` path: {Protection::TestSuiteOracle} shells out to the project's test
+    # runner, and concurrent suite invocations would race over the same working tree.
+    module MutationForkScan
+      module_function
+
+      # A parse failure for one file, carrying only the marshalable error count (Prism error objects are not
+      # reliably marshalable, and the accumulator only needs the count).
+      ParseError = Data.define(:count)
+
+      # @param paths [Array<String>] the files to measure, in caller order.
+      # @param scanner [Protection::MutationScanner] built on the parent; COW-inherited by workers.
+      # @param environment [Rigor::Environment] the scanner's environment, prewarmed here before forking.
+      # @param configuration [Rigor::Configuration] for the Prism `target_ruby` version.
+      # @param workers [Integer] resolved worker count (≤1 → sequential).
+      # @return [Hash{String => Protection::MutationScanner::FileResult, ParseError}] one entry per path.
+      def run(paths:, scanner:, environment:, configuration:, workers:)
+        # Force the full RBS load on the parent so children copy-on-write inherit a warm environment rather
+        # than each rebuilding it after the fork. A no-op on the sequential path but cheap.
+        environment.rbs_loader&.prewarm if Inference::ForkMap.parallel?([workers, paths.size].min)
+
+        payloads = Inference::ForkMap.call(items: paths, workers: workers) do |slice|
+          slice.to_h { |path| [path, scan_path(path, scanner, configuration)] }
+        end
+        payloads.each_with_object({}) { |slice_results, merged| merged.merge!(slice_results) }
+      end
+
+      # Measures one file and returns the scanner's {Protection::MutationScanner::FileResult}, or a
+      # {ParseError} when the source does not parse — the same read → parse → guard → scan order the sequential
+      # loop used, so a broken file is reported identically either side of the fork.
+      def scan_path(path, scanner, configuration)
+        source = File.read(path)
+        parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
+        return ParseError.new(count: parse_result.errors.size) if parse_result.errors.any?
+
+        scanner.scan_file(path, source: source)
+      end
+    end
+  end
+end

data/lib/rigor/cli/mutation_protection_renderer.rb

@@ -30,10 +30,22 @@ module Rigor
         @out.puts "Type-protection effectiveness (Tier 2 — mutation kill rate)"
         @out.puts "  caught breakages: #{report.total_killed} / #{report.grand_total}  (#{pct}%)"
         @out.puts "  (effectiveness = when a type-visible bug was introduced, Rigor caught it)"
+        render_harness_errors(report)
         render_missed(report)
         render_files(report)
       end
 
+      # #264 — surfaced only when non-zero: a harness-level failure is a defect in the measurement itself, not
+      # in the code being measured, and a clean run should not carry a permanent line about a bucket that is
+      # always empty.
+      def render_harness_errors(report)
+        count = report.total_harness_errors
+        return if count.zero?
+
+        @out.puts "  harness errors: #{count} mutant(s) failed inside the measurement harness " \
+                  "(excluded from the ratio — see --format=json's \"harness_errors\")"
+      end
+
       def render_missed(report)
         missed = report.missed
         return if missed.empty?