henitai 0.1.10 → 0.2.0

data/lib/henitai/survivor_loader.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Henitai
+  # Reads a Stryker-compatible mutation report and extracts survivor data.
+  #
+  # Returns a +Report+ value object carrying:
+  #   - +survivor_ids+  — stable IDs of survived mutants
+  #   - +coverage_map+  — stableId → [test_files] from prior coveredBy data
+  #   - +git_sha+       — git HEAD at the time the report was written (may be nil)
+  #
+  # Scope validation is intentionally shallow: checks schemaVersion presence
+  # and at least one file path overlap with config.includes.
+  class SurvivorLoader
+    # Value object returned by #load.
+    Report = Struct.new(:survivor_ids, :coverage_map, :git_sha)
+
+    class FileNotFoundError < StandardError; end
+    class InvalidReportError < StandardError; end
+    class ScopeMismatchError < StandardError; end
+
+    # @param path          [String]        path to a Stryker-compatible JSON report
+    # @param include_paths [Array<String>] from config.includes; used for scope validation
+    def initialize(path, include_paths: [])
+      @path          = path
+      @include_paths = include_paths
+    end
+
+    # @return [Report]
+    def load
+      raw    = read_file
+      report = parse_json(raw)
+      validate_scope(report)
+      build_report(report)
+    end
+
+    private
+
+    def build_report(report)
+      entries = known_entries(report)
+      Report.new(
+        survivor_ids: extract_survivor_ids(entries),
+        coverage_map: extract_coverage_map(entries),
+        git_sha: report["gitSha"]
+      )
+    end
+
+    # Returns mutant entries that have a stableId, warning about those that don't.
+    def known_entries(report)
+      all_mutants(report).select do |entry|
+        if entry["stableId"]
+          true
+        else
+          warn "henitai: survivor report entry missing stableId — skipping"
+          false
+        end
+      end
+    end
+
+    def extract_survivor_ids(entries)
+      entries.filter_map { |e| e["stableId"] if e["status"] == "Survived" }
+    end
+
+    def extract_coverage_map(entries)
+      entries.each_with_object({}) do |entry, map|
+        covered = Array(entry["coveredBy"]).compact
+        map[entry["stableId"]] = covered unless covered.empty?
+      end
+    end
+
+    def read_file
+      File.read(@path)
+    rescue Errno::ENOENT
+      raise FileNotFoundError, "Survivor report not found: #{@path}"
+    end
+
+    def parse_json(raw)
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise InvalidReportError, "Invalid JSON in survivor report #{@path}: #{e.message}"
+    end
+
+    def validate_scope(report)
+      validate_schema_version!(report)
+      return if @include_paths.empty?
+
+      report_files = normalized_report_files(report)
+      include_dirs_raw = normalized_include_dirs_raw
+      include_dirs_abs = normalized_include_dirs_abs(include_dirs_raw)
+
+      return if any_report_file_overlaps?(report_files, include_dirs_raw, include_dirs_abs)
+
+      raise ScopeMismatchError,
+            "Survivor report #{@path} has no file overlap with configured includes — " \
+            "did you pass a report from a different project?"
+    end
+
+    def validate_schema_version!(report)
+      return if report.key?("schemaVersion")
+
+      raise InvalidReportError,
+            "Survivor report #{@path} is missing schemaVersion — is this a Henitai report?"
+    end
+
+    def normalized_report_files(report)
+      (report.fetch("files", {}) || {}).keys.map { |p| strip_trailing_slash(p.to_s) }
+    end
+
+    def normalized_include_dirs_raw
+      @include_paths.map { |p| strip_trailing_slash(p.to_s) }.uniq
+    end
+
+    def normalized_include_dirs_abs(dirs_raw)
+      dirs_raw.map { |p| File.expand_path(p) }.uniq
+    end
+
+    def strip_trailing_slash(path)
+      path.sub(%r{/\z}, "")
+    end
+
+    def any_report_file_overlaps?(report_files, include_dirs_raw, include_dirs_abs)
+      report_files.any? do |file|
+        include_dirs_raw.any? { |inc| path_prefix_match?(file, inc) } ||
+          include_dirs_abs.any? { |inc_abs| path_prefix_match?(File.expand_path(file), inc_abs) }
+      end
+    end
+
+    def path_prefix_match?(path, dir)
+      return false if path.empty? || dir.empty?
+
+      path == dir || path.start_with?(dir + File::SEPARATOR)
+    end
+
+    def all_mutants(report)
+      files = report.fetch("files", {}) || {}
+      files.values.compact.flat_map { |file_data| file_data.fetch("mutants", []) }
+    end
+  end
+end

