saboteur 0.6.0 → 0.8.0

data/lib/saboteur/engine/coverage_store.rb

@@ -15,19 +15,32 @@ module Saboteur
       LOCKFILES = %w[Gemfile.lock gems.locked].freeze
       LOG = "coverage-build.log"
 
-      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, load_lines: {})
+      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, load_lines: {}, load_methods: {},
+                     timeout_cap: nil)
         @config = config
         @integration = integration
         @hooks = hooks
         @supervisor = supervisor
         @diagnostics = diagnostics
+        @timeout_cap = timeout_cap
         @load_lines = load_lines
+        @load_methods = load_methods
         @root = File.realpath(config.root)
+        @root_prefixes = Selection::CoverageMap.root_prefixes(config.root)
+      end
+
+      # True when fetch would reuse the cached map instead of running the
+      # suite pass that builds it: lets the run announce the real number of
+      # full passes up front (#260). Loads the map with the same validation
+      # fetch uses and retains it, so a corrupt or truncated cache announces
+      # a build pass, not a reuse it cannot keep.
+      def reusable?(files)
+        !cached_map(files).nil?
       end
 
       def fetch(files)
-        path = File.join(@config.path("cache_dir"), "coverage-#{cache_key(files)}.json")
-        cached = @config["cache"] ? Selection::CoverageMap.load(path) : nil
+        path = cache_path(files)
+        cached = cached_map(files)
         return refuse_empty_map(cached, files) if cached
 
         map = refuse_empty_map(build(files), files)
@@ -39,6 +52,31 @@ module Saboteur
 
       private
 
+      def write_map(writer, recorder, build_seconds)
+        writer.write(recorder.result(build_seconds: build_seconds, loaded_files: loaded_project_files).to_json)
+        writer.close
+      end
+
+      # Every project source this child loaded, even a lazy require outside the
+      # include list that the recorder drops: --incremental must watch it, or a
+      # change there keeps stale verdicts (#353).
+      def loaded_project_files
+        $LOADED_FEATURES.filter_map do |file|
+          path = Text.utf8_strict(Selection::CoverageMap.canonical(file))
+          path if path.end_with?(".rb") && @root_prefixes.any? { |prefix| path.start_with?(prefix) }
+        end
+      end
+
+      def cache_path(files)
+        File.join(@config.path("cache_dir"), "coverage-#{cache_key(files)}.json")
+      end
+
+      def cached_map(files)
+        return nil unless @config["cache"]
+
+        @cached_map ||= Selection::CoverageMap.load(cache_path(files))
+      end
+
       def cache_key(files)
         inputs = JSON.generate(CACHE_INPUTS.to_h { |key| [key, @config[key]] })
         all = files + @integration.test_files + SuiteFiles.new(@config).files + lockfiles
@@ -49,6 +87,12 @@ module Saboteur
         LOCKFILES.map { |file| File.join(@root, file) }.select { |file| File.file?(file) }
       end
 
+      # An admitted build still gets only the time left in the run budget
+      # (see BaselineGuard#phase_timeout).
+      def build_timeout
+        @timeout_cap ? @timeout_cap.call(@config["coverage_timeout"]) : @config["coverage_timeout"]
+      end
+
       def build(files)
         unless Coverage.respond_to?(:state) && Coverage.state == :suspended
           raise Error, "Coverage is #{Coverage.state}; saboteur must set it up before the app loads. " \
@@ -61,13 +105,16 @@ module Saboteur
         # reduce later copying of shared pages.
         Execution::ForkReadiness.prepare_heap
         heartbeat = @diagnostics.progress_heartbeat("building coverage map").watch(log_path)
-        result = @supervisor.run(timeout: @config["coverage_timeout"], on_tick: heartbeat.method(:tick)) do |writer|
+        admitted = build_timeout
+        result = @supervisor.run(timeout: admitted, on_tick: heartbeat.method(:tick),
+                                 label: "coverage child died during the map build") do |writer|
           record(writer, files)
         end
-        map_from(result)
+        map_from(result, admitted)
       end
 
