padded_cell 0.1.0 → 0.3.0

data/ext/padded_cell_native/core/src/restarts.rs

@@ -0,0 +1,64 @@
+//! When to stop replacing dead workers.
+//!
+//! A worker that dies takes its test with it and gets replaced; a worker
+//! that keeps dying (a boot that segfaults, an `after_fork` hook that exits)
+//! would otherwise turn every remaining test into a crash report, one fork
+//! at a time.
+//!
+//! The decision is [`supervisor_machines`]'s: one-for-one, restart
+//! intensity over a sliding window. Spawning, killing and reaping stay with
+//! the caller.
+
+use supervisor_machines::{Decision, Exit, Intensity, Policy, Strategy, Supervisor};
+
+#[cfg(test)]
+mod tests;
+
+/// Restart timestamps kept: bounds [`Restarts::limit`].
+const HISTORY: usize = 1024;
+
+/// Deaths allowed per worker inside one window, before giving up.
+const PER_WORKER: u32 = 4;
+
+/// Deaths allowed inside one window whatever the worker count: a few tests
+/// that kill their worker are what cells and workers exist to contain.
+const FLOOR: u32 = 16;
+
+/// The sliding window, in nanoseconds.
+pub const WINDOW_NS: u64 = 10_000_000_000;
+
+/// Worker deaths seen by one pool.
+#[derive(Debug, Clone)]
+pub struct Restarts {
+    supervisor: Supervisor<1, HISTORY>,
+}
+
+impl Restarts {
+    /// For a pool of `jobs` workers: `4 * jobs` deaths per 10 seconds, at
+    /// least 16.
+    #[must_use]
+    pub fn new(jobs: usize) -> Self {
+        let jobs = u32::try_from(jobs).unwrap_or(u32::MAX);
+        let limit = jobs.saturating_mul(PER_WORKER).clamp(FLOOR, HISTORY_LIMIT);
+        Self { supervisor: Supervisor::new(Strategy::OneForOne, Intensity::new(limit, WINDOW_NS)) }
+    }
+
+    /// A worker died at `now_ns` (monotonic): true to replace it, false to
+    /// give up. Once false, always false.
+    pub const fn died(&mut self, now_ns: u64) -> bool {
+        matches!(
+            self.supervisor.stopped(0, Policy::Permanent, Exit::Abnormal, now_ns),
+            Decision::Restart(_)
+        )
+    }
+
+    /// Deaths allowed inside [`WINDOW_NS`].
+    #[must_use]
+    pub const fn limit(&self) -> u32 {
+        self.supervisor.intensity().restarts
+    }
+}
+
+/// The history must hold one more death than the limit to see it exceeded.
+#[expect(clippy::cast_possible_truncation, reason = "HISTORY is 1024")]
+const HISTORY_LIMIT: u32 = HISTORY as u32 - 1;

data/ext/padded_cell_native/ffi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "padded_cell_native"
-version = "0.1.0"
+version = "0.3.0"
 description = "Ruby bindings for the padded_cell crate"
 publish = false
 edition.workspace = true
@@ -15,5 +15,6 @@ crate-type = ["cdylib"]
 workspace = true
 
 [dependencies]
+deadline_machines.workspace = true
 magnus.workspace = true
 padded_cell.workspace = true

data/ext/padded_cell_native/ffi/src/chart.rs

