hegeltest 0.1.1-aarch64-linux → 0.2.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ad0af74a5c0c3a5d06d5852d116dc5b438b8e00b0bf77dffea85d491fad0c0d
-  data.tar.gz: ff6608d783f1d683c4fb913dd6944b1ec36158ec42c5a47e4a1ecd6af9b5df4b
+  metadata.gz: aaeb9d0de3eed73e101255a9737dcd411e7819dfd559b9b6654556563bd1a9ab
+  data.tar.gz: 1a8b52232cc7ea3b746c4224b5a16aebd910405a0b6a8403e067a23ce175ad6b
 SHA512:
-  metadata.gz: e024d0729ccae8b3dbc4f1ed44ed85527d6a6e68dc32e164c67082db7ffd8af1dedbed57f21d3f32f16ee483be7ceeebdf347ecd7fa462f0c4fc9de39c537380
-  data.tar.gz: 4767de13f596d0b956879e4ff3dc7cf8b36aa1b3b1dae7217f17785d69fbfcde45693653b821439ec05a6b1d85f3af0d36b8c719cb1dd424438d697164a48bca
+  metadata.gz: 15fd917172691c48b448ba688ca00fae54cea30bf67408a4f34f96a09a95d37564e8c6cfb90eaf7e2dc68adf4d2285d8f6f3315e771a0838d7cf9e2f8fb0d2e4
+  data.tar.gz: 28c4f53b9dfeedf865f266940a27e8d012604bb4c32c3fc63d2db5af9af48449d08a933e24e2017d6a726512653b714c7c88bcacb55afe928cd8d5ea2e04ba29

data/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.2.1] - 2026-10-08
+
+Each platform gem carries `libhegel` 0.45.1, up from 0.45.0. A caller has
+nothing to change. The engine now reads a NULL string buffer with length
+zero as the empty string, and it rejects a NULL buffer with a nonzero
+length. These bindings send neither case, so a drawn value does not
+change: `from_regex("", fullmatch: true)` draws `""` on both engines.
+
+## [0.2.0] - 2026-10-07
+
+The floor is Ruby 3.4. A project on Ruby 3.3 stays on 0.1.1. See
+[ADR 0017](docs/adr/0017-raise-the-ruby-floor-to-3-4.md).
+
+Each platform gem carries `libhegel` 0.45.0, up from 0.32.5. The engine
+changed its C interface in several places between the two, and these
+bindings follow each change.
+
+### Changes a caller has to make
+
+`Hegel.test` no longer takes `stateful_step_count:`. Pass `step_count:` to
+`Hegel::Stateful.run` instead; it defaults to 50, as hegel-rust, hegel-go,
+and hegel-java do. The engine no longer has a default of its own.
+
+An invariant no longer runs after every rule. It runs before the first
+rule and after the last, and between rules when the engine samples it,
+about once in a test case that runs every step. Declare it with
+`invariant :name, always_run: true` to keep the check after every rule.
+See [ADR 0021](docs/adr/0021-run-a-state-machine-in-rounds-with-its-own-step-count.md).
+
+### Failure reports
+
+The report comes from the engine's own final replay of each failure, which
+it runs inside the loop before the run ends. The body is no longer run
+again after the run, so a failing run calls it once fewer per failure. A
+`tc.note` block runs on each case the engine stamps for capture, which can
+be more than one per failure. See
+[ADR 0019](docs/adr/0019-report-failures-from-the-cases-the-engine-stamps.md).
+
+A body that fails only some of the time is now reported as an ordinary
+failure, with a `note:` line from the engine that says how often it
+reproduced. Before, such a body ended the run in `Hegel::Error`. A failure the engine could not confirm comes
+without a blob, and its report leaves out the reproduction line.
+
+`reproduce_failure:` now replays its blob as a run, until a replay fails,
+within the engine's own budget. A blob from a nondeterministic failure
+reproduces this way too. When no replay fails, `Hegel.test` raises
+`Hegel::Error` and names both causes: a fixed bug, or a body whose failure
+did not recur.
+
+A body that rejects its input with `tc.assume` or `tc.reject` before it
+draws anything now raises `Hegel::Error` ("Unsatisfiable"). Before, the
+run stopped after that one case and passed.
+
+### Settings
+
+A keyword left `nil` now takes its value from the engine's settings
+profile: libhegel's default, a `hegel.toml`, or a `HEGEL_*` environment
+variable such as `HEGEL_TEST_CASES`. On a CI server the engine picks its
+`ci` profile, which derandomizes the run and turns the example database
+off, so a run with `database_key:` and no `database:` stores nothing there.
+A keyword you pass still wins. See
+[ADR 0023](docs/adr/0023-leave-unset-settings-to-the-engines-profile.md).
+
+### Generated values
+
+The engine draws integers and floats from new distributions, and shrinks
+further in several cases, so a seeded run draws different values
+than it did on 0.32.5. `from_regex` follows Python's `re` more closely
+under `(?i)` and `(?a)`, and its pattern may now hold a NUL character.
+
+`times` and `datetimes` keep microsecond precision. The engine now draws
+nanoseconds, and the binding rounds each one down. See
+[ADR 0022](docs/adr/0022-keep-microsecond-times-over-a-nanosecond-engine.md).
+
+A `datetimes` bound with a fraction of a microsecond could produce a value
+outside it, because only the bound's whole microseconds reached the
+engine. The lower bound now rounds up and the upper rounds down.
+
+### Other changes
+
+`HEGEL_LIBHEGEL_PATH` pointing at an engine that lacks a function these
+bindings call raises `Hegel::Error` that names the function. Before, FFI
+raised a `TypeError` that named nothing.
+
+`rake libhegel:fetch` downloads from hegel-rust's `libhegel-v<version>`
+release tags, which hegel-rust uses for engine releases since 0.42.1.
+
 ## [0.1.1] - 2026-08-31
 
 The reference that ships inside the gem told a reader to install `hegeltest`