-      def map_from(result)
+      def map_from(result, admitted = @config["coverage_timeout"])
+        raise_budget_stop(admitted) if budget_stopped?(result, admitted)
         raise Error, "coverage map build stopped: #{result.detail}" if result.stopped_by
         raise Error, "coverage map build failed: #{died(result.exit_status)}" if result.payload.empty?
 
@@ -77,16 +124,32 @@ module Saboteur
         with_parent_load_lines(Selection::CoverageMap.from_json(result.payload))
       end
 
+      # A build that hit its deadline only because --max-duration shortened
+      # the admission below the configured phase timeout: the budget ended
+      # the run, the suite is not broken (see BaselineGuard#budget_stopped?).
+      def budget_stopped?(result, admitted)
+        result.stopped_by == :timeout && admitted < @config["coverage_timeout"]
+      end
+
+      def raise_budget_stop(admitted)
+        raise BudgetPhaseTimeout, "the --max-duration budget stopped the coverage map build " \
+                                  "(admitted #{admitted.round(1)}s of the #{@config['coverage_timeout']}s " \
+                                  "phase timeout)"
+      end
+
       # The parent's load lines merge into the freshly built map: the forked
       # build child cannot inherit the parent's Coverage counters.
       def with_parent_load_lines(map)
-        @load_lines.empty? ? map : map.with_load_lines(@load_lines)
+        @load_lines.empty? && @load_methods.empty? ? map : map.with_load_lines(@load_lines, @load_methods)
       end
 
       # A whole-suite build that records nothing - no line hit and no method
-      # call - in any included file fails the run (exit 3): usually no test
-      # in the suite exercises these files, or the setup hid the app from
-      # Coverage (Bootsnap's compile cache is the default Rails case). An
+      # call - in any included file fails the run (exit 3). The recorder's map
+      # also holds the suite's spec files, so the check is per included file,
+      # not whole-map: a suite that tests nothing here still records its own
+      # spec code. Usually no test in the suite exercises these files, or
+      # the setup hid the app from Coverage (Bootsnap's compile cache is the
+      # default Rails case). An
       # all-endless-def file records method calls only and passes. Either way
       # a run on a truly empty map would test nothing, and exit 0 would lie.
       # With explicit tests (--test) an empty map is a legitimate outcome
@@ -95,7 +158,7 @@ module Saboteur
       # map too, so a map cached before this check cannot keep a run green,
       # and the guard runs before saving, so an empty map is never cached.
       def refuse_empty_map(map, files)
-        return map if files.empty? || !map.empty?
+        return map if files.empty? || !map.empty_for?(files)
 
         if @config["tests"].empty?
           raise Error, "Coverage recorded nothing in #{files.size} included files during a whole-suite " \
@@ -133,7 +196,10 @@ module Saboteur
         $stderr.reopen($stdout)
         @hooks.run(:after_fork)
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        recorder = Selection::Recorder.new(files)
+        # The suite's own files are recorded too: a spec can read a
+        # constant directly, and without its line hits no test maps to the
+        # read (#319).
+        recorder = Selection::Recorder.new(files + @integration.test_files)
         recorder.start
         Kernel.srand(@config["seed"])
         passed = @integration.run_all(recorder)
@@ -141,9 +207,7 @@ module Saboteur
           raise Error, "the unchanged suite failed while building coverage. Fix the suite, then run again " \
                        "with seed #{@config['seed']}."
         end
