henitai 0.4.0 → 0.5.0

data/lib/henitai/integration/loaded_features.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # Answers whether a test file has already been required, by matching it
+    # against `$LOADED_FEATURES`.
+    #
+    # Both sides need normalizing: `$LOADED_FEATURES` holds absolute paths for
+    # required files but callers hand over repository-relative test paths, and
+    # either side may or may not carry the `.rb` suffix. A feature string that
+    # cannot be expanded (invalid encoding, for instance) falls back to its raw
+    # form rather than aborting the whole check — this runs inside a mutant
+    # child whose only job is diagnostics.
+    class LoadedFeatures
+      def include?(file)
+        candidates = candidates_for(file)
+        $LOADED_FEATURES.any? do |feature|
+          candidates.include?(feature) || candidates.include?(normalize(feature))
+        end
+      end
+
+      def map(files) = files.map { |file| [file, include?(file)] }
+
+      private
+
+      def candidates_for(file)
+        expanded = File.expand_path(file)
+        [expanded, "#{expanded}.rb", file, "#{file}.rb"].uniq
+      end
+
+      def normalize(feature)
+        File.expand_path(feature)
+      rescue StandardError
+        feature
+      end
+    end
+  end
+end

data/lib/henitai/integration/mutant_run_support.rb

@@ -47,7 +47,7 @@ module Henitai
         with_subprocess_env do
           suppress_simplecov!
           suppress_coverage!
-          install_debug_timeout_trap if debug_child?
+          install_debug_timeout_trap if child_debug_log.enabled?
           with_non_interactive_stdin do
             run_child_activation_and_tests(mutant:, test_files:, log_paths:)
           end
@@ -63,11 +63,11 @@ module Henitai
       def run_child_activation_and_tests(mutant:, test_files:, log_paths:)
         scenario_log_support.with_coverage_dir(mutant.id) do
           scenario_log_support.capture_child_output(log_paths) do
-            debug_child_mutant_meta(mutant) if debug_child?
-            debug_child_activation_start(mutant.id)
+            child_debug_log.mutant_meta(mutant)
+            child_debug_log.activation_start(mutant.id)
             activation_result = Mutant::Activator.activate!(mutant)
-            debug_child_activation_check if debug_child?
-            debug_child_activation_end(activation_result, test_files:)
+            child_debug_log.activation_check
+            child_debug_log.activation_end(activation_result, test_files:)
             activation_result == :compile_error ? 2 : run_tests(test_files)
           end
         end

data/lib/henitai/integration/rspec_child_runner.rb

@@ -9,19 +9,20 @@ module Henitai
       private
 
       def run_rspec_runner(test_files)
-        debug_child_puts("[henitai-debug-child] build_rspec_runner_start")
+        log = child_debug_log
+        log.write("[henitai-debug-child] build_rspec_runner_start")
         runner = build_rspec_runner
-        debug_child_puts("[henitai-debug-child] build_rspec_runner_return")
-        debug_child_puts("[henitai-debug-child] configure_rspec_runner_start")
+        log.write("[henitai-debug-child] build_rspec_runner_return")
+        log.write("[henitai-debug-child] configure_rspec_runner_start")
         configure_rspec_runner(runner)
-        debug_child_puts("[henitai-debug-child] configure_rspec_runner_return")
+        log.write("[henitai-debug-child] configure_rspec_runner_return")
         load_rspec_spec_files(test_files)
         run_rspec_specs(runner)
       rescue SystemExit => e
-        debug_child_puts("[henitai-debug-child] runner_run_system_exit status=#{e.status.inspect}")
+        log.write("[henitai-debug-child] runner_run_system_exit status=#{e.status.inspect}")
         raise
       ensure
-        debug_child_puts("[henitai-debug-child] runner_run_ensure")
+        child_debug_log.write("[henitai-debug-child] runner_run_ensure")
       end
 
       def build_rspec_runner
@@ -32,28 +33,28 @@ module Henitai
       end
 
       def configure_rspec_runner(runner)
