mutineer 0.11.2 → 0.11.3

data/lib/mutineer/coverage_map.rb

@@ -12,21 +12,23 @@ require_relative "test_runners"
 
 module Mutineer
   # Maps `(source_file, line) -> [test_files]` so each mutant runs only against
-  # the tests that actually exercise its line. Built once (Phase A), then queried
-  # per mutant (Phase B via #tests_for). Persisted to .mutineer/coverage.json with
-  # a content-based digest that rebuilds the map whenever any tracked file changes.
+  # the tests that actually exercise its line. Built once, then queried per
+  # mutant via #tests_for. Persisted to .mutineer/coverage.json with a
+  # content-based digest that rebuilds the map whenever any tracked file changes.
   #
-  # Keys are "file:line" strings (relative to project_root) everywhere — in
-  # memory and on disk — so load/save needs no key transformation (KTD4).
+  # Keys are "file:line" strings (relative to project_root) everywhere, in
+  # memory and on disk, so load/save needs no key transformation.
   class CoverageMap
-    DEFAULT_CAPTURE_TIMEOUT = 120 # seconds, per coverage subprocess (R3)
+    # Seconds per coverage subprocess before the parent kills it.
+    DEFAULT_CAPTURE_TIMEOUT = 120
 
     attr_reader :project_root, :failed_test_files, :phase_a_ran, :map
 
-    # Build a QUERY-ONLY map from data captured elsewhere (the daemon builds the map
-    # app-side and ships `map` + `failed_test_files` over IPC; the tool reconstructs it
-    # here for per-mutant selection). Skips the capture machinery entirely — only the
-    # three fields #tests_for / #method_uncapturable? read are set (U7).
+    # Build a QUERY-ONLY map from data captured elsewhere (the daemon builds the
+    # map app-side and ships `map` + `failed_test_files` over IPC; the tool
+    # reconstructs it here for per-mutant selection). Skips the capture machinery
+    # entirely: only the three fields #tests_for / #method_uncapturable? read are
+    # set.
     #
     # @param map [Hash] the "file:line" => [test_files] map.
     # @param failed_test_files [Array<String>] test files whose capture failed.
@@ -58,14 +60,14 @@ module Mutineer
       @phase_a_ran  = false
     end
 
-    # Phase A entry point (standalone): load the cached map when the content
-    # digest matches, otherwise rebuild from subprocesses and overwrite the cache.
+    # Standalone entry: load the cached map when the content digest matches,
+    # otherwise rebuild from subprocesses and overwrite the cache.
     def build_or_load
       warn_external_sources
       cached_or { run_phase_a }
     end
 
-    # Boot-mode Phase A: Coverage is already running in the parent (started before
+    # Boot-mode build: Coverage is already running in the parent (started before
     # the app booted, so booted source lines are instrumented). A clean `ruby`
     # subprocess has no booted env, so per-test coverage is captured by FORKING
     # the booted parent instead. Inverts into the same map #tests_for reads, and
@@ -76,25 +78,25 @@ module Mutineer
       cached_or { run_phase_a_via_fork(after_fork: after_fork) }
     end
 
-    # Phase B lookup: the test files that cover `file:line`, or [] when none do.
-    # ponytail: per-file granularity; upgrade to per-method when throughput
-    # warrants (requires Minitest method isolation + finer Coverage tracking).
+    # Lookup: the test files that cover `file:line`, or [] when none do.
+    # Per-file granularity; upgrade to per-method when throughput warrants
+    # (requires Minitest method isolation + finer Coverage tracking).
     def tests_for(file, line)
       @map["#{relativize(file)}:#{line}"] || []
     end
 
-    # #9: is this source file's empty coverage the result of an *errored* capture
-    # rather than a genuine coverage gap? True iff (KTD-2) some capture failed this
-    # run AND this file got zero coverage from any successful capture AND a failed
+    # Is this source file's empty coverage the result of an *errored* capture
+    # rather than a genuine coverage gap? True iff some capture failed this run
+    # AND this file got zero coverage from any successful capture AND a failed
     # test file maps to it by the standard _test/_spec naming convention. Derived