@@ -0,0 +1,205 @@
+use std::path::PathBuf;
+
+use magnus::{Error, RArray, RHash, Ruby, Symbol, TryConvert, Value};
+use padded_cell::chart::{
+    self, Arm, CRITERIA, Condition, Criterion, FileCoverage, Format, Meta, Method, Options, Scope,
+    Span, Stats, Summary, Thresholds, Totals,
+};
+
+use crate::file_error;
+use padded_cell::FileError;
+
+/// Reads every source, writes the reports, checks the thresholds, and
+/// returns what it found:
+///
+/// ```text
+/// files    [[path, name, lines, branches or nil, methods or nil, loaded], ...]
+///            branches  [[type, l1, c1, l2, c2, [[type, l1, c1, l2, c2, hits], ...]], ...]
+///            methods   [[owner, name, l1, c1, l2, c2, hits], ...]
+/// groups   [[name, [file index, ...]], ...]
+/// options  {dir:, formats: ["lcov", "json"], nocov_token:, criteria: ["line", "branch"],
+///           minimum:, minimum_by_file:, maximum_drop:, last_run: [line, branch, method] (nil: none),
+///           minimum_by_group: [[name, [line, branch, method]], ...], write_last_run:,
+///           root:, timestamp:, created_at:, commit:, project_name:, generator:}
+///
+/// => {total: stats, groups: [[name, stats], ...], files: [[name, stats], ...],
+///     violations: [[scope, name or nil, criterion, limit, actual], ...]}
+///    stats  {line: [covered, missed, omitted, hits, percent, strength], branch: ..., method: ...}
+/// ```
+pub fn chart_report(
+    ruby: &Ruby,
+    files: RArray,
+    groups: Vec<(String, Vec<usize>)>,
+    options: RHash,
+) -> Result<RHash, Error> {
+    let option = |key: &str| ruby.to_symbol(key);
+    let formats = options
+        .fetch::<_, Vec<String>>(option("formats"))?
+        .iter()
+        .map(|name| name.parse::<Format>())
+        .collect::<Result<Vec<_>, _>>()
+        .map_err(|error| Error::new(ruby.exception_arg_error(), error.to_string()))?;
+    let measured: Vec<Criterion> = options
+        .fetch::<_, Vec<String>>(option("criteria"))?
+        .iter()
+        .filter_map(|name| CRITERIA.into_iter().find(|criterion| criterion.singular() == name))
+        .collect();
+    let thresholds = Thresholds {
+        minimum: options.fetch(option("minimum"))?,
+        minimum_by_file: options.fetch(option("minimum_by_file"))?,
+        minimum_by_group: options.fetch(option("minimum_by_group"))?,
+        maximum_drop: options.fetch(option("maximum_drop"))?,
+        last_run: options.fetch(option("last_run"))?,
+    };
+    let meta = Meta {
+        root: options.fetch(option("root"))?,
+        timestamp: options.fetch(option("timestamp"))?,
+        created_at: options.fetch(option("created_at"))?,
+        commit: options.fetch(option("commit"))?,
+        project_name: options.fetch(option("project_name"))?,
+        generator: options.fetch(option("generator"))?,
+    };
+    let dir: PathBuf = options.fetch(option("dir"))?;
+    let analysis = Options {
+        nocov_token: options.fetch(option("nocov_token"))?,
+        methods: measured.contains(&Criterion::Method),
+    };
+    let files = (0..files.len())
+        .map(|index| file(files.entry(index.cast_signed())?))
+        .collect::<Result<Vec<_>, Error>>()?;
+
+    let failed = |error: FileError| file_error(ruby, &error);
+    let reports = chart::analyze_all(&files, &analysis).map_err(failed)?;
+    let totals = Totals::of_files(&reports);
+    let groups: Vec<(String, Vec<usize>, Totals)> = groups
+        .into_iter()
+        .map(|(name, members)| {
+            let totals = Totals::of_files(members.iter().filter_map(|&index| reports.get(index)));
+            (name, members, totals)
+        })
+        .collect();
+    let named: Vec<(String, Totals)> =
+        groups.iter().map(|(name, _, totals)| (name.clone(), *totals)).collect();
+    let violations = chart::violations(&thresholds, &measured, &totals, &reports, &named);
+    let summary = Summary { files: &reports, measured, totals, groups, violations, meta };
+    for format in formats {
+        chart::write(&dir, format, &summary).map_err(failed)?;
+    }
+    if options.fetch(option("write_last_run"))? {
+        chart::write_last_run_file(&dir, &summary).map_err(failed)?;
+    }
+    result(ruby, &summary)
+}
+
+fn result(ruby: &Ruby, summary: &Summary<'_>) -> Result<RHash, Error> {
+    let result = ruby.hash_new();
+    result.aset(ruby.to_symbol("total"), totals(ruby, &summary.totals)?)?;
+    let groups = ruby.ary_new_capa(summary.groups.len());
+    for (name, _, group) in &summary.groups {
+        groups.push((name.as_str(), totals(ruby, group)?))?;
+    }
+    result.aset(ruby.to_symbol("groups"), groups)?;
+    let files = ruby.ary_new_capa(summary.files.len());
+    for report in summary.files {
+        let stats = criteria(ruby, |criterion| report.stats.with_percent(criterion))?;
+        files.push((report.file.name.as_str(), stats))?;
+    }
+    result.aset(ruby.to_symbol("files"), files)?;
+    let violations = ruby.ary_new_capa(summary.violations.len());
+    for violation in &summary.violations {
+        let (scope, name) = match &violation.scope {
+            Scope::Total => ("total", None),
+            Scope::File(name) => ("file", Some(name.as_str())),
+            Scope::Group(name) => ("group", Some(name.as_str())),
+            Scope::Drop => ("drop", None),
+        };
+        let criterion = violation.criterion.singular();
+        violations.push((
+            ruby.to_symbol(scope),
+            name,
+            ruby.to_symbol(criterion),
+            violation.limit,
+            violation.actual,
+        ))?;
+    }
+    result.aset(ruby.to_symbol("violations"), violations)?;
+    Ok(result)
+}
+
+fn totals(ruby: &Ruby, totals: &Totals) -> Result<RHash, Error> {
+    criteria(ruby, |criterion| {
+        let stats = totals.get(criterion);
+        (stats, stats.percent())
+    })
+}
+
+fn criteria(ruby: &Ruby, stats: impl Fn(Criterion) -> (Stats, f64)) -> Result<RHash, Error> {
+    let hash = ruby.hash_new();
+    for criterion in CRITERIA {
+        let (stats, percent) = stats(criterion);
+        let row =
+            (stats.covered, stats.missed, stats.omitted, stats.hits, percent, stats.strength());
+        hash.aset(ruby.to_symbol(criterion.singular()), row)?;
+    }
+    Ok(hash)
+}
+
+fn file(row: RArray) -> Result<FileCoverage, Error> {
+    Ok(FileCoverage {
+        path: row.entry(0)?,
+        name: row.entry(1)?,
+        lines: row.entry::<RArray>(2)?.to_vec()?,
+        branches: row.entry::<Option<RArray>>(3)?.map(conditions).transpose()?,
+        methods: row.entry::<Option<RArray>>(4)?.map(methods).transpose()?,
+        loaded: row.entry(5)?,
+    })
+}
+
+fn conditions(rows: RArray) -> Result<Vec<Condition>, Error> {
+    rows.into_iter()
+        .map(|row| {
+            let row = RArray::try_convert(row)?;
+            let arms = RArray::try_convert(row.entry(5)?)?
+                .into_iter()
+                .map(|arm| {
+                    let arm = RArray::try_convert(arm)?;
+                    Ok(Arm { kind: name(arm.entry(0)?)?, span: span(arm, 1)?, hits: arm.entry(5)? })
+                })
+                .collect::<Result<_, Error>>()?;
+            Ok(Condition { kind: name(row.entry(0)?)?, span: span(row, 1)?, arms })
+        })
+        .collect()
+}
+
+fn methods(rows: RArray) -> Result<Vec<Method>, Error> {
+    rows.into_iter()
+        .map(|row| {
+            let row = RArray::try_convert(row)?;
+            Ok(Method {
+                owner: row.entry(0)?,
+                name: name(row.entry(1)?)?,
+                span: span(row, 2)?,
+                hits: row.entry(6)?,
+            })
+        })
+        .collect()
+}
+
+/// Four integers from `at`: first line, first column, last line, last column.
+fn span(row: RArray, at: isize) -> Result<Span, Error> {
+    Ok(Span {
+        start_line: row.entry(at)?,
+        start_column: row.entry(at.strict_add(1))?,
+        end_line: row.entry(at.strict_add(2))?,
+        end_column: row.entry(at.strict_add(3))?,
+    })
+}
+
+/// A branch type or method name: a Symbol from Ruby's Coverage, a String
+/// once through JSON.
+fn name(value: Value) -> Result<String, Error> {
+    match Symbol::from_value(value) {
+        Some(symbol) => Ok(symbol.name()?.into_owned()),
+        None => String::try_convert(value),
+    }
+}

