mutineer 0.9.1 → 0.11.0

data/lib/mutineer/rails_worker_db.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # #26/#27 Phase 2b (U5) — per-worker database isolation for the daemon path.
+  #
+  # Loaded APP-SIDE by {DaemonServer} (a sibling gem file, pulled in by absolute path
+  # so it bypasses the app bundle — the same trick {DaemonClient} uses to run
+  # `daemon_server.rb` under a bundle that has no mutineer). It uses the app's OWN
+  # already-booted ActiveRecord and NEVER `require "active_record"` (R10/KTD-8): every
+  # method that touches AR first confirms {available?}, so the daemon core stays
+  # framework-agnostic and the gem keeps its zero-runtime-dependency promise.
+  #
+  # Isolation model (KTD-7): each parallel worker gets its OWN database so concurrent
+  # forks can't clobber each other's transactional fixtures (the measured #26
+  # corruption). {after_fork} runs inside a freshly-forked child and points that
+  # child's connection at the worker's database BEFORE any test loads; transactional
+  # fixtures then repopulate that isolated database per test.
+  #
+  # Scope: this pass ships the **SQLite** adapter (per-worker file, hermetic,
+  # spike-proven). Postgres per-worker provisioning (`CREATE DATABASE <db>-<worker>` —
+  # the measured corruption case) extends {worker_db_config}/{provision} at the marked
+  # seam in U10; until then a non-SQLite config raises a clear NotImplementedError
+  # rather than silently mis-routing.
+  #
+  # Honest limit (KTD-5): routing failures surface as `error` via {verify_connection!}.
+  # Re-raising an AR error that fires *inside a test body* past Minitest (so an in-test
+  # DB failure is `error`, not `killed`) is only observable under concurrent load and
+  # is deferred to U6 with the parallel gate — noted, not silently skipped.
+  module RailsWorkerDb
+    # True when the app has ActiveRecord loaded — the only condition under which any
+    # other method here may touch AR. Never triggers an autoload/require of AR itself.
+    #
+    # @return [Boolean]
+    def self.available?
+      defined?(ActiveRecord::Base) ? true : false
+    end
+
+    # Derive a per-worker database path from a base path by inserting `-<worker>`
+    # before the extension. Pure string transform (no AR) so it is unit-testable in
+    # the zero-dep suite. `storage/test.sqlite3`, worker 1 -> `storage/test-1.sqlite3`.
+    #
+    # @param database [String] the base database path.
+    # @param worker [Integer] the worker slot index (0..N-1).
+    # @return [String] the per-worker database path.
+    def self.worker_database_path(database, worker)
+      ext = File.extname(database)
+      "#{database.delete_suffix(ext)}-#{worker}#{ext}"
+    end
+
+    # Build the AR connection config for one worker by copying the app's current
+    # (default test) config and swapping in the per-worker database path. SQLite only
+    # this pass — a non-SQLite adapter raises so the SQLite-first scope fails loud
+    # instead of mis-routing (Postgres is U10).
+    #
+    # @param worker [Integer] the worker slot index.
+    # @return [Hash] a symbol-keyed AR configuration hash for the worker database.
+    # @raise [NotImplementedError] when the app's database is non-SQLite or in-memory.
+    def self.worker_db_config(worker)
+      hash    = ActiveRecord::Base.connection_db_config.configuration_hash
+      adapter = hash[:adapter].to_s
+      # U10 seam: the config-SHAPING below (per_worker_config) is already
+      # adapter-general — it derives correct SQLite *and* Postgres worker-DB names.
+      # What's gated is runtime PROVISIONING: SQLite files are created on connect,
+      # but Postgres needs an explicit `CREATE DATABASE` per worker (U10). Until that
+      # lands, refuse non-SQLite loudly rather than route to a database that doesn't
+      # exist. To finish U10: implement provision() for PG and drop this guard.
+      unless adapter.start_with?("sqlite")
+        raise NotImplementedError,
+              "worker-DB isolation currently provisions SQLite only (got adapter #{adapter.inspect}); " \
+              "Postgres per-worker provisioning is U10 (#26/#35) — use a SQLite test DB, or drop --jobs."
+      end
+
+      per_worker_config(hash, worker)
+    end
+
+    # Pure config-shaping (no AR): given a connection config hash, return the
+    # per-worker variant with its database swapped to the worker's own name.
+    # Adapter-general — SQLite (`storage/test.sqlite3` → `storage/test-<w>.sqlite3`)
+    # and Postgres (`myapp_test` → `myapp_test-<w>`, Rails `parallelize` naming) both
+    # fall out of {worker_database_path}. Extracted + unit-tested so the Postgres
+    # SHAPE is proven ready for U10 without a live database.
+    #
+    # @param config_hash [Hash] a connection config hash (symbol or string keys).
+    # @param worker [Integer] the worker slot index.
+    # @return [Hash] the per-worker config (symbol keys), database swapped.
+    # @raise [NotImplementedError] for an in-memory or empty database (no per-worker split).
+    def self.per_worker_config(config_hash, worker)
+      hash     = config_hash.transform_keys(&:to_sym)
+      database = hash[:database].to_s
+      if database.empty? || database == ":memory:"
+        raise NotImplementedError,
+              "worker-DB isolation needs a file/name-backed database (got #{database.inspect})."
+      end
+
+      hash.merge(database: worker_database_path(database, worker))
+    end
+
+    # Child-side (after fork): route this process's ActiveRecord at the worker's own
+    # database and confirm it is reachable, so a routing failure reads as `error`
+    # (via the daemon's child rescue) rather than a false verdict. Loads the schema
+    # into the worker database when a schema path is given (idempotent — schema.rb
+    # runs with `force: true`), covering a fresh worker file.
+    #
+    # @param worker [Integer] the worker slot index.
+    # @param schema_path [String, nil] absolute path to `db/schema.rb`, or nil to skip.
+    # @return [void]
+    def self.after_fork(worker, schema_path = nil)
+      return unless available?
+
+      ActiveRecord::Base.establish_connection(worker_db_config(worker))
+      load_schema(schema_path) if schema_path
+      verify_connection!
+    end
+
+    # Explicit, parent-side provisioning: create + schema-load every worker database
+    # up front, then restore the app's default connection. This is the EXPLICIT
+    # provisioning entry point (V2 — never silent auto-create mid-audit) and the seam
+    # U10 extends for Postgres (`CREATE DATABASE` per worker). For SQLite the files are
+    # created on connect and the schema load makes them ready; idempotent to re-run.
+    #
+    # @param worker_count [Integer] number of worker databases to provision.
+    # @param schema_path [String, nil] absolute path to `db/schema.rb`, or nil to skip.
+    # @return [void]
+    def self.provision(worker_count, schema_path)
+      return unless available?
+
+      original = ActiveRecord::Base.connection_db_config
+      (0...worker_count).each do |worker|
+        ActiveRecord::Base.establish_connection(worker_db_config(worker))
+        load_schema(schema_path) if schema_path
+      end
+    ensure
+      ActiveRecord::Base.establish_connection(original) if original
+    end
+
+    # Load a Rails `schema.rb` into the current connection with its output silenced,
+    # so a parent-side {provision} call can never spill schema chatter onto the daemon
+    # IPC pipe. (In a fork the child's stdout is already `File::NULL`; this guards the
+    # parent path too.)
+    #
+    # @param schema_path [String] absolute path to `db/schema.rb`.
+    # @return [void]
+    def self.load_schema(schema_path)
+      ActiveRecord::Migration.verbose = false if defined?(ActiveRecord::Migration)
+      original = $stdout
+      $stdout = File.open(File::NULL, "w")
+      load schema_path
+    ensure
+      $stdout.close unless $stdout.equal?(original)
+      $stdout = original
+    end
+
+    # Force a round-trip to the freshly-routed connection so a broken route fails HERE
+    # (→ `error`) instead of later masquerading as a test failure (→ false `killed`).
+    #
+    # @return [void]
+    def self.verify_connection!
+      ActiveRecord::Base.connection.execute("SELECT 1")
+    end
+  end
+end

