mutineer 0.11.2 → 0.11.4

data/lib/mutineer/daemon_client.rb

@@ -4,19 +4,23 @@ require "json"
 require "open3"
 
 module Mutineer
-  # Raised when the daemon cannot be booted (bad boot path, app error, or it dies on
-  # the handshake). The CLI maps it to a runtime error.
+  # Raised when the daemon cannot be booted or is gone for good: a bad boot path, an
+  # app error, a failed handshake, a spawn the OS refused, or MAX_RESTARTS crashes.
+  # It means "stop the run" — a backend that scored the remaining mutants against a
+  # dead daemon would report a score covering a fraction of the work. The CLI maps it
+  # to a runtime error (exit 1).
   class DaemonBootError < StandardError; end
 
-  # #26/#27 Phase 2a — the TOOL-side handle for the app-side daemon.
+  # Tool-side handle for the app-side daemon.
   #
-  # Spawns `daemon_server.rb` UNDER THE APP'S BUNDLE/RUBY (cleaned env so the gem's
-  # bundler context never leaks; the daemon file is loaded by absolute path with
-  # `-r`, which bypasses the app bundle that has no mutineer), completes the ready
-  # handshake, then ships per-mutant payloads and reads structured verdicts. If the
-  # daemon dies mid-run it respawns (bounded) and marks the in-flight mutant `error`
-  # rather than corrupting the run. Reuses the cleaned-env spawn + stderr-drain proven
-  # in the spike driver and the spawn discipline of ExternalBackend.
+  # Spawns `daemon_server.rb` UNDER THE APP'S BUNDLE/RUBY (cleaned env so the
+  # gem's bundler context never leaks; the daemon file is loaded by absolute path
+  # with `-r`, which bypasses the app bundle that has no mutineer), completes the
+  # ready handshake, then ships per-mutant payloads and reads structured verdicts.
+  # If the daemon dies mid-run it respawns (bounded) and marks the in-flight
+  # mutant `error` rather than corrupting the run. Reuses the cleaned-env spawn
+  # and stderr-drain proven in the spike driver and the spawn discipline of
+  # ExternalBackend.
   class DaemonClient
     # Absolute path to the daemon entry, loaded app-side by `-r` (bypasses the bundle).
     DAEMON_PATH = File.expand_path("daemon_server.rb", __dir__)
@@ -49,16 +53,22 @@ module Mutineer
 
     # Run one mutant: ship the payload + covering tests, return the verdict string.
     # On a daemon crash (EOF/dead pipe) respawn (bounded) and return `"error"` for
-    # this mutant — never a wrong verdict, never a wedged run.
+    # this mutant. Never a wrong verdict, never a wedged run.
     #
     # @param id [Integer] request id (echoed back for ordering safety).
     # @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).
+    #   `<db>-<worker>` for isolation. Defaults to 0 (serial).
     # @return [String] one of survived/killed/error/timeout.
     def request(id:, payload:, tests:, timeout:, worker: 0)
+      # close_io nils the pipes, so a client whose respawn never completed would
+      # otherwise fail per-mutant forever (NoMethodError on nil) and let the backend
+      # score every remaining mutant against nothing. Deadness is a property of the
+      # client, not of whichever exception happened to escape.
+      raise DaemonBootError, "daemon is not running" if @stdin.nil?
+
       # 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
@@ -76,10 +86,11 @@ 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.
+    # 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
@@ -103,8 +114,8 @@ module Mutineer
 
     private
 
-    # Cleaned environment for the app bundle: strip the gem's bundler/Ruby context so
-    # `bundle exec` resolves the APP's Gemfile under the requested Ruby.
+    # Cleaned environment for the app bundle: strip the gem's bundler/Ruby context
+    # so `bundle exec` resolves the APP's Gemfile under the requested Ruby.
     def app_env
       env = ENV.to_h.reject { |k, _| k.start_with?("BUNDLE_", "RUBY", "GEM_") }
       env["BUNDLE_GEMFILE"] = @gemfile
@@ -118,25 +129,38 @@ module Mutineer
     # @return [void]
     # @raise [Mutineer::DaemonBootError] when the daemon fails to boot.
     def spawn_daemon
