mutineer 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92b74299812649a42303c4387412bd3bd67014e7e91c656df36489836773ae08
-  data.tar.gz: 20c25fed6e5a490deb8d5f9068cd47187efe16fdfa0625a18e9e1fe7296b17f6
+  metadata.gz: 2dd1784f527b49eaed8d13a3e03c59c8a30082a44cf625f3a6ce1f252ffb3a60
+  data.tar.gz: 164d53165ea6f85c31158783ea43f8f2c88c3df058240d748df01f960da23897
 SHA512:
-  metadata.gz: 0d838506311eff5c879ee9b23701a995c112a84ce4d7e0cfa9d1b43788ff39eb39cfafcbc4111db1547feb5f5874c0f5e07489f2c7597235c3cd37ef360d407f
-  data.tar.gz: 15ec124714bb63d42a2ac95e5ea8582f4329f7577e8fabfe7e544fe062e5667b60bcb9b3d07b167e731c3b7980a7c71ed18f368b7c8fe4d32d20f28021e0cdb0
+  metadata.gz: a8bcaae29c133ca1ac0f9da31dc143b7b5deeef347104e209386cf6029252e77586d1240440e97bcec082e9e11a355087ffda91e7ca5495de85ac0f6bf1c2155
+  data.tar.gz: 06f108bfbb0f4b32318ca120e086ce88516b036ebc622e37b81963f4f93b7a87d5cdb6403b95cd69aa7a196e910718ba52b632d376a10f2763bf05f9f94a8fc8

