padded_cell 0.1.0-aarch64-linux-gnu → 0.3.0-aarch64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e61ac6aa1468930e0eb7feb94901aba611f11f2eeda222beef54917c37bb4b3
-  data.tar.gz: 5046cf840a35e01dca0c36e37772129cfe1454e6805f05119f3476b67f8bc450
+  metadata.gz: 8989d567fd19a8fd3d7713dc0c008b0f7c7c58567b837d69b39f2d1ac7f8db69
+  data.tar.gz: 98254fdb4722ef9a0fcc50c302c3f2496e8ffcc75eb92330844bc3ec6aabfba2
 SHA512:
-  metadata.gz: ce4abe5735a7bb637f871a7dd47b0712ac6f49c3700940add46374c8ded101ef85309f7fde9fc3876304404b31b3de05db680cd5cd55b43049e10845125e98b9
-  data.tar.gz: 420514f129aeef7f48be23ba4204710c6b4975682308c12506732a7fa7fb72875d25f169cbe42a759988d18c26fd0a3e8052e7b744574cd883aa3c25402a5686
+  metadata.gz: 1031e64b53b8d5c156057513bea76d2585a4d05fcb6f73edc672f598f32331ff630189bf93dd8683cf83b66594b91c4346a1915539fe1565d843a505287e3f72
+  data.tar.gz: 44194137c0688850c83d563b153becb8ac3aef01d1d2b38648e5a54064ae203e3cac5bf159ad8a46e9e0a7a44989d70b8accf67a0ec0d590143ff6b1398b8861

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.3.0 (2026-11-08)
+
+- `--budget SECONDS`: a deadline for the whole run, loading included. Once
+  it's spent, nothing more is dispatched and running tests are killed. Tests
+  it left out fail the run (exit 1). `--timeout` never outlives it.
+- Workers that keep dying (more than 4 per worker, at least 16, in 10s) are
+  no longer replaced forever. padded_cell gives up, reports how many tests
+  never ran, and exits 1. Uses `supervisor-machines`.
+- A replacement worker that died before its first test crashed the run with
+  `Errno::EPIPE` (exit 2). A worker reset mid-frame is now reported as dead.
+- `--asylum` retry seeds keep all 64 bits: they were folded modulo 0xffff,
+  so large `--seed`s shared the same few retry seeds.
+
+## 0.2.0 (2026-10-11)
+
+- Built-in coverage: `--coverage[=lines,branches,methods,eval]` (or
+  `PADDED_CELL_COVERAGE`) measures the runner, every worker and every cell,
+  and sums them exactly. Configured with `PaddedCell.coverage` in the test
+  helper: tracked files, filters, groups, the `:rails` profile. Honors
+  `# :nocov:` blocks and `# simplecov:disable` comments. Writes
+  `coverage.md` (the code that never ran, for agents, reviews and CI
+  summaries), `lcov.info`, and `coverage.json` / `.resultset.json`.
+  `minimum`, `minimum_by_file`, `minimum_by_group` and `maximum_drop` fail a
+  whole passing run with exit 3. `--coverage-merge` merges shards' reports.
+- `--seed` must be 0 to 2**64 - 1; others crashed the planner.
+- `--asylum[=N]`: retry failed tests (N times, default 2) after the run,
+  alone and in fresh cells. Tests that pass on retry count as passed and are
+  reported as flaky, with the likely cause (timing and shared state, or
+  randomness and order) and their first failure; JUnit gets
+  `<flakyFailure>`, JSON a `flaky` field.
+- A `cleanup` hook that raises fails the run (exit 1), `--asylum` retries
+  included. It exited 0 when the tests passed.
+- A passing run filtered with `--name` exits 0: it exited 1, reporting that
+  nothing ran.
+- `--list` applies `--name` and `--exclude`, before `--shard`, as a run does.
+- An invalid `--name` or `--exclude` regexp is a usage error (exit 2), not a
+  crash.
+
 ## 0.1.0 (2026-10-11)
 
 First release, for CRuby 4.0+ and Minitest 6 on Linux, macOS and FreeBSD: a

data/README.md

@@ -69,14 +69,18 @@ $ padded_cell user_test.rb:12-30:41        # tests overlapping 12..30, or spanni
 $ padded_cell -n /refund/ -e test_slow     # Minitest's --include / --exclude
 $ padded_cell -j 8 --seed 1234             # 8 workers, reproducible order
 $ padded_cell --timeout 30                 # kill and fail anything running 30s
+$ padded_cell --budget 600                 # the whole run gets 10 minutes; what's left out fails it
 $ padded_cell --fail-fast
+$ padded_cell --asylum                     # retry failures; report the flaky ones (see below)
 $ padded_cell --list                       # what would run, without loading anything
 $ padded_cell --shard 2/4                  # CI: the second quarter of the classes
 $ padded_cell --junit tmp/junit.xml --json tmp/results.jsonl