-      # Plain `bundle exec ruby` — NOT `rbenv exec`, which would break CI and any
-      # non-rbenv setup. When bundler/ruby are rbenv shims, the RBENV_VERSION carried
-      # in app_env still selects the app's Ruby; otherwise the active Ruby is used.
-      @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(
-        app_env, "bundle", "exec", "ruby",
-        "-r", DAEMON_PATH, "-e", "Mutineer::DaemonServer.run", chdir: @app_root
-      )
-      # Drain daemon stderr to the tool's stderr so child/boot errors are visible.
-      # Tracked (not fire-and-forget) so close_io can reclaim it on quit/respawn; the
-      # rescue swallows the benign EBADF/IOError raised when close_io closes the pipe
-      # out from under an in-flight copy_stream.
-      @drain = Thread.new do # rubocop:disable ThreadSafety/NewThread
-        IO.copy_stream(@stderr, @errio)
-      rescue IOError, Errno::EBADF
-        nil
-      end
+      # Plain `bundle exec ruby`, NOT `rbenv exec`, which would break CI and any
+      # non-rbenv setup. When bundler/ruby are rbenv shims, the RBENV_VERSION
+      # carried in app_env still selects the app's Ruby; otherwise the active
+      # Ruby is used.
+      # Everything up to the handshake is terminal, not one mutant's problem: a spawn
+      # the OS refuses (EMFILE/ENOMEM under --jobs N, ENOENT when `bundle` does not
+      # resolve) and a daemon that dies before accepting the boot payload (EPIPE on
+      # the write) both leave a client that cannot recover. Raise the class that ends
+      # the run — a SystemCallError would reach the CLI as a usage error (exit 2).
+      ready =
+        begin
+          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(
+            app_env, "bundle", "exec", "ruby",
+            "-r", DAEMON_PATH, "-e", "Mutineer::DaemonServer.run", chdir: @app_root
+          )
+          # Drain daemon stderr to the tool's stderr so child/boot errors are visible.
+          # Tracked (not fire-and-forget) so close_io can reclaim it on quit/respawn;
+          # the rescue swallows the benign EBADF/IOError raised when close_io closes
+          # the pipe out from under an in-flight copy_stream.
+          @drain = Thread.new do # rubocop:disable ThreadSafety/NewThread
+            IO.copy_stream(@stderr, @errio)
+          rescue IOError, Errno::EBADF
+            nil
+          end
+
+          send_line(@boot)
+          read_line
+        rescue SystemCallError, IOError => e
+          close_io
+          raise DaemonBootError, "daemon could not be started: #{e.class}: #{e.message}"
+        end
 
-      send_line(@boot)
-      ready = read_line
       unless ready && ready["ready"]
         detail = ready && ready["error"] ? ready["error"] : "daemon exited before the handshake"
         close_io

data/lib/mutineer/daemon_server.rb

@@ -4,19 +4,20 @@ require "json"
 require "tempfile"
 
 module Mutineer
-  # #26/#27 Phase 2a — the app-side daemon (persistent worker).
+  # App-side daemon (persistent worker).
   #
   # Runs UNDER THE APP'S OWN BUNDLE/RUBY (the tool's DaemonClient spawns it via
   # `bundle exec ruby`). It boots the app ONCE, then serves per-mutant test-run
-  # requests over stdin/stdout as newline-delimited JSON. For each request it FORKS
-  # a child that loads the mutated source text the tool sent, runs the covering
-  # tests, and exits with a status the parent decodes into a verdict.
+  # requests over stdin/stdout as newline-delimited JSON. For each request it
+  # FORKS a child that loads the mutated source text the tool sent, runs the
+  # covering tests, and exits with a status the parent decodes into a verdict.
   #