-        build_seconds = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
-        writer.write(recorder.result(build_seconds: build_seconds).to_json)
-        writer.close
+        write_map(writer, recorder, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
       rescue Exception => e # rubocop:disable Lint/RescueException
         writer.write(JSON.generate(error: "#{e.class}: #{e.message}"))
         exit!(1)

data/lib/saboteur/engine/defined_order_prefix.rb

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # The examples an order-dependent spec file needs, in the order RSpec
+    # defines them: for each file with a covering example, every example from
+    # the start of the file through its last covering example. Later examples
+    # cannot change earlier ones, so this is the smallest run that keeps
+    # whatever state the earlier examples leave behind.
+    class DefinedOrderPrefix
+      ID_PATTERN = /\A(?<file>.*)\[(?<path>[\d:]+)\]\z/
+
+      # every_test: all example ids the map knows, in any order.
+      def initialize(every_test)
+        @every_test = every_test
+      end
+
+      # The prefix for the covering examples; nil when it adds nothing to
+      # what already ran (an id that is not an RSpec id included).
+      def for(covering)
+        parsed = covering.map { |id| parse(id) }
+        return nil if parsed.any?(&:nil?)
+
+        prefix = parsed.group_by(&:first).flat_map { |file, entries| file_prefix(file, entries.map(&:last).max) }
+        prefix == covering ? nil : prefix
+      end
+
+      private
+
+      def file_prefix(file, last_position)
+        in_file = @every_test.filter_map { |id| (entry = parse(id)) && entry.first == file ? entry : nil }
+        through = in_file.select { |entry| (entry.last <=> last_position) <= 0 }.sort_by(&:last)
+        through.map { |entry| "#{file}[#{entry.last.join(':')}]" }
+      end
+
+      def parse(id)
+        match = ID_PATTERN.match(id)
+        match && [match[:file], match[:path].split(":").map(&:to_i)]
+      end
+    end
+  end
+end

data/lib/saboteur/engine/diagnostics.rb

@@ -76,8 +76,9 @@ module Saboteur
       attr_reader :warnings, :invalid_mutations, :generation_events, :omissions, :discovery_failures,
                   :hazard_suppressions, :inline_suppressions
 
-      def initialize(err)
+      def initialize(err, verbose: false)
         @err = err
+        @verbose = verbose
         @warnings = []
         @invalid_mutations = 0
         @generation_events = []
@@ -85,12 +86,30 @@ module Saboteur
         @discovery_failures = []
         @hazard_suppressions = 0
         @inline_suppressions = []
+        @erb_template_skips = []
+        @erb_template_note_emitted = false
       end
 
       def warn(message)
         @warnings << message
       end
 
+      # ERB generator templates (Rails generators carry `.rb` files with ERB
+      # interpolation, conventionally under `lib/generators/**/templates/`)
+      # can never parse as plain Ruby, so they can never hold mutation
+      # subjects (#372). One summarized note per run replaces the per-file
+      # parse warning every discovery pass used to print; a real syntax
+      # error in a plain Ruby file still warns per file.
+      def record_erb_template_skip(file, root:)
+        relative = file.to_s.delete_prefix("#{root}/")
+        @erb_template_skips << relative.freeze unless @erb_template_skips.include?(relative)
+        return if @erb_template_note_emitted
+
+        @erb_template_note_emitted = true
+        warn("skipping ERB template files that cannot parse as Ruby " \
+             "(for example #{relative}); templates are not mutation subjects")
+      end
+
       def count_invalid_mutation
         @invalid_mutations += 1
       end
@@ -102,8 +121,11 @@ module Saboteur
         @generation_events << GenerationEvent.new(*values)
       end
 
+      # The selection and the test inference each walk the same changed
+      # files in one run; a failure either of them finds is recorded once.
       def record_discovery_failure(file, reason:)
-        @discovery_failures << DiscoveryFailure.new(file: file.to_s.dup.freeze, reason: reason.to_s.dup.freeze)
+        failure = DiscoveryFailure.new(file: file.to_s.dup.freeze, reason: reason.to_s.dup.freeze)
+        @discovery_failures << failure unless @discovery_failures.include?(failure)
       end
 
       # A mutant the hazard guard refused to generate (issue #102): counted
@@ -129,6 +151,23 @@ module Saboteur
         @err.puts("saboteur: #{message}")
       end
 
+      # --verbose: one line per finished subject with its result marks, so a
+      # survivor is attributable to a method as soon as the subject
+      # completes, before the whole run ends (#262).
+      def subject_progress(subject, results)
+        return unless @verbose
+        return if results.empty?
+
+        marks = results.map { |result| MARKS.fetch(result.status, "?") }.join
+        inform("#{subject.id}  #{marks}")
+      end
+
+      # A message that is both a report warning and a stderr note.
+      def announce(message)
+        warn(message)
+        inform(message)
+      end
+
       # A heartbeat for a long phase: the supervisor's wait loop calls tick
       # in the parent after the fork, so no extra thread is ever alive at
       # fork time. Prints "<label>: N s elapsed" about every interval

data/lib/saboteur/engine/diff_scope.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "../text"
+
 module Saboteur
   class Engine
     # Review-shaped diff mode (--since). A reviewer asks "do the tests check
@@ -14,7 +16,7 @@ module Saboteur
       end
 
       def restrict(subject, candidates)
-        changed = @changed_lines.fetch(subject.file, Set.new)
+        changed = lines_for(subject)
         candidates.select do |mutation, _|
           mutation.coarse || mutation.edits.any? { |edit| edited_lines(subject, edit).any? { changed.include?(_1) } }
         end
@@ -24,22 +26,39 @@ module Saboteur
       # several lines is mutated as one piece and reported at its first line,
       # which can sit above the line that changed; this names the changed line.
       def changed_lines_for(subject, mutation)
-        changed = @changed_lines.fetch(subject.file, Set.new)
+        changed = lines_for(subject)
         mutation.edits.flat_map { |edit| edited_lines(subject, edit).to_a }.uniq.select { changed.include?(_1) }.sort
       end
 
       # Distance to the nearest changed line in this file. Unknown outside
-      # the diff is nil, not a made-up nearby location.
+      # the diff is nil, not a made-up nearby location. A range answers
+      # geometrically - 0 when the edit overlaps, else the gap to the nearer
+      # endpoint - so a whole-file range never materializes one entry per
+      # line.
       def distance_for(subject, mutation)
-        changed = @changed_lines.fetch(subject.file, Set.new)
+        changed = lines_for(subject)
         mutation.edits.map do |edit|
           first, last = edited_lines(subject, edit).minmax
-          changed.map { |line| (line - line.clamp(first, last)).abs }.min
+          if changed.is_a?(Range)
+            if last < changed.begin then changed.begin - last
+            elsif first > changed.end then first - changed.end
+            else 0
+            end
+          else
+            changed.map { |line| (line - line.clamp(first, last)).abs }.min
+          end
         end.min
       end
 
       private
 
+      # subject.file carries the locale tag under a non-UTF-8 locale
+      # while the map keys are UTF-8; retag losslessly or a non-ASCII
+      # path never matches and every fine mutant is silently dropped.
+      def lines_for(subject)
+        @changed_lines.fetch(Text.utf8_identity(subject.file), Set.new)
+      end
+
       def edited_lines(subject, edit)
         first = subject.line_of(edit.start_byte)
         last = subject.line_of([edit.end_byte - 1, edit.start_byte].max)

data/lib/saboteur/engine/distribution.rb

@@ -9,23 +9,41 @@ module Saboteur
     # candidate list, so results look the same either way.
     class Distribution
       # After run: the subjects a stop_after callable left unrun (always empty
-      # without one).
-      attr_reader :unreached
+      # without one), and the subjects that started but stopped mid-list as
+      # [subject, omitted_candidate_count] pairs (a spent --max-duration
+      # breaking a subject's scheduler loop). unverified lists the subjects
+      # whose fresh kills the spent budget left unchecked (#296).
+      attr_reader :unreached, :truncated, :unverified
+
+      # The run's peak-memory record for the JSON report (#202): each
+      # worker's kernel peak RSS and the supervisor's own, nil when the
+      # platform measured neither so the report omits the section. No total:
+      # fork copy-on-write makes per-process RSS non-additive.
+      def memory_report
+        workers = (@pool&.worker_peaks || {}).sort.map { |number, mb| { worker: number, peakMb: mb } }
+        supervisor = Execution::PeakMemory.peak_mb
+        workers.empty? && supervisor.nil? ? nil : { workers: workers, supervisorPeakMb: supervisor }.compact
+      end
 
       # stop_after: nil, or a callable that gets one subject's results and
       # returns true to stop before the next subject (--fail-fast). It only
       # works on one process: parallel workers have already started the
       # other subjects.
       def initialize(jobs:, scheduler:, diagnostics:, cache:, on_start: nil, after_subject: nil,
-                     stop_after: nil)
+                     stop_after: nil, halt_check: nil,
+                     drain_timeout: 30) # seconds; two minimum-strength mutant deadlines at default settings
         @jobs = jobs
         @stop_after = stop_after