+$ PADDED_CELL_JSON=tmp/results.jsonl padded_cell   # same, from a CI runner's env
+$ padded_cell --coverage                   # line and branch coverage (see Coverage)
 ```
 
 Exit status: 0 when everything passed, 1 otherwise, 2 for usage or load
-errors, 130 when interrupted.
+errors, 3 when only coverage is below a threshold, 130 when interrupted.
 
 ### How a run works
 
@@ -108,11 +112,60 @@ cheap, and order-dependent tests stop depending on order.
 Rails' `parallelize`. A worker that crashes or times out is still reported
 and replaced.
 
+Replaced up to a point. If workers keep dying, say a boot that segfaults or an
+`after_fork` hook that calls `exit`, every remaining test would come back as a
+crash report, one fork at a time. So past 4 deaths per worker in 10 seconds
+(16 at least), padded_cell gives up: it lists how many tests never ran and
+exits 1. The decision comes from
+[supervisor_machines](https://github.com/seuros/supervisor_machines), the same
+one-for-one restart intensity OTP uses.
+
+### Budget
+
+`--budget SECONDS` caps the whole run, loading included. Once it's spent,
+nothing more is dispatched, and a test still running is killed and fails
+("run budget of 600.0s spent"). A test's `--timeout` never outlives the
+budget. If the budget left tests out, the run fails and says how many. The
+deadline math comes from
+[deadline_machines](https://github.com/seuros/deadline_machines).
+
 The default is `test`, except when Active Record fixtures are loaded: a fork
 discards Active Record's connection pool, and every test would reload its
 fixtures, so those suites default to `worker`. The `Run options:` line shows
 which one a run uses; `--isolation` overrides it.
 
+### Flaky tests
+
+`--asylum[=N]` gives failed tests up to N more attempts (default 2) once the
+run is over: one test at a time, each in a fresh cell. A test that passes on
+retry counts as passed, but padded_cell shows every attempt, its seed, and
+what made the difference:
+
+```console
+4 runs, 4 assertions, 1 failures, 0 errors, 0 skips
+
+You're not crazy, the world is. 2 tests failed, then passed:
+
+  FlakyTest#test_passes_when_retried
+    seed 1      lost the race
+    seed 1      passed, alone → timing, contention or state left by other tests
+
+  FlakyTest#test_depends_on_the_seed
+    seed 1      unlucky seed.
+    seed 1      unlucky seed. (alone)
+    seed 15472  passed, alone → randomness or test order
+
+It's not the world, it's the test:
+  FlakyTest#test_always_fails failed all 3 attempts
+```
+
+The first retry keeps the run's seed and runs alone, so passing there points
+at timing, contention or leftover state; later retries change the seed, so
+passing only there points at randomness or order. A test that fails every
+attempt keeps its first failure, and the run fails. JUnit reports carry a
+`<flakyFailure>` per flaky test; JSON lines carry the attempts in a `flaky`
+field, or an `asylum` field for a test that never passed.
+
 ### Hooks
 
 For anything that must not be shared across forks:
@@ -125,7 +178,115 @@ PaddedCell.cleanup { |worker| Database.drop("app_test_#{worker}") }
 ```
 
 `before_fork` runs in the runner, `after_fork` and `cleanup` once per worker