-  # HARD CONSTRAINT (KTD-2/R4): this file must be loadable WITHOUT Prism or the rest
-  # of mutineer — the app's Ruby may be < 3.4 (no stdlib Prism) and its bundle has no
-  # mutineer. So it requires ONLY stdlib + the app's own boot file; it re-implements
-  # the fork/timeout/decode loop rather than requiring `isolation.rb` (which pulls in
-  # Prism). All parsing/mutation happened tool-side; the daemon only `load`s text.
+  # HARD CONSTRAINT: this file must be loadable WITHOUT Prism or the rest of
+  # mutineer. The app's Ruby may be < 3.4 (no stdlib Prism) and its bundle has no
+  # mutineer. So it requires ONLY stdlib + the app's own boot file; it
+  # re-implements the fork/timeout/decode loop rather than requiring
+  # `isolation.rb` (which pulls in Prism). All parsing/mutation happened
+  # tool-side; the daemon only `load`s text.
   #
   # Protocol (one JSON object per line, both directions):
   #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment",
@@ -27,16 +28,18 @@ module Mutineer
   #   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.
+  # Worker isolation: when the app is Rails, each fork is routed to its own
+  # database `<db>-<worker>` via {RailsWorkerDb} BEFORE any test loads, so
+  # concurrent workers cannot clobber each other's transactional fixtures.
+  # `worker` defaults to 0 (serial). SQLite this pass; Postgres provisioning is
+  # not yet implemented.
   #
-  # 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,
-  # 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.
+  # Verdict mapping: child exit 0=survived (suite 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 only observable under the concurrent gate and is not yet
+  # implemented.
   module DaemonServer
     # Poll interval (seconds) for the per-fork deadline wait loop.
     POLL = 0.02
@@ -65,16 +68,16 @@ module Mutineer
           begin
             req = JSON.parse(line)
           rescue JSON::ParserError => e
-            # A corrupt line has no id to address a reply to (and the client only ever
-            # sends valid JSON, so it can't be a pending request) — log and read on
-            # rather than write an unaddressable verdict onto the channel.
+            # A corrupt line has no id to address a reply to (and the client only
+            # ever sends valid JSON, so it cannot be a pending request). Log and
+            # read on rather than write an unaddressable verdict onto the channel.
             @errio.puts("[daemon] dropped unparseable line: #{e.message}")
             next
           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.
+          # 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
@@ -88,8 +91,8 @@ module Mutineer
 
       private
 
-      # BOOT ONCE. chdir + require the app's boot file so the whole app is loaded and
-      # inherited by every fork. Never requires 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")
@@ -97,30 +100,30 @@ module Mutineer
         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.
+        # 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
+        # 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.
+        # 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.
         @output.puts(JSON.generate("ready" => false, "error" => "#{e.class}: #{e.message}"))
         @output.flush
         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
+      # 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. 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"
@@ -134,11 +137,11 @@ module Mutineer
         @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.