-    # purely from already-persisted state (@map keys + @failed_test_files); no rerun,
-    # no new cached field, no digest change.
+    # purely from already-persisted state (@map keys + @failed_test_files); no
+    # rerun, no new cached field, no digest change.
     #
-    # ponytail: file-level, convention-based attribution. A line covered only by a
-    # failed test in an otherwise-covered file stays no_coverage (condition 2), and
-    # a source with no naming-convention test match is never tainted. Upgrade path:
-    # persist per-file coverage per successful run and diff against the failed set,
-    # or record test->source targets explicitly. Not needed for the #8/#9 cases.
+    # File-level, convention-based attribution. A line covered only by a failed
+    # test in an otherwise-covered file stays no_coverage (condition 2), and a
+    # source with no naming-convention test match is never tainted. Upgrade path:
+    # persist per-file coverage per successful run and diff against the failed
+    # set, or record test->source targets explicitly.
     def uncapturable_source?(file)
       return false if @failed_test_files.empty?
 
@@ -104,14 +106,14 @@ module Mutineer
       failed_test_targets.include?(File.basename(rel, ".rb"))
     end
 
-    # #25: per-METHOD taint. A mutant on a line whose enclosing method got zero
+    # Per-method taint. A mutant on a line whose enclosing method got zero
     # successful coverage, in a file a failed sibling test targets, is
-    # :uncapturable (the capture that would have covered it errored) — NOT a
+    # :uncapturable (the capture that would have covered it errored), NOT a
     # genuine gap. A method with any covered line means its uncovered lines are a
     # real :no_coverage. A failed capture emits no coverage, so per-line intent is
-    # unknowable; method-range + successful coverage is the finest derivable signal.
-    # Fully-failed files behave exactly as uncapturable_source? did (every method
-    # range has zero coverage), so #8/#9/#19 behavior is unchanged.
+    # unknowable; method-range + successful coverage is the finest derivable
+    # signal. Fully-failed files behave exactly as uncapturable_source? did
+    # (every method range has zero coverage).
     #
     # @param file [String] source file path.
     # @param line_range [Range] 1-based enclosing-method line range.
@@ -155,7 +157,7 @@ module Mutineer
       self
     end
 
-    # Runs standalone Phase A coverage capture.
+    # Runs standalone coverage capture.
     #
     # @api private
     def run_phase_a
@@ -171,11 +173,11 @@ module Mutineer
       end
     end
 
-    # Boot-mode Phase A. For each test file, fork the booted parent; the child
+    # Boot-mode capture. For each test file, fork the booted parent; the child
     # resets its Coverage delta, runs that ONE test, and marshals back the raw
     # per-source coverage counts. record() inverts them exactly as the subprocess
-    # path does. ponytail: serial fork (one test at a time) — boot apps fork
-    # cheaply via COW and per-test isolation matters more than throughput here.
+    # path does. Serial fork (one test at a time): boot apps fork cheaply via COW
+    # and per-test isolation matters more than throughput here.
     def run_phase_a_via_fork(after_fork:)
       @phase_a_ran = true
       @map = {}
@@ -183,9 +185,9 @@ module Mutineer
       abs_sources = abs_source_paths
 
       @test_paths.each do |test_path|
-        # Tri-state payload (KTD-1): Hash = coverage, String = error diagnostic
-        # from the child, nil = pipe gone / empty.
-        # ponytail/#9: this String diagnostic is what #9 turns into an :uncapturable status.
+        # Tri-state payload: Hash = coverage, String = error diagnostic from the
+        # child, nil = pipe gone / empty. The String diagnostic is what becomes
+        # an :uncapturable status.
         case (coverage = fork_capture(absolute(test_path), abs_sources, after_fork))
         when Hash   then record(coverage, test_path)
         when String