data/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-02
+
+### Added
+- **`--daemon` backend — fast, parallel-safe Rails mutation testing** (#26/#27
+  Phase 2). Boots the app **once** in a persistent daemon and forks per mutant
+  (restoring shared-boot speed), and gives **each parallel worker its own
+  database** so `--jobs N` is safe under Rails for the first time — parallel
+  verdicts are proven identical to serial (no fixture cross-talk). Coverage
+  narrowing is restored on this path (each mutant runs only its covering tests;
+  a mutant on an uncovered line is `no_coverage`), so the daemon score is
+  comparable to the in-process `--rails` score. Opt in with `--rails --daemon`
+  (also `daemon: true` in `.mutineer.yml`); `--daemon` can't be combined with
+  `--test-command`. **SQLite** today (hermetic, CI-proven); **Postgres**
+  per-worker provisioning is in progress (#34/#35). The gem core stays Prism +
+  stdlib, zero runtime dependencies — worker-DB routing uses the app's own
+  ActiveRecord.
+
 ## [0.10.0] - 2026-07-02
 
 ### Added
@@ -200,6 +217,8 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[0.11.0]: https://github.com/davidteren/mutineer/releases/tag/v0.11.0
+[0.10.0]: https://github.com/davidteren/mutineer/releases/tag/v0.10.0
 [0.9.1]: https://github.com/davidteren/mutineer/releases/tag/v0.9.1
 [0.9.0]: https://github.com/davidteren/mutineer/releases/tag/v0.9.0
 [0.8.0]: https://github.com/davidteren/mutineer/releases/tag/v0.8.0

data/README.md

@@ -57,6 +57,7 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 | `--verbose` | Surface the real error when a fork capture fails (alias `--debug`) |
 | `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
 | `--test-command CMD` | Run the suite as a subprocess in the app's own runtime (for apps on Ruby < 3.4); `CMD` must contain `%{files}`. See [Apps on Ruby < 3.4](#apps-on-ruby--34) |
+| `--daemon` | Boot the app once in a persistent daemon and fork per mutant, with per-worker DB isolation so `--jobs N` is safe under Rails (needs `--rails`/`--boot`; not with `--test-command`). See [the daemon backend](#faster-parallel-safe-rails-the---daemon-backend) |
 | `--format human\|json\|html` | Report format (default: human; `html` is a self-contained file) |
 | `--output FILE` | Write the report to FILE instead of stdout |
 | `--dry-run` | List candidate mutations without executing (honors suppression) |
@@ -104,6 +105,33 @@ Add Mutineer to your Gemfile's test group:
 gem "mutineer", group: :test, require: false
 ```
 
+### Faster, parallel-safe Rails (the `--daemon` backend)
+
+`--rails` boots your app once but runs mutants **serially** — parallel `--jobs`
+under Rails is unsafe, because every worker shares one test database and clobbers
+the others' fixtures. `--daemon` fixes both: it boots the app once in a persistent
+helper and forks per mutant, and gives **each parallel worker its own database**,
+so `--jobs N` is safe and its verdicts are proven identical to a serial run.
+
+```sh
+RAILS_ENV=test bundle exec mutineer run \
+  app/models/order.rb --test test/models/order_test.rb \
+  --rails --daemon --jobs 4
+```
+
+- **One boot, forked per mutant** — restores the shared-boot speed.
+- **Coverage-guided** — each mutant runs only its covering tests (like `--rails`);
+  a mutant on an uncovered line is `no_coverage`, so the score stays comparable to
+  the in-process `--rails` score.
+- **Safe `--jobs N`** — each worker routes to its own copy of the test database, so
+  parallel verdicts equal serial (no fixture cross-talk).
+- **One backend at a time** — `--daemon` can't be combined with `--test-command`
+  (choose one), and it needs an app to boot (`--rails` or `--boot`).
+
+Status: **SQLite** today (hermetic, CI-proven). **Postgres** per-worker
+provisioning is in progress (#34/#35); until it lands, use `--daemon` with a
+SQLite test database, or drop `--jobs` to run serially on other adapters.
+
 ### Apps on Ruby < 3.4
 
 Mutineer's own process needs Ruby ≥ 3.4 (it parses with stdlib Prism), and the
@@ -136,7 +164,8 @@ Tradeoffs (Phase 1) — this path is correct but not free:
   is scored as a kill. Mutineer prints this caveat on every run and aborts up
   front (a "smoke check") if your unmutated suite isn't green.
 - **Reload strategy only** (`--strategy redefine` is rejected on this path) and
-  **serial** (`--jobs` is forced to 1 — safe parallelism is tracked in #26).
+  **serial** (`--jobs` is forced to 1). For apps on Ruby ≥ 3.4, `--daemon` gives
+  safe parallelism instead (see [the daemon backend](#faster-parallel-safe-rails-the---daemon-backend)).
 
 ## Suppressing equivalent mutants
 

data/lib/mutineer/cli.rb

@@ -51,6 +51,9 @@ module Mutineer
                              subprocess (for apps on Ruby < 3.4). CMD must contain
                              %{files} (expands to the --test paths). Env is inherited,
                              e.g. RAILS_ENV=test mutineer run ... --test-command "..."
+        --daemon             Boot the app ONCE in a persistent daemon and fork per
+                             mutant, with per-worker DB isolation so --jobs N is safe
+                             under Rails (needs --rails/--boot; not with --test-command)
         --format human|json|html  Report format (default: human)
         --output FILE        Write the report to FILE instead of stdout
         --dry-run            List mutations without executing
@@ -112,6 +115,9 @@ module Mutineer
         # #27: run the target suite as a subprocess in the app's OWN runtime so
         # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
         o.on("--test-command CMD") { |v| opts[:test_command] = v; explicit << :test_command }
+        # #26/#27 Phase 2: boot the app ONCE in a persistent daemon and fork per
+        # mutant, with per-worker DB isolation so --jobs N is safe under Rails.
+        o.on("--daemon") { opts[:daemon] = true; explicit << :daemon }
       end
 
       begin
@@ -242,6 +248,7 @@ module Mutineer
       end
 
       validate_test_command!(config) if config.test_command
+      validate_daemon!(config, explicit) if config.daemon
 
       validate_since!(config) if config.since
       preflight_output!(config.output) if config.output
@@ -300,6 +307,30 @@ module Mutineer
       config.jobs = 1
     end
 
+    # #26/#27 Phase 2 (U8): --daemon selects the persistent-daemon backend (boot once,
+    # fork per mutant, per-worker DB isolation). Two usage errors, both exit 2 (KTD-10):
+    # it cannot be combined with --test-command (choose ONE backend — never silently
+    # pick one), and it requires an app to boot (--rails or --boot). Under Rails,
+    # Config.resolve already keeps --jobs serial unless the user explicitly asks for
+    # parallelism, and each worker gets its own SQLite database on demand — so there is
+    # no "missing worker DB" precondition to check here for SQLite. Postgres worker-DB
+    # provisioning + its missing-DB error (KTD-9) arrives with the Postgres adapter (U10).
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @param explicit [Set<Symbol>] explicit CLI fields.
+    # @return [void]
+    def self.validate_daemon!(config, _explicit = Set.new)
+      if config.test_command
+        warn "mutineer: choose one backend — --daemon and --test-command cannot be combined"
+        exit 2
+      end
+      return if config.rails || config.boot
+
+      warn "mutineer: --daemon needs an app to boot; add --rails (or --boot FILE)"
+      exit 2
+    end
+
     # --since needs a real git repo and a resolvable ref; either failure is a
     # usage error (exit 2) so CI sees "bad invocation," not "tests too weak."
     # Validates the --since ref.
@@ -437,6 +468,15 @@ module Mutineer
              "and an infra failure is scored as a kill."
       end
 
+      # #26/U8: same disclosure as --test-command above — the daemon backend has no
+      # coverage narrowing yet (Phase 2c), so this score is a lower bound (uncovered
+      # mutants count as survivors) and not comparable to an in-process run.
+      if config.daemon
+        warn "[mutineer] --daemon score is a lower bound, not comparable to an " \
+             "in-process run: no coverage narrowing yet (uncovered mutants count as " \
+             "survivors)."
+      end
+
       # #14: nudge toward the opt-in tier-2 operators (human report only — never
       # pollute JSON output).
       if !%w[json html].include?(config.format) && (hint = tier2_hint(config.operators))

data/lib/mutineer/config.rb

@@ -25,9 +25,8 @@ module Mutineer
     :cache_dir, :project_root, :load_paths,
     :jobs, :format, :output, :strategy, :require_paths,
     :boot, :rails, :since, :framework, :verbose, :ignore,
-    # :daemon / :daemon_timeout are NOT user-facing yet — no CLI flag or KNOWN_KEYS
-    # entry until the Phase 2c `--daemon` unit lands (which adds the flag + a `to_i`
-    # coerce + KNOWN_KEYS). For now they're set programmatically (tests/Runner).
+    # :daemon is user-facing as of U8 (--daemon flag + KNOWN_KEYS + boolean coerce).
+    # :daemon_timeout stays programmatic (set by tests/Runner; no flag yet).
     :baseline, :baseline_epsilon, :fail_fast, :test_command,
     :daemon, :daemon_timeout,
     keyword_init: true
@@ -35,7 +34,7 @@ module Mutineer
     # Config file name.
     CONFIG_FILE = ".mutineer.yml"
     # Keys accepted in .mutineer.yml (R7). `require` maps to the :require_paths field.
-    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast test_command].freeze
+    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast test_command daemon].freeze
 
     def initialize(**kwargs)
       super
@@ -168,6 +167,7 @@ module Mutineer
       when "boot"      then value.to_s
       when "framework" then value.to_s
       when "rails"     then value == true || value.to_s == "true"
+      when "daemon"    then value == true || value.to_s == "true"
       when "verbose"   then value == true || value.to_s == "true"
       when "ignore"    then Array(value).map(&:to_s)
       when "baseline"  then value.to_s

data/lib/mutineer/coverage_map.rb

@@ -21,7 +21,24 @@ module Mutineer
   class CoverageMap
     DEFAULT_CAPTURE_TIMEOUT = 120 # seconds, per coverage subprocess (R3)
 
-    attr_reader :project_root, :failed_test_files, :phase_a_ran
+    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).
+    #
+    # @param map [Hash] the "file:line" => [test_files] map.
+    # @param failed_test_files [Array<String>] test files whose capture failed.
+    # @param project_root [String] project root (for path relativization).
+    # @return [Mutineer::CoverageMap] a query-only map.
+    def self.from_data(map:, failed_test_files:, project_root:)
+      instance = allocate
+      instance.instance_variable_set(:@map, map || {})
+      instance.instance_variable_set(:@failed_test_files, failed_test_files || [])
+      instance.instance_variable_set(:@project_root, project_root)
+      instance
+    end
 
     def initialize(source_paths:, test_paths:, cache_dir: ".mutineer",
                    load_paths: ["lib"], project_root: Dir.pwd,
@@ -54,9 +71,9 @@ module Mutineer
     # the booted parent instead. Inverts into the same map #tests_for reads, and
     # reuses the digest cache (the digest mixes in the boot file so a boot cache
     # never collides with a standalone one).
-    def build_via_fork(rails: false)
+    def build_via_fork(after_fork: nil)
       warn_external_sources
-      cached_or { run_phase_a_via_fork(rails: rails) }
+      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.
@@ -159,7 +176,7 @@ module Mutineer
     # 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.
-    def run_phase_a_via_fork(rails:)
+    def run_phase_a_via_fork(after_fork:)
       @phase_a_ran = true
       @map = {}
       @failed_test_files = []
@@ -169,7 +186,7 @@ module Mutineer
         # 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.
-        case (coverage = fork_capture(absolute(test_path), abs_sources, rails))
+        case (coverage = fork_capture(absolute(test_path), abs_sources, after_fork))
         when Hash   then record(coverage, test_path)
         when String
           fail_test(test_path, @verbose ? "fork capture failed: #{coverage}" :
@@ -182,7 +199,7 @@ module Mutineer
     # Fork the booted parent, run one test under the inherited Coverage, and
     # return its per-source counts hash (or nil on failure). Reuses the same
     # fork + Marshal-over-pipe + hard-exit! discipline as WorkerPool/Isolation.
-    def fork_capture(abs_test, abs_sources, rails)
+    def fork_capture(abs_test, abs_sources, after_fork)
       rd, wr = IO.pipe
       # #19: Marshal output is binary — an un-binmoded pipe can raise
       # Encoding::UndefinedConversionError on write, which the child's rescue then
@@ -193,7 +210,10 @@ module Mutineer
         rd.close
         payload =
           begin
-            Runner.send(:reconnect_active_record) if 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])
             # lines:true yields {file => {lines: [...]}}; reduce to the counts

data/lib/mutineer/daemon_client.rb

@@ -55,15 +55,17 @@ module Mutineer
     # @param payload [Hash] {"code" => mutated ruby, "source_file" => path}.
     # @param tests [Array<String>] covering test file paths.
     # @param timeout [Numeric] per-mutant wall-clock timeout (seconds).
+    # @param worker [Integer] worker slot; the daemon routes the fork to
+    #   `<db>-<worker>` (#26 isolation). Defaults to 0 (serial in U5).
     # @return [String] one of survived/killed/error/timeout.
-    def request(id:, payload:, tests:, timeout:)
+    def request(id:, payload:, tests:, timeout:, worker: 0)
       # A crash can surface on the WRITE (daemon died idle between requests →
       # Errno::EPIPE) as well as the read (EOF), so guard both: either way, respawn
       # for future mutants and score THIS one error (re-running a crash-causing
       # mutant could loop). Never let a dead pipe abort the whole run.
       reply =
         begin
-          send_line("id" => id, "payload" => payload, "tests" => tests, "timeout" => timeout)
+          send_line("id" => id, "worker" => worker, "payload" => payload, "tests" => tests, "timeout" => timeout)
           read_line
         rescue Errno::EPIPE, IOError
           nil
@@ -74,6 +76,19 @@ module Mutineer
       "error"
     end
 
+    # #26/U7: ask the daemon to build the coverage map app-side and return it.
+    # One-shot control message (no id). Returns `{"map"=>..., "failed_test_files"=>...}`
+    # (possibly with an `"error"`), or nil if the daemon vanished — the caller then
+    # falls back to running the full test set (no narrowing) rather than mis-scoring.
+    #
+    # @return [Hash, nil] the coverage payload, or nil on a dead pipe.
+    def coverage
+      send_line("cmd" => "coverage")
+      read_line
+    rescue Errno::EPIPE, IOError
+      nil
+    end
+
     # Graceful shutdown; leaves no orphaned daemon/child.
     #
     # @return [void]

data/lib/mutineer/daemon_server.rb

@@ -20,17 +20,23 @@ module Mutineer
   #
   # Protocol (one JSON object per line, both directions):
   #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment",
-  #               "load_paths":["test"],"framework":"minitest","rails":true}
+  #               "load_paths":["test"],"framework":"minitest","rails":true,"schema":"db/schema.rb"}
   #   ready out: {"ready":true,"ruby":"3.3.6"}   (or {"ready":false,"error":"..."} then exit)
-  #   run  in  : {"id":N,"payload":{"code":"<ruby>","source_file":"app/models/order.rb"},
+  #   run  in  : {"id":N,"worker":I,"payload":{"code":"<ruby>","source_file":"app/models/order.rb"},
   #               "tests":["test/models/order_test.rb"],"timeout":30}
   #   verdict  : {"id":N,"verdict":"survived"|"killed"|"error"|"timeout"}
   #   quit in  : {"cmd":"quit"}
   #
+  # Worker isolation (#26/U5): when the app is Rails, each fork is routed to its own
+  # database `<db>-<worker>` via {RailsWorkerDb} BEFORE any test loads, so concurrent
+  # workers can't clobber each other's transactional fixtures. `worker` defaults to 0
+  # (serial). SQLite this pass; Postgres provisioning is U10.
+  #
   # Verdict mapping (KTD-5, Phase-2a honest limit): child exit 0=survived (suite
-  # passed), 1=killed (suite failed), 2=error (child raised AROUND the test — load or
-  # boot failure); parent-detected timeout. Tagging an in-TEST DB error as `error`
-  # (vs killed) is a Phase-2b concern (needs the after_fork adapter's re-raise).
+  # passed), 1=killed (suite failed), 2=error (child raised AROUND the test — load,
+  # boot, or worker-DB routing failure); parent-detected timeout. Tagging an in-TEST DB
+  # error (one fired inside a test body, vs at routing time) as `error` rather than
+  # `killed` is a U6 concern — only observable under the concurrent gate.
   module DaemonServer
     # Poll interval (seconds) for the per-fork deadline wait loop.
     POLL = 0.02
@@ -67,6 +73,14 @@ module Mutineer
           end
           break if req["cmd"] == "quit"
 
+          # #26/U7: build the coverage map app-side and ship it to the tool, which
+          # then selects covering tests per mutant. One-shot control message.
+          if req["cmd"] == "coverage"
+            output.puts(JSON.generate(build_coverage_map))
+            output.flush
+            next
+          end
+
           output.puts(JSON.generate(run_mutant(req)))
           output.flush
         end
@@ -77,16 +91,24 @@ module Mutineer
       # BOOT ONCE. chdir + require the app's boot file so the whole app is loaded and
       # inherited by every fork. Never requires mutineer.
       def boot!(cfg)
+        @cfg = cfg
         @framework = cfg.fetch("framework", "minitest")
         @source_dirs = Array(cfg["source_dirs"]).map { |d| File.expand_path(d) }
         Dir.chdir(cfg["project_root"]) if cfg["project_root"]
         ENV["RAILS_ENV"] ||= "test" if cfg["rails"]
         Array(cfg["load_paths"]).each { |d| $LOAD_PATH.unshift(File.expand_path(d)) }
+        # #26/U7: start Coverage BEFORE the app loads, so booted source lines are
+        # instrumented — the map build (build_via_fork) forks this booted parent.
+        if cfg["coverage"]
+          require "coverage"
+          Coverage.start(lines: true)
+        end
         # Clear any mutant tempfile a prior SIGKILLed timeout child orphaned in a
         # source dir BEFORE the app boots — Zeitwerk would otherwise choke on the
         # tempfile's non-constant name during autoload setup.
         sweep_temps
         require File.expand_path(cfg["boot"]) if cfg["boot"]
+        setup_worker_db(cfg) if cfg["rails"]
       rescue Exception => e # rubocop:disable Lint/RescueException
         # Boot failed (bad boot path, app error) — tell the client and exit so it can
         # surface a clean error rather than hang on the handshake.
@@ -95,9 +117,54 @@ module Mutineer
         exit!(1)
       end
 
+      # Load the per-worker DB adapter app-side (sibling gem file, by relative path so
+      # it bypasses the app bundle — like this daemon itself). No-op unless the app has
+      # ActiveRecord. Records the adapter + schema path so each fork can route to its
+      # own database (#26 isolation, U5). SQLite-only this pass; a non-SQLite config
+      # raises in the fork and reads as `error`, never a mis-routed verdict.
+      def setup_worker_db(cfg)
+        require_relative "rails_worker_db"
+        @worker_db = RailsWorkerDb.available? ? RailsWorkerDb : nil
+        schema = cfg["schema"] && File.expand_path(cfg["schema"])
+        @schema_path = schema if schema && File.exist?(schema)
+      rescue LoadError => e
+        @errio.puts("[daemon] worker-DB routing unavailable: #{e.message}")
+        @worker_db = nil
+      end
+
+      # #26/U7: build the coverage map app-side (Coverage was started at boot) and
+      # return it as `{map, failed_test_files}` for the tool to select covering tests.
+      # Capture forks route to worker 0's DB (isolated, serial). On any failure return
+      # an empty map + an error string — the tool then falls back to the full test set
+      # rather than mis-scoring everything as no_coverage.
+      def build_coverage_map
+        require_relative "coverage_map"
+        root = @cfg["project_root"] || Dir.pwd
+        cmap = CoverageMap.new(
+          source_paths: Array(@cfg["sources"]), test_paths: Array(@cfg["tests"]),
+          load_paths: Array(@cfg["load_paths"]), project_root: root,
+          boot_path: @cfg["boot"], framework: @framework, cache_dir: File.join(root, ".mutineer")
+        ).build_via_fork(after_fork: coverage_after_fork)
+        { "map" => cmap.map, "failed_test_files" => cmap.failed_test_files }
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        @errio.puts("[daemon] coverage build failed: #{e.class}: #{e.message}")
+        { "map" => {}, "failed_test_files" => [], "error" => "#{e.class}: #{e.message}" }
+      end
+
+      # Fork-safety hook for coverage capture: route each capture fork to worker 0's
+      # isolated DB (captures run serially, so one worker is enough). Nil when the app
+      # has no worker-DB adapter (non-Rails) — capture then runs as before.
+      def coverage_after_fork
+        return nil unless @worker_db
+
+        schema = @schema_path
+        -> { @worker_db.after_fork(0, schema) }
+      end
+
       # Fork a child to run one mutant in isolation; decode its exit into a verdict.
       def run_mutant(req)
         timeout = req.fetch("timeout", 30)
+        worker  = req.fetch("worker", 0)
         pid = fork do
           # New process group so a per-fork timeout can SIGKILL the whole subtree
           # (carries the Phase-1 pgroup discipline), and silence the child's stdout so
@@ -106,6 +173,10 @@ module Mutineer
           $stdout.reopen(File::NULL, "w")
           code =
             begin
+              # Route THIS fork at its own worker database before any test loads, so
+              # concurrent workers can't clobber each other's fixtures (#26). A routing
+              # failure raises here and is scored `error` below, never a false verdict.
+              @worker_db&.after_fork(worker, @schema_path)
               apply_payload(req["payload"])
               run_tests(Array(req["tests"]))
             rescue Exception => e # rubocop:disable Lint/RescueException

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

@@ -90,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,
@@ -241,37 +241,196 @@ module Mutineer
     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) }