-        debug_child_puts("[henitai-debug-child] trap_interrupt_start")
+        child_debug_log.write("[henitai-debug-child] trap_interrupt_start")
         ::RSpec::Core::Runner.__send__(:trap_interrupt)
-        debug_child_puts("[henitai-debug-child] trap_interrupt_return")
-        debug_child_puts("[henitai-debug-child] runner_configure_start")
+        child_debug_log.write("[henitai-debug-child] trap_interrupt_return")
+        child_debug_log.write("[henitai-debug-child] runner_configure_start")
         runner.send(:configure, $stderr, $stdout)
-        debug_child_puts("[henitai-debug-child] runner_configure_return")
+        child_debug_log.write("[henitai-debug-child] runner_configure_return")
       end
 
       def load_rspec_spec_files(test_files)
-        debug_child_puts("[henitai-debug-child] load_spec_files_start")
+        child_debug_log.write("[henitai-debug-child] load_spec_files_start")
         ::RSpec.configuration.files_to_run = test_files.map do |file|
           File.expand_path(file)
         end
         ::RSpec.configuration.load_spec_files
-        debug_child_example_count("after_load")
-        debug_child_puts("[henitai-debug-child] load_spec_files_return")
+        child_debug_log.example_count("after_load")
+        child_debug_log.write("[henitai-debug-child] load_spec_files_return")
       end
 
       def run_rspec_specs(runner)
-        debug_child_puts("[henitai-debug-child] run_specs_start")
+        child_debug_log.write("[henitai-debug-child] run_specs_start")
         result = runner.send(:run_specs, ::RSpec.world.ordered_example_groups)
-        debug_child_puts("[henitai-debug-child] run_specs_return result=#{result.inspect}")
+        child_debug_log.write("[henitai-debug-child] run_specs_return result=#{result.inspect}")
         result
       end
     end

data/lib/henitai/integration/rspec_process_runner.rb

@@ -32,7 +32,7 @@ module Henitai
           ended_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           @mutex.synchronize do
             @live_count -= 1
-            entry = @intervals.rfind { |i| i[:pid] == pid && i[:ended_at].nil? }
+            entry = @intervals.reverse_each.find { |i| i[:pid] == pid && i[:ended_at].nil? }
             entry[:ended_at] = ended_at if entry
           end
         end
@@ -84,8 +84,13 @@ module Henitai
       # Forks a child, sets process group, activates the mutant, runs tests.
       # Returns a ChildHandle with the forked pid and log_paths.
       def spawn_mutant(integration, mutant:, test_files:, log_paths:)
+        # Captured here, in the parent. Reading Process.ppid inside the child
+        # would race the very death the watchdog looks for: a parent dying
+        # between fork and that read leaves the child with ppid 1 as its
+        # baseline, so it would never consider itself orphaned.
+        parent_pid = Process.pid
         pid = Process.fork do