@@ -201,7 +203,7 @@ module Mutineer
     # fork + Marshal-over-pipe + hard-exit! discipline as WorkerPool/Isolation.
     def fork_capture(abs_test, abs_sources, after_fork)
       rd, wr = IO.pipe
-      # #19: Marshal output is binary — an un-binmoded pipe can raise
+      # Marshal output is binary: an un-binmoded pipe can raise
       # Encoding::UndefinedConversionError on write, which the child's rescue then
       # swallows, losing the real error and yielding a bare "no result".
       rd.binmode
@@ -210,9 +212,9 @@ module Mutineer
         rd.close
         payload =
           begin
-            # Fork-safety hook: the in-process path reconnects AR; the daemon routes
-            # to its worker DB. Nil (non-Rails) = no-op. Injected so this file needs
-            # neither Runner (Prism) nor Rails.
+            # Fork-safety hook: the in-process path reconnects AR; the daemon
+            # routes to its worker DB. Nil (non-Rails) = no-op. Injected so this
+            # file needs neither Runner (Prism) nor Rails.
             after_fork&.call
             Coverage.result(clear: true, stop: false) # discard pre-test delta
             TestRunners.for(@framework).run([abs_test])
@@ -222,7 +224,7 @@ module Mutineer
                     .select { |f, _| abs_sources.include?(f) }
                     .transform_values { |v| v.is_a?(Hash) ? v[:lines] : v }
           rescue Exception => e # rubocop:disable Lint/RescueException
-            # KTD-1: stringify (an arbitrary Exception may not marshal); the parent
+            # Stringify (an arbitrary Exception may not marshal); the parent
             # surfaces this under --verbose. A String marshals safely over the pipe.
             "#{e.class}: #{e.message}#{e.backtrace&.first ? " @ #{e.backtrace.first}" : ''}"
           end
@@ -239,7 +241,7 @@ module Mutineer
       data = rd.read
       rd.close
       _, status = Process.waitpid2(pid)
-      # #19: an empty pipe means the child died before writing (e.g. a hard crash,
+      # An empty pipe means the child died before writing (e.g. a hard crash,
       # OOM, or a signal from the test's own subprocess handling). Report HOW it
       # died (exit status / signal) as a diagnostic string so --verbose has
       # something actionable instead of a silent "no result".
@@ -266,8 +268,8 @@ module Mutineer
 
     # Spawns a fresh `ruby` reading an inline script from stdin. A fork would
     # miss already-loaded app lines, so Coverage must start in a clean process
-    # before any source is loaded (KTD1/KTD2). Returns the parsed Coverage.result
-    # hash, or nil when the subprocess failed (logged + skipped per R6).
+    # before any source is loaded. Returns the parsed Coverage.result hash, or
+    # nil when the subprocess failed (logged + skipped).
     def capture(test_path)
       out = +""
       status = nil
@@ -275,8 +277,8 @@ module Mutineer
         stdin.write(subprocess_script(test_path))
         stdin.close
         reader = Thread.new { out << stdout.read }
-        # R3: bound the subprocess with a wall clock — a hanging test file must
-        # not wedge the whole run before any per-mutant timeout.
+        # Bound the subprocess with a wall clock: a hanging test file must not
+        # wedge the whole run before any per-mutant timeout.
         unless wait_thr.join(@capture_timeout)
           Process.kill(:KILL, wait_thr.pid) rescue nil # rubocop:disable Style/RescueModifier
           reader.kill
@@ -374,7 +376,7 @@ module Mutineer
       rel_test = relativize(test_path)
       coverage.each do |abs_file, data|
         rel = relativize(abs_file)
-        next if rel.start_with?("/") # outside project_root — not our source
+        next if rel.start_with?("/") # outside project_root: not our source
 
         counts = data.is_a?(Array) ? data : data["lines"]
         counts.each_with_index do |count, idx|