+      # 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
@@ -153,9 +156,9 @@ module Mutineer
         { "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.
+      # 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
 
@@ -190,16 +193,16 @@ module Mutineer
         verdict = wait_verdict(pid, timeout)
         # Mark ready only when the child finished cleanly after schema load
         # (killed/survived). Timeout can interrupt mid-load_schema; error is a
-        # routing failure — both leave the slot unready so the next fork reloads.
+        # routing failure. Both leave the slot unready so the next fork reloads.
         @schema_ready[worker] = true if schema_for_fork && %w[killed survived].include?(verdict)
-        # A SIGKILLed timeout child skipped its Tempfile unlink — sweep the orphan so
-        # it can't outlive the run or trip Zeitwerk on a later fork.
+        # A SIGKILLed timeout child skipped its Tempfile unlink. Sweep the orphan
+        # so it cannot outlive the run or trip Zeitwerk on a later fork.
         sweep_temps if verdict == "timeout"
         { "id" => req["id"], "verdict" => verdict }
       end
 
       # Remove orphaned mutant tempfiles from the source dirs (parent-side; the
-      # SIGKILL path can't run the child's ensure). Mirrors Runner.sweep_orphans.
+      # SIGKILL path cannot run the child's ensure). Mirrors Runner.sweep_orphans.
       def sweep_temps
         @source_dirs.to_a.each do |dir|
           Dir.glob(File.join(dir, "mutineer_daemon*.rb")).each do |f|
@@ -209,12 +212,12 @@ module Mutineer
       end
 
       # Single-waiter deadline loop (mirrors Isolation.run and
-      # ExternalBackend.wait_with_timeout, re-implemented here because Isolation pulls
-      # in Prism which is forbidden app-side). NOTE: this is the 3rd copy of the
-      # waitpid2(WNOHANG)+deadline+pgroup-SIGKILL+decode discipline — a fix to the
-      # kill/reap/decode logic must be applied to all three in lockstep. SIGKILL the
-      # child's process group past the deadline; a signalled child (nil exitstatus) is
-      # `error`.
+      # ExternalBackend.wait_with_timeout, re-implemented here because Isolation
+      # pulls in Prism which is forbidden app-side). NOTE: this is the 3rd copy of
+      # the waitpid2(WNOHANG)+deadline+pgroup-SIGKILL+decode discipline. A fix to
+      # the kill/reap/decode logic must be applied to all three in lockstep.
+      # SIGKILL the child's process group past the deadline; a signalled child
+      # (nil exitstatus) is `error`.
       def wait_verdict(pid, timeout)
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
         loop do
@@ -242,14 +245,15 @@ module Mutineer
         end
       end
 
-      # Write the tool-built mutated text beside the real source and `load` it —
-      # reopening the mutated class/method in THIS child only. It goes in the source
-      # file's directory (like Isolation.apply_whole_file) so a `require_relative` in
-      # the mutated source resolves against its real neighbours — writing it to the
-      # tmpdir would LoadError on such files and score a spurious `error` that
-      # diverges from the in-process path. The Zeitwerk hazard (a stray `.rb` in an
-      # autoload dir) is handled by the boot/timeout `sweep_temps`, not by relocating
-      # the file. Same path for reload (whole file) and redefine (wrapped snippet).
+      # Write the tool-built mutated text beside the real source and `load` it,
+      # reopening the mutated class/method in THIS child only. It goes in the
+      # source file's directory (like Isolation.apply_whole_file) so a
+      # `require_relative` in the mutated source resolves against its real
+      # neighbours. Writing it to the tmpdir would LoadError on such files and
+      # score a spurious `error` that diverges from the in-process path. The
+      # Zeitwerk hazard (a stray `.rb` in an autoload dir) is handled by the
+      # boot/timeout `sweep_temps`, not by relocating the file. Same path for
+      # reload (whole file) and redefine (wrapped snippet).
       def apply_payload(payload)
         dir = File.dirname(File.expand_path(payload.fetch("source_file")))
         Tempfile.create(["mutineer_daemon", ".rb"], dir) do |f|
@@ -260,7 +264,7 @@ module Mutineer
       end
 
       # Load the covering test files and run them; 0 = all passed (survived),
-      # 1 = a failure/error (killed). Minitest only in 2a (rspec is a later unit).
+      # 1 = a failure/error (killed). Minitest only; rspec is not yet on this path.
       def run_tests(tests)
         raise "unsupported framework #{@framework.inspect}" unless @framework == "minitest"
 

data/lib/mutineer/file_swap.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # Raised when a source file's backup already exists as FileSwap.with begins —
-  # a second mutineer run is racing on the same file (the backup path is shared
+  # Raised when a source file's backup already exists as FileSwap.with begins.
+  # A second mutineer run is racing on the same file (the backup path is shared
   # and unlocked). Aborting beats silently leaving the tree mutated.
   class ConcurrentRunError < StandardError
     def initialize(backup)
@@ -11,11 +11,11 @@ module Mutineer
     end
   end
 
-  # #27 (U2): apply one whole-file mutant to the REAL source path for the external
+  # Apply one whole-file mutant to the REAL source path for the external
   # (`--test-command`) backend, and guarantee the original is restored on every
-  # exit path. A separate `bundle exec` subprocess has its own VM and cannot see an
-  # in-process `load`, so the mutant must live on disk while its suite runs — which
-  # makes leaving the file mutated the one genuinely dangerous failure mode.
+  # exit path. A separate `bundle exec` subprocess has its own VM and cannot see
+  # an in-process `load`, so the mutant must live on disk while its suite runs,
+  # which makes leaving the file mutated the one genuinely dangerous failure mode.
   #
   # Defense in depth, mirroring the tempfile-orphan discipline
   # (`Runner.sweep_orphans`, `isolation.rb` tempfiles):
@@ -39,12 +39,13 @@ module Mutineer
     # @return [Object] the block's return value.
     def self.with(source_file, mutated)
       backup = source_file + BACKUP_SUFFIX
-      # A backup already on disk means either a prior hard-killed run (restore_orphans
-      # should have healed it at startup) or a SECOND mutineer run racing us on the
-      # same file. The backup path is shared and unlocked, so proceeding would let
-      # us capture the other run's mutant AS the "original" and permanently mutate
-      # the tree. Refuse loudly rather than silently corrupt — and do it BEFORE
-      # `created` is set, so the ensure below never touches a backup we don't own.
+      # A backup already on disk means either a prior hard-killed run
+      # (restore_orphans should have healed it at startup) or a SECOND mutineer
+      # run racing us on the same file. The backup path is shared and unlocked, so
+      # proceeding would let us capture the other run's mutant AS the "original"
+      # and permanently mutate the tree. Refuse loudly rather than silently
+      # corrupt, and do it BEFORE `created` is set, so the ensure below never
+      # touches a backup we don't own.
       raise ConcurrentRunError, backup if File.exist?(backup)
 
       original = File.binread(source_file)
@@ -74,11 +75,11 @@ module Mutineer
           backup_bytes = File.binread(backup)
           if !File.exist?(source_file)
             # A real user file that merely ends in our suffix, with no sibling to
-            # restore — leave it untouched (never create a file from it).
+            # restore. Leave it untouched (never create a file from it).
             next
           elsif File.binread(source_file) == backup_bytes
-            # Redundant backup (e.g. a crash between restore and unlink): nothing to
-            # heal, just clear the orphan so the next run doesn't see a false race.
+            # Redundant backup (e.g. a crash between restore and unlink): nothing
+            # to heal, just clear the orphan so the next run does not see a false race.
             File.unlink(backup)
           else
             File.binwrite(source_file, backup_bytes)

data/lib/mutineer/rails_worker_db.rb

@@ -1,33 +1,32 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # #26/#27 Phase 2b (U5) — per-worker database isolation for the daemon path.
+  # 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
+  # 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"`: 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.
+  # Isolation model: each parallel worker gets its OWN database so concurrent
+  # forks cannot clobber each other's transactional fixtures. {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 DBs (`CREATE DATABASE <db>-<worker>`) are not
-  # implemented yet; a non-SQLite config raises a clear NotImplementedError rather
-  # than silently mis-routing.
+  # Scope: SQLite adapter only (per-worker file, hermetic). Postgres per-worker
+  # DBs (`CREATE DATABASE <db>-<worker>`) are not implemented yet; 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.
+  # Routing failures surface as `error` via {verify_connection!}. Tagging an
+  # in-test DB failure as `error` (not `killed`) is only observable under
+  # concurrent load and is not yet implemented.
   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.
+    # 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?
@@ -35,8 +34,9 @@ module Mutineer
     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`.
+    # 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).
@@ -47,9 +47,9 @@ module Mutineer
     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).
+    # (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.
     #
     # @param worker [Integer] the worker slot index.
     # @return [Hash] a symbol-keyed AR configuration hash for the worker database.
@@ -57,16 +57,15 @@ module Mutineer
     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 until Postgres worker creation is implemented.
+      # Config shaping (per_worker_config) is already adapter-general: it derives
+      # correct SQLite and Postgres worker-DB names. What is gated is runtime
+      # provisioning: SQLite files are created on connect, but Postgres needs an
+      # explicit `CREATE DATABASE` per worker. Until that lands, refuse non-SQLite
+      # loudly rather than route to a database that does not exist.
       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."
+              "Postgres per-worker provisioning is not yet supported. Use a SQLite test DB, or drop --jobs."
       end
 
       per_worker_config(hash, worker)
@@ -74,10 +73,10 @@ module Mutineer
 
     # 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.
+    # 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 and unit-tested so the
+    # Postgres shape is proven ready without a live database.
     #
     # @param config_hash [Hash] a connection config hash (symbol or string keys).
     # @param worker [Integer] the worker slot index.
@@ -94,11 +93,12 @@ module Mutineer
       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.
+    # 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.
@@ -126,8 +126,9 @@ module Mutineer
       $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`).
+    # 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!