data/lib/henitai/survivor_selector.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Filters a mutant list to those that match a set of prior survivor stable IDs.
+  #
+  # After calling #select, #unmatched_ids reports which survivor IDs had no
+  # corresponding mutant in the current generation. A high unmatched ratio
+  # indicates that the source has drifted and a full run is recommended.
+  class SurvivorSelector
+    DRIFT_THRESHOLD = 0.5
+    class SelectionError < StandardError; end
+
+    def initialize(survivor_ids:)
+      @survivor_ids  = survivor_ids.to_set
+      @unmatched_ids = nil
+    end
+
+    def select(mutants)
+      current_index = mutants.to_h { |m| [m.stable_id, m] }
+      matched_ids, @unmatched_ids = @survivor_ids.partition { |id| current_index.key?(id) }
+      matched_ids.filter_map { |id| current_index[id] }
+    end
+
+    def unmatched_ids
+      raise SelectionError, "Call #select before accessing #unmatched_ids" if @unmatched_ids.nil?
+
+      @unmatched_ids
+    end
+
+    def drift_warning?
+      return false if @survivor_ids.empty?
+
+      unmatched_ids.size.to_f / @survivor_ids.size > DRIFT_THRESHOLD
+    end
+  end
+end

data/lib/henitai/survivor_test_filter.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Splits a matched survivor set into stable and pending subsets by consulting
+  # a git diff against the covering tests from the prior report.
+  #
+  # A survivor is **stable** (can skip re-execution) when:
+  #   - it has covering test data in the prior report, AND
+  #   - none of those test files appear in the diff between the prior run's
+  #     git_sha and the current HEAD.
+  #
+  # A survivor is **pending** (must execute) when:
+  #   - git_sha is nil (no anchor → conservative), OR
+  #   - its coveredBy data is absent or empty, OR
+  #   - at least one covering test file changed.
+  #
+  # On any git error the filter conservatively treats all survivors as pending.
+  class SurvivorTestFilter
+    # @param coverage_map  [Hash<String, Array<String>>] stableId → [test_files]
+    # @param git_sha       [String, nil] git SHA from the prior report
+    # @param dirty_source_files [Boolean] true when the current worktree has
+    #   dirty source files and the survivor shortcut must be disabled
+    # @param worktree_changed_files [Array<String>] dirty tracked/untracked files
+    # @param diff_analyzer [GitDiffAnalyzer]
+    def initialize(
+      coverage_map:,
+      git_sha:,
+      dirty_source_files: false,
+      worktree_changed_files: [],
+      diff_analyzer: GitDiffAnalyzer.new
+    )
+      @coverage_map  = coverage_map
+      @git_sha       = git_sha
+      @dirty_source_files = dirty_source_files
+      @worktree_changed_files = Array(worktree_changed_files)
+      @diff_analyzer = diff_analyzer
+    end
+
+    # @param mutants [Array<Mutant>]
+    # @return [Hash<Symbol, Array<Mutant>>] { stable: [...], pending: [...] }
+    def apply(mutants)
+      return { stable: [], pending: mutants } if @dirty_source_files
+      return { stable: [], pending: mutants } if @git_sha.nil?
+
+      changed = changed_test_files
+      return { stable: [], pending: mutants } if changed.nil?
+
+      mutants.each_with_object({ stable: [], pending: [] }) do |mutant, result|
+        bucket = stable_survivor?(mutant, changed) ? :stable : :pending
+        result[bucket] << mutant
+      end
+    end
+
+    private
+
+    def stable_survivor?(mutant, changed)
+      covering = @coverage_map[mutant.stable_id]
+      return false if covering.nil? || covering.empty?
+
+      covering.none? { |test_file| changed.include?(test_file) }
+    end
+
+    # Returns a Set of changed test file paths, or nil on any git error
+    # (nil triggers conservative fallback in #apply — all survivors pending).
+    def changed_test_files
+      committed = @diff_analyzer.changed_files(from: @git_sha, to: "HEAD")
+      (committed + @worktree_changed_files).to_set
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/henitai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Henitai
-  VERSION = "0.1.10"
+  VERSION = "0.2.0"
 end