@@ -39,5 +128,7 @@ The engine is called through the `ffi` gem. Each platform gem carries the
 matching `libhegel` 0.32.5 build. The platform-independent gem carries none,
 so a run on it needs `HEGEL_LIBHEGEL_PATH` pointing at a local build.
 
+[0.2.1]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.2.1
+[0.2.0]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.2.0
 [0.1.1]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.1.1
 [0.1.0]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.1.0

data/README.md

@@ -55,10 +55,22 @@ compiles nothing and needs no engine on the side. The Hegel maintainers
 permit a third-party project to redistribute their release binaries
 ([hegeldev/hegel-rust#411]).
 
-Every push to main runs the suite on Ruby 3.3, 3.4, and 4.0, across Linux x64
-and arm64, macOS arm64, and Windows x64 and arm64. Windows arm64 starts at
-Ruby 3.4, the oldest Ruby that RubyInstaller publishes an arm64 build for. A
-pull request runs Linux x64 alone.
+A project that already has a `Gemfile.lock` needs one more step. Bundler keeps
+the platform list the lock already holds. It adds only the platform of the
+machine that runs `bundle install`. A lock therefore names only the platforms
+of the machines that have run it. A Linux CI job cannot find the gem when the
+lock names no Linux platform. Add each platform your CI uses:
+
+```bash
+bundle lock --add-platform x86_64-linux
+```
+
+A project with no lock yet reads the `PLATFORMS` section of the lock its first
+`bundle install` writes, and adds whatever its CI needs the same way.
+
+Every push to main runs the suite on Ruby 3.4 and 4.0, across Linux x64 and
+arm64, macOS arm64, and Windows x64 and arm64. A pull request runs Linux x64
+alone.
 
 [hegeldev/hegel-rust#411]: https://github.com/hegeldev/hegel-rust/issues/411
 
@@ -70,7 +82,7 @@ pull request runs Linux x64 alone.
 | Require path | `require "hegel"` (`require "hegeltest"` also works) |
 | Namespace | `Hegel` |
 | Binding | the `ffi` gem, which publishes a prebuilt binary for every platform above |
-| Ruby | 3.3, 3.4, and 4.0 |
+| Ruby | 3.4 and 4.0 |
 | Platforms | Linux amd64/arm64, macOS arm64, Windows amd64/arm64 |
 | Engine delivery | One prebuilt `libhegel` per platform-specific gem, built by `rake platform_gems:build` |
 
@@ -203,7 +215,7 @@ Expected: [0, 0]
 
 Some bugs need a sequence of operations rather than one input. Declare the
 operations as rules on a `Hegel::StateMachine`, and Hegel picks which runs
-next, checks your invariants after each one, and shrinks a failure to the
+next, checks your invariants along the way, and shrinks a failure to the
 shortest sequence that still shows it:
 
 ```ruby
@@ -238,12 +250,23 @@ something an earlier rule produced, such as freeing a handle that some
 `alloc` actually returned, put the value in a `Hegel::Stateful::Pool` and
 draw it back out.
 
+Every invariant runs before the first rule and after the last. Between rules,
+the engine samples each one, so that it runs about once in a test case
+that runs every step.
+Declare an invariant with `always_run: true` to check it after every rule
+instead. `Hegel::Stateful.run(machine, tc, step_count: 50)` sets the most
+rules one test case runs; 50 is the default.
+
 ### Shaping a run
 
 `Hegel.test` takes keywords for the rest: `test_cases`, `seed`,
-`derandomize`, `verbosity`, `phases`, `suppress_health_check`,
-`report_multiple_failures`, and `stateful_step_count`. Each one left unset
-means the engine's own default.
+`derandomize`, `verbosity`, `phases`, `suppress_health_check`, and
+`report_multiple_failures`. `report_multiple_failures` defaults to `false`.
+Each of the others left unset takes its value from the engine's settings
+profile. That is libhegel's own default, unless a
+`hegel.toml` or a `HEGEL_*` environment variable says otherwise. On a CI
+server the engine picks its `ci` profile, which derandomizes the run and
+turns the example database off.
 
 Two more turn on libhegel's example database, which stores a failing case and
 replays it first next time. `database_key` is the switch and `database`

data/Rakefile

@@ -17,3 +17,84 @@ task :coverage do
 end
 
 task default: %i[coverage standard]
+
+# Mutation testing with mutineer, over lib/. Four settings make the suite
+# run under it; ADR 0016 records why:
+# - RUBYOPT gets -Itest, since mutineer puts only lib/ on the load path and
+#   every test file starts with `require "test_helper"`.
+# - Each test file gets its own --test flag. The flag takes one file, and a
+#   second path after it becomes a source to mutate.
+# - test_conformance.rb stays out. Its capture_subprocess_io reopens
+#   $stdout, and mutineer replaces $stdout with a StringIO, so the file fails
+#   before any mutant runs.
+# - --strategy redefine reloads only the mutated method. The default,
+#   reload, loads the whole mutated file by a relative path, which breaks
+#   Hegel::Runner.origin_for and killed three mutants the suite does not
+#   catch.
+# MUTINEER_ARGS passes more flags, for example
+# MUTINEER_ARGS="--since origin/main" to mutate only the lines changed since
+# origin/main.
+#
+# `rake mutation` fails on a survivor that the baseline does not list
+# (ADR 0018). `rake mutation:baseline` rewrites the baseline from a full run.
+MUTATION_BASELINE = "test/mutation-baseline.json"
+
+def run_mutineer(*extra)
+  require "shellwords"
+  tests = Dir["test/*.rb", "test/hegel/*.rb"].sort -
+    %w[test/test_helper.rb test/hegel/test_conformance.rb]
+  args = ["lib", "--strategy", "redefine", *tests.flat_map { |t| ["--test", t] }, *extra, *Shellwords.split(ENV.fetch("MUTINEER_ARGS", ""))]
+  rubyopt = ["-Itest", ENV["RUBYOPT"]].compact.join(" ")
+  # mutineer keeps its cache here, and refuses an --output path whose
+  # directory does not exist yet.
+  mkdir_p ".mutineer", verbose: false
+  sh({"RUBYOPT" => rubyopt}, "bundle", "exec", "mutineer", "run", *args)
+end
+
+# mutineer writes its JSON report on one line, so a change to it reads as one
+# changed line in a pull request. mutineer's --baseline reads only
+# schema_version, summary.score, summary.scoped, and each survivor's id, so
+# the committed file keeps those and writes one survivor per line, sorted.
+# It leaves out line numbers: an edit above a survivor would move every
+# line after it, and the id does not depend on the position. "change" holds
+# the mutated line before and after, so a reviewer can read the survivor.
+def write_mutation_baseline(report_path, baseline_path)
+  require "json"
+  report = JSON.parse(File.read(report_path))
+  # mutineer refuses a --since run as a baseline, since it covers only the
+  # changed lines.
+  abort "#{report_path} comes from a --since run; rewrite the baseline from a full run" if report.dig("summary", "scoped")
+  rows = report.fetch("survivors").map do |survivor|
+    change = survivor.fetch("diff").lines.grep(/^[-+] /).map { |line| line.chomp.sub(/^([-+]) +/, '\1 ') }.join(" | ")
+    {"id" => survivor.fetch("id"), "file" => survivor.fetch("file"), "subject" => survivor.fetch("subject"),
+     "operator" => survivor.fetch("operator"), "change" => change}
+  end
+  rows.sort_by! { |row| row.values_at("file", "subject", "id") }
+  text = +"{\n"
+  text << %(  "schema_version": #{report.fetch("schema_version").to_json},\n)
+  text << %(  "summary": #{report.fetch("summary").slice("score", "scoped").to_json},\n)
+  text << %(  "survivors": [\n#{rows.map { |row| "    #{row.to_json}" }.join(",\n")}\n  ]\n}\n)
+  # The baseline is committed to a public repository, so a path from this
+  # machine must not reach it.
+  leak = [Dir.pwd, Dir.home].find { |path| text.include?(path) }
+  abort "#{baseline_path} would contain #{leak}; not written" if leak
+  File.write(baseline_path, text)
+end
+
+desc "Run mutation testing over lib/, and fail on a survivor that #{MUTATION_BASELINE} does not list"
+task :mutation do
+  # --baseline also fails on a lower score. A mutant that times out on a slow
+  # machine leaves the score and can lower it by a fraction of a point, and
+  # it can never add a survivor. The epsilon absorbs that, and the survivor
+  # ids stay the gate.
+  run_mutineer("--baseline", MUTATION_BASELINE, "--baseline-epsilon", "1")
+end
+
+namespace :mutation do
+  desc "Rewrite #{MUTATION_BASELINE} from a full mutation testing run over lib/"
+  task :baseline do
+    report = ".mutineer/baseline-run.json"
+    run_mutineer("--format", "json", "--output", report)
+    write_mutation_baseline(report, MUTATION_BASELINE)
+  end
+end

data/docs/README.md

@@ -21,6 +21,16 @@ An index of the design records for `hegel-ruby`.
 - [0012: Build a failure origin from the caller's own frame](adr/0012-build-a-failure-origin-from-the-callers-own-frame.md)
 - [0013: Bind libhegel through the ffi gem](adr/0013-bind-libhegel-through-the-ffi-gem.md)
 - [0014: Name a drawn value only when the draw is the whole assigned value](adr/0014-name-a-drawn-value-only-when-the-draw-is-the-whole-assigned-value.md)
+- [0015: Follow the hegeldev interface, and take changes upstream first](adr/0015-follow-the-hegeldev-interface-and-take-changes-upstream-first.md)
+- [0016: Run mutation testing with mutineer](adr/0016-run-mutation-testing-with-mutineer.md)
+- [0017: Raise the Ruby floor to 3.4](adr/0017-raise-the-ruby-floor-to-3-4.md)
+- [0018: Gate mutation testing on a committed baseline](adr/0018-gate-mutation-testing-on-a-committed-baseline.md)
+- [0019: Report failures from the cases the engine stamps](adr/0019-report-failures-from-the-cases-the-engine-stamps.md)
+- [0020: Derive span labels from generator names](adr/0020-derive-span-labels-from-generator-names.md)
+- [0021: Run a state machine in rounds, with its own step count](adr/0021-run-a-state-machine-in-rounds-with-its-own-step-count.md)
+- [0022: Keep microsecond times over a nanosecond engine](adr/0022-keep-microsecond-times-over-a-nanosecond-engine.md)
+- [0023: Leave unset settings to the engine's profile](adr/0023-leave-unset-settings-to-the-engines-profile.md)
+- [0024: Release when a merge changes the gem version](adr/0024-release-when-a-merge-changes-the-gem-version.md)
 
 A new decision gets a new record. A changed decision supersedes the old
 record instead of editing it, so the history stays readable.

data/docs/adr/0015-follow-the-hegeldev-interface-and-take-changes-upstream-first.md

@@ -0,0 +1,101 @@
+# 0015: Follow the hegeldev interface, and take changes upstream first
+
+## Status
+
+Accepted.
+
+## Context
+
+This gem is one binding of libhegel among several. The Hegel project
+publishes implementations for Rust, Go, C++, TypeScript, Java, and OCaml,
+and each one drives the same engine. A person who writes a property in one
+language and then writes the same property in another expects the same call
+to mean the same thing.
+
+`CLAUDE.md` already names hegel-rust as the authority on meaning: what a
+call does, what an error code means, how a value shrinks. That rule settles
+disputes about behaviour. It does not say what to do when this gem's public
+surface is shaped differently from every other binding while each shape
+behaves as documented.
+
+`floats` is that case. Three implementations write the same rule for its
+defaults:
+
+- hegel-rust, `src/generators/numeric.rs:315`:
+  `allow_nan.unwrap_or(!has_min && !has_max)`, and
+  `allow_infinity.unwrap_or(!has_min || !has_max)`
+- hegel-go, `primitives.go:136`: the same two expressions, resolved through
+  a nil pointer check
+- hegel-typescript, `src/generators/numeric.ts:126`: the same two
+  expressions, resolved through `??`
+
+This gem instead fixed both to `false`, whatever the bounds. The comment on
+`Hegel::Generators::FloatGenerator` carried the reasoning: a caller who
+never asks for NaN never has to reason about it, a keyword can be added
+later without breaking anyone, and a default flipped from `true` to `false`
+would break someone.
+
+That reasoning weighs this gem's own callers. It leaves out what the
+difference costs. `floats` with no bounds is the ordinary way to ask for a
+double. Under the sibling rule that draw yields NaN and both infinities;
+here it yields neither. A property that passes here can fail the moment
+somebody ports it to Rust, and the Ruby test was the weaker one all along,
+because it never drew the values that break floating-point code. The
+difference is invisible at the call site: the same six-word call means two
+things.
+
+The skill this repository ships states the difference as a gotcha, so a
+reader who finds it is warned. A reader who does not find it gets a green
+run and a false conclusion.
+
+## Decision
+
+**The public surface follows the interface the hegeldev implementations
+share.** Names, arguments, defaults, and the meaning of each. A feature
+that this gem alone has, and a feature that this gem alone lacks, are both
+divergences.
+
+**A change to that interface starts as a proposal upstream.** Do not
+implement it here first and wait for the others to follow. When a proposal
+is accepted, this gem takes the name and the semantics that were settled on,
+rather than choosing again.
+
+hegel-rust stays the authority. Where the sibling implementations disagree
+with each other, hegel-rust decides, as it already does for behaviour.
+
+Three things stay outside this rule, because they are mechanism rather than
+interface. How the engine is reached (the `ffi` gem, ADR 0013). What Ruby
+alone can offer a reader, such as recovering a drawn value's name from the
+caller's source (ADR 0005, ADR 0014). Where a Ruby hazard forces a
+different construction, such as the control exceptions that must inherit
+from `Exception`.
+
+This record replaces the reasoning in the comment on
+`Hegel::Generators::FloatGenerator`, which decided the same question for
+`floats` alone and decided it the other way.
+
+## Consequences
+
+`floats` changes its defaults to the shared rule, and gains the two checks
+that come with it: `allow_nan: true` with either bound, and
+`allow_infinity: true` with both bounds, each raise `Hegel::Error` at draw
+time. hegel-rust and hegel-go both write those checks; the messages here
+carry the same substring as theirs.
+
+This breaks callers. A property that draws unbounded `floats` and passes
+today will see NaN and infinity after the change, and code that does not
+handle them will fail. That failure is the point: the property was not
+testing what it appeared to test. A caller who wants the old behaviour
+passes `allow_nan: false, allow_infinity: false`, and the call then says
+what it does.
+
+Growing the surface gets slower. A generator or an option that would be
+useful here has to be worth proposing upstream before it can ship here, and
+a proposal can be rejected. The gem trades the speed of deciding alone for
+callers who can move between languages.
+
+The comparison has to be made rather than assumed. Adding an option means
+reading how the other implementations spell it and what they default it to.
+`hegel-rust/src/generators/` holds the generator surface, and hegel-go and
+hegel-typescript hold the two closest readings of it for a language with
+keyword-style options.

data/docs/adr/0016-run-mutation-testing-with-mutineer.md

@@ -0,0 +1,87 @@
+# 0016: Run mutation testing with mutineer
+
+## Status
+
+Accepted. [ADR 0017](0017-raise-the-ruby-floor-to-3-4.md) supersedes the
+Gemfile group `mutation` in the Consequences.
+
+## Context
+
+The suite holds line and branch coverage at 100%. Coverage shows that a line
+ran. It does not show that a test would notice a change to that line.
+Mutation testing measures that: it changes the source in small ways, one at
+a time, and runs the tests against each change.
+
+mutineer is a mutation testing tool for Ruby. It parses the source with
+Prism and has no runtime dependency. It runs Minitest, and it selects, for
+each mutant, the test files that cover the mutated line.
+
+A first run over `lib/` met four problems, all measured on mutineer 1.0.2:
+
+- mutineer puts only `lib/` on the load path. Every test file starts with
+  `require "test_helper"`, so each one failed to load. The run then reported
+  every mutant as uncovered, with a score of N/A and exit status 0. The load
+  error appears only with `--verbose`.
+- mutineer pairs a source with `test/<name>_test.rb` only. This suite
+  names its tests `test_<name>.rb`, so each test file must be named with
+  `--test`. The flag takes one file, and it repeats. A first run gave one
+  flag several files, and the files after the first became sources to
+  mutate, so the score read 0.7%.
+- mutineer replaces `$stdout` with a `StringIO` before it runs the tests.
+  Minitest's `capture_subprocess_io` reopens `$stdout` on a file, so
+  `test/hegel/test_conformance.rb` failed before any mutant ran.
+- mutineer runs every mutant's tests in this one working directory. A
+  mutant that wrote `./.hegel` left the directory in place, and the
+  teardown check in five test classes then failed the tests of every later
+  mutant too.
+
+## Decision
+
+`bundle exec rake mutation` (and `just mutation`) runs mutineer 1.0.2 over
+`lib/`, with four settings:
+
+1. `RUBYOPT` gets `-Itest`, so `require "test_helper"` resolves.
+2. Each test file gets its own `--test` flag.
+3. `test/hegel/test_conformance.rb` stays out of the run. It still runs in
+   `rake test`.
+4. `--strategy redefine`. mutineer's default, `reload`, loads the whole
+   mutated file from a tempfile by a relative path, so its backtrace lines
+   show a relative path. `Hegel::Runner.origin_for` then takes a line in
+   `lib/` for the caller's, and its test fails for every mutant of
+   `lib/hegel/test_case.rb`. That alone killed three mutants that the
+   suite does not catch: one of them, applied by hand, left all 377 tests
+   passing. `redefine` loads only the mutated method.
+
+The five teardowns share `HegelDirectoryGuard#refute_new_hegel_directory`
+(`test/test_helper.rb`). When a test leaves a `./.hegel` it did not find at
+the start, the guard removes the directory, then fails the test. The mutant
+that wrote it is still killed, and later mutants no longer fail on the
+leftover. A `./.hegel` that existed before the test stays in place.
+
+`mutineer` is a development dependency, pinned exact and never required at
+load time. It needs Ruby 3.4 or later, and the gem supports 3.3, so it sits
+in the Gemfile group `mutation`. CI leaves that group out on every job, and
+a 3.3 install leaves it out with `bundle config set --local without
+mutation`. Mutation testing then runs on 3.4 or later only.
+`.mutineer/` (the cache and reports) and `.hegel/` are ignored by git.
+
+## Consequences
+
+The run over `lib/` covers 706 mutants in about a minute: 539 killed, 153
+survived, 8 without coverage, 6 without a verdict, a score of 77.9%. Measured
+with the reload strategy, the guard alone turned 10 former kills into
+survivors, which were false kills before.
+
+The survivors are a list of tests to add. A later change works through them
+by file.
+
+Settings 1, 3, and 4 work around mutineer itself, and setting 2 follows
+from its pairing rule. Each is reported: the load path as
+[davidteren/mutineer#119](https://github.com/davidteren/mutineer/issues/119),
+the pairing rule as
+[davidteren/mutineer#120](https://github.com/davidteren/mutineer/issues/120),
+the `StringIO` as
+[davidteren/mutineer#121](https://github.com/davidteren/mutineer/issues/121),
+and the relative path as
+[davidteren/mutineer#123](https://github.com/davidteren/mutineer/issues/123).
+When a mutineer release fixes one, drop the setting that it replaces.

data/docs/adr/0017-raise-the-ruby-floor-to-3-4.md

@@ -0,0 +1,43 @@
+# 0017: Raise the Ruby floor to 3.4
+
+## Status
+
+Accepted. Supersedes the Gemfile group `mutation` in the Consequences of
+[ADR 0016](0016-run-mutation-testing-with-mutineer.md).
+
+## Context
+
+The gem supported Ruby 3.3, 3.4, and 4.0. Ruby 3.3 has had security
+maintenance only since 2026-04-01, and its end of life is expected on
+2027-03-31.
+
+mutineer 1.0.2, the mutation testing tool of ADR 0016, needs Ruby 3.4 or
+later. With mutineer in the Gemfile, `bundle install` failed on every 3.3 job
+in CI. The first fix put mutineer in a Gemfile group `mutation`. Every CI job
+left that group out, and a developer on 3.3 had to leave it out by hand. That
+fix gave the repository two install paths, and CI never installed a tool that
+the repository runs.
+
+## Decision
+
+The floor is Ruby 3.4:
+
+- `required_ruby_version` is `>= 3.4.0`.
+- CI runs Ruby 3.4 and 4.0.
+- `.standard.yml` targets Ruby 3.4.
+- mutineer is back in the default Gemfile group, and CI installs it.
+
+Keeping 3.3 with the group was refused, because of the two install paths above.
+
+## Consequences
+
+A project on Ruby 3.3 stays on 0.1.1, the last release that installs there.
+The next release says so in the changelog.
+
+Every CI job installs the same bundle, and a developer needs one Ruby for the
+gem and its tools. The matrix loses its one exclusion: RubyInstaller has an
+arm64 Windows build for every Ruby in it.
+
+ADR 0001, ADR 0005, and ADR 0008 name 3.3 as the floor, which it was when
+they were written. ADR 0005's reason still holds on 3.4: Ruby 3.4 also ships
+Prism as a default gem.

data/docs/adr/0018-gate-mutation-testing-on-a-committed-baseline.md

@@ -0,0 +1,74 @@
+# 0018: Gate mutation testing on a committed baseline
+
+## Status
+
+Accepted. It builds on
+[ADR 0016](0016-run-mutation-testing-with-mutineer.md).
+
+## Context
+
+ADR 0016 runs mutineer over `lib/`: 706 mutants in about a minute, with 153
+survivors. Nothing checked the result, so a change could add a survivor and
+no one would see it.
+
+mutineer has two ways to narrow what fails a run. `--since REF` mutates only
+the lines changed since `REF`. `--baseline FILE` compares the run with an
+earlier JSON report, and fails on a survivor whose stable id is not in the
+report, or on a lower score. The id does not depend on the line number.
+
+mutineer writes its JSON report on one line of about 55 KB. Committed as it
+is, a change to the survivors reads as one changed line in a pull request.
+
+## Decision
+
+`test/mutation-baseline.json` holds the accepted survivors, and CI fails on
+any other survivor:
+
+- `rake mutation` runs over all of `lib/` with `--baseline` on that file.
+  `rake mutation:baseline` rewrites the file from a full run.
+- The file keeps what `--baseline` reads: `schema_version`, `summary.score`,
+  `summary.scoped`, and each survivor's `id`. Each survivor is one line,
+  sorted by file, method, and id, with the mutated line before and after. It
+  leaves out line numbers.
+- `--baseline-epsilon 1` absorbs a small score drop. A mutant that times out
+  on a slow machine leaves the score, and it can never add a survivor.
+- The CI job `mutation` runs `rake mutation` once, on Linux with Ruby 4.0, for
+  every push and pull request.
+- `rake mutation:baseline` refuses a `--since` run, which mutineer refuses as
+  a baseline too. It also refuses to write a file that contains the working
+  directory or the home directory, because the file is public.
+
+A full run takes about a minute, so CI runs in full. `--since` stays for a
+local run on a change in progress.
+
+Two alternatives were refused:
+
+- A baseline made on main by CI and passed to a pull request as an artifact.
+  It adds no file to the repository, but a reviewer cannot see a change to the
+  survivors, and the workflow needs to find the artifact of the right run.
+- A gate on `--since` alone, which fails on any survivor on a changed line. An
+  edit to a line with an old survivor would then fail for a survivor that the
+  edit did not add.
+
+## Consequences
+
+A pull request that adds a survivor fails, until it adds a test or accepts
+the survivor with `rake mutation:baseline`. The accepted survivor then shows
+as one added line in the diff. A pull request that kills a survivor passes
+without a change to the file, and the next rewrite shows the survivor as one
+removed line.
+
+A survivor that no test can kill, because the mutant behaves the same as the
+original, gets a `# mutineer:disable-line <operator>` marker on its line,
+with the reason in a comment on the line above. The judgment then moves
+with the code through an edit or a move, which an id list in
+`.mutineer.yml` does not do. The reason cannot follow the marker on the same
+line, because mutineer reads every word after the marker as an operator
+name. The survivor then leaves the baseline too.
+
+A marker suppresses every mutant of its operator on its line. When a line
+holds an equivalent mutant and a killed one of the same operator, a marker
+would also hide the killed one. `Runner.classify` has three such lines,
+and `TestCase#generate_boolean` has one. Those equivalent mutants go in
+`.mutineer.yml` under `ignore:`, by their stable id. The reason stays in a
+comment beside the code, and the comment names `.mutineer.yml`.