-          Process.setpgid(0, 0)
+          ChildBootstrap.after_fork!(parent_pid:)
           ENV["HENITAI_MUTANT_ID"] = mutant.id
           Process.exit(
             integration.run_in_child(

data/lib/henitai/integration.rb

@@ -3,10 +3,12 @@
 require "fileutils"
 require "stringio"
 require_relative "process_wakeup"
+require_relative "integration/child_bootstrap"
 require_relative "integration/rspec_process_runner"
 require_relative "integration/scenario_log_support"
 require_relative "integration/coverage_suppression"
-require_relative "integration/child_debug_support"
+require_relative "integration/child_debug_log"
+require_relative "integration/loaded_features"
 require_relative "integration/base"
 require_relative "integration/mutant_run_support"
 require_relative "integration/rspec_child_runner"
@@ -111,13 +113,14 @@ module Henitai
       def run_tests(test_files)
         require "rspec/core"
         ::RSpec.__send__(:configuration).fail_if_no_examples = true
-        debug_child_rspec_trace(test_files:, rspec_options: [], rspec_argv: test_files)
-        debug_child_example_count("before_run") # steep:ignore Ruby::NoMethod
-        debug_child_puts("[henitai-debug-child] runner_run_start")
+        log = child_debug_log
+        log.rspec_trace(test_files:, rspec_options: [], rspec_argv: test_files)
+        log.example_count("before_run")
+        log.write("[henitai-debug-child] runner_run_start")
         status = run_rspec_runner(test_files)
-        debug_child_puts("[henitai-debug-child] runner_run_return status=#{status.inspect}")
-        debug_child_example_count("after_run") # steep:ignore Ruby::NoMethod
-        debug_child_rspec_exit(status)
+        log.write("[henitai-debug-child] runner_run_return status=#{status.inspect}")
+        log.example_count("after_run")
+        log.rspec_exit(status)
         return status if status.is_a?(Integer)
 
         status == true ? 0 : 1

data/lib/henitai/mutation_skip_directives.rb

@@ -25,7 +25,13 @@ module Henitai
   # Matching mutants are reported as ignored by {StaticFilter}, not dropped.
   class MutationSkipDirectives
     DIRECTIVE = /\A#\s*henitai:disable(?<kind>-start|-end)?(?<rest>[:\s].*)?\z/
-    VALID_OPERATOR_NAMES = Operator::FULL_SET
+
+    # The whitelist is the operator *registry*, not the configured set: the
+    # widest set names every operator henitai knows. Narrowing it to the
+    # configured set would reject a directive for a registered operator the
+    # current run happens not to enable — hard-set names above all, which is
+    # precisely where the escape hatch is needed (ADR-12).
+    VALID_OPERATOR_NAMES = Operator::HARD_SET
 
     # A parsed directive: +operators+ is nil (all) or a Set of canonical
     # operator names; +reason+ is optional free text shown in reports.

data/lib/henitai/operators/return_value.rb

@@ -65,7 +65,7 @@ module Henitai
         body = method_node.children.last
         return body unless body&.type == :begin
 
-        body.children.rfind { |child| child.is_a?(Parser::AST::Node) }
+        body.children.reverse_each.find { |child| child.is_a?(Parser::AST::Node) }
       end
 
       # rubocop:disable Lint/BooleanSymbol

data/lib/henitai/orphan_watchdog.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Makes a forked mutant child exit when its parent dies.
+  #
+  # Children `setpgid(0, 0)` into their own process group, and all parent-side
+  # cleanup (timeout kills, graceful drain, signal traps) only runs while the
+  # parent's event loop is alive. If the parent is SIGKILLed, OOM-killed, or
+  # crashes, its children receive no signal at all: they reparent to init and
+  # keep running, each holding a full Ruby and test-framework image. Runs have
+  # been observed leaving a dozen such orphans behind, several gigabytes in
+  # total.
+  #
+  # A child cannot be told to die by a parent that is already gone, so it has
+  # to notice by itself. This is a poll: portable, and cheap enough at a
+  # multi-second interval that it costs nothing next to running a test suite.
+  # PDEATHSIG (Linux) and kqueue NOTE_EXIT (macOS) would be prompter but are
+  # platform-specific; they can be layered on later behind the same interface.
+  class OrphanWatchdog
+    DEFAULT_INTERVAL = 1.5
+    ENV_ENABLED = "HENITAI_CHILD_WATCHDOG"
+    ENV_INTERVAL = "HENITAI_CHILD_WATCHDOG_INTERVAL"
+
+    # Exit code used when the watchdog fires. 2 classifies as :compile_error
+    # (see ScenarioExecutionResult.status_for), which surfaces in reports and
+    # logs. Codes at 3 and above classify as :killed, which would let a
+    # false positive silently inflate the mutation score -- so a visibly wrong
+    # verdict is preferred to an invisibly wrong one. In the true-positive case
+    # the parent is dead and nothing classifies this child at all.
+    ORPHAN_EXIT_CODE = 2
+
+    # Captured at load time, for the same reason as ProcessLiveness::KILL: the
+    # mutant child runs the host project's own suite, and a spec there stubbing
+    # `Process.ppid` would otherwise make this child believe it had been
+    # reparented and exit itself.
+    PPID = Process.method(:ppid)
+
+    # Opt-OUT, deliberately inverted relative to HENITAI_DEBUG_CHILD's opt-in:
+    # a watchdog that defaulted to off would never protect the runs it exists
+    # for. Set HENITAI_CHILD_WATCHDOG=0 to disable.
+    def self.enabled?(env = ENV)
+      env[ENV_ENABLED] != "0"
+    end
+
+    def self.poll_interval(env = ENV)
+      seconds = Float(env[ENV_INTERVAL], exception: false)
+      seconds&.positive? ? seconds : DEFAULT_INTERVAL
+    end
+
+    # Starts the watchdog in a background thread. Call in the child, right
+    # after fork, with the pid captured in the parent beforehand.
+    #
+    # @return [Thread, nil] nil when disabled
+    def self.start(parent_pid:, env: ENV)
+      return nil unless enabled?(env)
+
+      watchdog = new(parent_pid:, interval: poll_interval(env))
+      Thread.new { watchdog.run }
+    end
+
+    # Every collaborator is injectable so the decision logic can be specced
+    # without forking a process or waiting on a real clock.
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(parent_pid:, interval: DEFAULT_INTERVAL, liveness: ProcessLiveness,
+                   ppid: PPID, on_orphan: nil, sleeper: nil)
+      @parent_pid = parent_pid
+      @interval   = interval
+      @liveness   = liveness
+      @ppid       = ppid
+      @on_orphan  = on_orphan || -> { Kernel.exit!(ORPHAN_EXIT_CODE) }
+      @sleeper    = sleeper || ->(seconds) { Kernel.sleep(seconds) }
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Two arms, because neither alone is sufficient. A changed ppid is
+    # definitive -- we have been reparented, and no pid reuse can fake that --
+    # but it stays equal while the parent lingers as a zombie, which the
+    # liveness probe catches.
+    def orphaned?
+      @ppid.call != @parent_pid || !@liveness.alive?(@parent_pid)
+    end
+
+    # Polls until orphaned, then hands over to the orphan handler -- which by
+    # default calls exit! and so never returns. Checks before sleeping, so a
+    # child forked from an already-dead parent dies immediately rather than
+    # after one interval.
+    def run
+      @sleeper.call(@interval) until orphaned?
+
+      @on_orphan.call
+    end
+  end
+end

data/lib/henitai/process_liveness.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Answers whether a process id is still running.
+  #
+  # Extracted so the one subtle rule here lives in a single place: EPERM means
+  # the process exists but belongs to someone else, so it counts as *alive*.
+  # Only ESRCH proves it is gone. Getting that backwards would let
+  # OrphanWatchdog kill live children, and would make the reports-directory
+  # lock report a running owner as dead.
+  module ProcessLiveness
+    # Captured at load time, before any test double can replace
+    # `Process.kill`. A `Method` object keeps pointing at the original
+    # definition even after the singleton method is redefined, which is what
+    # makes this immune to stubbing.
+    #
+    # This is not defensiveness for its own sake: a mutant child runs the host
+    # project's own suite, and a spec in that suite stubbing `Process.kill` to
+    # raise ESRCH made this answer "parent is dead" while the parent was very
+    # much alive. OrphanWatchdog then exited the child, which the scheduler
+    # recorded as CompileError. Observed on henitai's own dogfood run.
+    KILL = Process.method(:kill)
+
+    # @param pid [Integer, nil] process id to probe
+    # @param kill [#call] signalling primitive; injected only by specs, which
+    #   cannot reach {KILL} by stubbing and must not be able to
+    # @return [Boolean] false only when the pid provably does not exist
+    def self.alive?(pid, kill: KILL)
+      return false unless pid.is_a?(Integer)
+
+      kill.call(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue StandardError
+      # EPERM and anything unexpected: assume alive, the conservative answer
+      # for every caller.
+      true
+    end
+  end
+end

data/lib/henitai/reports_directory_lock.rb

@@ -18,7 +18,17 @@ module Henitai
       File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |file|
         acquire(file)
         write_owner(file)
-        yield
+        # Registered so a forked mutant child can close its inherited copy: the
+        # flock lives on the shared open file description, so a child that
+        # outlives its parent would otherwise keep this lock held. Unregistered
+        # inside the File.open block, keeping the registration's lifetime a
+        # subset of the handle's.
+        InheritedFdRegistry.register(file)
+        begin
+          yield
+        ensure
+          InheritedFdRegistry.unregister(file)
+        end
       end
     end
 
@@ -55,16 +65,7 @@ module Henitai
 
     # True only when the recorded owner pid provably no longer exists. EPERM
     # means the process is alive but owned by someone else — treated as alive.
-    def dead_owner?(pid)
-      return false unless pid.is_a?(Integer)
-
-      Process.kill(0, pid)
-      false
-    rescue Errno::ESRCH
-      true
-    rescue StandardError
-      false
-    end
+    def dead_owner?(pid) = !ProcessLiveness.alive?(pid)
 
     def write_owner(file)
       file.rewind

data/lib/henitai/result.rb

@@ -15,8 +15,28 @@ module Henitai
     SCHEMA_VERSION = "1.0"
     DEFAULT_THRESHOLDS = { high: 80, low: 60 }.freeze
 
+    # Which outcomes count as "the test suite detected this mutant" for the MS
+    # numerator. Duplicated from Configuration rather than read from it: Result
+    # is a domain object and must not depend on configuration loading. The same
+    # arrangement already exists for DEFAULT_THRESHOLDS, and result_spec asserts
+    # the two constants stay equal.
+    DEFAULT_COVERAGE_CRITERIA = {
+      test_result: true,
+      timeout: true,
+      process_abort: true
+    }.freeze
+
+    # Maps each criterion to the mutant status it governs. process_abort has no
+    # producer in lib/ yet -- nothing classifies a mutant as :runtime_error --
+    # so that entry is forward-looking wiring rather than a live code path.
+    CRITERION_STATUSES = {
+      test_result: :killed,
+      timeout: :timeout,
+      process_abort: :runtime_error
+    }.freeze
+
     attr_reader :mutants, :started_at, :finished_at, :thresholds, :survivor_stats,
-                :session_id, :git_sha, :since
+                :session_id, :git_sha, :since, :coverage_criteria
 
     # @param source_provider [#call] maps a file path to its source string.
     #   Injected so the domain object performs no disk IO; the caller (which
@@ -33,7 +53,7 @@ module Henitai
                    partial_rerun: false, survivor_stats: nil,
                    session_id: SecureRandom.uuid, git_sha: nil,
                    source_provider: ->(_file) { "" }, authoritative: true,
-                   since: nil)
+                   since: nil, coverage_criteria: nil)
       @mutants         = mutants
       @started_at      = started_at
       @finished_at     = finished_at
@@ -45,6 +65,7 @@ module Henitai
       @source_provider = source_provider
       @authoritative   = authoritative
       @since           = since
+      @coverage_criteria = DEFAULT_COVERAGE_CRITERIA.merge(coverage_criteria || {})
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -140,7 +161,13 @@ module Henitai
     private
 
     def detected_in(list)
-      list.count { |m| %i[killed timeout runtime_error].include?(m.status) }
+      list.count { |m| detected_statuses.include?(m.status) }
+    end
+
+    def detected_statuses
+      @detected_statuses ||= CRITERION_STATUSES.filter_map do |criterion, status|
+        status if @coverage_criteria[criterion]
+      end
     end
 
     def mutation_score_for(list)

data/lib/henitai/runner.rb

@@ -30,9 +30,16 @@ module Henitai
 
     # @param mode [Hash] execution-mode flags: +dry_run:+ stops before Gate 4,
     #   +incremental:+ reuses still-valid Killed verdicts from history.
+    # +deps+ is assigned in the body, not defaulted in the signature: the
+    # default needs @config, and `config:` itself defaults to a load.
+    #
+    # rubocop:disable Metrics/ParameterLists -- these are the CLI's own flags
+    # plus the dependency seam; a params object would only move the list.
     def initialize(config: Configuration.load, subjects: nil, since: nil, survivors_from: nil,
-                   mode: {})
+                   mode: {}, deps: nil)
+      # rubocop:enable Metrics/ParameterLists
       @config         = config