data/ext/padded_cell_native/ffi/src/lib.rs

@@ -18,6 +18,9 @@ use magnus::prelude::*;
 use magnus::{Error, RArray, RString, Ruby, function};
 use padded_cell::{Discovery, FileError};
 
+mod chart;
+mod limits;
+
 /// `Errno::*` for the path, as Ruby's own file reading raises.
 fn file_error(ruby: &Ruby, error: &FileError) -> Error {
     let path = error.path.display().to_string();
@@ -116,5 +119,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     module.define_module_function("discover", function!(discover, 1))?;
     module.define_module_function("discover_files", function!(discover_files, 1))?;
     module.define_module_function("plan", function!(plan, 5))?;
+    module.define_module_function("chart_report", function!(chart::chart_report, 3))?;
+    limits::define(ruby, module)?;
     Ok(())
 }

data/ext/padded_cell_native/ffi/src/limits.rs

@@ -0,0 +1,83 @@
+//! What bounds a run: `PaddedCellNative::Deadline` (`--timeout` and
+//! `--budget`) and `PaddedCellNative::Restarts` (dead workers). Times are
+//! monotonic nanoseconds, the same clock in the runner, its workers and their
+//! cells.
+
+use std::cell::RefCell;
+
+use deadline_machines::{Deadline, Instant};
+use magnus::{Error, Module, Object, RModule, Ruby, function, method};
+use padded_cell::Restarts;
+
+/// A point in monotonic time past which a test (or the run) is cut short, or
+/// never.
+#[magnus::wrap(class = "PaddedCellNative::Deadline", free_immediately, size, frozen_shareable)]
+struct RbDeadline(Deadline);
+
+impl RbDeadline {
+    const fn after(now_ns: u64, ns: u64) -> Self {
+        Self(Deadline::after(Instant(now_ns), ns))
+    }
+
+    const fn never() -> Self {
+        Self(Deadline::never())
+    }
+
+    /// `timeout_ns` from `now_ns`, never past this deadline; nil: this one.
+    fn derive(&self, now_ns: u64, timeout_ns: Option<u64>) -> Self {
+        Self(timeout_ns.map_or(self.0, |ns| self.0.derive(Instant(now_ns), ns)))
+    }
+
+    /// Nanoseconds left (0 once expired), nil when never.
+    const fn remaining_ns(&self, now_ns: u64) -> Option<u64> {
+        self.0.remaining_ns(Instant(now_ns))
+    }
+
+    const fn is_expired(&self, now_ns: u64) -> bool {
+        self.0.is_expired(Instant(now_ns))
+    }
+
+    /// Monotonic nanoseconds, nil when never.
+    fn expires_at(&self) -> Option<u64> {
+        self.0.expires_at().map(|at| at.0)
+    }
+}
+
+#[magnus::wrap(class = "PaddedCellNative::Restarts", free_immediately, size)]
+struct RbRestarts(RefCell<Restarts>);
+
+impl RbRestarts {
+    fn new(jobs: usize) -> Self {
+        Self(RefCell::new(Restarts::new(jobs)))
+    }
+
+    /// True to replace the dead worker, false to give up.
+    fn died(&self, now_ns: u64) -> bool {
+        self.0.borrow_mut().died(now_ns)
+    }
+
+    fn limit(&self) -> u32 {
+        self.0.borrow().limit()
+    }
+
+    const fn window_ns() -> u64 {
+        padded_cell::restarts::WINDOW_NS
+    }
+}
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    let deadline = module.define_class("Deadline", ruby.class_object())?;
+    deadline.define_singleton_method("after", function!(RbDeadline::after, 2))?;
+    deadline.define_singleton_method("never", function!(RbDeadline::never, 0))?;
+    deadline.define_method("derive", method!(RbDeadline::derive, 2))?;
+    deadline.define_method("remaining_ns", method!(RbDeadline::remaining_ns, 1))?;
+    deadline.define_method("expired?", method!(RbDeadline::is_expired, 1))?;
+    deadline.define_method("expires_at", method!(RbDeadline::expires_at, 0))?;
+
+    let restarts = module.define_class("Restarts", ruby.class_object())?;
+    restarts.define_singleton_method("new", function!(RbRestarts::new, 1))?;
+    restarts.define_singleton_method("window_ns", function!(RbRestarts::window_ns, 0))?;
+    restarts.define_method("died", method!(RbRestarts::died, 1))?;
+    restarts.define_method("limit", method!(RbRestarts::limit, 0))?;
+    Ok(())
+}