+        @halt_check = halt_check
         @unreached = []
+        @truncated = []
+        @unverified = []
         @on_start = on_start
         @scheduler = scheduler
         @diagnostics = diagnostics
         @cache = cache
         @after_subject = after_subject
+        @drain_timeout = drain_timeout
       end
 
       # lists: each subject's [[mutation, text]] candidates, in subject order.
@@ -35,23 +53,116 @@ module Saboteur
         # The watcher runs as each subject's row arrives, before the pool
         # hands out more work, so a tripped canary stops the queue (jobs>1
         # used to check only after the whole batch returned, issue #102).
-        arrival = lambda do |i, row|
-          @after_subject&.call(subjects[i], decode(row, subjects[i], lists[i]))
+        # A tool error no longer raises on sight: one wiped log dir hits
+        # every worker, and a bystander whose current job ran no mutant
+        # reports "an unknown mutant", which could land before the report
+        # of the worker whose mutant did the damage (macOS CI on #285).
+        # The pool is halted instead - no new work, and the drain is
+        # bounded by drain_timeout so a wedged worker cannot stall the
+        # abort - and the abort raises the report with the best
+        # attribution.
+        # The abort reports and the pool are run state: a Distribution
+        # runs once. @pool is only read from arrivals, which fire inside
+        # @pool.map after the assignment.
+        # A budget already spent by boot, baselines or the coverage map
+        # launches nothing: every subject comes back unreached (#245).
+        if @halt_check&.call
+          @unreached = subjects
+          return []
         end