data/lib/mutineer/runner.rb

@@ -11,6 +11,9 @@ require_relative "changed_lines"
 require_relative "mutator_registry"
 require_relative "worker_pool"
 require_relative "mutant_id"
+require_relative "file_swap"
+require_relative "external_backend"
+require_relative "daemon_client"
 require "set"
 
 module Mutineer
@@ -38,6 +41,16 @@ module Mutineer
     def self.execute(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
 
+      # #27: the external backend runs the suite as a subprocess in the app's own
+      # runtime — it does no in-process boot/require or coverage build, so branch
+      # before any of that. The in-process path below is untouched.
+      return execute_external(config, operator_classes) if config.test_command
+
+      # #26/#27 Phase 2a: the daemon backend boots the app ONCE in a persistent
+      # subprocess under the app's bundle and forks per mutant. Tool-side we only
+      # discover jobs + build payloads (Prism), so branch before any in-process boot.
+      return execute_daemon(config, operator_classes) if config.daemon
+
       # Boot mode: require the boot file ONCE so the app env (e.g. Rails) is booted
       # in the parent and inherited by every fork. Do NOT manually require the
       # sources — under Zeitwerk a manual require of an autoloadable file raises;
@@ -77,7 +90,7 @@ module Mutineer
           load_paths: config.load_paths, framework: config.framework,
           boot_path: File.expand_path(config.boot, config.project_root),
           verbose: config.verbose
-        ).build_via_fork(rails: config.rails)
+        ).build_via_fork(after_fork: (config.rails ? -> { reconnect_active_record } : nil))
       else
         coverage_map = CoverageMap.new(
           source_paths: config.sources, test_paths: config.tests,
@@ -87,11 +100,49 @@ module Mutineer
       end
 
       # Collect every (subject, mutation) up front so the pool can fan them out.
-      # #10: a mutant the user marked known-equivalent (inline disable-line comment
-      # or .mutineer.yml ignore id) is classified :ignored here and NEVER forked —
-      # it is removed from the killed+survived denominator so a strong file reaches
-      # 100%. The stable id is computed per subject (occurrence needs the full list)
-      # and carried on every job so the parent can reattach it after the run.
+      jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
+
+      jobs = filter_since(jobs, source_map, config) if config.since
+
+      # C3: 7a writes mutineer_mutant*.rb into each source dir (so require_relative
+      # resolves). A SIGKILL'd child skips the tempfile's ensure-unlink, orphaning
+      # it. `ensure` is unreliable vs SIGKILL, so the PARENT sweeps each source dir
+      # before and after the run — orphans are impossible after a normal run.
+      dirs = source_dirs(config)
+      sweep_orphans(dirs)
+
+      strategy = config.strategy
+      results =
+        begin
+          framework = config.framework
+          # #21: --fail-fast stops scheduling new mutants after the first survivor;
+          # in-flight workers drain, unscheduled jobs stay nil (dropped below).
+          stop_when = config.fail_fast ? ->(r) { r.survived? } : nil
+          bare = WorkerPool.new(config.jobs).run(jobs, stop_when: stop_when) do |subject, mutation|
+            run(mutation, source_file: subject.file, coverage_map: coverage_map,
+                subject: subject, strategy: strategy, rails: config.rails, framework: framework)
+          end
+          # The bare Results carry only status (Subjects hold live AST nodes that
+          # do not marshal); reattach subject+mutation+id in the parent, in order.
+          # filter_map drops nils for jobs --fail-fast left unscheduled.
+          bare.each_with_index.filter_map { |r, i| r&.with(subject: jobs[i][0], mutation: jobs[i][1], id: jobs[i][2]) }
+        ensure
+          sweep_orphans(dirs)
+        end
+
+      [AggregateResult.new(results + ignored_results), source_map]
+    end
+
+    # Collect every (subject, mutation, id) up front so a backend can run them.
+    # #10: a mutant the user marked known-equivalent (inline disable-line comment
+    # or .mutineer.yml ignore id) is classified :ignored here and NEVER run — it is
+    # removed from the killed+survived denominator so a strong file reaches 100%.
+    # The stable id is computed per subject (occurrence needs the full list) and
+    # carried on every job so the parent can reattach it after the run. Shared by
+    # the in-process and external (#27) backends so job selection can never drift.
+    #
+    # @return [Array(Array, Array<Result>, Hash<String,String>)] jobs, ignored, source_map.
+    def self.collect_jobs(config, operator_classes)
       source_map = {}
       disabled_map = {}
       ignore_set = config.ignore.to_set
@@ -112,37 +163,326 @@ module Mutineer
           end
         end
       end
+      [jobs, ignored_results, source_map]
+    end
 
+    # #27: external backend orchestration. Runs each mutant's whole-file mutation on
+    # disk (crash-safe swap) and executes the user's --test-command as a subprocess
+    # in the app's own runtime. Serial by construction (KTD-5: one shared DB, no
+    # per-worker isolation yet). No coverage narrowing — every mutant runs the full
+    # --test set (KTD-6); the score is therefore an upper bound and not comparable
+    # to an in-process run (the CLI discloses this).
+    #
+    # @param config [Mutineer::Config] run configuration (test_command set).
+    # @param operator_classes [Array<Class>] resolved operators.
+    # @return [Array(Mutineer::AggregateResult, Hash<String,String>)] aggregate and source map.
+    def self.execute_external(config, operator_classes)
+      abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
+      dirs      = source_dirs(config)
+
+      # Heal any file a prior hard-killed run left mutated BEFORE reading source —
+      # collect_jobs computes mutation offsets/ids from the on-disk bytes, so a
+      # still-mutated file would yield garbage offsets against the later-healed
+      # source. Heal first, then discover jobs from the clean tree.
+      FileSwap.restore_orphans(dirs)
+
+      jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
       jobs = filter_since(jobs, source_map, config) if config.since
 
-      # C3: 7a writes mutineer_mutant*.rb into each source dir (so require_relative
-      # resolves). A SIGKILL'd child skips the tempfile's ensure-unlink, orphaning
-      # it. `ensure` is unreliable vs SIGKILL, so the PARENT sweeps each source dir
-      # before and after the run — orphans are impossible after a normal run.
-      source_dirs = config.sources
-                          .map { |f| File.dirname(File.expand_path(f, config.project_root)) }.uniq
-      sweep_orphans(source_dirs)
+      # Calibrate the per-mutant timeout from the clean run (a real suite far
+      # outlasts the 10s in-process fork budget), and abort if it isn't green.
+      # ponytail: 3x the clean run, floor 30s, ceiling 300s — a heuristic. The
+      # floor covers a fast suite; the ceiling bounds a hung mutant (infinite loop)
+      # so a handful can't stall a serial run for ~45min on a slow suite.
+      smoke_elapsed = ExternalBackend.smoke_check!(config.test_command, abs_tests)
+      timeout = [[smoke_elapsed * 3, 30].max, 300].min.ceil
+
+      results = []
+      begin
+        jobs.each do |subject, mutation, id|
+          r = run_external(subject, mutation, config.test_command, abs_tests,
+                           timeout: timeout, verbose: config.verbose)
+          results << r.with(subject: subject, mutation: mutation, id: id)
+          break if config.fail_fast && r.survived? # #21: stop at the first survivor
+        end
+      ensure
+        FileSwap.restore_orphans(dirs)
+      end
+
+      [AggregateResult.new(results + ignored_results), source_map]
+    end
+
+    # Runs one mutant through the external backend: apply the whole-file mutation on
+    # disk, run the command, restore. KTD-8: an invalid (non-reparsing) mutant would
+    # fail to load and score a false `killed`, so skip it tool-side (Prism, already
+    # cheap) and never write the file — preserving the `skipped` verdict the
+    # in-process path gives at runner.rb's pre-fork check.
+    #
+    # @return [Mutineer::Result] verdict for this mutant.
+    def self.run_external(subject, mutation, command, abs_tests, timeout:, verbose:)
+      source  = File.read(subject.file)
+      mutated = mutation.apply(source)
+      return Result.skipped if Parser.parse_string(mutated).errors.any?
+
+      FileSwap.with(subject.file, mutated) do
+        ExternalBackend.run(command, abs_tests, timeout: timeout, verbose: verbose)
+      end
+    end
+
+    # #26/#27 Phase 2a — daemon backend orchestration (serial). Boots the app ONCE in
+    # a persistent subprocess and forks per mutant, restoring the one-boot speed the
+    # Phase 1 subprocess path gives up. Tool-side we build the ready-to-`load` payload
+    # (KTD-2/KTD-3: whole-file reload by default — the spike-proven path) and ship it;
+    # the daemon needs no Prism/mutineer. Serial in 2a (worker-DB isolation +
+    # parallelism is Phase 2b). No coverage narrowing yet (Phase 2c), so every mutant
+    # runs the full `--test` set.
+    #
+    # @return [Array(Mutineer::AggregateResult, Hash<String,String>)] aggregate and source map.
+    def self.execute_daemon(config, operator_classes)
+      jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
+      jobs = filter_since(jobs, source_map, config) if config.since
+      abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
+
+      # #26/U7: build the coverage map once (app-side, via a short-lived daemon) so
+      # each mutant runs ONLY its covering tests and a mutant on an uncovered line is
+      # no_coverage. nil when the build fails — the runners fall back to the full
+      # --test set (no narrowing) rather than mis-scoring everything as no_coverage.
+      coverage_map = daemon_coverage_map(config, abs_tests)
+
+      # #26/U6: worker count = resolved --jobs, capped at the job count (no idle
+      # daemons). >1 → N concurrent daemon handles, each on its OWN worker DB (V6:
+      # 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 can't race.
+      worker_count = [config.jobs || 1, 1].max
+      worker_count = 1 if config.fail_fast
+      worker_count = [worker_count, jobs.size].min if jobs.size.positive?
 
-      strategy = config.strategy
       results =
-        begin
-          framework = config.framework
-          # #21: --fail-fast stops scheduling new mutants after the first survivor;
-          # in-flight workers drain, unscheduled jobs stay nil (dropped below).
-          stop_when = config.fail_fast ? ->(r) { r.survived? } : nil
-          bare = WorkerPool.new(config.jobs).run(jobs, stop_when: stop_when) do |subject, mutation|
-            run(mutation, source_file: subject.file, coverage_map: coverage_map,
-                subject: subject, strategy: strategy, rails: config.rails, framework: framework)
+        if worker_count > 1
+          run_daemon_parallel(jobs, worker_count, config, abs_tests, coverage_map, source_map)
+        else
+          run_daemon_serial(jobs, config, abs_tests, coverage_map, source_map)
+        end
+
+      [AggregateResult.new(results + ignored_results), source_map]
+    end
+
+    # #26/U7: 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 (no narrowing) rather than mis-scoring. The dedicated daemon
+    # costs one extra boot; correctness over that boot (ponytail — the map is reused
+    # for every mutant).
+    #
+    # @param config [Mutineer::Config] the run config.
+    # @param abs_tests [Array<String>] absolute --test paths.
+    # @return [Mutineer::CoverageMap, nil]
+    #
+    # ponytail: the coverage-build IPC read is unbounded (no wall-clock) — a --test
+    # file that infinite-loops during capture wedges this call, mirroring the existing
+    # in-process build_via_fork limitation. A capture timeout is a follow-up. When the
+    # map comes back empty (all captures failed), this returns nil and the run falls
+    # back to the FULL --test set per mutant — so on a total capture failure the daemon
+    # score is an upper bound (more testing), diverging from the in-process no_coverage
+    # scoring for that degenerate case only; a normal (nonempty) map scores identically.
+    def self.daemon_coverage_map(config, abs_tests)
+      client = DaemonClient.new(boot: daemon_boot_config(config, abs_tests, coverage: true),
+                                app_root: config.project_root).start
+      data = begin
+        client.coverage
+      ensure
+        client.quit
+      end
+      return nil unless data && !(data["map"] || {}).empty?
+
+      CoverageMap.from_data(map: data["map"], failed_test_files: data["failed_test_files"] || [],
+                            project_root: config.project_root)
+    rescue DaemonBootError
+      nil
+    end
+
+    # Serial daemon path: one daemon (worker 0), one mutant at a time. Honors
+    # --fail-fast (#21: stop at the first survivor).
+    #
+    # @return [Array<Mutineer::Result>] results in input order.
+    def self.run_daemon_serial(jobs, config, abs_tests, coverage_map, source_map)
+      client = DaemonClient.new(boot: daemon_boot_config(config, abs_tests),
+                                app_root: config.project_root).start
+      results = []
+      begin
+        jobs.each_with_index do |job, i|
+          r = daemon_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 daemon path (#26/U6): N daemon handles, each pinned to its own worker
+    # slot (→ its own DB, so concurrent workers can't clobber each other's fixtures).
+    # A shared queue of job indices feeds N tool-side threads; each thread blocks on
+    # IPC (GVL released), so the N daemons run genuinely concurrently. Results are
+    # placed by input index and compacted, so the verdict SET is identical to serial
+    # regardless of finish order (R7). `execute_daemon` never calls this with
+    # `config.fail_fast` set (forced to the serial path instead) — a wall-clock stop
+    # here, unlike serial's input-index break, would make the survivor set and score
+    # non-deterministic. The stop-flag machinery below stays as a defensive no-op for
+    # any direct caller that bypasses that guard.
+    #
+    # @return [Array<Mutineer::Result>] completed results in input order.
+    def self.run_daemon_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 }
+      stop       = false
+      stop_mutex = Mutex.new
+
+      clients = Array.new(worker_count) do
+        DaemonClient.new(boot: daemon_boot_config(config, abs_tests),
+                         app_root: config.project_root).start
+      end
+
+      clients.each_with_index.map do |client, worker|
+        Thread.new do
+          until stop_mutex.synchronize { stop }
+            i = begin
+              queue.pop(true) # non-blocking; ThreadError when drained
+            rescue ThreadError
+              break
+            end
+            r = daemon_job_result(jobs[i], i, client, worker, config, coverage_map, abs_tests, source_map)
+            results[i] = r
+            stop_mutex.synchronize { stop = true } if config.fail_fast && r.survived?
           end
-          # The bare Results carry only status (Subjects hold live AST nodes that
-          # do not marshal); reattach subject+mutation+id in the parent, in order.
-          # filter_map drops nils for jobs --fail-fast left unscheduled.
-          bare.each_with_index.filter_map { |r, i| r&.with(subject: jobs[i][0], mutation: jobs[i][1], id: jobs[i][2]) }
         ensure
-          sweep_orphans(source_dirs)
+          client.quit
         end
+      end.each(&:join)
 
-      [AggregateResult.new(results + ignored_results), source_map]
+      results.compact
+    end
+
+    # Build the payload for one job, run it on the given daemon/worker, and attach
+    # the subject/mutation/id — the shared body of both daemon paths.
+    #
+    # @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.
+    # @return [Mutineer::Result] the decorated result.
+    def self.daemon_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)
+      # KTD-8 (carried): skip an invalid mutant tool-side — never ship a payload that
+      # would fail to load and read as a false `killed`.
+      # #26/U7: narrow to covering tests (shared with the in-process path via
+      # 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 && 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 || DAEMON_TIMEOUT,
+            payload: { "code" => mutated, "source_file" => File.expand_path(subject.file, config.project_root) },
+            tests: sel ? sel[1] : abs_tests
+          )
+          daemon_result(verdict)
+        end
+      r.with(subject: subject, mutation: mutation, id: id)
+    end
+
+    # Coverage-based test selection, shared by the in-process ({run}) and daemon
+    # paths so both narrow identically (score parity, U7/V5). Returns
+    # `[:run, abs_test_paths]` when some test covers the mutant's line, or
+    # `[:verdict, Result]` (no_coverage / uncapturable) when none do.
+    #
+    # #9/#25: an empty selection is `:uncapturable` (not `:no_coverage`) when the
+    # mutant's enclosing method body got coverage from no *successful* capture but a
+    # sibling test failed to capture — the coverage was lost, not absent. Both are
+    # excluded from the score denominator, so this distinction is reporting-only and
+    # never changes the daemon-vs-in-process score.
+    #
+    # @param source_file [String] the mutated source file path.
+    # @param mutation [Mutineer::Mutation] the mutation (for its line offset).
+    # @param subject [Mutineer::Subject, nil] the subject (for its method body range).
+    # @param source [String] the original source text.
+    # @param coverage_map [Mutineer::CoverageMap] the built/loaded coverage map.
+    # @return [Array(Symbol, Object)] `[:run, Array<String>]` or `[:verdict, Result]`.
+    def self.coverage_selection(source_file, mutation, subject, source, coverage_map)
+      line   = source.byteslice(0, mutation.start_offset).count("\n") + 1
+      chosen = coverage_map.tests_for(source_file, line)
+      if chosen.empty?
+        # Method BODY range, not the whole def: the def/end lines are "covered" at
+        # class-load even when the body never runs (body_loc is the statements' span).
+        loc   = subject&.body_loc
+        range = loc ? (loc.start_line..loc.end_line) : (line..line)
+        return [:verdict, coverage_map.method_uncapturable?(source_file, range) ? Result.uncapturable : Result.no_coverage]
+      end
+
+      [:run, chosen.map { |t| File.expand_path(t, coverage_map.project_root) }]
+    end
+
+    # Default per-mutant timeout on the daemon path. Generous because 2a runs the full
+    # `--test` set per mutant (no coverage narrowing until Phase 2c).
+    DAEMON_TIMEOUT = 60
+
+    # 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.
+    def self.daemon_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: test_load_roots(abs_tests),
+        source_dirs: source_dirs(config), # so the daemon can sweep orphan mutant temps
+        framework: config.framework,
+        rails: config.rails,
+        # #26/U5: 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: daemon_schema_path(config),
+        # #26/U7: 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 (#26/U5). Only
+    # `schema.rb` is supported this pass; `structure.sql` apps get nil and fall back to
+    # whatever the worker DB already holds (Postgres provisioning is U10).
+    #
+    # @param config [Mutineer::Config] the run config.
+    # @return [String, nil] absolute schema path or nil.
+    def self.daemon_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 (KTD-5); pre-fork states (skipped/no_coverage/…) are
+    # resolved tool-side before a request is ever sent.
+    def self.daemon_result(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
 
     # Scan a source once into { line_number => :all | Set[operator_syms] } from
@@ -222,6 +562,17 @@ module Mutineer
       warn "[mutineer] RAILS_ENV was unset; defaulting to 'test' for --rails."
     end
 
+    # The unique absolute directories holding the sources — the sweep target for
+    # both orphan mechanisms (in-process mutant tempfiles and external backup
+    # files). Shared so the path-expansion rule can't drift between the two paths.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [Array<String>] unique absolute source directories.
+    def self.source_dirs(config)
+      config.sources.map { |f| File.dirname(File.expand_path(f, config.project_root)) }.uniq
+    end
+
     # Removes stale mutant tempfiles from the given directories.
     #
     # @api private
@@ -256,24 +607,12 @@ module Mutineer
 
       # Coverage selection (both standalone and boot mode): a mutation on a line
       # no test exercises is :no_coverage (no fork); otherwise exactly the
-      # covering test files run in the child.
-      line   = source.byteslice(0, mutation.start_offset).count("\n") + 1
-      chosen = coverage_map.tests_for(source_file, line)
-      # #9/#25: distinguish a genuine coverage gap from a line whose would-be test
-      # errored during capture (coverage lost) — the latter is :uncapturable.
-      # #25: taint per-METHOD (the mutant's enclosing def range), not whole-file,
-      # so a covered method's uncovered line stays :no_coverage while a method
-      # reachable only by a failed capture is :uncapturable.
-      if chosen.empty?
-        # Use the method BODY range, not the whole def: the `def`/`end` lines are
-        # "covered" at class-load even when the body never runs, which would mask
-        # an uncovered method. body_loc is the body statements' span.
-        loc = subject&.body_loc
-        range = loc ? (loc.start_line..loc.end_line) : (line..line)
-        return coverage_map.method_uncapturable?(source_file, range) ? Result.uncapturable : Result.no_coverage
-      end
+      # covering test files run in the child. Shared with the daemon path so both
+      # narrow identically (score parity, U7/V5).
+      kind, payload = coverage_selection(source_file, mutation, subject, source, coverage_map)
+      return payload if kind == :verdict
 
-      abs_tests = chosen.map { |t| File.expand_path(t, coverage_map.project_root) }
+      abs_tests = payload
 
       Isolation.run(timeout: timeout) do
         # Forking inherits the parent's live DB connection; sharing one socket

data/lib/mutineer/version.rb

@@ -2,5 +2,5 @@
 
 module Mutineer
   # Current Mutineer release version.
-  VERSION = "0.9.1"
+  VERSION = "0.11.0"
 end