data/lib/padded_cell/asylum.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  # --asylum: tests that failed get more attempts once the run is over, one
+  # at a time, each in a fresh cell. A test that passes on retry counts as
+  # passed but is reported as flaky, with every attempt and what changed:
+  #
+  #   attempt 1, same seed, run alone:  timing, contention, or state left by
+  #                                     the tests that ran around it
+  #   attempt 2+, another seed:         randomness or test order
+  #
+  # A test that fails every attempt keeps its first failure.
+  class Asylum
+    ALONE = 'timing, contention or state left by other tests'
+    RESEEDED = 'randomness or test order'
+    SEEDS = 2**64
+
+    # The seed of retry attempt, derived from the run's seed so a report can
+    # be replayed. Attempt 1 keeps the run's seed. Wraps within the planner's
+    # 64-bit seeds, as --seed accepts them.
+    def self.retry_seed(seed, attempt)
+      attempt == 1 ? seed : (seed + (attempt * 0x9e37)) % SEEDS
+    end
+
+    def initialize(tests, attempts:, seed:, limits: Limits.new)
+      @tests = tests
+      @attempts = attempts
+      @seed = seed
+      @limits = limits
+      @success = true
+    end
+
+    # False when a retry's worker failed (its cleanup hook).
+    def success? = @success
+
+    # failures: {test index => first failing result}. Yields (index, result)
+    # once per test, with its final result. Its metadata holds the attempts:
+    # :flaky when it passed on retry, :asylum when it never did. Both are
+    # plain data, for Marshal and the JUnit and JSON reports.
+    def call(failures)
+      history = failures.to_h { |index, result| [index, [attempt_entry(@seed, false, result)]] }
+      pending = failures.keys
+      1.upto(@attempts) do |attempt|
+        break if pending.empty?
+
+        pending -= retry_round(pending, history, attempt) do |index, result|
+          result.metadata[:flaky] = flaky(failures[index], history[index], attempt)
+          yield index, result
+        end
+      end
+      pending.each do |index|
+        failures[index].metadata[:asylum] = { attempts: history[index].size, history: history[index] }
+        yield index, failures[index]
+      end
+    end
+
+    private
+
+    # Runs the pending tests once more, alone; returns the ones that passed.
+    def retry_round(pending, history, attempt)
+      seed = self.class.retry_seed(@seed, attempt)
+      passed = []
+      pool = Pool.new(@tests, jobs: 1, isolation: :test, seed:, limits: @limits)
+      pool.run([pending.dup]) do |index, result|
+        recovered = result.passed? && !result.skipped?
+        history[index] << attempt_entry(seed, true, recovered ? nil : result)
+        next unless recovered
+
+        passed << index
+        yield index, result
+      end
+      @success &&= pool.success?
+      passed
+    end
+
+    # One attempt: its seed, whether it ran alone, and how it ended.
+    def attempt_entry(seed, alone, failed)
+      { seed:, alone:, outcome: failed ? summary(failed.failure)[:message] : 'passed' }
+    end
+
+    def flaky(first, history, attempt)
+      {
+        attempts: history.size, seed: history.last[:seed], cause: attempt == 1 ? ALONE : RESEEDED,
+        first_failure: summary(first.failure), history:
+      }
+    end
+
+    def summary(failure)
+      type = failure.is_a?(Minitest::UnexpectedError) ? failure.error.class.name : failure.class.name
+      { type:, message: failure.message.lines.first.to_s.strip }
+    end
+  end
+end