-        pool = Execution::WorkerPool.new(jobs: @jobs, on_start: @on_start, on_result: arrival)
-        rows = pool.map(subjects.each_index.to_a, weights: lists.map(&:size)) do |i|
+
+        @abort_reports = []
+        arrival = arrival_for(subjects, lists)
+        @pool = Execution::WorkerPool.new(jobs: @jobs, on_start: @on_start, on_result: arrival,
+                                          drain_timeout: @drain_timeout)
+        rows = @pool.map(subjects.each_index.to_a, weights: lists.map(&:size)) do |i|
           work(subjects[i], lists[i])
         end
-        rows.each_with_index.flat_map { |row, i| rebuild(row, subjects[i], lists[i]) }
+        raise_preferred_tool_error(@abort_reports) if @abort_reports.any?
+        record_unreached(rows, subjects, lists)
+        rows.each_with_index.flat_map do |row, i|
+          next [] if row.nil?
+
+          raise_if_tool_error(row)
+          rebuild(row, subjects[i], lists[i])
+        end
       end
 
       private
 
+      # @pool is only read here from arrivals, which fire inside @pool.map
+      # after the assignment. A spent --max-duration budget stops the queue
+      # without the safety-abort drain: in-flight subjects finish and
+      # report, and only never-started ones come back as nil holes, so
+      # unreached never mislabels an interrupted subject as unrun (#245).
+      def arrival_for(subjects, lists)
+        lambda do |i, row|
+          if row["tool_error"]
+            collect_abort_report(row)
+          else
+            check_subject(subjects, lists, i, row)
+            @pool.halt!(drain: false) if @halt_check&.call
+          end
+        end
+      end
+
+      # nil rows never started; a short results list is a subject whose
+      # scheduler stopped mid-list at the budget deadline. Worker-level error
+      # rows synthesize an error per candidate, so they never look truncated.
+      def unverified_result?(result)
+        result.is_a?(MutantResult) && result.status == :unverified
+      end
+
+      def record_unreached(rows, subjects, lists)
+        @unreached = []
+        @truncated = []
+        @unverified = []
+        rows.each_with_index do |row, i|
+          if row.nil?
+            @unreached << subjects[i]
+            next
+          end
+          next unless row["results"] && !row["error"]
+
+          @truncated << [subjects[i], lists[i].size - row["results"].size] if row["results"].size < lists[i].size
+          @unverified << subjects[i] if row["results"].any? { |result| result["status"] == "unverified" }
+        end
+      end
+
+      # @pool is always assigned when an arrival fires: arrivals only fire
+      # from inside @pool.map, which runs after the assignment.
+      def collect_abort_report(row)
+        @abort_reports << row
+        @pool.halt!
+      end
+
+      # A canary trip from the end-of-subject check folds into the same
+      # record + halt + preferred-report path as a worker's own report:
+      # escaping the pool here would override a collected report that
+      # names the real culprit (#285 review).
+      def check_subject(subjects, lists, index, row)
+        @after_subject&.call(subjects[index], decode(row, subjects[index], lists[index]))
+      rescue Error => e
+        collect_abort_report(Execution::WorkerPool.tool_error_row(e))
+      end
+
       def run_serially(subjects, lists)
         results = []
         subjects.zip(lists).each_with_index do |(subject, list), index|
