padded_cell 0.1.0-aarch64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81bd623809416824f228b0ef5425f04dbd55256dd8e9f619cc26ea32fe0350bc
+  data.tar.gz: 5c6adc84d4a5f65c6f72f542ad9f07ae4ba454feee194b672de7ce54ef2df630
+SHA512:
+  metadata.gz: 6719550f356599f156114a2252fe7de3b678987039d15c281eef821f125ee3d8d747a75d4f726ed67c6fd3726b34d021753f63386d46ecb789e00a470bf9818b
+  data.tar.gz: a5e3b1795e07f22d31ca23b9b88f378f578dfd59ae2fd472a36399f868eb9fabec0b90f6f2f4e7f394017514def07c15fbf195491b4848188207c8f303230e67

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0 (2026-10-11)
+
+First release, for CRuby 4.0+ and Minitest 6 on Linux, macOS and FreeBSD: a
+drop-in runner for Minitest and Rails test suites. Windows, JRuby and
+TruffleRuby are not supported.
+
+- Fork-per-test cells (`--isolation test`) or long-lived workers
+  (`--isolation worker`); crashes, `exit`, `exit!` and `--timeout` become
+  error results, and dead workers are replaced.
+- Static discovery with Prism: `file:line[-line]`, `--list` and `--shard I/N`
+  without loading tests.
+- Tests grouped by class (fixtures load once per class), seeded order,
+  slowest classes and tests first from the previous run's timings; idle
+  workers split big classes. `--shard` splits by class.
+- Worker isolation by default when Active Record fixtures are loaded.
+- Minitest's reporters and plugins, plus `--junit` and `--json` reports.
+- `PaddedCell.before_fork` / `after_fork` / `cleanup` hooks; ActiveSupport's
+  parallelization hooks and Active Record's per-worker test databases.
+- Discovery and scheduling in Rust, as a native extension: precompiled gems
+  for Linux, macOS and FreeBSD, a source gem that compiles it elsewhere.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,184 @@
+# padded_cell
+
+Your tests aren't crazy. They just need their own room.
+
+padded_cell is a drop-in runner for Minitest and Rails test suites. Nothing in
+your tests changes; padded_cell replaces the thing that runs them:
+
+- **every test in its own forked cell**: a test that segfaults, calls `exit`,
+  hangs, monkey patches `Time` or leaves a thread behind takes down its cell,
+  not the run, and not the next test (Rails suites with fixtures default to
+  sharing a worker instead, see [Isolation](#isolation));
+- **workers fed whole classes**, slowest first from the timings of the
+  previous run, so per-class setup such as fixtures happens once; idle
+  workers split the remaining big classes;
+- **static discovery** with Prism: `file:line`, `--list` and CI sharding work
+  without loading a single test file;
+- Minitest's own reporters and plugins, plus JUnit XML and JSON lines.
+
+Discovery and scheduling are Rust, in a native extension: Prism parses the
+test files on every core, and a deterministic scheduler orders the run.
+
+```console
+$ bundle exec padded_cell
+Run options: --seed 33512 --isolation test
+
+# Running:
+
+.....E.......................................
+
+Finished in 2.083220s, 21.6013 runs/s, 233.2927 assertions/s.
+
+  1) Error:
+PaymentTest#test_refund:
+PaddedCell::CellCrashed: cell killed by SIGABRT
+    test/models/payment_test.rb:41:in 'PaymentTest#test_refund'
+
+45 runs, 486 assertions, 0 failures, 1 errors, 0 skips
+```
+
+One test segfaulted a C extension (Ruby aborts on a segfault) and took its cell
+down. The other 44 never noticed.
+
+## Installation
+
+Requires CRuby 4.0 or newer and Minitest 6, on Linux, macOS or FreeBSD.
+padded_cell is built on `fork`: Windows, JRuby and TruffleRuby are not
+supported.
+
+```ruby
+group :test do
+  gem "padded_cell"
+end
+```
+
+Precompiled gems ship for Linux (x86_64 and aarch64; glibc 2.34+ such as
+Debian 13, Ubuntu 26.04, RHEL 10, Fedora, Arch or Omarchy, plus musl for
+Alpine), macOS 13+ (arm64, x86_64) and FreeBSD 15.1 (amd64): no Rust, no
+compiler, nothing to build. Anything else (another CPU, an older glibc) gets
+the source gem, which compiles the extension at install and needs Rust 1.99+.
+padded_cell does not load without its extension.
+
+## Usage
+
+```console
+$ padded_cell                              # test/**/*_test.rb, minus system, dummy and fixtures
+$ padded_cell test/models                  # a directory
+$ padded_cell test/models/user_test.rb:12  # the test spanning line 12
+$ padded_cell user_test.rb:12-30:41        # tests overlapping 12..30, or spanning 41
+$ 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 --fail-fast
+$ 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
+```
+
+Exit status: 0 when everything passed, 1 otherwise, 2 for usage or load
+errors, 130 when interrupted.
+
+### How a run works
+
+1. **Select** files the way `rails test` does, `file:line` included.
+2. **Discover** tests statically with Prism (`def test_*` and Rails'
+   `test "..."` in classes inheriting from a `...Test` or `...TestCase`).
+3. **Load** the test files once, in the runner. Workers and cells are forks of
+   that process, so the app boots once, and copy-on-write shares its memory.
+   `minitest/autorun` is neutralized, so the suite does not run again at exit.
+4. **Order**: keep each class's tests together, as Minitest and Rails do.
+   Shard by a stable hash of the class name, shuffle classes and tests with
+   the seed, then put the slowest classes, and within them the slowest
+   tests, first (`tmp/padded_cell/timings.tsv`).
+5. **Run**: a worker takes a whole class; once no class is left to take, an
+   idle worker splits off the second half of another worker's remainder.
+   Each test sends back its `Minitest::Result`. A cell or worker that dies or
+   times out becomes an error result.
+6. **Report** through Minitest's own reporters and plugins.
+
+Loaded tests are the source of truth: inherited, `define_method` and other
+dynamic tests run even though static discovery cannot see them.
+
+### Isolation
+
+`--isolation test` forks a cell per test. Forking a preloaded process is
+cheap, and order-dependent tests stop depending on order.
+
+`--isolation worker` runs tests directly in the long-lived workers, like
+Rails' `parallelize`. A worker that crashes or times out is still reported
+and replaced.
+
+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.
+
+### Hooks
+
+For anything that must not be shared across forks:
+
+```ruby
+# test/test_helper.rb
+PaddedCell.before_fork { Database.disconnect }
+PaddedCell.after_fork { |worker| Database.connect("app_test_#{worker}") }
+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.
+
+## Rails
+
+Nothing to configure. ActiveSupport's parallelization hooks run around
+padded_cell's workers as they would around Rails' own: `parallelize_setup`,
+`parallelize_teardown`, `parallelize_before_fork`, and Active Record's
+per-worker test databases (`app_test-0`, `app_test-1`...).
+`ActiveSupport::TestCase.parallel_worker_id` is set. A
+`parallelize(workers: ...)` call in `test_helper.rb` stays inert, since
+padded_cell is the executor.
+
+```console
+$ 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.
+
+## Library
+
+The engine-backed parts load without Minitest:
+
+```ruby
+require "padded_cell"
+
+PaddedCell::Discovery.call(Dir["test/**/*_test.rb"]).map { [it.id, it.lines] }
+# => [["UserTest#test_valid", 10..12], ...]
+
+PaddedCell::Scheduler.batches(class_names, durations: seconds, seed: 42, shard: [0, 4])
+# => [[test indices of one class], ...] in run order
+```
+
+## 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
+published as a crate.
+
+## Development
+
+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 lint            # dictator, cargo fmt --check, clippy
+```
+
+## License
+
+MIT

data/exe/padded_cell

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'padded_cell/cli'
+
+exit PaddedCell::CLI.start(ARGV)

data/lib/padded_cell/active_support_hooks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'active_support/testing/parallelization'
+
+module PaddedCell
+  # Runs ActiveSupport's parallelization hooks around padded_cell's workers,
+  # as Rails runs them around its own: parallelize_before_fork,
+  # parallelize_setup, parallelize_teardown, and Active Record's per-worker
+  # test databases (app_test-0, app_test-1...).
+  #
+  # The runner installs this after loading the tests when ActiveSupport::TestCase
+  # is defined. Any parallelize(workers:) call in test_helper.rb stays inert:
+  # padded_cell is the executor.
+  module ActiveSupportHooks
+    module_function
+
+    def install
+      return if @installed
+
+      @installed = true
+      parallelization = ActiveSupport::Testing::Parallelization
+      PaddedCell.before_fork { parallelization.before_fork_hooks.each(&:call) }
+      PaddedCell.after_fork do |worker|
+        ActiveSupport::TestCase.parallel_worker_id = worker if ActiveSupport::TestCase.respond_to?(:parallel_worker_id=)
+        parallelization.after_fork_hooks.each { it.call(worker) }
+      end
+      PaddedCell.cleanup { |worker| parallelization.run_cleanup_hooks.each { it.call(worker) } }
+    end
+  end
+end

data/lib/padded_cell/cell.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  # One test in its own forked process. Whatever the test does to its process
+  # (crash, exit, hang, monkey patches, leaked threads) stays in the cell.
+  module Cell
+    CHUNK = 65_536
+
+    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.
+    #
+    #   close: descriptors the cell must not keep open (the worker's socket)
+    def run(klass, name, seed:, timeout: nil, close: [])
+      # 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)
+      writer.close
+      collect(pid, reader, klass, name, started, timeout)
+    ensure
+      reader&.close
+      writer&.close unless writer&.closed?
+    end
+
+    # Runs klass#name in this process. A test calling exit is reported as an
+    # error instead of ending the process.
+    def execute(klass, name)
+      klass.new(name).run
+    rescue SystemExit => e
+      Results.crashed(klass, name, "exit(#{e.status}) called during the test")
+    end
+
+    def fork_cell(klass, name, seed, reader, writer, close)
+      $stdout.flush
+      $stderr.flush
+      Process.fork do
+        status = 1
+        begin
+          reader.close
+          close.each(&:close)
+          srand(seed)
+          writer.write(Results.dump(execute(klass, name)))
+          status = 0
+        rescue Exception => e # anything: report it, then exit!
+          warn "padded_cell: cell #{klass}##{name} failed to report: #{e.class}: #{e.message}"
+        ensure
+          # exit! skips at_exit handlers: the cell is not the test run.
+          exit!(status)
+        end
+      end
+    end
+
+    def collect(pid, reader, klass, name, started, timeout)
+      data = read(reader, timeout && (started + timeout))
+      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)
+      end
+
+      _, status = Process.wait2(pid)
+      return Results.load(data, klass, name) unless data.empty?
+
+      Results.crashed(klass, name, Results.describe(status, 'cell'), time: elapsed)
+    end
+
+    # Everything until EOF, or nil when the deadline passes first.
+    def read(io, deadline)
+      data = String.new(encoding: Encoding::BINARY)
+      loop do
+        remaining = deadline && (deadline - Minitest.clock_time)
+        return if remaining&.<= 0
+        next unless io.wait_readable(remaining)
+
+        chunk = io.read_nonblock(CHUNK, exception: false)
+        return data if chunk.nil?
+
+        data << chunk if chunk.is_a?(String)
+      end
+    end
+  end
+end

data/lib/padded_cell/cli.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative 'runner'
+
+module PaddedCell
+  # The padded_cell command.
+  module CLI
+    BANNER = <<~TEXT
+      Usage: padded_cell [options] [paths...]
+
+      Runs a Minitest (or Rails) test suite, every test in its own forked cell.
+
+      Paths are files, directories, globs or file:line[-line][:line...].
+      Without paths: test/**/*_test.rb, minus test/{system,dummy,fixtures}.
+
+    TEXT
+
+    module_function
+
+    # Exit status: 0 passed, 1 failed, 2 usage or load error, 130 interrupted.
+    def start(argv, io: $stdout)
+      options = { io: }
+      parser(options).parse!(argv)
+      options[:paths] = argv
+      Runner.new(**options).run
+    rescue OptionParser::ParseError, ArgumentError, LoadFailure, Unsupported, SystemCallError => e
+      warn "padded_cell: #{e.message}"
+      2
+    end
+
+    def parser(options)
+      OptionParser.new do |opts|
+        opts.banner = BANNER
+        opts.version = VERSION
+        runner_options(opts, options)
+        output_options(opts, options)
+        opts.on('--version', 'Print the version') do
+          options[:io].puts "padded_cell #{VERSION}"
+          exit
+        end
+        opts.on('-h', '--help', 'Show this help') do
+          options[:io].puts opts
+          exit
+        end
+      end
+    end
+
+    def runner_options(opts, options)
+      opts.on('-j', '--jobs N', Integer, "Workers (default: #{Etc.nprocessors})") do
+        options[:jobs] = positive(it)
+      end
+      opts.on('-s', '--seed SEED', Integer, 'Order seed (default: random, or $SEED)') { options[:seed] = it }
+      opts.on('-n', '-i', '--name', '--include PATTERN', 'Only tests matching (/regexp/ or exact name)') do
+        options[:include] = it
+      end
+      opts.on('-e', '-x', '--exclude PATTERN', 'Skip tests matching (/regexp/ or exact name)') do
+        options[:exclude] = it
+      end
+      opts.on('--shard I/N', 'Run shard I of N (1-based), split by class') { options[:shard] = shard(it) }
+      opts.on('--isolation MODE', %w[test worker], 'test: a fork per test; worker: tests share their worker ' \
+                                                   '(default: worker with Active Record fixtures, else test)') do
+        options[:isolation] = it.to_sym
+      end
+      opts.on('--timeout SECONDS', Float, 'Kill and fail a test running longer') do
+        options[:timeout] = positive(it)
+      end
+      opts.on('--fail-fast', 'Stop dispatching after the first failure') { options[:fail_fast] = true }
+      opts.on('--list', 'List the tests that would run (static, loads nothing)') { options[:list] = true }
+    end
+
+    def output_options(opts, options)
+      opts.on('-v', '--verbose', 'One line per test, with timings') { options[:verbose] = true }
+      opts.on('--show-skips', 'Show skipped tests at the end') { options[:show_skips] = true }
+      opts.on('--junit PATH', 'Also write JUnit XML to PATH') { options[:junit] = it }
+      opts.on('--json PATH', 'Also write JSON lines to PATH') { options[:json] = it }
+      opts.on('--timings PATH', 'Timings file (default: tmp/padded_cell/timings.tsv)') { options[:timings] = it }
+      opts.on('--no-timings', 'Neither read nor write timings') { options[:timings] = nil }
+    end
+
+    # OptionParser names the switch in the message.
+    def positive(value)
+      raise OptionParser::InvalidArgument, "#{value} (must be positive)" unless value.positive?
+
+      value
+    end
+
+    def shard(value)
+      index, count = value.split('/', 2).map { Integer(it, 10, exception: false) }
+      unless index && count&.positive? && index.between?(1, count)
+        raise OptionParser::InvalidArgument, "--shard #{value} (expected I/N, 1 <= I <= N)"
+      end
+
+      [index - 1, count]
+    end
+  end
+end

data/lib/padded_cell/discovery.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  # A statically discovered test.
+  TestRef = Data.define(:file, :class_name, :name, :start_line, :end_line) do
+    def id = "#{class_name}##{name}"
+
+    def lines = start_line..end_line
+  end
+
+  # Static discovery, without loading anything.
+  module Discovery
+    module_function
+
+    # TestRefs for files, in file order, then source order. The extension
+    # reads and parses the files itself, on every core.
+    def call(files) = PaddedCellNative.discover_files(files).zip(files).flat_map { |rows, file| refs(rows, file) }
+
+    # TestRefs for one source string.
+    def source(source, file: '(source)') = refs(PaddedCellNative.discover(source), file)
+
+    def refs(rows, file) = rows.map { TestRef.new(file, *it) }
+  end
+end

data/lib/padded_cell/hooks.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  # Process lifecycle hooks, for anything that must not be shared across
+  # forks (database connections, sockets, per-worker resources):
+  #
+  #   PaddedCell.before_fork { Database.disconnect }
+  #   PaddedCell.after_fork { |worker| Database.connect("app_test_#{worker}") }
+  #   PaddedCell.cleanup { |worker| Database.drop("app_test_#{worker}") }
+  #
+  # before_fork runs in the runner before workers start, after_fork in each
+  # worker (worker index 0...jobs) and cleanup when a worker finishes.
+  # Cells (one fork per test) run no hooks: they inherit their worker.
+  module Hooks
+    @before_fork = []
+    @after_fork = []
+    @cleanup = []
+
+    class << self
+      def before_fork(&block) = @before_fork << block
+
+      def after_fork(&block) = @after_fork << block
+
+      def cleanup(&block) = @cleanup << block
+
+      def run_before_fork = @before_fork.each(&:call)
+
+      def run_after_fork(worker) = @after_fork.each { it.call(worker) }
+
+      def run_cleanup(worker) = @cleanup.each { it.call(worker) }
+    end
+  end
+end

data/lib/padded_cell/loader.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  # A test file that would not load.
+  class LoadFailure < StandardError; end
+
+  # Loads test files once, in the runner, so every worker and cell starts
+  # from the same preloaded (copy-on-write) process.
+  module Loader
+    # Test helpers require minitest/autorun (or Rails' equivalent): its
+    # at_exit would run the whole suite again, unisolated.
+    module NoAutorun
+      def autorun = nil
+    end
+
+    module_function
+
+    def call(files, seed:)
+      Minitest.singleton_class.prepend(NoAutorun)
+      Minitest.seed = seed
+      # What `rake test` and `rails test` put on the load path.
+      %w[test lib].each do |dir|
+        path = File.expand_path(dir)
+        $LOAD_PATH.unshift(path) if File.directory?(path) && !$LOAD_PATH.include?(path)
+      end
+      files.each { load_file(it) }
+    end
+
+    def load_file(file)
+      require file
+    rescue ScriptError, StandardError => e
+      raise LoadFailure, "#{file}: #{e.class}: #{e.message}"
+    end
+
+    # [klass, method_name] for every loaded test, the way Minitest finds them.
+    def tests
+      Minitest::Runnable.runnables.flat_map do |klass|
+        klass.runnable_methods.map { [klass, it] }
+      rescue NotImplementedError
+        []
+      end
+    end
+  end
+
+  # Which loaded tests run: Minitest's --include/--exclude, plus file:line.
+  class Filter
+    def initialize(selection, refs, include: nil, exclude: nil)
+      @selection = selection
+      @include = pattern(include)
+      @exclude = pattern(exclude)
+      @ends = refs.to_h { [[it.file, it.start_line], it.end_line] }
+      @selected = selection.files.to_h { [it, true] }
+    end
+
+    def call(klass, name)
+      id = "#{klass}##{name}"
+      return false if @include && !matches?(@include, name, id)
+      return false if @exclude && matches?(@exclude, name, id)
+
+      !@selection.line_filtered? || line_selected?(klass, name)
+    end
+
+    private
+
+    # "/re/" is a Regexp, anything else an exact name, as in Minitest.
+    def pattern(value)
+      match = value.is_a?(String) && %r{\A/(.*)/\z}.match(value)
+      match ? Regexp.new(match[1]) : value
+    end
+
+    def matches?(pattern, name, id) = [name, id].any? { pattern === it }
+
+    # With file:line arguments, a test runs when its file was named and its
+    # definition overlaps a requested line, or its file was named whole.
+    def line_selected?(klass, name)
+      file, line = klass.instance_method(name).source_location
+      return false unless file && @selected[file]
+
+      @selection.covers?(file, line..@ends.fetch([file, line], line))
+    end
+  end
+end

data/lib/padded_cell/native.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Loads the Rust extension, which does discovery and scheduling. There is no
+# fallback: platform gems ship it precompiled under the Ruby ABI version, the
+# source gem compiles it at install, and a checkout builds it with
+# `rake compile`.
+
+require 'rbconfig'
+
+shipped = File.join(__dir__, RUBY_VERSION[/\A\d+\.\d+/], "padded_cell_native.#{RbConfig::CONFIG['DLEXT']}")
+begin
+  File.exist?(shipped) ? require(shipped) : require('padded_cell/padded_cell_native')
+rescue LoadError => e
+  raise LoadError, "padded_cell: native extension not loaded (#{e.message}). Precompiled gems need " \
+                   'glibc 2.34+ (Linux), macOS 13+ or FreeBSD 15.1; elsewhere the gem builds it with Rust ' \
+                   'at install. In a checkout, run `rake compile`.'
+end
+
+# A stale build may implement other semantics.
+unless PaddedCellNative.version == PaddedCell::VERSION
+  raise LoadError, "padded_cell: native extension #{PaddedCellNative.version} does not match padded_cell " \
+                   "#{PaddedCell::VERSION}: rebuild it (`rake compile` in a checkout, or reinstall the gem)"
+end