data/lib/padded_cell/cell.rb

@@ -9,18 +9,23 @@ module PaddedCell
     module_function
 
     # Runs klass#name in a fork and returns its Minitest::Result, or an error
-    # result when the cell died or ran past timeout seconds.
+    # result when the cell died or ran past its deadline.
     #
-    #   close: descriptors the cell must not keep open (the worker's socket)
-    def run(klass, name, seed:, timeout: nil, close: [])
+    #   limits: the run's Limits (--timeout, --budget); nil: no deadline
+    #   close:  descriptors the cell must not keep open (the worker's socket)
+    #   probe:  the worker's Chart::Probe, which gets the cell's coverage
+    def run(klass, name, seed:, limits: nil, close: [], probe: nil)
       # Binary: the result is Marshal data, and with Encoding.default_internal
       # set (Rails sets it) a text-mode pipe transcodes what is written to it.
       reader, writer = IO.pipe
       [reader, writer].each(&:binmode)
       started = Minitest.clock_time
-      pid = fork_cell(klass, name, seed, reader, writer, close)
+      deadline = limits&.for_test
+      pid = fork_cell(klass, name, seed, reader, writer, close, probe)
       writer.close
-      collect(pid, reader, klass, name, started, timeout)
+      delta, result = collect(pid, reader, klass, name, started, deadline) { limits.message(deadline) }
+      delta ? probe.absorb(delta) : probe&.lost
+      result
     ensure
       reader&.close
       writer&.close unless writer&.closed?