+          # Same pre-dispatch budget check as the parallel first wave: an
+          # already-spent baseline starts no further subjects (#245).
+          if @halt_check&.call
+            @unreached = subjects.drop(index)
+            break
+          end
+
           subject_results = @scheduler.call(subject, list)
           results.concat(subject_results)
+          # A scheduler that stopped mid-list at the budget deadline: the
+          # completed results stay, the omitted candidates are accounted.
+          omitted = list.size - subject_results.size
+          @truncated << [subject, omitted] if omitted.positive?
+          @unverified << subject if subject_results.any? { |result| unverified_result?(result) }
           @after_subject&.call(subject, subject_results)
           next unless @stop_after&.call(subject_results)
 
@@ -91,6 +202,21 @@ module Saboteur
 
       # Turns a worker row back into results, without diagnostics or caching:
       # used both at result arrival (the canary) and at rebuild time.
+      # A tool error from the worker (a vanished cache dir, ...) aborts
+      # the whole run with exit 3; it is not a per-mutant outcome (#283).
+      def raise_if_tool_error(row)
+        raise Error, row["tool_error"] if row["tool_error"]
+      end
+
+      # The abort names a culprit when any report can, ranked by
+      # attribution quality (#285 review): a report carrying its mutant's
+      # per-mutant digest first, then a canary trip (the hazard report
+      # still beats a bare report, #283), then the first bare report.
+      def raise_preferred_tool_error(rows)
+        row = rows.find { |r| r["culprit"] } || rows.find { |r| r["canary"] } || rows.first
+        raise Error, row["tool_error"]
+      end
+
       def decode(row, subject, list)
         return failed(row["error"], subject, list) if row["error"]
 

data/lib/saboteur/engine/early_stop_recording.rb

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Records the subjects an early stop left behind - whole subjects that
+    # never started and candidates skipped mid-way through a subject - so
+    # the report says the verdict covers less than the selection.
+    module EarlyStopRecording
+      private
+
+      # The subjects a stop left unrun or mid-way: the verdict covers less than the selection.
+      def record_early_stop(distribution, planned_mutants: nil)
+        return if distribution.unreached.empty? && distribution.truncated.empty? && distribution.unverified.empty?
+
+        truncated = distribution.truncated.map { |subject, omitted| { subject: subject.id, omitted: omitted } }
+        @early_stop = EarlyStop.new(reason: stop_reason(distribution), unreached: distribution.unreached.map(&:id),
+                                    truncated: truncated, unverified: distribution.unverified.map(&:id),
+                                    planned_mutants: planned_mutants)
+      end
+
+      # Mid-subject omissions and skipped checks are budget work: only a
+      # stop that left whole subjects unreached can be fail_fast's.
+      def stop_reason(distribution)
+        return "max_duration" if distribution.truncated.any? || distribution.unverified.any?
+
+        run_early_stop_reason
+      end
+
+      # max_duration was announced before fail_fast could stop the run: a
+      # budget stop overrides a failure stop announced later.
+      def run_early_stop_reason
+        @budget_announced ? "max_duration" : "fail_fast"
+      end
+
+      # A baseline or coverage phase stopped because --max-duration ate its
+      # allowance: budget exhaustion, not a broken suite. The run reports
+      # partial with every selected subject unreached (exit 4) (#296).
+      def budget_phase_stop(error, subjects)
+        @diagnostics.warn(error.message)
+        @early_stop = EarlyStop.new(reason: "max_duration", unreached: subjects.map(&:id), truncated: [],
+                                    unverified: [])
+        []
+      end
+    end
+  end
+end