+      @deps           = deps || RunnerDependencies.new(config: @config)
       @subjects       = subjects
       @since          = since
       @survivors_from = survivors_from
@@ -88,13 +95,13 @@ module Henitai
     end
 
     def resolve_subjects(source_files = self.source_files)
-      subjects = subject_resolver.resolve_from_files(source_files)
-      return subjects if pattern_subjects.empty?
+      subject_selection.resolve(source_files)
+    end
 
-      selected_subjects = pattern_subjects.flat_map do |pattern|
-        subject_resolver.apply_pattern(subjects, pattern.expression)
-      end
-      unique_subjects(selected_subjects)
+    def subject_selection
+      @subject_selection ||= SubjectSelection.new(
+        subject_resolver: subject_resolver, patterns: @subjects
+      )
     end
 
     def generate_mutants(subjects)
@@ -164,6 +171,7 @@ module Henitai
         started_at:,
         finished_at:,
         thresholds: result_thresholds,
+        coverage_criteria: result_coverage_criteria,
         partial_rerun: survivor_rerun?,
         survivor_stats: survivor_strategy.survivor_stats,
         git_sha: safe_head_sha,
@@ -173,20 +181,6 @@ module Henitai
       )
     end
 
-    # Reads each source file once and caches it, so Result consumes source
-    # content while performing no disk IO of its own. Returns "" for files that
-    # cannot be read (e.g. recipe stubs with synthetic locations).
-    def source_provider
-      cache = {} # : Hash[String, String]
-      lambda do |file|
-        cache[file] ||= begin
-          File.read(file)
-        rescue StandardError
-          ""
-        end
-      end
-    end
-
     def safe_head_sha
       git_diff_analyzer.head_sha
     rescue StandardError
