rigortype 0.3.0 → 0.3.2

data/lib/rigor/cli/check_invocation.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # The one place a CLI command turns a loaded {Configuration} into an {Analysis::Result}.
+    #
+    # {CheckRunnerFactory} builds the runner; this module owns the *invocation* wrapped around it — resolving the
+    # analysed paths, running, and handing back both the runner (`rigor check`'s reporting tail still needs its cache
+    # store and stats) and the raw result. It exists so a non-`check` command — `rigor doctor`, `rigor skill describe
+    # --deep` — reaches a check result through the same code path `rigor check` walks, instead of re-deriving the
+    # plumbing (issue #148; ADR-73 § "Field-trial follow-ups" names the shared helper as the prerequisite).
+    #
+    # Nothing here is required at load time: {CheckRunnerFactory} pulls the inference engine, so both entry points
+    # require it lazily. A command that merely *mentions* this module therefore stays engine-free until it actually
+    # runs an analysis — the property ADR-87 WD4 protects for `rigor check`'s cache-hit fast path, and the property
+    # that keeps an un-flagged `rigor skill describe` from loading the engine at all.
+    module CheckInvocation
+      # A completed analysis. `runner` is exposed because `rigor check`'s tail reads its `cache_store` (eviction,
+      # `--cache-stats`) and feeds it to `--coverage`; `result` is the raw, pre-baseline-filter {Analysis::Result}.
+      Invocation = Data.define(:runner, :result)
+
+      # The outcome of {.attempt} — the best-effort variant. Exactly one of the two is non-nil, so a caller can never
+      # read "the check could not run" as "the check ran clean": `result` is nil precisely when `error` is set.
+      Outcome = Data.define(:result, :error) do
+        # @return [Boolean] true when an analysis actually completed.
+        def ran?
+          !result.nil?
+        end
+      end
+
+      # Options for a caller that wants a check *result* rather than a check *run*: no cache writes, no explain
+      # traces, sequential. `stats: true` because the RBS-environment signal (`stats.rbs_classes_total`) lives there.
+      # This is `rigor doctor`'s preset — a diagnostic command that must not churn the project's cache.
+      READ_ONLY_OPTIONS = { no_cache: true, explain: false, stats: true, workers: 0 }.freeze
+
+      # Options for an opt-in deep probe (`rigor skill describe --deep`). Unlike {READ_ONLY_OPTIONS} this uses the
+      # configured cache and worker count, i.e. it behaves exactly like `rigor check` — fast on a warm cache, and it
+      # WRITES `.rigor/cache`. That side effect is the whole reason the flag is opt-in.
+      DEEP_OPTIONS = { no_cache: false, explain: false, stats: true, workers: nil }.freeze
+
+      module_function
+
+      # Runs the analysis the way `rigor check` does and returns the runner + its raw result.
+      #
+      # @param configuration [Rigor::Configuration]
+      # @param options [Hash] at least `:no_cache`, `:explain`, `:stats`, `:workers` (see {CheckRunnerFactory.build}).
+      # @param paths [Array<String>, nil] analysed paths; nil falls back to the configuration's `paths:`.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @param cache_root [String, nil] nil falls back to the configuration's cache path.
+      # @return [Invocation]
+      def run(configuration:, options:, paths: nil, buffer: nil, cache_root: nil)
+        require_relative "check_runner_factory"
+        runner = CheckRunnerFactory.build(
+          configuration: configuration,
+          options: options,
+          buffer: buffer,
+          cache_root: cache_root || configuration.cache_path
+        )
+        Invocation.new(runner: runner, result: runner.run(paths || configuration.paths))
+      end
+
+      # Best-effort variant for a *routing* caller: one that wants to sharpen a recommendation with check evidence and
+      # has a perfectly good answer when there is none. Loads the configuration itself and converts every way the run
+      # can fail outright — an unreadable / invalid config, an unloadable plugin, an engine error — into an {Outcome}
+      # carrying a short human-readable `error`. It never raises and never fabricates a clean result.
+      #
+      # Deliberately broad: the caller's contract is "degrade to the presence-only answer, whatever went wrong". A
+      # routing hint is outside the false-positive envelope, but a crash in it is not — `describe` must stay a command
+      # an agent can run freely.
+      #
+      # @param config_path [String, nil] path to the config file; nil uses {Configuration.discover}.
+      # @param options [Hash] runner options (defaults to {DEEP_OPTIONS}).
+      # @param paths [Array<String>, nil]
+      # @return [Outcome]
+      def attempt(config_path: nil, options: DEEP_OPTIONS, paths: nil)
+        require_relative "../configuration"
+        configuration = Configuration.load(config_path)
+        Outcome.new(result: run(configuration: configuration, options: options, paths: paths).result, error: nil)
+      rescue StandardError, LoadError => e
+        Outcome.new(result: nil, error: "#{e.class}: #{e.message.to_s.lines.first.to_s.strip}")
+      end
+    end
+  end
+end

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/doctor_command.rb

@@ -12,7 +12,7 @@ require_relative "../plugin/loader"
 require_relative "../plugin/services"
 require_relative "../reflection"
 require_relative "../type/combinator"
-require_relative "check_runner_factory"
+require_relative "check_invocation"
 require_relative "command"
 require_relative "options"
 
@@ -53,14 +53,12 @@ module Rigor
         findings.concat(audit_config(configuration))
 
         # 2. Run a scoped analysis to gather stats + diagnostics for the
-        #    deeper checks.  Use no-cache so the probe doesn't churn disk.
-        runner = CheckRunnerFactory.build(
+        #    deeper checks, through the shared check-invocation entry point (#148).
+        #    `READ_ONLY_OPTIONS` is no-cache so the probe doesn't churn disk.
+        result = CheckInvocation.run(
           configuration: configuration,
-          options: { no_cache: true, explain: false, stats: true, workers: 0 },
-          buffer: nil,
-          cache_root: configuration.cache_path
-        )
-        result = runner.run(configuration.paths)
+          options: CheckInvocation::READ_ONLY_OPTIONS
+        ).result
 
         # 3. RBS environment check.
         findings.concat(check_rbs_environment(result))

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?