data/lib/henitai.rb

@@ -26,6 +26,7 @@ module Henitai
   autoload :PerTestCoverageSelector, "henitai/per_test_coverage_selector"
   autoload :Subject, "henitai/subject"
   autoload :Mutant, "henitai/mutant"
+  autoload :MutantIdentity, "henitai/mutant_identity"
   autoload :Operator, "henitai/operator"
   autoload :Operators, "henitai/operators"
   autoload :SourceParser, "henitai/source_parser"
@@ -39,6 +40,10 @@ module Henitai
   autoload :EquivalenceDetector, "henitai/equivalence_detector"
   autoload :StaticFilter, "henitai/static_filter"
   autoload :StillbornFilter, "henitai/stillborn_filter"
+  autoload :SurvivorLoader,          "henitai/survivor_loader"
+  autoload :SurvivorSelector,        "henitai/survivor_selector"
+  autoload :SurvivorTestFilter,      "henitai/survivor_test_filter"
+  autoload :SurvivorActivationCache, "henitai/survivor_activation_cache"
   autoload :ScenarioExecutionResult, "henitai/scenario_execution_result"
   autoload :CoverageFormatter, "henitai/coverage_formatter"
   autoload :MinitestCoverageReporter, "henitai/minitest_coverage_reporter"
@@ -47,6 +52,9 @@ module Henitai
   autoload :SamplingStrategy, "henitai/sampling_strategy"
   autoload :TestPrioritizer, "henitai/test_prioritizer"
   autoload :ExecutionEngine, "henitai/execution_engine"
+  autoload :ParallelExecutionRunner, "henitai/parallel_execution_runner"
+  autoload :ProcessWorkerRunner, "henitai/process_worker_runner"
+  autoload :ProcessWakeup, "henitai/process_wakeup"
   autoload :Runner, "henitai/runner"
   autoload :Reporter, "henitai/reporter"
   autoload :Integration, "henitai/integration"

data/sig/henitai.rbs

@@ -73,6 +73,38 @@ module Henitai
   module Operators
   end
 
+  module Integration::ChildDebugSupport
+    private
+
+    def run_rspec_runner: (Array[String]) -> untyped
+    def build_rspec_runner: () -> untyped
+    def configure_rspec_runner: (untyped) -> void
+    def load_rspec_spec_files: (Array[String]) -> void
+    def run_rspec_specs: (untyped) -> untyped
+    def debug_child_timeout_dump: (Integer) -> void
+    def install_debug_timeout_trap: () -> void
+    def debug_child_thread_dump: (String) -> void
+    def debug_child_puts: (String) -> void
+    def debug_child?: () -> bool
+    def debug_child_rspec_trace: (
+      test_files: Array[String],
+      rspec_options: Array[String],
+      rspec_argv: Array[String]
+    ) -> void
+    def debug_child_rspec_exit: (untyped) -> void
+    def debug_child_example_count: (String) -> void
+    def debug_child_activation_start: (String) -> void
+    def debug_child_activation_end: (untyped, test_files: Array[String]) -> void
+    def debug_child_mutant_meta: (Mutant) -> void
+    def debug_child_activation_check: () -> void
+    def suppress_simplecov!: () -> void
+    def suppress_coverage!: () -> void
+    def loaded_feature_map: (Array[String]) -> Array[[String, bool]]
+    def loaded_feature?: (String) -> bool
+    def rspec_world_example_count: () -> Integer?
+    def pause: (Float) -> void
+  end
+
   class Configuration
     DEFAULT_TIMEOUT: Float
     DEFAULT_OPERATORS: Symbol
@@ -106,11 +138,14 @@ module Henitai
     private
 
     def load_raw_configuration: (String) -> Hash[Symbol, untyped]