@@ -34,7 +39,7 @@ module PaddedCell
       Results.crashed(klass, name, "exit(#{e.status}) called during the test")
     end
 
-    def fork_cell(klass, name, seed, reader, writer, close)
+    def fork_cell(klass, name, seed, reader, writer, close, probe)
       $stdout.flush
       $stderr.flush
       Process.fork do
@@ -43,7 +48,9 @@ module PaddedCell
           reader.close
           close.each(&:close)
           srand(seed)
-          writer.write(Results.dump(execute(klass, name)))
+          probe&.start
+          result = execute(klass, name)
+          writer.write(Results.envelope(probe&.capture, result))
           status = 0
         rescue Exception => e # anything: report it, then exit!
           warn "padded_cell: cell #{klass}##{name} failed to report: #{e.class}: #{e.message}"
@@ -54,26 +61,28 @@ module PaddedCell
       end
     end
 
-    def collect(pid, reader, klass, name, started, timeout)
-      data = read(reader, timeout && (started + timeout))
+    # [coverage delta or nil, result]. Yields for the message of a cell
+    # killed at its deadline.
+    def collect(pid, reader, klass, name, started, deadline)
+      data = read(reader, deadline)
       elapsed = Minitest.clock_time - started
       if data.nil?
         Process.kill(:KILL, pid)
         Process.wait(pid)
-        return Results.crashed(klass, name, "timed out after #{timeout}s", time: elapsed)
+        return [nil, Results.crashed(klass, name, yield, time: elapsed)]
       end
 
       _, status = Process.wait2(pid)
-      return Results.load(data, klass, name) unless data.empty?
+      return Results.unwrap(data, klass, name) unless data.empty?
 
-      Results.crashed(klass, name, Results.describe(status, 'cell'), time: elapsed)
+      [nil, Results.crashed(klass, name, Results.describe(status, 'cell'), time: elapsed)]
     end
 