@@ -199,123 +193,47 @@ module Henitai
       coverage_bootstrapper.ensure!(source_files:, config:, integration:, test_files:)
     end
 
-    def subject_resolver = @subject_resolver ||= SubjectResolver.new
-
-    def git_diff_analyzer = @git_diff_analyzer ||= GitDiffAnalyzer.new
-
-    def mutant_generator = @mutant_generator ||= MutantGenerator.new
-
-    def static_filter = @static_filter ||= StaticFilter.new
-
-    def execution_engine = @execution_engine ||= ExecutionEngine.new
+    attr_reader :deps
 
-    def coverage_bootstrapper = @coverage_bootstrapper ||= CoverageBootstrapper.new
+    def subject_resolver = deps.subject_resolver
+    def git_diff_analyzer = deps.git_diff_analyzer
+    def mutant_generator = deps.mutant_generator
+    def static_filter = deps.static_filter
+    def execution_engine = deps.execution_engine
+    def coverage_bootstrapper = deps.coverage_bootstrapper
+    def integration = deps.integration
+    def operators = deps.operators
+    def history_store = deps.history_store
+    def per_test_coverage = deps.per_test_coverage
+    def source_provider = deps.source_provider
 
-    def integration
-      @integration ||= Integration.for(config.integration).new
-    end
-
-    def operators
-      @operators ||= Operator.for_set(config.operators)
-    end
-
-    # Fans progress out to the terminal reporter (when enabled) and the
-    # checkpoint writer (when enabled and a file report is configured), so a
-    # long run persists partial results incrementally.
-    def progress_reporter
-      CompositeProgressReporter.for(config:, source_provider:, full_run: full_run?)
-    end
-
-    def history_store
-      @history_store ||= MutantHistoryStore.new(
-        path: File.join(config.reports_dir, Henitai::HISTORY_STORE_FILENAME), per_test_coverage:
-      )
-    end
-
-    # One shared live view of the per-test coverage map: the incremental
-    # filter proves survivor reuse against it and the history store records
-    # the same intersection set — one implementation, one snapshot.
-    def per_test_coverage
-      @per_test_coverage ||= PerTestCoverage.new(reports_dir: config.reports_dir)
-    end
+    def progress_reporter = deps.progress_reporter(full_run: full_run?)
 
     def source_files
