henitai 0.5.1 → 0.6.0

data/README.md

@@ -77,17 +77,22 @@ excludes:
   - lib/henitai/eager_load.rb   # standalone entry points with no in-process coverage
 
 test_excludes:
-  - spec/end_to_end/*_spec.rb   # never select these files for individual mutants
+  - spec/end_to_end/*_spec.rb   # never run these files, mutants or coverage baseline
 
 mutation:
   operators: light   # light | full
   timeout: 10.0
+  timeout_multiplier: 3.0
   max_flaky_retries: 3
+  flaky_detection: false   # run the baseline twice to find flaky test files
   max_log_bytes: 5000000
   max_timeout: 30.0
+  control_runs: true   # re-run detected subjects with the unmutated method
+  fork_server: false   # opt-in: boot the RSpec/Minitest environment once, fork each mutant run from it (any jobs; falls back to per-mutant boot with a warning)
   sampling:
     ratio: 0.05
     strategy: stratified
+    seed: 0   # integer >= 0; selects which mutants of each stratum are kept
 reports_dir: reports
 reporters:
   - terminal
@@ -109,28 +114,88 @@ when a value is invalid.
 
 CLI flags override the corresponding values from `.henitai.yml`.
 
-`test_excludes` removes matching test files from per-mutant selection. A mutant
-with no tests left is reported as `NoCoverage` and is not executed.
+`test_excludes` removes matching test files from per-mutant selection *and* from
+the coverage-bootstrap suite. A mutant with no tests left is reported as
+`NoCoverage` and is not executed. Excluding slow end-to-end or integration
+suites therefore also keeps them out of the baseline run — which matters,
+because a test that never runs against a mutant can never kill one, and the
+baseline suite has a fixed timeout. Lines covered only by excluded tests count
+as uncovered and are not mutated. Excluding every test file aborts with
+`Henitai::ConfigurationError`.
 `mutation.max_log_bytes` is a positive per-stream byte cap for captured child
-output. `mutation.max_timeout` caps auto-calibrated timeouts; an explicit
+output. Without an explicit `mutation.timeout`, each mutant's timeout is
+calibrated as `mutation.timeout_multiplier` (default `3.0`) × (the summed
+durations of the selected test files + the measured suite boot time), with a
+2 s floor. `mutation.max_timeout` (default `30.0`) caps the calibrated value,
+but never below the measured baseline plus 2 s; when the baseline alone exceeds
+`max_timeout`, Henitai warns once and uses baseline + 2 s. An explicit
 `mutation.timeout` still takes precedence. When JSON or HTML reporting is
 enabled, `reports.checkpoint*` controls periodic canonical-report checkpoints.
 Each checkpoint updates `mutation-report.json`; when the HTML reporter is
 configured, it also regenerates `mutation-report.html` from that merged JSON.
 
+`mutation.sampling` keeps `ceil(size * ratio)` mutants per subject (at least
+one). Mutants are stratified by operator: each operator's mutants are ordered
+by a SHA256 of `seed` and the mutant's stable ID, and the strata are visited
+round-robin, so every operator is represented before any contributes a second
+mutant. The kept mutants retain their original order. The same seed selects the
+same mutants across runs and line shifts; change `seed` to draw another sample.
+The applied `{strategy, ratio, seed}` is recorded in the report under
+`sampling`.
+
+Scoped runs (`--since`, subject patterns, survivor reruns) are merged into the
+existing `mutation-report.json` by `stableId`. A run that mutated every
+subject of a file (a non-authoritative run without subject patterns, such as
+`--since`) lists it under the top-level `completeFiles` and replaces that
+file's prior entry wholesale, dropping it when it yields no mutants, so stale
+mutants of edited or deleted code do not linger. Each file entry carries
+`sessionId` and `gitSha` provenance of the run that produced it; a file merged
+from several sessions has none. `--since` diffs against the merge base
+(`REF...HEAD`), so commits that landed on the base branch after you forked do
+not count as your changes.
+
 Before mutation testing starts, Henitai checks whether the current coverage data
 covers the configured source files. If not, Henitai runs the configured test
 suite once to bootstrap a usable coverage baseline. If coverage is still
 unavailable for the current sources, `henitai run` aborts with
 `Henitai::CoverageError`.
 
-Surviving mutants are retried up to `mutation.max_flaky_retries` times before
-they are classified as survivors. The default retry budget is 3.
+Survivors are never retried: flakiness can only turn a survivor into a kill, so
+a retry could only inflate the score. A killed mutant is retried, up to
+`mutation.max_flaky_retries` times (default 3), only when every test file that
+failed for it is a known flaky test; if any retry survives, the mutant is
+reported as `Survived`.
+
+Known flaky tests come from the opt-in `mutation.flaky_detection: true`. The
+baseline suite then runs twice (existing coverage is not reused), and test files
+whose pass/fail outcome differs between the runs are written to
+`reports/henitai_flaky_tests.json`. Without `flaky_detection` there is no flaky
+set and nothing is retried. At the end of the run Henitai reports the flaky
+tests and how many kills were re-checked.
+
+A mutant only counts as detected when a test failed because of the mutation.
+Before a mutant runs, Henitai checks that its activated code differs from the
+original method by exactly the reported mutation; a mutant that fails this
+check is reported as `CompileError` with the reason in `statusReason` instead
+of running. Each mutant child reports what it got to — a failed activation, a
+finished test run, or a `SystemExit` raised by the code under test — and only
+a finished test run yields `Killed` or `Survived`. A failed activation is a
+`CompileError`; a child killed by a signal, one that exits without reporting,
+and a `SystemExit` during the tests are `RuntimeError`. With
+`mutation.control_runs` (on by default), every subject that has detected
+mutants is run once more with its unmutated method injected; if its tests fail
+then, the injection itself is broken for that subject and its detected
+verdicts are reclassified as `CompileError`.
 
 Per-test coverage reporting is currently wired through the RSpec child runner.
 Minitest integration reuses the same selection and execution flow, but does not
 yet enable the per-test coverage formatter.
 
+Test selection is coverage first: the per-test coverage map is the primary source
+of candidate tests for a mutant, and name matching is only the fallback for when
+the map cannot decide (no map, no location, or no covering test left in the
+integration).
+
 Henitai currently defaults to linear mutant execution. Set `jobs` in
 `.henitai.yml` or pass `--jobs N` to opt into parallel mutant execution.
 
@@ -155,6 +220,13 @@ for framework errors. With `--strict-exit-codes` (opt-in, additive) it also
 exits `3` when one or more mutants timed out and `4` when runtime/compile
 errors are present; precedence `2` > `3` > `4` > `1` > `0`. The timeout code
 is informational — a run can pass its threshold and still exit `3`.
+A run with no scoreable mutant passes its threshold only when there was
+nothing to score (no changed code, everything ignored). When `CompileError`
+harness errors emptied the score denominator, nothing was tested, and the run
+exits `1`.
+`Pending` mutants (left over from an interrupted run, without a verdict) are
+excluded from both the MS and the MSI denominators; MSI is
+`killed / (total - pending)`.
 
 For pull-request feedback, add the `github` reporter to `reporters:` in
 `.henitai.yml`: it prints one `::warning file=...,line=...` workflow command
@@ -168,10 +240,13 @@ and every covering test file are byte-identical to what was recorded. A
 `Survived` verdict needs more proof, because a *new* test could now kill it:
 it is reused only when, additionally, the live covering set derived from the
 current per-test coverage map matches the recorded set exactly (no test
-added, dropped, or changed) and the dependency fingerprint (spec helpers,
-`spec/support`, fixtures/factories, `Gemfile.lock`, `.henitai.yml`, `.rspec`)
-is unchanged. When per-test coverage is unavailable, survivors simply
-re-execute — reuse never happens on doubt (see ADR-11).
+added, dropped, or changed). Both kinds additionally require the *reuse
+context* to be unchanged: a fingerprint of the test dependency files (spec
+helpers, `spec/support`, fixtures/factories, `Gemfile.lock`, `.henitai.yml`,
+`.rspec`), the henitai version, the integration, the operator set,
+`test_excludes` and `coverage_criteria`. Verdicts recorded without a reuse
+context are never reused. When per-test coverage is unavailable, survivors
+simply re-execute — reuse never happens on doubt (see ADR-11).
 Reused mutants stay visible in the report (`fromCache: true` beside
 `stableId`) and count toward MS/MSI; the terminal prints
 `N of M verdicts reused from history (K killed, S survived)` plus an
@@ -180,7 +255,8 @@ results.
 Generated mutants temporarily include `legacyStableId` so scoped runs replace
 canonical entries written before site-offset IDs were introduced instead of
 duplicating them.
-Timeouts and errors always re-execute. `--force` bypasses reuse.
+Timeouts and errors always re-execute. `--force` bypasses reuse, including
+the reuse applied to `--survivors-from` reruns.
 `henitai run --dry-run` lists the post-filter mutant set without executing
 mutants and always exits `0`. Gate 0 may still run the configured test suite to
 refresh baseline coverage.
@@ -195,9 +271,20 @@ authoritative, and the file may be the only artifact a dry run creates.
 
 `henitai run --survivors-from ...` performs a partial rerun: it reports only
 the selected survivors, skips threshold-based exit checks, and does not update
-the run trend history. Dirty worktree changes are included, so you can edit
+the run trend history. The selected survivors go through the same reuse rules
+as `--incremental`, always, not only with that flag: a survivor is skipped
+(reported with `fromCache: true`) only when its subject source, its covering
+test set and the reuse context are unchanged, so new or edited tests and
+helpers invalidate it. Dirty worktree changes are included, so you can edit
 tests locally without committing first; if source files under `includes` are
-dirty, Henitai reruns the matched survivors conservatively.
+dirty, the activation-recipe fast path is not used and the survivors are
+re-matched against freshly generated mutants. Survivors restored from
+activation recipes have no source range to fingerprint and are always
+re-executed. When `--survivors-from` names a canonical report, Henitai uses the
+matching session snapshot only if every file entry carries that report's
+`sessionId`; a report merged from several runs is used as is.
+Only authoritative runs (no `--since`, no subject patterns, no survivor rerun)
+add a row to the trend history.
 
 ### Skipping mutations inline
 
@@ -220,8 +307,11 @@ standalone comment in the contiguous comment block directly above a `def`
 (a blank line breaks the association). Trailing text is allowed
 (`# henitai:disable -- reviewed defensive branch`). Skipped mutants are
 reported as `Ignored`, so they stay visible in the report instead of silently
-vanishing. Use `mutation.ignore_patterns` for repo-wide policy and
-`# henitai:disable` for one-off, reviewed exclusions.
+vanishing. `mutation.ignore_patterns` is matched against the source line where
+each mutant's node starts, so only mutants on a matching line are reported as
+`Ignored`; an enclosing `if` or block whose body matches stays mutated. Use
+`mutation.ignore_patterns` for repo-wide policy and `# henitai:disable` for
+one-off, reviewed exclusions.
 
 Directives can also target specific operators, carry a reason (serialized as
 `statusReason`, visible in the HTML report), and cover regions:
@@ -301,7 +391,8 @@ dashboard:
 Set `STRYKER_DASHBOARD_API_KEY` in your CI environment to publish reports. When
 the key, project, and version are present, the `dashboard` reporter uploads the
 Stryker-schema report to the dashboard REST API (default
-`https://dashboard.stryker-mutator.io`); otherwise it is skipped silently. The
+`https://dashboard.stryker-mutator.io`); otherwise it is skipped silently.
+Scoped runs upload the merged canonical report rather than their partial one. The
 project defaults to the git remote and the version to the current branch or CI
 ref (`GITHUB_REF_NAME`/`GITHUB_REF`/`GITHUB_SHA`).
 
@@ -317,6 +408,8 @@ bundle install
 bundle exec rspec        # run tests
 bundle exec ruby bin/verify-process-free-specs # verify self-mutation-safe specs
 bundle exec rake smoke:integration:all # run rspec/minitest integration smoke projects
+bundle exec rake oracle # measure false kills/survivors on the oracle corpus
+bundle exec rake oracle:reuse # check --incremental verdicts equal fresh runs
 bundle exec rubocop      # lint
 bundle exec henitai clean # remove stale generated report artifacts
 bundle exec henitai run  # dogfood

data/assets/schema/henitai.schema.json

@@ -65,6 +65,21 @@
           "type": "number",
           "exclusiveMinimum": 0
         },
+        "flaky_detection": {
+          "type": "boolean",
+          "default": false,
+          "description": "Run the baseline suite twice and mark test files whose outcome differs between runs as flaky. Only killed mutants whose killing tests are all flaky are re-checked, up to max_flaky_retries times."
+        },
+        "fork_server": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opt-in. Boot the test environment once in a long-lived fork server and fork each mutant run from it instead of re-booting per mutant. Supported for RSpec and Minitest with any jobs value; unsupported integrations and a server that fails to boot fall back to per-mutant boot with a warning."
+        },
+        "control_runs": {
+          "type": "boolean",
+          "default": true,
+          "description": "After execution, re-run each subject that has detected mutants with its unmutated method injected; if its tests fail, the subject's detections are reclassified as CompileError."
+        },
         "ignore_patterns": {
           "type": "array",
           "items": {
@@ -83,6 +98,11 @@
             },
             "strategy": {
               "enum": ["stratified"]
+            },
+            "seed": {
+              "type": "integer",
+              "minimum": 0,
+              "default": 0
             }
           }
         }

data/lib/henitai/arid_node_filter.rb

@@ -10,32 +10,17 @@ module Henitai
     INVARIANT_METHODS = %i[is_a? respond_to? kind_of?].freeze
     DSL_METHODS = %i[let subject before after].freeze
 
-    def suppressed?(node, config)
-      custom_pattern_match?(node, config) || catalog_match?(node)
+    def suppressed?(node)
+      catalog_match?(node)
     end
 
     private
 
-    def custom_pattern_match?(node, config)
-      source = node.location&.expression&.source
-      return false unless source
-
-      compiled_ignore_patterns(config).any? do |pattern|
-        pattern.match?(source)
-      end
-    end
-
-    def compiled_ignore_patterns(config)
-      patterns = Array(config&.ignore_patterns).dup.freeze
-      @compiled_ignore_patterns ||= {}
-      @compiled_ignore_patterns[patterns] ||= patterns.map { |pattern| Regexp.new(pattern) }
-    end
-
     def catalog_match?(node)
       case node.type
       when :send
         send_match?(node)
-      when :block
+      when :block, :numblock
         block_match?(node)
       when :or_asgn
         # Memoization-style ||= is treated as arid on purpose. UpdateOperator
@@ -64,7 +49,7 @@ module Henitai
       return false unless send_node&.type == :send
 
       receiver, method_name, = send_node.children
-      receiver.nil? && DSL_METHODS.include?(method_name.to_sym)
+      (receiver.nil? && DSL_METHODS.include?(method_name.to_sym)) || send_match?(send_node)
     end
 
     def direct_output_call?(receiver, method_name)

data/lib/henitai/bootstrap_error_message.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Explains a failed baseline suite run, pointing at its log when one exists.
+  module BootstrapErrorMessage
+    GENERIC = "Configured test suite failed while generating coverage"
+
+    module_function
+
+    def build(result)
+      return GENERIC unless result.respond_to?(:log_path)
+
+      tail = result.tail(12).strip
+      message = +GENERIC
+      message << " (see #{result.log_path})"
+      message << "\n#{tail}" unless tail.empty?
+      message
+    end
+  end
+end

data/lib/henitai/canonical_report_merger.rb

@@ -11,6 +11,11 @@ module Henitai
   # falls back to the current run's schema by itself -- structurally never
   # worse than the unconditional overwrite this replaces.
   #
+  # Files the current run lists under `completeFiles` (it mutated every subject
+  # of them) are the exception: their prior entry is replaced wholesale, or
+  # removed when the run produced no mutants for them, so stale mutants of
+  # changed or deleted code cannot linger next to the new ones.
+  #
   # Merges at mutant granularity, keyed by `stableId`, not file granularity:
   # a `--survivors-from` rerun's schema only contains the re-verified
   # survivors for a file, so replacing that file's whole entry would drop
@@ -37,10 +42,12 @@ module Henitai
     end
 
     def self.merge_files(current, prior, prune_missing:)
-      merged_files = overlay_current_mutants(deep_dup(prior["files"]), current)
+      prior_files = deep_dup(prior["files"])
+      Array(current["completeFiles"]).each { |file| prior_files.delete(file) }
+      merged_files = overlay_current_mutants(prior_files, current)
       merged_files.reject! { |_, file| file["mutants"].empty? }
       prune_missing_source_files(merged_files) if prune_missing
-      current.merge("files" => merged_files)
+      current.except("completeFiles").merge("files" => merged_files)
     end
     private_class_method :merge_files
 
@@ -68,11 +75,25 @@ module Henitai
     def self.append_current_mutants(merged_files, current)
       current.fetch("files", {}).each do |file, entry|
         target = merged_files[file] ||= { "mutants" => [] }
+        merge_provenance(target, entry)
         target["source"] = entry["source"]
         target["language"] = entry["language"]
         target["mutants"] += entry["mutants"]
       end
     end
+
+    # A file merged from several sessions has no single snapshot holding all
+    # its mutants, so its provenance is dropped unless both sides agree.
+    def self.merge_provenance(target, entry)
+      provenance = entry.slice("sessionId", "gitSha")
+      # A fresh run with no prior mutants left in this file: the current
+      # entry's provenance covers every mutant in it.
+      fresh = target["mutants"].empty?
+      agree = fresh || target["sessionId"] == entry["sessionId"]
+      %w[sessionId gitSha].each { |key| target.delete(key) }
+      target.merge!(provenance) if agree
+    end
+    private_class_method :merge_provenance
     private_class_method :append_current_mutants
 
     def self.mutant_ids(schema)

data/lib/henitai/cli/run_command.rb

@@ -43,7 +43,8 @@ module Henitai
           survivors_from: resolved_survivors_from,
           mode: {
             dry_run: options.fetch(:dry_run, false),
-            incremental: options.fetch(:incremental, false) && !options.fetch(:force, false)
+            incremental: options.fetch(:incremental, false) && !options.fetch(:force, false),
+            force: options.fetch(:force, false)
           }
         )
         runner.run
@@ -64,7 +65,7 @@ module Henitai
         # being a snapshot path; this keeps activation-recipes lookup correct.
         return survivors_from if File.basename(parent_dir) == "sessions"
 
-        session_id = session_id_from_report(survivors_from)
+        session_id = single_session_id_from_report(survivors_from)
         return survivors_from if session_id.nil?
 
         snapshot_path = survivors_snapshot_path(report_dir, session_id)
@@ -85,9 +86,16 @@ module Henitai
         File.join(report_dir, "sessions", session_id, "mutation-report.json")
       end
 
-      def session_id_from_report(path)
+      # The report's sessionId only names a snapshot holding every survivor when
+      # each file entry was produced by that very session. A merged canonical
+      # report (or a legacy one without per-file provenance) is used as is.
+      def single_session_id_from_report(path)
         parsed = JSON.parse(File.read(path))
-        parsed["sessionId"]
+        session_id = parsed["sessionId"]
+        files = parsed["files"]
+        return nil unless files.is_a?(Hash) && files.each_value.all? { |f| f["sessionId"] == session_id }
+
+        session_id
       rescue JSON::ParserError, Errno::ENOENT
         nil
       end
@@ -104,6 +112,18 @@ module Henitai
         strict_status || threshold_status_for(result, config)
       end
 
+      # An empty score denominator passes only when there was nothing to score
+      # (no changed code, everything ignored). When harness errors emptied it,
+      # nothing was tested, and the run must not pass its threshold.
+      def empty_score_status(result)
+        harness_errors = result.mutants.count { |mutant| mutant.status == :compile_error }
+        return 0 if harness_errors.zero?
+
+        warn "henitai: no mutant could be scored: #{harness_errors} harness error(s) " \
+             "(CompileError, see statusReason in the report)"
+        1
+      end
+
       # Expanded, opt-in exit codes (precedence: timeout > runtime/compile
       # error > threshold miss). The timeout code is informational and
       # independent of coverage_criteria.timeout: a run can pass its threshold
@@ -118,9 +138,7 @@ module Henitai
 
       def threshold_status_for(result, config)
         score = result.mutation_score
-        # No valid mutants to evaluate (e.g. an incremental run with no changed
-        # code) cannot fail a threshold — treat it as success.
-        return 0 if score.nil?
+        return empty_score_status(result) if score.nil?
 
         score.to_i >= config.thresholds.fetch(:low, 60) ? 0 : 1
       end

data/lib/henitai/cli/run_options.rb

@@ -79,7 +79,7 @@ module Henitai
       def add_force_option(opts, options)
         opts.on(
           "--force",
-          "Bypass verdict reuse and execute every mutant (only meaningful with --incremental)"
+          "Bypass verdict reuse (--incremental, --survivors-from) and execute every mutant"
         ) do
           options[:force] = true
         end

data/lib/henitai/cli.rb

@@ -37,7 +37,10 @@ module Henitai
       %w[coverage .resultset.json],
       %w[coverage .last_run.json],
       ["henitai_per_test.json"],
-      [CoverageBootstrapper::DEPENDENCY_MANIFEST_FILE]
+      [PerTestCoverageCollector::BOOT_FILE_NAME],
+      [CoverageBootstrapper::DEPENDENCY_MANIFEST_FILE],
+      [FlakyTestRegistry::FILE_NAME],
+      [TestFileOutcomes::REPORT_FILE_NAME]
     ].freeze
 
     # Whole directories of per-mutant scratch artifacts, removed recursively.

data/lib/henitai/configuration.rb

@@ -43,7 +43,7 @@ module Henitai
 
     attr_reader :integration, :includes, :excludes, :test_excludes, :operators, :timeout,
                 :timeout_multiplier, :ignore_patterns, :sampling, :jobs,
-                :max_flaky_retries, :max_log_bytes, :max_timeout,
+                :max_flaky_retries, :max_log_bytes, :max_timeout, :control_runs, :flaky_detection, :fork_server,
                 :coverage_criteria, :thresholds,
                 :reporters, :reports_dir,
                 :checkpoint_enabled, :checkpoint_every, :checkpoint_interval,
@@ -124,6 +124,9 @@ module Henitai
       @max_flaky_retries = mutation.fetch(:max_flaky_retries, DEFAULT_MAX_FLAKY_RETRIES)
       @max_log_bytes = mutation[:max_log_bytes] || DEFAULT_MAX_LOG_BYTES
       @max_timeout = mutation[:max_timeout] || DEFAULT_MAX_TIMEOUT
+      @control_runs = mutation.fetch(:control_runs, true)
+      @flaky_detection = mutation.fetch(:flaky_detection, false)
+      @fork_server = mutation.fetch(:fork_server, false)
     end
 
     def apply_reports_defaults(raw)

data/lib/henitai/configuration_validator/rules.rb

@@ -100,6 +100,13 @@ module Henitai
         Scalars.validate_max_flaky_retries(value[:max_flaky_retries])
         Scalars.validate_max_log_bytes(value[:max_log_bytes])
         Scalars.validate_max_timeout(value[:max_timeout])
+        validate_mutation_flags(value)
+      end
+
+      def validate_mutation_flags(value)
+        %i[control_runs flaky_detection fork_server].each do |key|
+          Scalars.validate_boolean(value[key], "mutation.#{key}") unless value[key].nil?
+        end
       end
 
       def validate_mutation_filters(value)
@@ -133,6 +140,7 @@ module Henitai
         Scalars.validate_sampling_completeness(value)
         Scalars.validate_sampling_ratio(value[:ratio])
         Scalars.validate_sampling_strategy(value[:strategy])
+        Scalars.validate_sampling_seed(value[:seed])
       end
 
       def warn_unknown_keys(raw, allowed_keys, path = nil)

data/lib/henitai/configuration_validator/scalars.rb

@@ -150,6 +150,15 @@ module Henitai
         )
       end
 
+      def validate_sampling_seed(value)
+        return if value.nil?
+        return if value.is_a?(Integer) && value >= 0
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.sampling.seed: expected Integer >= 0, got #{value.inspect}"
+        )
+      end
+
       def validate_sampling_completeness(value)
         return if value.key?(:ratio) && value.key?(:strategy)
 

data/lib/henitai/configuration_validator.rb

@@ -26,9 +26,10 @@ module Henitai
     ].freeze
     VALID_MUTATION_KEYS = %i[
       operators timeout timeout_multiplier ignore_patterns max_flaky_retries max_log_bytes max_timeout sampling
+      control_runs flaky_detection fork_server
     ].freeze
     VALID_REPORTS_KEYS = %i[checkpoint checkpoint_every checkpoint_interval].freeze
-    VALID_SAMPLING_KEYS = %i[ratio strategy].freeze
+    VALID_SAMPLING_KEYS = %i[ratio strategy seed].freeze
     VALID_COVERAGE_CRITERIA_KEYS = %i[test_result timeout process_abort].freeze
     VALID_THRESHOLDS_KEYS = %i[high low].freeze
     VALID_DASHBOARD_KEYS = %i[project base_url].freeze

data/lib/henitai/constant_path.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Names constants as the source writes them and attributes them to the
+  # namespace they belong to, as far as the source alone can tell.
+  module ConstantPath
+    module_function
+
+    # The constant path of a +const+ or +casgn+ node as written;
+    # root-qualified paths keep their leading +::+. nil for other nodes.
+    def of(node)
+      return unless node.respond_to?(:type)
+
+      case node.type
+      when :const, :casgn
+        parent = of(node.children[0])
+        own = node.children[1].to_s
+        parent.nil? ? own : "#{parent}::#{own}"
+      when :cbase
+        ""
+      end
+    end
+
+    # +name+ inside +namespace+. A root-qualified name (+::Top+) ignores the
+    # enclosing namespace.
+    def qualify(namespace, name)
+      return name.delete_prefix("::") if name&.start_with?("::")
+      return name if namespace.nil? || namespace.empty?
+      return namespace if name.nil? || name.empty?
+
+      "#{namespace}::#{name}"
+    end
+
+    # The object a singleton method or singleton class is defined on: the
+    # enclosing namespace for +self+, the named constant otherwise, nil for
+    # any other object. A relative constant is attributed to the innermost
+    # lexical candidate, which Ruby also tries first. The source alone cannot
+    # tell whether +Other+ inside +module Outer+ is +Outer::Other+ or
+    # +::Other+, so this name can be off; activation resolves the real object
+    # at runtime (Mutant::Activator).
+    def owner(receiver, namespace)
+      case receiver.type
+      when :self then namespace
+      when :const then qualify(namespace, of(receiver))
+      end
+    end
+  end
+end

data/lib/henitai/control_run.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Verifies, after execution, that the activation path itself does not break
+  # a subject's tests.
+  #
+  # For every subject with a detected verdict (Killed, Timeout, RuntimeError)
+  # the unmutated method is injected through the same activation and fork
+  # path, against the same test files. The tests must pass. If they do not,
+  # injecting the method is what made them fail -- a lost constant scope,
+  # `super` or `yield` inside `define_method`, a rebuilt parameter list -- so
+  # none of that subject's detections can be credited to its mutations. They
+  # are reclassified as CompileError with the control's outcome as reason.
+  #
+  # Verdicts reused from history are left alone: they were not produced by
+  # this run's activation.
+  class ControlRun
+    DETECTED = %i[killed timeout runtime_error].freeze
+
+    # @param timeout_for [#call] test files -> timeout in seconds
+    def initialize(integration:, timeout_for:)
+      @integration = integration
+      @timeout_for = timeout_for
+    end
+
+    # @return [Hash] verified:, failed: subjects; reclassified: mutants
+    def verify(mutants)
+      stats = { verified: 0, failed: 0, reclassified: 0 }
+      detected_groups(mutants).each_value do |detected|
+        stats[:verified] += 1
+        result = run_control(detected.first)
+        next if result.status == :survived
+
+        stats[:failed] += 1
+        stats[:reclassified] += reclassify(detected, result)
+      end
+      stats
+    end
+
+    private
+
+    def detected_groups(mutants)
+      Array(mutants)
+        .select { |mutant| DETECTED.include?(mutant.status) && !mutant.from_cache? && mutant.original_node }
+        .group_by { |mutant| [mutant.subject, test_files(mutant)] }
+    end
+
+    def run_control(mutant)
+      files = test_files(mutant)
+      @integration.run_mutant(mutant: control_for(mutant), test_files: files, timeout: @timeout_for.call(files))
+    end
+
+    def control_for(mutant)
+      node = mutant.original_node
+      Mutant.new(subject: mutant.subject, operator: "Control", nodes: { original: node, mutated: node },
+                 description: "unmutated control", location: mutant.location)
+    end
+
+    def reclassify(detected, result)
+      reason = "control run failed: the unmutated method fails its tests when injected " \
+               "(#{[result.status, result.status_reason].compact.join(': ')})"
+      detected.each do |mutant|
+        mutant.status = :compile_error
+        mutant.status_reason = reason
+      end
+      detected.size
+    end
+
+    def test_files(mutant)
+      Array(mutant.covered_by).sort
+    end
+  end
+end