data/lib/saboteur/engine/gated_run.rb

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # A threshold or mutant-count gate judges the score, so a path that
+    # narrows what the score covers (a partially mapped --since run, #370)
+    # must keep its hard stop instead of green-lighting the change.
+    module GatedRun
+      private
+
+      def gated?
+        config["threshold"] || Gates.new(config).any?
+      end
+
+      # Reports the guess's skipped and subjectless files, then stops or
+      # warns on unmapped files per the gate (#370).
+      def report_unmapped(guess)
+        @diagnostics.inform(guess.subjectless_message(since: config["since"])) if guess.subjectless.any?
+        inform_skipped_specs(guess)
+        stop_or_warn_unmapped(guess)
+      end
+
+      # A --since run with a partial mapping runs the mapped subset with a
+      # loud warning per unmapped file (#370); a full run, a zero guess and
+      # a gated run keep the hard stop.
+      def stop_or_warn_unmapped(guess)
+        return if guess.unmatched.empty?
+        raise ConfigError, guess.unmatched_message if !config["since"] || guess.specs.empty? || gated?
+
+        guess.unmatched.each { |file| @diagnostics.announce(guess.unmatched_warning(file)) }
+      end
+    end
+  end
+end

data/lib/saboteur/engine/load_coverage.rb

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "coverage"
+
+module Saboteur
+  class Engine
+    # The boot's coverage snapshot, read in the parent because a forked
+    # child does not inherit Coverage counters: the lines and the def
+    # calls that ran while the app and spec files loaded. The executable
+    # counts from its first line, so this snapshot holds the whole boot.
+    # The lines tell ran-at-load mutants apart from uncovered ones; the
+    # def calls name def-time macros whose only caller ran here, so their
+    # mutants read as ran at load instead of surviving on the pristine
+    # closure (#409).
+    module LoadCoverage
+      # Returns [load_lines, load_methods]: file => line numbers for each.
+      def self.capture(files)
+        return [{}, {}] unless Coverage.state == :suspended
+
+        wanted = files.to_set { |file| Selection::CoverageMap.canonical(file) }
+        CoverageReads.result(stop: false, clear: false)
+                     .each_with_object([{}, {}]) do |(path, data), (lines_h, methods_h)|
+          file = Selection::CoverageMap.canonical(path)
+          next unless wanted.include?(file)
+
+          lines = data[:lines].each_with_index.filter_map { |count, index| index + 1 if count&.positive? }
+          lines -= uncalled_shared_lines(data)
+          lines_h[file] = lines unless lines.empty?
+          defs = data.fetch(:methods, {}).filter_map { |(_owner, _name, first, *), count| first if count.positive? }
+          methods_h[file] = defs.uniq.sort unless defs.empty?
+        end
+      end
+
+      # A one-line or endless definition executes its def line even when its
+      # body is never called. If any sibling on that physical line is uncalled,
+      # discard its ambiguous line evidence rather than crediting every body.
+      def self.uncalled_shared_lines(data)
+        shared = data.fetch(:methods, {}).select { |(_owner, _name, first, _column, last, *), _| first == last }
+        calls = shared.group_by { |(_owner, _name, first, *), _count| first }
+        calls.filter_map { |line, entries| line if entries.any? { |_key, count| count.zero? } }
+      end
+    end
+  end
+end