hegeltest 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: facbe6e366b74782ab68e979295856ef15c8da56ea9d9fe9291764cbf1629eb3
-  data.tar.gz: e78e0364232dc02974f7ca81135a34325a76287c425d59f1d384ef2f2acfb2aa
+  metadata.gz: fc58a6595c70e7dd1e873f76049109ceea93f5a7304ff4a6b4d2287072d0a0e6
+  data.tar.gz: 42099dfad36fa60a4a15b17d4713062a5224b4926a2ea15f56e84758f56e93f8
 SHA512:
-  metadata.gz: c977d4fd78f3439b18b731ae14c6772968aff53271fe1f44a8712f044a6dc0bcdcbd0ece18da677a7e3599a831651806a979c6985d5b942e6d89534c5c6eae14
-  data.tar.gz: 429fb8e7ce09f224c32368ad0d34bc69d1020f56891bdb2616da02acb86fa0ef5c174f340f27fc5a0cdf4918e8a4f82075781128850656b571e0b4232143abf5
+  metadata.gz: eb7cdb67a056b0db5e3803f915bb8b09001ac2ea5918ec1fd3763345f295e56140075aa02260a8efcc3bf3f6d6009b352066ab116a23797f02b42691cc93b018
+  data.tar.gz: 06bd1f1bfae6a4918adff338816c0d2f35cfca94fb063017ebcfdbd34c27581fe60b7006d7244fc12266e51a19e704a68053a3e568952aa5e28133703cae871f

data/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## [Unreleased]
+
+## [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`
+from git and to point `HEGEL_LIBHEGEL_PATH` at a local build. 0.1.0 shipped
+that text, and 0.1.0 needs neither. A reader who followed it spent their first
+minutes on a checkout and an engine build. The reference now says what the
+README says.
+
+A drawn value written inside a larger expression named itself after the
+assignment target, so `term_start_date = Date.new(tc.draw(...), 2, 29)`
+reported `term_start_date` beside a year. Such a draw now takes the generic
+name, and `label:` names it when a name is wanted. See
+[ADR 0014](docs/adr/0014-name-a-drawn-value-only-when-the-draw-is-the-whole-assigned-value.md).
+
+The settings table names 100 as libhegel's own default for `test_cases`. The
+README shows how to scope `Hegel::Syntax::Methods` to tagged example groups in
+a suite that already exists, and how to share a group of draws through a plain
+Ruby method. The `text` section says which generators cover the character-set
+options it does not take, measured against libhegel 0.32.5.
+
 ## [0.1.0] - 2026-08-20
 
 The first release.
@@ -19,4 +120,6 @@ 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.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

@@ -31,8 +31,7 @@ same process. There is no server and no Python dependency.
 
 ## Status
 
-**The first release is prepared, and the version is `0.1.0`.** Everything
-described below runs: Hegel finds a counterexample, shrinks it,
+**Released as `hegeltest` 0.1.0.** Hegel finds a counterexample, shrinks it,
 names the values it drew, and re-raises your own exception.
 
 Work ran in three stages, and all three are done:
@@ -44,26 +43,34 @@ Work ran in three stages, and all three are done:
 3. **The advanced features**: the example database, targeted testing,
    stateful testing, phases, and health checks.
 
-**Nothing is published to RubyGems yet.** The packaging is built:
-`rake platform_gems:build` produces one gem per platform, each carrying the
-matching `libhegel` build. The arm64 macOS gem is verified to find that
-engine inside itself and run a property with no `HEGEL_LIBHEGEL_PATH` set.
-A `v*` tag publishes all six gems from CI. The Hegel maintainers permit a
-third-party project to redistribute their release binaries
+Install it the way you install any gem:
+
+```ruby
+# Gemfile
+gem "hegeltest"
+```
+
+Each platform gem carries the matching `libhegel` build, so an install
+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]).
 
-So running this today means cloning the repository:
+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
-bin/setup
-bundle exec rake libhegel:fetch   # downloads the pinned build, checked against its SHA-256
-bundle exec rake
+bundle lock --add-platform x86_64-linux
 ```
 
-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 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
 
@@ -75,17 +82,17 @@ 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` |
 
-`HEGEL_LIBHEGEL_PATH` will override the bundled engine with a local build.
+`HEGEL_LIBHEGEL_PATH` overrides the bundled engine with a local build.
 
 The gem name follows the Rust implementation, whose published crate is
 `hegeltest` and whose library is `hegel`. The name `hegel` on RubyGems.org
 stays free for whoever publishes an official Ruby implementation.
 
-macOS on Intel has no published `libhegel` artifact, so that platform will need
+macOS on Intel has no published `libhegel` artifact, so that platform needs
 `HEGEL_LIBHEGEL_PATH` and a local build.
 
 ## Quickstart
@@ -135,6 +142,33 @@ Including `Hegel::Syntax::Methods` makes the generators available without a
 prefix, the way FactoryBot makes `create` available. The same generators stay
 reachable as `Hegel::Generators.arrays(...)` without the include.
 