@@ -385,7 +387,7 @@ module Mutineer
       end
     end
 
-    # R4: digest each file's ROLE + relative path + content length + content, plus
+    # Digest each file's ROLE + relative path + content length + content, plus
     # the load_paths. Without role/path/length delimiters the digest collides
     # (("ab","c") == ("a","bc")) and is blind to source/test role swaps, silently
     # accepting a stale cached map.
@@ -426,7 +428,7 @@ module Mutineer
       end
     end
 
-    # R7: a configured source that resolves outside project_root would silently be
+    # A configured source that resolves outside project_root would silently be
     # dropped (its coverage relativizes to an absolute path). Warn instead.
     def warn_external_sources
       @source_paths.each do |p|
@@ -452,7 +454,7 @@ module Mutineer
 
       JSON.parse(File.read(cache_path))
     rescue JSON::ParserError
-      nil # corrupt cache — rebuild from scratch
+      nil # corrupt cache: rebuild from scratch
     end
 
     # Saves the coverage cache.

data/lib/mutineer/daemon_backend.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+require_relative "result"
+require_relative "coverage_map"
+require_relative "daemon_client"
+# No require_relative "runner" on purpose: runner.rb requires this file, and the
+# reverse edge makes Ruby warn "circular require considered harmful" on every -w
+# load. Runner is loaded first on every real path; requiring this file alone leaves
+# it undefined. Rationale and the real fix: #75.
+
+module Mutineer
+  # Daemon execution backend. Boots the app ONCE in a persistent subprocess under
+  # the app's own bundle and forks per mutant, so a Rails run pays the boot cost
+  # once instead of per mutant. Tool-side this only discovers jobs and builds the
+  # ready-to-`load` payload (Prism); the daemon needs no Prism/mutineer.
+  #
+  # When jobs > 1 each worker runs against its OWN database, which is what makes
+  # `--jobs N` safe under Rails (#26): parallel verdicts are identical to serial.
+  #
+  # Job collection, `--since` filtering and coverage selection stay on {Runner} and
+  # are called from here, so the daemon path can never drift from the in-process
+  # path on which mutants run or which tests narrow a mutant (score parity).
+  #
+  # Unlike {ExternalBackend}, which is a leaf {Runner} calls into, this module owns
+  # its orchestration and calls back for that shared vocabulary.
+  module DaemonBackend
+    # Default per-mutant timeout on the daemon path (seconds), overridden by
+    # config.daemon_timeout. Coverage narrowing usually keeps each job short; this
+    # still covers a slow suite or full-suite fallback when the map is unavailable.
+    # Named like its in-process counterpart {Isolation::DEFAULT_TIMEOUT}, not like
+    # {ExternalBackend::SMOKE_TIMEOUT}, which bounds a different thing.
+    DEFAULT_TIMEOUT = 60
+
+    # The daemon's per-mutant tempfile, written into the source dir so
+    # require_relative resolves. Kept in step with DaemonServer#sweep_temps.
+    DAEMON_TEMP_GLOB = "mutineer_daemon*.rb"
+
+    # Full daemon run: collect jobs, build the coverage map once, then execute
+    # serially or across N worker daemons. Fail-fast forces serial so the survivor
+    # set matches jobs 1.
+    #
+    # @param config [Mutineer::Config] run configuration (daemon set).
+    # @param operator_classes [Array<Class>] resolved operators.
+    # @return [Array(Mutineer::AggregateResult, Hash<String,String>)] aggregate and source map.
+    def self.execute(config, operator_classes)
+      jobs, ignored_results, source_map = Runner.collect_jobs(config, operator_classes)
+      jobs = Runner.filter_since(jobs, source_map, config) if config.since
+      abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
+
+      # Nothing to mutate (`--since` matched no changed line, or every mutant is
+      # suppressed). Return before booting anything: the coverage daemon and the
+      # worker daemons below each boot the whole app, and README documents
+      # `--since origin/<base>` for PR CI, where a docs-only PR is routine.
+      if jobs.empty?
+        # The daemon sweeps orphaned temps at boot and nothing boots here, so sweep
+        # tool-side. A file a hard-killed run left in app/models breaks the app's own
+        # Zeitwerk boot, not just Mutineer's next run.
+        Runner.sweep_orphans(Runner.source_dirs(config), DAEMON_TEMP_GLOB)
+        return [AggregateResult.new(ignored_results), source_map]
+      end
+
+      # Build the coverage map once (app-side). nil when the build fails: runners
+      # fall back to the full --test set (and emit a stderr warning) rather than
+      # mis-scoring everything as no_coverage.
+      coverage_map = build_coverage_map(config, abs_tests)
+
+      # Worker count = resolved --jobs, capped at the job count (no idle daemons).
+      # >1 → N concurrent daemon handles, each on its OWN worker DB (N-handles, the
+      # spike-proven shape). 1 → the serial single-daemon path. --fail-fast forces
+      # serial: parallel's stop flag fires on the first survivor by WALL-CLOCK, not
+      # input index, so the verdict set would diverge from serial (a different,
+      # non-deterministic survivor set/score). The "identical to --jobs 1" guarantee
+      # below only holds when fail-fast cannot race.
+      worker_count = [config.jobs || 1, 1].max
+      worker_count = 1 if config.fail_fast
+      worker_count = [worker_count, jobs.size].min
+
+      results =
+        if worker_count > 1
+          run_parallel(jobs, worker_count, config, abs_tests, coverage_map, source_map)
+        else
+          run_serial(jobs, config, abs_tests, coverage_map, source_map)
+        end
+
+      [AggregateResult.new(results + ignored_results), source_map]
+    end
+
+    # Build the coverage map via a short-lived daemon (boots the app once, captures
+    # per-test coverage app-side, ships the map back). Returns a query-only
+    # CoverageMap, or nil when the build fails / returns empty. Callers then run the
+    # full --test set. Coverage-build IPC has no wall-clock (same limitation as
+    # in-process build_via_fork). A normal nonempty map scores like in-process;
+    # nil falls back to the full suite (more testing, not comparable).
+    #
+    # @param config [Mutineer::Config] the run config.
+    # @param abs_tests [Array<String>] absolute --test paths.
+    # @return [Mutineer::CoverageMap, nil]
+    def self.build_coverage_map(config, abs_tests)
+      client = DaemonClient.new(boot: boot_config(config, abs_tests, coverage: true),
+                                app_root: config.project_root).start
+      data = begin
+        client.coverage
+      ensure
+        client.quit
+      end
+      unless data && !(data["map"] || {}).empty?
+        reason = data.is_a?(Hash) && data["error"] ? data["error"] : "empty map"
+        warn_coverage_fallback(reason)
+        return nil
+      end
+
+      CoverageMap.from_data(map: data["map"], failed_test_files: data["failed_test_files"] || [],
+                            project_root: config.project_root)
+    rescue DaemonBootError => e
+      warn_coverage_fallback("#{e.class}: #{e.message}")
+      nil
+    end
+
+    # Stderr note when daemon coverage is unavailable (full --test set per mutant).
+    #
+    # @api private
+    # @param reason [String] short cause (boot error message, empty map, …).
+    # @return [void]
+    def self.warn_coverage_fallback(reason = "unknown")
+      warn "[mutineer] daemon coverage map unavailable (#{reason}); running every " \
+           "mutant against the full --test set (score not comparable to an in-process run)."
+    end
+    private_class_method :warn_coverage_fallback
+
+    # Serial path: one daemon (worker 0), one mutant at a time. Honors --fail-fast
+    # (stop at the first survivor).
+    #
+    # @api private
+    # @return [Array<Mutineer::Result>] results in input order.
+    def self.run_serial(jobs, config, abs_tests, coverage_map, source_map)
+      client = DaemonClient.new(boot: boot_config(config, abs_tests),
+                                app_root: config.project_root).start
+      results = []
+      begin
+        jobs.each_with_index do |job, i|
+          r = job_result(job, i, client, 0, config, coverage_map, abs_tests, source_map)
+          results << r
+          break if config.fail_fast && r.survived?
+        end
+      ensure
+        client.quit
+      end
+      results
+    end
+
+    # Parallel path: N daemon handles, each pinned to its own worker slot (own DB).
+    # A shared queue of job indices feeds N tool-side threads; results are placed by
+    # input index so the verdict set matches serial. Callers must not pass fail_fast
+    # here ({execute} forces serial for fail-fast). Per-mutant crashes are classified
+    # in {job_result}, shared with the serial path; a {DaemonBootError} ends the run
+    # here rather than scoring the remainder against a daemon that has given up.
+    #
+    # @api private
+    # @return [Array<Mutineer::Result>] one result per input job, in input order.
+    def self.run_parallel(jobs, worker_count, config, abs_tests, coverage_map, source_map)
+      results = Array.new(jobs.size)
+      queue   = Queue.new
+      jobs.each_index { |i| queue << i }
+
+      # Built one at a time so a refused spawn part-way (EMFILE under a high --jobs)
+      # can still quit the daemons already up. Array.new would lose every reference.
+      clients = []
+      begin
+        worker_count.times do
+          clients << DaemonClient.new(boot: boot_config(config, abs_tests),
+                                      app_root: config.project_root).start
+        end
+      rescue StandardError
+        clients.each(&:quit)
+        raise
+      end
+
+      clients.each_with_index.map do |client, worker|
+        Thread.new do
+          # The abort below is re-raised by join and reported once there; without
+          # this Ruby also dumps the thread's backtrace, which the serial path never
+          # does. Same fault, same output, whatever --jobs is set to.
+          Thread.current.report_on_exception = false
+          loop do
+            i = begin
+              queue.pop(true)
+            rescue ThreadError
+              break
+            end
+            results[i] = job_result(jobs[i], i, client, worker, config, coverage_map, abs_tests, source_map)
+          end
+        rescue DaemonBootError
+          # The daemon gave up for good. Stop feeding the other workers rather
+          # than letting them score the rest of the run against a dead client;
+          # Thread#join re-raises this and ends the run.
+          queue.clear
+          raise
+        ensure
+          client.quit
+        end
+      end.each(&:join)
+
+      # Every job was popped by some worker and every pop assigns, so no slot can
+      # be nil here: an escaping exception aborts the run via join instead.
+      results
+    end
+
+    # Build the payload for one job, run it on the given daemon/worker, and attach
+    # the subject/mutation/id. Shared body of both daemon paths, so `--jobs 1` and
+    # `--jobs N` classify an identical fault identically.
+    #
+    # Error model, in one place because both paths call this: a crash while running
+    # ONE mutant is {DaemonClient}'s business: it respawns and answers `"error"`.
+    # Nothing is caught here on purpose — anything reaching this far is either
+    # {DaemonBootError}, which must end the run, or a defect, which must stay visible.
+    #
+    # @param job [Array(Mutineer::Subject, Mutineer::Mutation, String)] the work item.
+    # @param req_id [Integer] request id (echoed back for IPC ordering safety).
+    # @param client [Mutineer::DaemonClient] the daemon handle to run on.
+    # @param worker [Integer] the worker slot (→ worker DB) this daemon routes to.
+    # @api private
+    # @raise [Mutineer::DaemonBootError] when the daemon has given up; ends the run.
+    # @return [Mutineer::Result] the decorated result.
+    def self.job_result(job, req_id, client, worker, config, coverage_map, abs_tests, source_map)
+      subject, mutation, id = job
+      source  = source_map[subject.file]
+      mutated = mutation.apply(source)
+      # Skip an invalid mutant tool-side: never ship a payload that would fail to
+      # load and read as a false `killed`.
+      # Narrow to covering tests (shared with the in-process path via
+      # Runner.coverage_selection, so scores match). :verdict = no_coverage/uncapturable,
+      # no fork. No map (build failed) → run the full --test set (fallback, not
+      # narrowed).
+      sel = coverage_map && Runner.coverage_selection(subject.file, mutation, subject, source, coverage_map)
+      r =
+        if Parser.parse_string(mutated).errors.any?
+          Result.skipped
+        elsif sel && sel[0] == :verdict
+          sel[1]
+        else
+          verdict = client.request(
+            id: req_id, worker: worker, timeout: config.daemon_timeout || DEFAULT_TIMEOUT,
+            payload: { "code" => mutated, "source_file" => File.expand_path(subject.file, config.project_root) },
+            tests: sel ? sel[1] : abs_tests
+          )
+          result_for(verdict)
+        end
+      r.with(subject: subject, mutation: mutation, id: id)
+    end
+
+    # The boot config the daemon needs to boot the app once: where to boot, the test
+    # load roots (so `require "test_helper"` resolves in every fork), framework, and
+    # whether this is Rails.
+    #
+    # @param config [Mutineer::Config] the run config.
+    # @param abs_tests [Array<String>] absolute --test paths.
+    # @param coverage [Boolean] whether this daemon builds the coverage map.
+    # @return [Hash] the boot config shipped to the daemon.
+    def self.boot_config(config, abs_tests, coverage: false)
+      {
+        project_root: config.project_root,
+        boot: File.expand_path(config.boot || "config/environment", config.project_root),
+        load_paths: Runner.test_load_roots(abs_tests),
+        source_dirs: Runner.source_dirs(config), # so the daemon can sweep orphan mutant temps
+        framework: config.framework,
+        rails: config.rails,
+        # Schema for per-worker DB isolation. Sent when present; the daemon
+        # skips worker-DB schema loading if the path is absent (e.g. structure.sql apps).
+        schema: schema_path(config),
+        # Coverage narrowing. Only the short-lived map-building daemon starts
+        # Coverage (before boot); worker daemons boot with it OFF (no wasted
+        # instrumentation/memory across every mutant fork). `sources`/`tests` are the
+        # map-build inputs.
+        coverage: coverage,
+        sources: config.sources.map { |s| File.expand_path(s, config.project_root) },
+        tests: abs_tests
+      }
+    end
+
+    # Absolute path to the app's `db/schema.rb` if it exists, else nil. Used by the
+    # daemon to schema-load each fork's isolated worker database. Only `schema.rb`
+    # is supported this pass; `structure.sql` apps get nil and fall back to
+    # whatever the worker DB already holds.
+    #
+    # @param config [Mutineer::Config] the run config.
+    # @api private
+    # @return [String, nil] absolute schema path or nil.
+    def self.schema_path(config)
+      path = File.expand_path("db/schema.rb", config.project_root)
+      File.exist?(path) ? path : nil
+    end
+
+    # Map a daemon verdict string to a Result. The daemon reports the four
+    # run-time states it can decide; pre-fork states (skipped/no_coverage/…) are
+    # resolved tool-side before a request is ever sent.
+    #
+    # @param verdict [String] the daemon's verdict word.
+    # @api private
+    # @return [Mutineer::Result] the matching result.
+    def self.result_for(verdict)
+      case verdict
+      when "survived" then Result.survived
+      when "killed"   then Result.killed
+      when "timeout"  then Result.timeout
+      else Result.error("daemon verdict: #{verdict}")
+      end
+    end
+
+    # The module's contract is {execute} (the backend entry point) plus the two the
+    # tests drive directly: {boot_config} from the zero-dep suite and
+    # {build_coverage_map} from the daemon suite. Everything else is daemon-pipeline
+    # internals with no caller outside this file.
+    private_class_method :run_serial, :run_parallel, :job_result, :schema_path, :result_for
+  end
+end