hegeltest 0.3.4 → 0.4.0

data/README.md

@@ -27,78 +27,72 @@ failure to a minimal counterexample.
 
 This gem drives [libhegel](https://hegel.dev/reference/libhegel), the native
 engine that the official implementations also drive. The engine runs in the
-same process. There is no server and no Python dependency.
+same process, through the [`ffi`](https://github.com/ffi/ffi) gem. There is no
+server and no Python dependency.
 
-## Status
+## Installation
 
-**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:
-
-1. **The walking skeleton**: the libhegel binding, the run loop, and failure
-   reports.
-2. **The full generator set**: twenty-five generators, composing through
-   `map` and `filter`.
-3. **The advanced features**: the example database, targeted testing,
-   stateful testing, phases, and health checks.
-
-Install it the way you install any gem:
+The gem is published as [`hegeltest`](https://rubygems.org/gems/hegeltest):
 
 ```ruby
 # Gemfile
-gem "hegeltest"
+gem "hegeltest", group: :test
 ```
 
-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]).
+The require path is `hegel`, and the namespace is `Hegel`.
+`require "hegeltest"` also works, so Bundler's automatic require finds it.
+
+The gem needs Ruby 3.4 or later. Each platform gem carries the matching
+`libhegel` build, so an install compiles nothing and needs no engine on the
+side:
+
+| Platform | Gem platform |
+| --- | --- |
+| Linux x64 | `x86_64-linux` |
+| Linux arm64 | `aarch64-linux` |
+| macOS arm64 | `arm64-darwin` |
+| Windows x64 | `x64-mingw-ucrt` |
+| Windows arm64 | `aarch64-mingw-ucrt` |
+
+The Hegel maintainers permit a third-party project to redistribute their
+release binaries ([hegeldev/hegel-rust#411]).
 
-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:
+A project that already has a `Gemfile.lock` needs one more step. Bundler adds
+only the platform of the machine that runs `bundle install`, so a lock made on
+a Mac does not name Linux. A Linux CI job then cannot find the gem. 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.
+On a platform with no published `libhegel` build, such as macOS on Intel, build
+the engine yourself and set `HEGEL_LIBHEGEL_PATH` to the library file or to the
+directory that holds it. The same variable makes any platform use a local
+engine build in place of the bundled one.
 
 [hegeldev/hegel-rust#411]: https://github.com/hegeldev/hegel-rust/issues/411
 
-## Design
+### Which libhegel a release carries
 
-| Decision | Choice |
-| --- | --- |
-| Gem name | `hegeltest` |
-| 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.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` |
+Each gem release pins one libhegel release. To see the pinned version in your
+installed gem:
 
-`HEGEL_LIBHEGEL_PATH` overrides the bundled engine with a local build.
+```bash
+ruby -rhegel -e 'puts Hegel::LIBHEGEL_VERSION'
+```
 
-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.
+The [CHANGELOG](CHANGELOG.md) section of each gem release starts with the
+engine move, when there is one, and links the release notes of that engine
+version. The [GitHub releases](https://github.com/meganemura/hegel-ruby/releases)
+show the same text.
 
-macOS on Intel has no published `libhegel` artifact, so that platform needs
-`HEGEL_LIBHEGEL_PATH` and a local build.
+When libhegel publishes a new release, a pull request moves this gem to it.
+The gem version and the engine version are independent: a gem release can
+change the engine, the Ruby code, or both.
 
 ## Quickstart
 
-Everything below runs today.
-
 ```ruby
 # spec/spec_helper.rb
 require "hegel"
@@ -123,7 +117,7 @@ end
 ```
 
 That test fails, and Hegel shrinks the failure to the smallest input that
-still shows the bug:
+still shows the bug. The report looks like this:
 
 ```
 Falsified after 11 test cases (0 discarded):
@@ -134,27 +128,26 @@ To reproduce this failure, pass the blob below to Hegel.test:
     reproduce_failure: "AXicY2VgYGBkZOBiZEBhMAAAAd8AIQ=="
 ```
 
-Two duplicates are all it takes. Hegel names the value `xs` by reading the
-line the draw was written on, then re-raises RSpec's own expectation failure,
-so the framework reports it as its own.
+The count of test cases and the blob change from run to run, and between
+engine releases. The shrunk value is the part to read: two duplicates are all
+it takes. Hegel names the value `xs` by reading the line the draw was written
+on. Then it re-raises RSpec's own expectation failure, so RSpec reports it as
+its own.
 
 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.
+prefix, the way FactoryBot makes `create` available. The same generators are
+also available 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:
+To keep the generator names out of example groups that have their own
+helpers, include the methods only in tagged groups:
 
 ```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:
+which the default RuboCop naming rule accepts:
 
 ```ruby
 def draw_sorted_pair(test_case)
@@ -169,15 +162,9 @@ Hegel.test do |tc|
 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`,
-`sampled_from`, `sets`, `text`, `times`, `tuples`, `urls`, and `uuids`. Each
-one composes through `map` and `filter`.
-
 ### Minitest
 
-Hegel needs nothing from your test framework. Install the generator methods
+Hegel needs nothing from your test framework. Include the generator methods
 once, and write the property inside an ordinary test:
 
 ```ruby
@@ -201,8 +188,7 @@ class MySortTest < Minitest::Test
 end
 ```
 
-Minitest reports the shrunk case as its own assertion failure, pointing at
-your line:
+Minitest reports the shrunk case as its own assertion failure, at your line:
 
 ```
 1) Failure:
@@ -211,10 +197,28 @@ Expected: [0, 0]
   Actual: [0]
 ```
 
-### Stateful testing
+## Generators
+
+| Kind | Generators |
+| --- | --- |
+| Numbers and booleans | `integers`, `floats`, `booleans` |
+| Text and bytes | `text`, `characters`, `binary`, `from_regex`, `from_lark` |
+| Collections | `arrays`, `sets`, `hashes`, `tuples` |
+| Choice | `just`, `sampled_from`, `permutations`, `subsequences`, `samples`, `one_of`, `optional` |
+| Formats | `emails`, `urls`, `domains`, `ip_addresses`, `uuids` |
+| Time | `dates`, `times`, `datetimes`, `date_strings`, `time_strings`, `datetime_strings`, `durations` |
+| Your own | `composite`, `deferred`, `recursive` |
+
+Each one composes through `map` and `filter`. Options are keywords, with the
+names the other Hegel implementations use, such as
+`integers(min_value: 0, max_value: 9)`, `arrays(text, max_size: 5)`, or `arrays(integers, unique: true)`. An
+invalid combination of options raises when the generator is drawn, not when it
+is built.
+
+## Stateful testing
 
 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
+operations as rules on a `Hegel::StateMachine`. Hegel picks which rule runs
 next, checks your invariants along the way, and shrinks a failure to the
 shortest sequence that still shows it:
 
@@ -245,32 +249,48 @@ Hegel.test { |tc| Hegel::Stateful.run(StackMachine.new, tc) }
 ```
 
 `tc.assume` inside a rule rejects that rule and lets Hegel choose another,
-rather than throwing the whole test case away. For a rule that has to act on
-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.
+rather than throwing the whole test case away. When a rule must act on a value
+that an earlier rule made, such as freeing a handle that some `alloc` 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`, 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`
-chooses the directory:
+the engine samples each invariant. Declare an invariant with
+`always_run: true` to check it after every rule.
+`Hegel::Stateful.run(machine, tc, step_count: 50)` sets the largest number of
+rules that one test case runs; 50 is the default. `rule :name, weight: 2.5`
+asks Hegel to pick a rule more often than the others; the default weight is
+1.0.
+
+## Configuring a run
+
+`Hegel.test` takes these keywords:
+
+| Keyword | Effect |
+| --- | --- |
+| `profile` | The settings profile the run starts from; see [Profiles](#profiles) |
+| `test_cases` | How many test cases to generate |
+| `seed` | The seed for the random generation |
+| `derandomize` | Make the generation deterministic |
+| `verbosity` | How much the engine prints; `:quiet` also hides the failure report |
+| `phases` | Which engine phases run, such as generation and shrinking |
+| `suppress_health_check` | Which health checks to turn off |
+| `report_multiple_failures` | Report each distinct failure; `false` by default |
+| `stop_on_first_failure` | `false` spends the whole `test_cases` budget before reporting |
+| `print_blob` | `false` leaves the reproduction line out of the failure report |
+| `show_statistics` | Print what `tc.event` and `tc.event_value` recorded, at the end of the run |
+| `nondeterminism_strictness` | `:quiet`, `:warn`, or `:error` when the test behaves differently on a replay |
+| `backend` | `:default`, or `:urandom` to take fresh entropy on every draw, for Antithesis |
+| `database_key` | Turn the example database on for this property |
+| `database` | The directory of the example database |
+| `reproduce_failure` | Replay one failure from the blob in its report |
+
+A keyword that you do not set takes its value from the engine's settings
+profile. That is libhegel's own default, unless a `hegel.toml` file or a
+`HEGEL_*` environment variable changes it. On a CI server the engine uses its
+`ci` profile, which derandomizes the run and turns the example database off.
+
+The example database stores a failing case and replays it first next time.
+`database_key` turns it on, and `database` chooses the directory:
 
 ```ruby
 Hegel.test(database_key: "my_sort matches the builtin sort") { |tc| ... }
@@ -278,22 +298,104 @@ Hegel.test(database_key: "my_sort matches the builtin sort") { |tc| ... }
 
 Give each property its own key. See
 [ADR 0009](docs/adr/0009-turn-the-example-database-on-with-a-key.md) for why
-the key, rather than the directory, is what turns it on.
+the key, and not the directory, turns it on.
+
+Inside a test, `tc.note` records a message that the failure report prints,
+`tc.target` tells Hegel which inputs to search toward, and `tc.repeat` runs a
+block for as many iterations as Hegel chooses.
+
+`tc.event` and `tc.event_value` check that a test reaches the cases you care
+about. With `show_statistics: true`, the engine prints how often each event
+happened and a summary of each value. The numbers change from run to run:
+
+```ruby
+Hegel.test(show_statistics: true) do |tc|
+  xs = tc.draw(arrays(integers))
+  tc.event("empty") if xs.empty?
+  tc.event_value("size", xs.size)
+end
+```
+
+```
+Statistics (over 100 test cases):
+  * empty: 6.0% of test cases
+  * size: count 100, min 0, median 6, mean 7.99, p90 19, max 20
+```
+
+## Profiles
+
+A profile is a named set of settings. The engine ships `development`, `ci`,
+and `workload`, and a `hegel.toml` file can define more. Pass `profile:` to
+start one run from a profile, and register your own with
+`Hegel::Settings.register_profile`:
+
+```ruby
+Hegel::Settings.register_profile("nightly", profile: "ci", test_cases: 10_000)
+
+Hegel.test(profile: "nightly") { |tc| ... }
+```
+
+A keyword passed to `Hegel.test` still beats the profile. A profile you
+name extends the default profile, so what it does not set comes from
+there. `Hegel::Settings.set_default_profile("nightly")` makes a profile the
+default for every run in the process, and `set_default_profile("")` clears
+it. Registration and the default are process-wide, and they do not change
+runs that have already started. `register_profile` takes the keywords of
+`Hegel.test` except `database_key`, which a profile does not carry, and
+`Hegel.test` always passes `report_multiple_failures`, so a profile's value
+for it never applies. An unknown name raises `Hegel::Error`. See
+[ADR 0028](docs/adr/0028-expose-settings-profiles-as-a-keyword-and-module-functions.md).
 
-Inside a test, `tc.note` records a message the failure report prints, and
-`tc.target` tells Hegel which inputs to search toward.
+## Agent skill
+
+Two skills work together. The official
+[hegel-skill](https://github.com/hegeldev/hegel-skill) from the Hegel
+maintainers teaches the method: which properties to look for, and how to
+check the tests an agent writes. It works with every Hegel implementation.
+[`skills/hegel-ruby`](skills/hegel-ruby/SKILL.md) adds the Ruby part: this
+gem's API and how to use it with RSpec and Minitest. Install both.
+
+In Claude Code, add each repository as a marketplace and install its plugin:
+
+```
+/plugin marketplace add hegeldev/hegel-skill
+/plugin install hegel-skill@hegeldev
+/plugin marketplace add meganemura/hegel-ruby
+/plugin install hegel-ruby@meganemura
+```
+
+For Codex and other agents, see the installation section of the
+[hegel-skill README](https://github.com/hegeldev/hegel-skill#installation).
+For this gem's skill, use the same steps with
+<https://github.com/meganemura/hegel-ruby/tree/main/skills/hegel-ruby>.
 
 ## Development
 
 ```bash
 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
+bundle exec rake                 # run the tests with coverage, and the linter
+bundle exec rake mutation        # run mutation testing
 bin/console                      # open an interactive prompt
 ```
 
-`just` recipes call the same Rake tasks, so `just test` and `just lint` work
-for anyone who already uses `just` with the other Hegel implementations.
+`just` recipes call the same Rake tasks, so `just check`, `just test`, and
+`just lint` work for anyone who uses `just` with the other Hegel
+implementations.
+
+CI runs the suite on each pull request and on each push to main, on every
+platform in the table above, with Ruby 3.4 and 4.0.
+
+The design records are in [docs/](docs/README.md).
+
+### Releasing
+
+A merge into main that changes `lib/hegel/version.rb` starts a release. The
+Release workflow waits for an approval of the `release` environment. After
+the approval, it runs the tests, publishes the gems to RubyGems, and then
+creates the tag `v<version>` and the GitHub release. The release notes come
+from the version's section of [CHANGELOG.md](CHANGELOG.md). See
+[ADR 0024](docs/adr/0024-release-when-a-merge-changes-the-gem-version.md).
 
 ## Contributing
 
@@ -308,3 +410,7 @@ This gem is available under the [MIT License](LICENSE.txt).
 Released gems also carry `libhegel`'s own license, which is MIT and copyright
 Antithesis, LLC. Each platform gem ships `NOTICE-libhegel.txt` next to the
 engine, and that file holds the text.
+
+---
+
+[日本語版 README](README.ja.md)

data/Rakefile

@@ -18,8 +18,8 @@ end
 
 task default: %i[coverage standard]
 
-# Mutation testing with mutineer, over lib/. Four settings make the suite
-# run under it; ADR 0016 records why:
+# Mutation testing with mutineer, over lib/. Five settings make the suite
+# run under it; ADR 0016 records the first four, and ADR 0032 the fifth:
 # - 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
@@ -31,6 +31,9 @@ task default: %i[coverage standard]
 #   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.
+# - test_recursive_engine.rb stays out too. Its 30-leaf shrink takes about
+#   ten seconds, mutineer's limit for one mutant, so a mutant on a line it
+#   covers timed out without a verdict.
 # MUTINEER_ARGS passes more flags, for example
 # MUTINEER_ARGS="--since origin/main" to mutate only the lines changed since
 # origin/main.
@@ -42,7 +45,7 @@ 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]
+    %w[test/test_helper.rb test/hegel/test_conformance.rb test/hegel/test_recursive_engine.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

data/docs/README.md

@@ -33,6 +33,15 @@ An index of the design records for `hegel-ruby`.
 - [0024: Release when a merge changes the gem version](adr/0024-release-when-a-merge-changes-the-gem-version.md)
 - [0025: Copy each string input into a hegel_string_t](adr/0025-copy-each-string-input-into-a-hegel-string-t.md)
 - [0026: Select the engine release repository by version](adr/0026-select-the-engine-release-repository-by-version.md)
+- [0027: Report each run's test location from the caller's frame](adr/0027-report-each-runs-test-location-from-the-callers-frame.md)
+- [0028: Expose settings profiles as a keyword and module functions](adr/0028-expose-settings-profiles-as-a-keyword-and-module-functions.md)
+- [0029: Keep notes local, and defer run error kinds](adr/0029-keep-notes-local-and-defer-run-error-kinds.md)
+- [0030: Represent a duration as Integer nanoseconds](adr/0030-represent-a-duration-as-integer-nanoseconds.md)
+- [0031: Take the alphabet options from hegel-rust](adr/0031-take-the-alphabet-options-from-hegel-rust.md)
+- [0032: Suppress span closes while an abandoned recursion attempt unwinds](adr/0032-suppress-span-closes-while-an-abandoned-recursion-attempt-unwinds.md)
+- [0033: Cache compiled grammars for the length of a run](adr/0033-cache-compiled-grammars-for-the-length-of-a-run.md)
+- [0034: Repeat a test body with a Ruby-side indent](adr/0034-repeat-a-test-body-with-a-ruby-side-indent.md)
+- [0035: Defer concurrent state machines and the engine printer](adr/0035-defer-concurrent-state-machines-and-the-engine-printer.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/0027-report-each-runs-test-location-from-the-callers-frame.md

@@ -0,0 +1,63 @@
+# 0027: Report each run's test location from the caller's frame
+
+## Status
+
+Accepted.
+
+## Context
+
+`hegel_settings_set_test_location` takes the file, the first line, the
+enclosing class, and the name of the test function. Under Antithesis, which
+the engine detects through `ANTITHESIS_OUTPUT_DIR`, the engine appends one
+`always` assertion named `<class>::<function> passes properties` to
+`sdk.jsonl` in that directory, located at `file:begin_line`. Outside
+Antithesis it uses nothing. hegel-rust fills the four values in
+`#[hegel::test]` from `file!()`, `module_path!()`, the function name, and
+`line!()`, and takes no keyword for them.
+
+Ruby has no macro that sees the definition. A `Hegel.test` call can read its
+own caller's frame with `caller_locations`, and a frame label in Ruby 3.4
+reads `Class#method` or `Class.method`, with `block in ` or
+`block (2 levels) in ` in front of it inside a block. A call at the top of a
+file, which is where an RSpec example sits, has the label `<main>` or
+`<top (required)>`, and a frame whose method is defined on an anonymous
+class has the bare method name.
+
+## Decision
+
+`Hegel.test` builds one `Hegel::TestLocation`, a `Data` of `file`,
+`begin_line`, `class_name`, and `function`, and hands it to `Runner.run`.
+`Runner.run` calls the setter after `Settings.apply` and before it starts
+the run or replays a blob. The location is identity, not a setting, so
+`Settings.apply` does not take it, and `Hegel.test` has no keyword for it.
+
+The frame is the first one that `Runner.infrastructure?` does not call
+infrastructure, the same rule that names the origin of a failure (see
+[ADR 0012](0012-build-a-failure-origin-from-the-callers-own-frame.md)). A
+wrapper in this gem, a gem, or the standard library is therefore never named
+as the test.
+
+`file` is the frame's absolute path made relative to `Dir.pwd` when it lies
+under it, and absolute otherwise. `begin_line` is the frame's line, the line
+of the `Hegel.test` call.
+
+A label that splits as `Class#method` or `Class.method`, after the `block
+... in ` prefix is stripped, gives `class_name` and `function`. Any other
+label has no name of its own, so `class_name` is the `file` without `.rb`
+and `function` is `line <n>`. Two examples in one spec file then report two
+assertions, where one shared name would merge them into one that fails when
+either fails.
+
+## Consequences
+
+The line is that of the call, where hegel-rust's is that of the function's
+definition, so a method with two `Hegel.test` calls reports two assertions
+with the same name at two lines.
+
+A caller cannot choose the name. hegel-rust's macro derives it as well, so a
+keyword would be a change to the shared interface, which starts as a proposal
+upstream (see
+[ADR 0015](0015-follow-the-hegeldev-interface-and-take-changes-upstream-first.md)).
+
+The cost is one `caller_locations` call and one regular expression match for
+each `Hegel.test` call, none for each test case.

data/docs/adr/0028-expose-settings-profiles-as-a-keyword-and-module-functions.md

@@ -0,0 +1,91 @@
+# 0028: Expose settings profiles as a keyword and module functions
+
+## Status
+
+Accepted. Builds on [ADR 0023](0023-leave-unset-settings-to-the-engines-profile.md),
+which left the profile to the engine, and applies
+[ADR 0015](0015-follow-the-hegeldev-interface-and-take-changes-upstream-first.md).
+
+## Context
+
+libhegel 0.47.2 has three calls for profiles. `hegel_settings_new_for_profile`
+builds a settings handle from a named profile. `hegel_settings_register_profile`
+stores a complete snapshot of a handle under a name, for the whole process,
+replacing an earlier registration of that name. `hegel_set_default_profile`
+names the profile that `hegel_settings_new` resolves, for the whole process,
+and an empty name clears it. A named profile still extends the default
+profile, except `base`. An unknown name, a reserved name, a malformed
+`hegel.toml`, and a malformed `HEGEL_*` variable return `HEGEL_E_INVALID_ARG`
+with a message. The snapshot leaves out the database key, and a registration
+does not change handles that already exist.
+
+hegel-rust exposes them on its `Settings` value: `Settings::from_profile`
+and `Settings::try_from_profile` return a `Settings` to adjust with builder
+methods, `Settings::register_profile(name, settings)` registers one, and
+`Settings::set_default_profile(name)` sets the default. Its documentation
+example is `Settings::register_profile("nightly",
+Settings::from_profile("ci").test_cases(10_000))`.
+
+Ruby has no `Settings` value. `Hegel.test` takes keywords, and
+`Hegel::Settings` is a module of functions that copy those keywords onto a
+native handle that exists only for the length of one run (ADR 0023).
+
+## Decision
+
+**`Hegel.test` takes `profile:`, which stands in for `from_profile`.** A
+`nil` profile calls `hegel_settings_new`, as before. A String calls
+`hegel_settings_new_for_profile`. The keywords apply afterwards in both
+cases, so one passed explicitly still beats the profile's value, and the
+`reproduce_failure:` path builds its settings the same way. This is a
+difference of mechanism under ADR 0015: the value that hegel-rust builds and
+then adjusts is, here, the argument of the call that uses it.
+
+**`Hegel::Settings.register_profile(name, profile: nil, **keywords)`
+registers a profile.** It sits on `Hegel::Settings` because hegel-rust puts
+`register_profile` on `Settings`. It opens a context of its own, builds a
+handle from `hegel_settings_new` or from the named `profile:`, applies the
+keywords, registers the handle, and frees the handle and then the context in
+an `ensure`. It takes an `impl:` keyword, defaulting to `Hegel.default_impl`,
+so a test can pass the Fake the way it does to `Hegel.test`.
+
+The keywords are those of `Hegel.test`, each `nil` meaning that no setter
+runs, with these exceptions:
+
+- `database_key:` is not accepted. The engine leaves the key out of the
+  snapshot, so accepting it would promise something the profile cannot keep.
+  Ruby's own `ArgumentError` rejects it, as it does any unknown keyword.
+- `database:` goes straight to `hegel_settings_set_database`, a path or `""`
+  to turn the database off. The table of ADR 0009 exists to decide what a
+  missing key means for a run, and a profile carries no key.
+- `report_multiple_failures:` is `nil` by default here, where `Hegel.test`
+  defaults it to `false`.
+
+Starting from `hegel_settings_new` matches `Settings::new()`, which resolves
+the default profile. hegel-rust's documented example starts from another
+profile instead, and `profile: "ci"` is the same thing here.
+
+**`Hegel::Settings.set_default_profile(name)` sets the default profile,**
+with the same `impl:` keyword. `""` clears it.
+
+An error from the engine raises `Hegel::Error` with the engine's message,
+through `LibHegel.check!`. hegel-rust panics with the same message.
+
+## Consequences
+
+`Hegel.test` always passes `report_multiple_failures`, as ADR 0023 decided,
+so a profile's value for it is overridden on every run. A profile can carry
+the setting, but it never changes what `Hegel.test` does.
+
+Registrations and the default profile are state of the process, held by the
+engine and not by any context. A test that registers a profile leaves it
+registered, and the engine has no call to remove one. A test that sets the
+default profile clears it again with `set_default_profile("")`. Neither
+affects a run that is already in progress.
+
+A `HEGEL_*` variable applies over a profile's snapshot, as the header says
+for every handle, so `HEGEL_PRINT_BLOB` beats a `print_blob: false` that the
+profile registered. The tests that observe a profile through the failure
+report clear those variables first.
+
+Each call to `register_profile` and `set_default_profile` opens and frees a
+context. Both are meant for setup, run once, not once per test case.