+An existing RSpec suite can limit the 25 generator names to tagged example
+groups. This keeps the names out of other groups that have their own helpers:
+
+```ruby
+config.include Hegel::Syntax::Methods, :hegel
+```
+
+A new project can include the methods in every group, as the Quickstart does.
+
+Hegel draws values imperatively, so an ordinary Ruby method can share a group
+of draws between properties. Give the method parameter a descriptive name,
+which the default RuboCop naming rule accepts where a block parameter `tc`
+needs no change:
+
+```ruby
+def draw_sorted_pair(test_case)
+  low = test_case.draw(integers(min_value: 0, max_value: 100))
+  high = test_case.draw(integers(min_value: low, max_value: 200))
+  [low, high]
+end
+
+Hegel.test do |tc|
+  low, high = draw_sorted_pair(tc)
+  expect(low).to be <= high
+end
+```
+
 The generators are `arrays`, `binary`, `booleans`, `characters`, `composite`,
 `dates`, `datetimes`, `deferred`, `domains`, `emails`, `floats`, `from_regex`,
 `hashes`, `integers`, `ip_addresses`, `just`, `one_of`, `optional`,
@@ -181,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
@@ -216,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`
@@ -241,9 +286,10 @@ Inside a test, `tc.note` records a message the failure report prints, and
 ## Development
 
 ```bash
-bin/setup          # install dependencies
-bundle exec rake   # run the tests and the linter
-bin/console        # open an interactive prompt
+bin/setup                        # install dependencies
+bundle exec rake libhegel:fetch  # download the pinned engine, checked against its SHA-256
+bundle exec rake                 # run the tests and the linter
+bin/console                      # open an interactive prompt
 ```
 
 `just` recipes call the same Rake tasks, so `just test` and `just lint` work

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

@@ -20,6 +20,16 @@ An index of the design records for `hegel-ruby`.
 - [0011: Let the test case own every pool drawn from it](adr/0011-let-the-test-case-own-every-pool-drawn-from-it.md)
 - [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)
 
 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/0014-name-a-drawn-value-only-when-the-draw-is-the-whole-assigned-value.md

@@ -0,0 +1,74 @@
+# 0014: Name a drawn value only when the draw is the whole assigned value
+
+## Status
+
+Accepted.
+
+## Context
+
+[ADR 0005](0005-name-drawn-values-from-the-callers-source-with-prism.md)
+recovers a drawn value's name by parsing the caller's source and reading the
+assignment that covers the draw's line. Its Consequences section lists three
+cases it had not checked: a heredoc, several draws on one line, and a method
+chain.
+
+A first use of the gem outside this repository reached one of them. The
+caller wrote a draw inside a larger expression:
+
+```ruby
+term_start_date = Date.new(tc.draw(integers(min_value: 1904, max_value: 1904)), 2, 29)
+```
+
+Measured against libhegel 0.32.5, the failure report printed:
+
+```
+term_start_date = 1904
+```
+
+The name says "a date". The value is a year. The reader misread that report
+twice before adding a `label:`.
+
+`Hegel::DrawName` already carries the rule this breaks. Its own
+documentation states it: a wrong name misdirects a reader of the failure
+report more than a missing one does, so an ambiguous line returns nil rather
+than choosing between candidates. The module applied that rule to two
+assignments written side by side, and applied the opposite rule to a draw
+buried in one assignment's value.
+
+A draw pulled out into a plain method is a separate case, and it already
+worked. Measured on the same engine, a helper whose body reads
+`year = tc.draw(integers(min_value: 1900, max_value: 1910))` reported
+`year = 1900`. `Hegel::TestCase::DRAW_CALLER_DEPTH` lands on the line that
+called the draw, which is the helper's own line, and the name there is the
+one the caller wrote.
+
+## Decision
+
+Recover a name only when the assignment's value is the draw call itself: the
+value node is a `Prism::CallNode` whose name is one of the methods that reach
+`Hegel::TestCase#record_draw`. Any other value node returns nil, and
+`Hegel::TestCase#name_for` falls back to the generic name.
+
+The three method names stay in `Hegel::TestCase`, which defines them, and
+`Hegel::DrawName.for` takes them as an argument. A fourth draw method then
+has one place to be added.
+
+## Consequences
+
+A draw written inside a larger expression reports the generic name and its
+value. The reader loses a name and keeps a value that agrees with it. A
+caller who wants the name back passes `label:`, which
+[ADR 0005](0005-name-drawn-values-from-the-callers-source-with-prism.md)
+already gives precedence over the recovered name.
+
+A method chain answers the question ADR 0005 left open, and answers it the
+same way: `xs = tc.draw_integer(0, 10).to_s` reports the generic name,
+because `xs` holds a String and the drawn value is an Integer.
+
+A draw written inside another draw's arguments shares the enclosing
+assignment's name, because the enclosing assignment's value is a draw call
+and one line carries both draws. `label:` separates them.
+
+`Hegel::DrawName` now answers a narrower question than its name suggests on
+its own, so its documentation states the question it answers and the reason
+for the narrowing.

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.