-      @source_files ||= filter_changed(reject_excluded(included_source_files))
+      @source_files ||= source_file_selection.call
     end
 
-    def included_source_files
-      Array(config.includes).flat_map do |include_path|
-        Dir.glob(File.join(include_path, "**", "*.rb"))
-      end.uniq
-    end
-
-    # Drops files matched by any `excludes:` glob (e.g. standalone entry points
-    # that cannot be mutation-tested in-process). Excludes apply regardless of
-    # the --since filter.
-    def reject_excluded(files)
-      excluded = excluded_source_files
-      return files if excluded.empty?
-
-      files.reject { |path| excluded.include?(normalize_path(path)) }
-    end
-
-    def excluded_source_files
-      Array(config.excludes)
-        .flat_map { |pattern| Dir.glob(pattern) }
-        .map { |path| normalize_path(path) }
-    end
-
-    def filter_changed(files)
-      return files unless @since
-
-      changed_file_set = changed_paths_since.map { |path| normalize_path(path) }
-      changed_file_set += covered_sources_for_changed_tests(changed_file_set)
-      files.select { |path| changed_file_set.include?(normalize_path(path)) }
-    end
-
-    # Committed changes since the ref plus the current working tree (tracked
-    # dirty and untracked files): the working tree is what gets tested, so it
-    # is always part of "changed since REF".
-    def changed_paths_since
-      git_diff_analyzer.changed_files(from: @since, to: "HEAD") +
-        git_diff_analyzer.working_tree_changed_files
-    end
-
-    # Changed test files select the source files they cover, so an edited
-    # test re-tests the subjects it can kill. Uses the per-test map from the
-    # previous run — Gate 1 runs before this run's bootstrap finishes.
-    def covered_sources_for_changed_tests(changed_paths)
-      changed_paths
-        .flat_map { |path| per_test_coverage.source_files_covered_by(path) }
-        .map { |path| normalize_path(path) }
-    end
-
-    def pattern_subjects
-      Array(@subjects)
-    end
-
-    def unique_subjects(subjects)
-      subjects.uniq { |subject| [subject.expression, subject.source_file] }
+    def source_file_selection
+      @source_file_selection ||= SourceFileSelection.new(
+        config: config, since: @since,
+        git_diff_analyzer: git_diff_analyzer, per_test_coverage: per_test_coverage
+      )
     end
 
-    def normalize_path(path)
-      File.expand_path(path)
-    end
+    def result_thresholds = optional_config(:thresholds)
 
-    def result_thresholds
-      return nil unless config.respond_to?(:thresholds)
+    def result_coverage_criteria = optional_config(:coverage_criteria)
 
-      config.thresholds
-    end
+    # Specs pass bare config doubles that expose only what the example needs, so
+    # scoring inputs are read defensively rather than assumed present.
+    def optional_config(name) = config.respond_to?(name) ? config.public_send(name) : nil
 
-    def survivor_rerun?
-      !@survivors_from.nil?
-    end
+    def survivor_rerun? = !@survivors_from.nil?
 
     # Mutation-scope full run, controlling Result#authoritative? — distinct
     # from the per-test-coverage plan's test-suite-scope "full run".
     def full_run?
-      pattern_subjects.empty? && @since.nil? && !survivor_rerun?
+      Array(@subjects).empty? && @since.nil? && !survivor_rerun?
     end
 
     def survivor_strategy