+    def detect_integration: () -> String
     def apply_defaults: (Hash[Symbol, untyped]) -> void
     def apply_general_defaults: (Hash[Symbol, untyped]) -> void
     def apply_mutation_defaults: (Hash[Symbol, untyped]) -> void
     def apply_analysis_defaults: (Hash[Symbol, untyped]) -> void
     def merge_defaults: (Hash[Symbol, untyped], Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
+    def resolve_integration_default: (untyped) -> untyped
+    def default_dashboard: (Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
     def symbolize_keys: (untyped) -> untyped
   end
 
@@ -171,8 +206,11 @@ module Henitai
     attr_accessor duration: Float?
     attr_accessor covered_by: Array[String]?
     attr_accessor tests_completed: Integer?
+    attr_reader precomputed_stable_id: String?
+    attr_reader precomputed_activation_source: String?
 
-    def initialize: (subject: Subject, operator: String, nodes: Hash[Symbol, untyped], description: String, location: Hash[Symbol, untyped]) -> void
+    def initialize: (subject: Subject, operator: String, nodes: Hash[Symbol, untyped], description: String, location: Hash[Symbol, untyped], ?precomputed_stable_id: String?, ?precomputed_activation_source: String?) -> void
+    def stable_id: () -> String
     def killed?: () -> bool
     def survived?: () -> bool
     def pending?: () -> bool
@@ -256,9 +294,12 @@ module Henitai
     def self.for: (String) -> untyped
 
     class Base
+      include ChildDebugSupport
+
       def select_tests: (Subject) -> Array[String]
       def test_files: () -> Array[String]
       def run_mutant: (mutant: Mutant, test_files: Array[String], timeout: Float) -> ScenarioExecutionResult
+      def spawn_mutant: (mutant: Mutant, test_files: Array[String]) -> ChildHandle
       def run_suite: (Array[String], ?timeout: Float) -> ScenarioExecutionResult
       def per_test_coverage_supported?: () -> bool
       def wait_with_timeout: (Integer, Float) -> untyped
@@ -268,9 +309,26 @@ module Henitai
       private
 
       def pause: (Float) -> void
+      def wait_nonblocking: (Integer) -> untyped
       def handle_timeout: (Integer) -> Symbol
       def cleanup_child_process: (Integer) -> void
-      def rspec_options: () -> Array[String]
+      def suppress_simplecov!: () -> void
+      def suppress_coverage!: () -> void
+      def run_tests: (Array[String]) -> Integer
+      def debug_child?: () -> bool
+      def debug_child_puts: (String) -> void
+      def debug_child_rspec_trace: (test_files: Array[String], rspec_options: Array[String], rspec_argv: Array[String]) -> void
+      def debug_child_rspec_exit: (untyped status) -> void
+      def debug_child_activation_start: (String mutant_id) -> void
+      def debug_child_activation_end: (untyped activation_result, test_files: Array[String]) -> void
+      def debug_child_mutant_meta: (Mutant) -> void
+      def debug_child_activation_check: () -> void
+      def debug_child_example_count: (String) -> void
+      def loaded_feature_map: (Array[String]) -> Array[[String, bool]]
+      def loaded_feature?: (String) -> bool
+      def rspec_world_example_count: () -> Integer?
+      def run_child_activation_and_tests: (mutant: Mutant, test_files: Array[String], log_paths: Hash[Symbol, String]) -> Integer
+      def with_non_interactive_stdin: () { () -> untyped } -> untyped
       def subprocess_env: () -> Hash[String, String]
       def scenario_log_support: () -> ScenarioLogSupport
       def with_subprocess_env: () { () -> untyped } -> untyped
@@ -300,9 +358,25 @@ module Henitai
       def stderr_stream: () -> IO
     end
 
+    module SchedulerDiagnostics
+      def self.enabled?: () -> bool
+      def self.child_started: (Integer?) -> void
+      def self.child_ended: (Integer?) -> void
+      def self.summary: () -> Hash[Symbol, untyped]
+      def self.reset!: () -> void
+    end
+
+    class ChildHandle
+      attr_accessor pid: Integer?
+      attr_accessor log_paths: Hash[Symbol, String]
+
+      def initialize: (pid: Integer?, log_paths: Hash[Symbol, String]) -> void
+    end
+
     class RspecProcessRunner
       def run_mutant: (Rspec, mutant: Mutant, test_files: Array[String], timeout: Float) -> ScenarioExecutionResult
       def run_suite: (Rspec, Array[String], timeout: Float) -> ScenarioExecutionResult
+      def spawn_mutant: (Rspec, mutant: Mutant, test_files: Array[String], log_paths: Hash[Symbol, String]) -> ChildHandle
     end
 
     class Rspec < Base
@@ -312,13 +386,21 @@ module Henitai
       def select_tests: (Subject) -> Array[String]
       def test_files: () -> Array[String]
       def run_mutant: (mutant: Mutant, test_files: Array[String], timeout: Float) -> ScenarioExecutionResult
+      def spawn_mutant: (mutant: Mutant, test_files: Array[String]) -> ChildHandle
       def run_suite: (Array[String], ?timeout: Float) -> ScenarioExecutionResult
       def per_test_coverage_supported?: () -> bool
 
       private
 
+      def mutant_log_name: (Mutant) -> String
       def run_in_child: (mutant: Mutant, test_files: Array[String], log_paths: Hash[Symbol, String]) -> Integer
+      def suppress_simplecov!: () -> void
+      def suppress_coverage!: () -> void
+      def install_debug_timeout_trap: () -> void
+      def debug_child_thread_dump: (String) -> void
+      def debug_child_example_count: (String) -> void
       def suite_command: (Array[String]) -> Array[String]
+      def rspec_suite_runner_script: () -> String
       def build_result: (untyped, Hash[Symbol, String]) -> ScenarioExecutionResult
       def scenario_status: (untyped) -> Symbol
       def exit_status_for: (untyped) -> Integer?
@@ -339,17 +421,29 @@ module Henitai
       def requires_source_file_transitively?: (String, String, ?Array[String]) -> bool
       def required_files: (String) -> Array[String]
       def resolve_required_file: (String, String, String) -> String?
+      def loaded_feature_map: (Array[String]) -> Array[[String, bool]]
+      def loaded_feature?: (String) -> bool
       def relative_candidates: (String, String) -> Array[String]
       def require_candidates: (String, String) -> Array[String]
       def expand_candidates: (String, String) -> Array[String]
     end
 
+    module CoverageRuntimeSuppressors
+      def self.suppress_simplecov!: () -> void
+      def self.suppress_coverage!: () -> void
+    end
+
     module SimpleCovStartSuppressor
       def start: (*untyped) -> nil
     end
 
+    module CoverageStartSuppressor
+      def start: (*untyped) -> nil
+    end
+
     class Minitest < Rspec
       def run_mutant: (mutant: Mutant, test_files: Array[String], timeout: Float) -> ScenarioExecutionResult
+      def spawn_mutant: (mutant: Mutant, test_files: Array[String]) -> ChildHandle
       def run_suite: (Array[String], ?timeout: Float) -> ScenarioExecutionResult
 
       private
@@ -358,6 +452,7 @@ module Henitai
       def run_tests: (Array[String]) -> Integer
       def preload_environment: () -> void
       def setup_load_path: () -> void
+      def suppress_minitest_autorun!: () -> nil
       def suppress_simplecov!: () -> void
       def subprocess_env: () -> Hash[String, String]
       def cleanup_suite_process: (Integer?, untyped) -> void
@@ -372,15 +467,21 @@ module Henitai
 
   class GitDiffAnalyzer
     def changed_files: (from: String, to: String, ?dir: String) -> Array[String]
+    def working_tree_changed_files: (?dir: String) -> Array[String]
+    def head_sha: (?dir: String) -> String?
   end
 
   class MutantGenerator
     def generate: (Array[Subject], Array[untyped], ?config: untyped) -> Array[Mutant]
   end
 
+  module MutantIdentity
+    def self.stable_id: (Mutant) -> String
+  end
+
   class MutantHistoryStore
     def initialize: (path: String) -> void
-    def record: (Result, version: String, ?recorded_at: Time) -> void
+    def record: (untyped, version: String, ?recorded_at: Time) -> void
     def trend_report: () -> Hash[Symbol, untyped]
   end
 
@@ -420,6 +521,16 @@ module Henitai
     def run: (Array[Mutant], untyped, untyped, untyped, ?Hash[Symbol, untyped]) -> void
   end
 
+  class ProcessWorkerRunner
+    SCHEDULER_POLL_INTERVAL: Float
+    PROCESS_DRAIN_WINDOW: Float
+
+    Slot: untyped
+
+    def initialize: (worker_count: Integer) -> void
+    def run: (Array[Mutant], untyped, untyped, untyped?, ?Hash[Symbol, untyped]) -> Array[ScenarioExecutionResult]
+  end
+
   class StaticFilter
     def initialize: (?coverage_report_reader: CoverageReportReader) -> void
     def apply: (Array[Mutant], untyped) -> Array[Mutant]
@@ -441,9 +552,7 @@ module Henitai
     def parallel_execution?: (untyped, Array[Mutant]) -> bool
     def worker_count: (untyped) -> Integer
     def run_linear: (Array[Mutant], untyped, untyped, untyped?, untyped) -> void
-    def run_parallel: (Array[Mutant], untyped, untyped, untyped?, untyped) -> void
-    def pipe_stdin?: () -> bool
-    def start_stdin_watcher: () { () -> void } -> Thread
+    def run_parallel: (Array[Mutant], untyped, untyped, untyped?) -> void
     def process_mutant: (Mutant, untyped, untyped, untyped?, ?untyped) -> void
     def prioritized_tests_for: (Mutant, untyped, untyped) -> Array[String]
     def test_prioritizer: () -> TestPrioritizer
@@ -457,6 +566,7 @@ module Henitai
     SERIALIZER_METHODS: Hash[Symbol, Symbol]
 
     def self.activate!: (untyped) -> Symbol?
+    def self.activation_source_for: (Mutant) -> String?
     def initialize: () -> void
     def activate!: (untyped) -> Symbol?
 
@@ -512,7 +622,10 @@ module Henitai
       private
 
       def report_lines: (Result) -> Array[String]
-      def summary_lines: (Result) -> Array[String]
+      def summary_lines: (untyped) -> Array[String]
+      def full_summary_lines: (untyped) -> Array[String]
+      def partial_summary_lines: (untyped) -> Array[String]
+      def append_survivor_stats: (Array[String], untyped) -> void
       def survived_detail_lines: (Result) -> Array[String]
       def survived_mutant_lines: (Mutant) -> Array[String]
       def survived_mutant_header: (Mutant) -> String
@@ -536,6 +649,13 @@ module Henitai
 
       private
 
+      def write_canonical: (Hash[Symbol, untyped]) -> void
+      def write_session_snapshot: (Hash[Symbol, untyped]) -> void
+      def write_activation_recipes: (untyped) -> void
+      def survived_mutants_for: (untyped) -> Array[Mutant]
+      def session_snapshot_path: (String) -> String
+      def session_recipe_path: (String) -> String
+      def canonical_path: () -> String
       def report_path: () -> String
       def write_history_report: () -> void
       def history_store_path: () -> String
@@ -595,8 +715,12 @@ module Henitai
     attr_reader started_at: Time
     attr_reader finished_at: Time
     attr_reader thresholds: Hash[Symbol, Integer]
+    attr_reader survivor_stats: Hash[Symbol, untyped]?
+    attr_reader session_id: String
+    attr_reader git_sha: String?
 
-    def initialize: (mutants: Array[Mutant], started_at: Time, finished_at: Time, ?thresholds: Hash[Symbol, Integer]?) -> void
+    def initialize: (mutants: Array[Mutant], started_at: Time, finished_at: Time, ?thresholds: Hash[Symbol, Integer]?, ?partial_rerun: bool, ?survivor_stats: Hash[Symbol, untyped]?, ?session_id: String, ?git_sha: String?) -> void
+    def partial_rerun?: () -> bool
     def killed: () -> Integer
     def survived: () -> Integer
     def equivalent: () -> Integer
@@ -609,6 +733,8 @@ module Henitai
 
     private
 
+    def base_schema: () -> Hash[Symbol, untyped]
+    def unmatched_survivor_ids: () -> Array[String]
     def build_files_section: () -> Hash[Symbol, untyped]
     def mutant_to_schema: (Mutant) -> Hash[Symbol, untyped]
     def coverage_schema: (Mutant) -> Hash[Symbol, untyped]
@@ -620,11 +746,56 @@ module Henitai
     def stryker_status: (Symbol) -> String
   end
 
+  class SurvivorLoader
+    FileNotFoundError: singleton(StandardError)
+    InvalidReportError: singleton(StandardError)
+    ScopeMismatchError: singleton(StandardError)
+
+    class Report
+      attr_reader survivor_ids: Array[String]
+      attr_reader coverage_map: Hash[String, Array[String]]
+      attr_reader git_sha: String?
+
+      def initialize: (survivor_ids: Array[String], coverage_map: Hash[String, Array[String]], git_sha: String?) -> void
+    end
+
+    def initialize: (String, ?include_paths: Array[String]) -> void
+    def load: () -> Report
+  end
+
+  class SurvivorTestFilter
+    def initialize: (
+      coverage_map: Hash[String, Array[String]],
+      git_sha: String?,
+      ?dirty_source_files: bool,
+      ?worktree_changed_files: Array[String],
+      ?diff_analyzer: GitDiffAnalyzer
+    ) -> void
+    def apply: (Array[Mutant]) -> Hash[Symbol, Array[Mutant]]
+  end
+
+  class SurvivorSelector
+    DRIFT_THRESHOLD: Float
+
+    def initialize: (survivor_ids: Array[String]) -> void
+    def select: (Array[Mutant]) -> Array[Mutant]
+    def unmatched_ids: () -> Array[String]
+    def drift_warning?: () -> bool
+  end
+
+  class SurvivorActivationCache
+    FILENAME: String
+
+    def self.compute: (Array[Mutant]) -> Hash[String, Hash[String, untyped]]
+    def self.load: (String) -> Hash[String, Hash[String, untyped]]?
+    def self.write: (String, Hash[String, Hash[String, untyped]]) -> void
+  end
+
   class Runner
     attr_reader config: Configuration
     attr_reader result: untyped
 
-    def initialize: (?config: Configuration, ?subjects: Array[Subject], ?since: String) -> void
+    def initialize: (?config: Configuration, ?subjects: Array[Subject], ?since: String, ?survivors_from: String?) -> void
     def run: () -> Result
     def resolve_subjects: (?Array[String]) -> untyped
     def generate_mutants: (untyped) -> untyped
@@ -656,6 +827,26 @@ module Henitai
     def mutants_for: (Array[Subject], Array[String]) -> Array[Mutant]
     def with_reports_dir: () { () -> untyped } -> untyped
     def result_thresholds: () -> Hash[Symbol, Integer]?
+    def survivor_rerun?: () -> bool
+    def apply_survivor_selection: (Array[Mutant]) -> Array[Mutant]
+    def try_recipe_run: () -> Array[Mutant]?
+    def load_survivor_report: () -> SurvivorLoader::Report
+    def run_from_recipes: (SurvivorLoader::Report, Array[String]?) -> Array[Mutant]?
+    def recipe_fast_path_safe?: (SurvivorLoader::Report, Array[String]?) -> bool
+    def recipe_selector_and_stubs: (Array[String], Hash[String, Hash[String, untyped]]) -> [SurvivorSelector, Array[Mutant]]
+    def load_activation_recipes: (Array[String]) -> Hash[String, Hash[String, untyped]]?
+    def build_stub_mutant: (String, Hash[String, untyped]) -> Mutant
+    def stub_subject_from_recipe: (Hash[String, untyped]) -> Subject
+    def recipe_location: (Hash[String, untyped]?) -> Hash[Symbol, untyped]
+    def finalize_survivor_split: (SurvivorSelector, Array[Mutant], Hash[Symbol, Array[Mutant]]) -> Array[Mutant]
+    def dirty_worktree_changed_files: () -> Array[String]?
+    def dirty_source_files?: (Array[String]?, ?git_sha: String?) -> bool
+    def committed_changed_files: (String?) -> Array[String]
+    def in_include_root?: (String, Array[String]) -> bool
+    def warn_survivor_drift: (SurvivorSelector) -> void
+    def build_survivor_stats: (SurvivorSelector, Array[Mutant], Hash[Symbol, Array[Mutant]]) -> Hash[Symbol, untyped]
+    def test_filter: (SurvivorLoader::Report, ?dirty_source_files: bool) -> SurvivorTestFilter
+    def safe_head_sha: () -> String?
   end
 
   class CoverageBootstrapper