-      client = DaemonClient.new(boot: daemon_boot_config(config, abs_tests),
+
+      # #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?
+
+      results =
+        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 |(subject, mutation, id), i|
-          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`.
-          r =
-            if Parser.parse_string(mutated).errors.any?
-              Result.skipped
-            else
-              verdict = client.request(
-                id: i, timeout: config.daemon_timeout || DAEMON_TIMEOUT,
-                payload: { "code" => mutated, "source_file" => File.expand_path(subject.file, config.project_root) },
-                tests: abs_tests
-              )
-              daemon_result(verdict)
-            end
-          results << r.with(subject: subject, mutation: mutation, id: id)
-          break if config.fail_fast && r.survived? # #21: stop at the first survivor
+        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
 
-      [AggregateResult.new(results + ignored_results), source_map]
+    # 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
+        ensure
+          client.quit
+        end
+      end.each(&:join)
+
+      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
@@ -281,17 +440,39 @@ module Mutineer
     # 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)
+    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
+        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.
@@ -426,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.10.0"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - David Teren
@@ -95,6 +95,7 @@ files:
 - lib/mutineer/pairing.rb
 - lib/mutineer/parser.rb
 - lib/mutineer/project.rb
+- lib/mutineer/rails_worker_db.rb
 - lib/mutineer/reporter.rb
 - lib/mutineer/result.rb
 - lib/mutineer/runner.rb