-(`0...jobs`). Cells run no hooks: they inherit their worker's state.
+(`0...jobs`). Cells run no hooks: they inherit their worker's state. A
+failing `after_fork` fails every test of its worker; a failing `cleanup`
+fails the run, even when every test passed.
+
+## Coverage
+
+Ruby's `Coverage`, measured in the runner, in every worker and in every
+cell, and summed exactly: a parallel run reports the counts of a serial one.
+
+```console
+$ padded_cell --coverage test/                         # lines and branches
+$ padded_cell --coverage=lines,branches,methods test/
+$ PADDED_CELL_COVERAGE=1 bin/rails padded_cell
+```
+
+Measuring starts before the suite loads, so what is measured (`lines`,
+`branches`, `methods`, and `eval` for templates, experimental) comes from the
+command line. The report is configured in the test helper:
+
+```ruby
+# test/test_helper.rb
+PaddedCell.coverage(:rails) do
+  track "{app,lib}/**/*.rb"           # report files never loaded, at 0%
+  skip "app/legacy/"                  # also `filter`
+  group "Operations", "app/concepts"  # string, regexp, array or block
+  group("Contracts") { |file| file.filename.include?("contract") }
+  minimum line: 90, branch: 80
+  minimum_by_file line: 50
+  minimum_by_group "Operations", line: 95
+  maximum_drop line: 1                # since the previous whole run
+  formats :markdown, :lcov, :json
+  dir "coverage"                      # --coverage-dir wins
+end
+```
+
+- Paths are matched relative to the project root. A string matches whole
+  path segments (`"app/models"` takes `app/models/user.rb`, not
+  `app/models_old/`), `"lib/"` a directory anywhere, `"contract.rb"` a file
+  name ending; a regexp matches the path; a block gets the file
+  (`filename`, `project_filename`, `src`).
+- Left out by default: `vendor/bundle`, hidden files, `test/`, `spec/`,
+  `features/`. `clear_filters` drops these.
+- `:rails` skips `config/` and `db/`, groups `app/channels`,
+  `app/controllers`, `app/helpers`, `app/jobs` and `app/workers`, `lib/`,
+  `app/mailers`, `app/models` and `app/views`, and tracks
+  `{app,lib}/**/*.rb`. A file in no group is Ungrouped.
+- Thresholds compare percents floored to 2 decimals.
+
+`PaddedCell.coverage` configures only; without `--coverage` nothing is
+measured. Outside padded_cell, guard it with `if defined?(PaddedCell.coverage)`.
+
+Into `coverage/` go, by format:
+
+- `markdown`: `coverage.md`, for agents, reviews and CI summaries
+  (`cat coverage/coverage.md >> $GITHUB_STEP_SUMMARY`): the totals and
+  groups, then every file with code that never ran, the most missed first,
+  with its missed lines, branches and methods, and that code. It stops
+  listing files at 1 MB, the size of a GitHub job summary.
+- `lcov`: `lcov.info` (`SF:./path`), for CI and editors.
+- `json`: `coverage.json` and `.resultset.json`, in SimpleCov's formats, for
+  the tools reading them.
+
+Also, every run: `.padded_cell.json` (what the report is made of, and what
+`--coverage-merge` reads), and after a whole passing run `.last_run.json`.
+
+Lines and branches inside `# :nocov:` blocks, and under
+`# simplecov:disable [line|branch|method]` / `# simplecov:enable` comments,
+are skipped. A directive after code skips its own line.
+
+A run below a threshold exits 3. Thresholds hold for a whole, passing,
+complete run only: they are not checked when tests failed, when tests were
+picked by name or line, under `--shard`, or when a worker or cell died
+before handing over what it measured (the report then says it is partial).
+Reports are written either way, failing runs included.
+
+A suite that starts SimpleCov as well is refused (exit 2): two tools cannot
+share Ruby's `Coverage`.
+
+### Shards
+
+Each shard reports on its own; merge them, at the same commit, without
+running anything:
+
+```console
+$ padded_cell --coverage --coverage-dir coverage/1 --shard 1/2 test/   # machine 1
+$ padded_cell --coverage --coverage-dir coverage/2 --shard 2/2 test/   # machine 2
+$ padded_cell --coverage-merge coverage/1,coverage/2 --coverage-dir coverage
+```
+
+The merge refuses files that differ between shards or from the checkout,
+and checks thresholds when every shard of the run is there. Lines that run
+while the suite loads count once per shard.
+
+### Cost
+
+Measuring is opt-in: Ruby's instrumentation slows tests down. On a Rails
+suite of 6,300 tests, lines and branches took the run from 465 s to 638 s of
+CPU.
+
+A worker hands over what it measured every 10 seconds or more: each time,
+Ruby copies the coverage of every file it loaded, gems included (a few
+milliseconds in a small app, a few hundred in a big Rails one), so the
+interval stretches to keep this under 1% of the worker's time. A worker that
+dies loses what it measured since. With `--isolation test` every cell pays
+one such copy, at its end.
+
+Files never loaded report their branches in the order Ruby compiles them.
+With `eval`, code that `class_eval` runs from a heredoc counts as lines of
+its file; directives in templates are not read.
 
 ## Rails
 
@@ -144,8 +305,7 @@ $ bin/rails padded_cell ARGS="-j 8 test/models"
 Rails suites with fixtures run with `--isolation worker` unless told
 otherwise (see [Isolation](#isolation)).
 
-Coverage tools that write their results from an `at_exit` hook (SimpleCov)
-see only the runner, as with Rails' process parallelization.
+For coverage, see [Coverage](#coverage).
 
 ## Library
 
@@ -164,7 +324,9 @@ PaddedCell::Scheduler.batches(class_names, durations: seconds, seed: 42, shard:
 ## Rust
 
 The extension lives in `ext/padded_cell_native`: `core` does discovery and
-scheduling in plain Rust (no Ruby types), `ffi` binds it to Ruby. Neither is
+scheduling in plain Rust (no Ruby types), `ffi` binds it to Ruby. Worker
+supervision and deadlines come from the published `supervisor-machines` and
+`deadline-machines` crates. Neither is
 published as a crate.
 
 ## Development
@@ -173,9 +335,9 @@ Needs Rust 1.99+ (`mise install` reads `mise.toml`).
 
 ```console
 bundle install
-rake test:all        # cargo test, then the Ruby suite (compiles the extension first)
-rake test            # the Ruby suite only
-rake dogfood         # this suite, run by padded_cell
+rake test:all        # cargo test, then this suite run by padded_cell itself
+rake dogfood         # this suite, run by padded_cell (compiles the extension first)
+rake test            # this suite on plain Minitest, for when padded_cell itself is broken
 rake lint            # dictator, cargo fmt --check, clippy
 ```
 

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