-    # Everything until EOF, or nil when the deadline passes first.
+    # Everything until EOF, or nil when the deadline (if any) passes first.
     def read(io, deadline)
       data = String.new(encoding: Encoding::BINARY)
       loop do
-        remaining = deadline && (deadline - Minitest.clock_time)
+        remaining = deadline && Limits.remaining(deadline)
         return if remaining&.<= 0
         next unless io.wait_readable(remaining)
 

data/lib/padded_cell/chart/accumulator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'coverage'
+require 'fileutils'
+require 'tmpdir'
+
+module PaddedCell
+  module Chart
+    # The runner's side. Starts Ruby's Coverage before the suite loads, hands
+    # each worker a Probe, then sums its own measure (loading the suite) with
+    # every frame the workers wrote.
+    class Accumulator
+      attr_reader :criteria
+
+      # criteria: what Ruby's Coverage measures, :lines always among them
+      def initialize(criteria)
+        @criteria = criteria
+        @root = File.realpath(Dir.pwd)
+        @roots = [Dir.pwd, @root].uniq.map { "#{it}/" }
+        @kept = {}
+        @lost = 0
+        @known = Set.new
+      end
+
+      # Nothing loaded before is measured.
+      def start
+        ::Coverage.setup(**@criteria.to_h { [it, true] })
+        ::Coverage.resume
+        @frames = Dir.mktmpdir('padded_cell-coverage')
+        self
+      end
+
+      # After the suite loaded, before the first fork: the files whose
+      # structure the runner will report itself. Forks inherit the set.
+      def snapshot
+        ::Coverage.peek_result.each_key { @known << it if keep?(it) }
+      end
+
+      # For a worker, right after its fork.
+      def probe
+        Probe.new(file: File.join(@frames, "#{Process.pid}.cov"), known: @known, keep: method(:keep?),
+                  methods: @criteria.include?(:methods), interval: Chart.config.interval)
+      end
+
+      # A worker died: what it measured since its last flush is gone.
+      def lost_worker = @lost += 1
+
+      # Sums everything (see Raw); nil for an interrupted run.
+      def finish(interrupted: false)
+        return if interrupted
+
+        total = Delta.capture(::Coverage.peek_result, Set.new, method(:keep?))
+        cells = 0
+        frames.each do |frame|
+          Delta.merge!(total, frame[:delta])
+          cells += frame[:lost]
+        end
+        Raw.build(normalize(total), root: @root, criteria: @criteria, lost: { workers: @lost, cells: })
+      ensure
+        FileUtils.rm_rf(@frames) if @frames
+      end
+
+      private
+
+      # Files under the project root, which exist (not eval'd code).
+      def keep?(path)
+        @kept.fetch(path) { @kept[path] = @roots.any? { path.start_with?(it) } && File.file?(path) }
+      end
+
+      # Every complete frame of every worker. A worker killed while writing
+      # leaves a truncated last frame, skipped.
+      def frames
+        Dir[File.join(@frames, '*.cov')].flat_map do |file|
+          data = File.binread(file)
+          offset = 0
+          frames = []
+          while offset + 4 <= data.bytesize
+            size = data.unpack1('N', offset:)
+            break if offset + 4 + size > data.bytesize
+
+            frames << Marshal.load(data.byteslice(offset + 4, size)) # written by our own workers
+            offset += 4 + size
+          end
+          frames
+        end
+      end
+
+      # Keys by real path relative to the root: a file required through a
+      # symlink and through its real path is one file. A file deleted during
+      # the run is not reported.
+      def normalize(total)
+        total.each_with_object({}) do |(path, entry), files|
+          relative = File.realpath(path).delete_prefix("#{@root}/")
+          next if relative.start_with?('/')
+
+          files[relative] ? Delta.merge!(files, { relative => entry }) : files[relative] = entry
+        rescue SystemCallError
+          next
+        end
+      end
+    end
+  end
+end