hegeltest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: facbe6e366b74782ab68e979295856ef15c8da56ea9d9fe9291764cbf1629eb3
+  data.tar.gz: e78e0364232dc02974f7ca81135a34325a76287c425d59f1d384ef2f2acfb2aa
+SHA512:
+  metadata.gz: c977d4fd78f3439b18b731ae14c6772968aff53271fe1f44a8712f044a6dc0bcdcbd0ece18da677a7e3599a831651806a979c6985d5b942e6d89534c5c6eae14
+  data.tar.gz: 429fb8e7ce09f224c32368ad0d34bc69d1020f56891bdb2616da02acb86fa0ef5c174f340f27fc5a0cdf4918e8a4f82075781128850656b571e0b4232143abf5

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.1.0] - 2026-08-20
+
+The first release.
+
+`Hegel.test` runs a property against libhegel, shrinks a failure to its
+smallest counterexample, reports the values it drew, and re-raises the
+exception the test body itself raised.
+
+Twenty-five generators, composing through `map` and `filter`. A test case can
+discard itself with `assume` and `reject`, leave messages with `note`, and
+steer generation with `target`. A run can be shaped with `phases`,
+`suppress_health_check`, `report_multiple_failures`, `stateful_step_count`,
+and libhegel's example database. Stateful testing runs a `Hegel::StateMachine`
+and shrinks a failing sequence of rules.
+
+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.1.0]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"hegeltest" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at [meganemura@users.noreply.github.com](mailto:meganemura@users.noreply.github.com).

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,264 @@
+# Hegel for Ruby
+
+> [!IMPORTANT]
+> **This is an unofficial, third-party implementation.** The Hegel project and
+> the `libhegel` engine belong to Antithesis, LLC. This repository has no
+> affiliation with Antithesis or with the `hegeldev` organization, and nobody
+> there reviews or endorses it.
+>
+> The official implementations are
+> [Rust](https://github.com/hegeldev/hegel-rust),
+> [Go](https://github.com/hegeldev/hegel-go),
+> [C++](https://github.com/hegeldev/hegel-cpp),
+> [TypeScript](https://github.com/hegeldev/hegel-typescript),
+> [Java](https://github.com/hegeldev/hegel-java), and
+> [OCaml](https://github.com/hegeldev/hegel-ocaml). Report problems with this
+> gem here, not to them.
+
+> [!NOTE]
+> Hegel itself is in beta, and its maintainers expect to make breaking changes.
+> See <https://hegel.dev/compatibility>.
+
+Hegel is a property-based testing framework based on
+[Hypothesis](https://github.com/hypothesisworks/hypothesis). Instead of writing
+tests with hand-picked inputs, you state a property that must hold for every
+input. Hegel generates inputs, tries to falsify the property, and shrinks any
+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.
+
+## Status
+
+**The first release is prepared, and the version is `0.1.0`.** Everything
+described below runs: 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.
+
+**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
+([hegeldev/hegel-rust#411]).
+
+So running this today means cloning the repository:
+
+```bash
+bin/setup
+bundle exec rake libhegel:fetch   # downloads the pinned build, checked against its SHA-256
+bundle exec rake
+```
+
+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.
+
+[hegeldev/hegel-rust#411]: https://github.com/hegeldev/hegel-rust/issues/411
+
+## Design
+
+| 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.3, 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.
+
+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
+`HEGEL_LIBHEGEL_PATH` and a local build.
+
+## Quickstart
+
+Everything below runs today.
+
+```ruby
+# spec/spec_helper.rb
+require "hegel"
+
+RSpec.configure do |config|
+  config.include Hegel::Syntax::Methods
+end
+```
+
+```ruby
+# spec/my_sort_spec.rb
+def my_sort(ls) = ls.sort.uniq # oops: uniq drops duplicates
+
+RSpec.describe "my_sort" do
+  it "matches the builtin sort" do
+    Hegel.test do |tc|
+      xs = tc.draw(arrays(integers))
+      expect(my_sort(xs)).to eq(xs.sort)
+    end
+  end
+end
+```
+
+That test fails, and Hegel shrinks the failure to the smallest input that
+still shows the bug:
+
+```
+Falsified after 11 test cases (0 discarded):
+
+  xs = [0, 0]
+
+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.
+
+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.
+
+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
+once, and write the property inside an ordinary test:
+
+```ruby
+# test/test_helper.rb
+require "hegel"
+
+class Minitest::Test
+  include Hegel::Syntax::Methods
+end
+```
+
+```ruby
+# test/my_sort_test.rb
+class MySortTest < Minitest::Test
+  def test_matches_the_builtin_sort
+    Hegel.test do |tc|
+      xs = tc.draw(arrays(integers))
+      assert_equal xs.sort, my_sort(xs)
+    end
+  end
+end
+```
+
+Minitest reports the shrunk case as its own assertion failure, pointing at
+your line:
+
+```
+1) Failure:
+MySortTest#test_matches_the_builtin_sort [test/my_sort_test.rb:5]:
+Expected: [0, 0]
+  Actual: [0]
+```
+
+### 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
+next, checks your invariants after each one, and shrinks a failure to the
+shortest sequence that still shows it:
+
+```ruby
+class StackMachine < Hegel::StateMachine
+  def initialize
+    @stack = BoundedStack.new(3)
+    @model = []
+  end
+
+  rule :push do |tc|
+    x = tc.draw(integers(min_value: 0, max_value: 9))
+    @stack.push(x)
+    @model.push(x) if @model.size < 3
+  end
+
+  rule :pop do |tc|
+    tc.assume(!@model.empty?)
+    raise "pop disagreed" unless @stack.pop == @model.pop
+  end
+
+  invariant :size_agrees do
+    raise "size disagreed" unless @stack.size == @model.size
+  end
+end
+
+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.
+
+### 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.
+
+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:
+
+```ruby
+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.
+
+Inside a test, `tc.note` records a message the failure report prints, and
+`tc.target` tells Hegel which inputs to search toward.
+
+## Development
+
+```bash
+bin/setup          # install dependencies
+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
+for anyone who already uses `just` with the other Hegel implementations.
+
+## Contributing
+
+Report bugs and open pull requests at
+<https://github.com/meganemura/hegel-ruby>. Contributors follow the
+[code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+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.

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+load File.expand_path("lib/tasks/libhegel.rake", __dir__)
+load File.expand_path("lib/tasks/platform_gems.rake", __dir__)
+
+require "standard/rake"
+
+desc "Run the test suite with coverage measurement enforced at 100%"
+task :coverage do
+  ENV["COVERAGE"] = "1"
+  Rake::Task["test"].invoke
+end
+
+task default: %i[coverage standard]

data/docs/README.md

@@ -0,0 +1,25 @@
+# Documentation
+
+An index of the design records for `hegel-ruby`.
+
+- [architecture.md](architecture.md): the layers between Ruby and
+  libhegel, and the boundary each one draws.
+
+## Architecture Decision Records
+
+- [0001: Bind libhegel through Fiddle](adr/0001-bind-libhegel-through-fiddle.md)
+- [0002: Ship one prebuilt engine per platform-specific gem](adr/0002-ship-one-prebuilt-engine-per-platform-specific-gem.md)
+- [0003: Publish as hegeltest, require as hegel](adr/0003-publish-as-hegeltest-require-as-hegel.md)
+- [0004: Expose generators through a mixin, with keyword options](adr/0004-expose-generators-through-a-mixin-with-keyword-options.md)
+- [0005: Name drawn values from the caller's source with Prism](adr/0005-name-drawn-values-from-the-callers-source-with-prism.md)
+- [0006: Verify the binding in seven layers, with full coverage](adr/0006-verify-the-binding-in-seven-layers-with-full-coverage.md)
+- [0007: Ship a thin Ruby skill, shaped for donation](adr/0007-ship-a-thin-ruby-skill-shaped-for-donation.md)
+- [0008: Revisit the binding after milestone C, on measurement](adr/0008-revisit-the-binding-after-milestone-c-on-measurement.md)
+- [0009: Turn the example database on with a key](adr/0009-turn-the-example-database-on-with-a-key.md)
+- [0010: Declare stateful rules with a class macro](adr/0010-declare-stateful-rules-with-a-class-macro.md)
+- [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)
+
+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/0001-bind-libhegel-through-fiddle.md

@@ -0,0 +1,54 @@
+# 0001: Bind libhegel through Fiddle
+
+## Status
+
+Superseded by [ADR 0013](0013-bind-libhegel-through-the-ffi-gem.md),
+which binds libhegel through the `ffi` gem instead, on the measurement
+[ADR 0008](0008-revisit-the-binding-after-milestone-c-on-measurement.md)
+scheduled.
+
+## Context
+
+libhegel is hegel-rust's native engine, exposed as a C ABI in
+`hegel-c/include/hegel.h`. It runs in the same process as its caller.
+Nearly every function takes a `hegel_context_t*` as its first argument and
+returns a `hegel_result_t` status code.
+
+CRuby needs a way to call that ABI. A C extension can call it directly, but
+building one needs a compiler at gem install time. Fiddle is a library
+bundled with Ruby. It wraps libffi and `dlopen`, so it calls a C function
+by address without compiling anything.
+
+The other implementations bind the same ABI under different constraints.
+The Java implementation drives it through the Foreign Function and Memory
+API. It caches one `MethodHandle` per C symbol, behind a `Libhegel`
+interface; `RealLibhegel` implements that interface in production, and a
+fake implements it in tests. The Go implementation opens the library with
+`dlopen` directly, giving each C symbol a Go func-typed struct field. The
+OCaml implementation binds through `ctypes`, declaring each function with
+`Foreign.foreign` over a handle from `Dl.dlopen`. The C++ implementation
+links the library at compile time and calls its functions directly, with
+no runtime loading step.
+
+## Decision
+
+Bind libhegel through Fiddle (`~> 1.1`). Confine every raw Fiddle call to
+one module, `Hegel::LibHegel`. The rest of the library will call that
+module's wrappers. This matches the way the Java implementation's
+`Libhegel` interface sits between its runner and the raw FFI calls.
+
+## Consequences
+
+Installing the gem needs no compiler and no link step against `hegel.h`.
+The Go binding shares this property: it opens the library at run time
+instead of linking against it.
+
+`Hegel::LibHegel` needs a substitute implementation for testing error-code
+translation without a real engine loaded. The Java implementation's fake
+binding plays that role in its own test suite.
+
+The gem can use only the Fiddle API that ships in Ruby 3.3's bundled
+fiddle, 1.1.2, since that Ruby is the oldest one supported.
+
+Whether `Fiddle::Closure` behaves the same from fiddle 1.1.2 through 1.1.8
+has not been checked yet.

data/docs/adr/0002-ship-one-prebuilt-engine-per-platform-specific-gem.md

@@ -0,0 +1,48 @@
+# 0002: Ship one prebuilt engine per platform-specific gem
+
+## Status
+
+Accepted
+
+## Context
+
+hegel-rust publishes libhegel as GitHub release assets. Release v0.32.5
+carries ten assets: one shared library and one sha256 checksum, for each of
+five platforms (`darwin-arm64`, `linux-amd64`, `linux-arm64`,
+`windows-amd64`, `windows-arm64`).
+
+The other implementations distribute these prebuilt libraries in different
+shapes. The TypeScript implementation publishes one npm package per
+platform, such as `@hegeldev/hegel-linux-x64`, listed as an
+`optionalDependencies` entry so npm installs only the matching one. The Go
+implementation embeds all five binaries into one module, behind
+per-platform `go:embed` build tags. A build for one target links in only
+its own binary. The OCaml implementation's loader can also download the
+matching binary at install or first run, through a `dune` site that a
+release tarball prefills.
+
+RubyGems can build one physical gem per `platform` value declared in a
+gemspec. Bundler and RubyGems then install and require the gem matching the
+local platform automatically.
+
+## Decision
+
+Publish `hegeltest` as five platform-specific gems, one prebuilt libhegel
+bundled in each, following the model the TypeScript implementation's
+per-platform npm packages set.
+
+libhegel resolves in two steps: `HEGEL_LIBHEGEL_PATH`, naming a file or a
+directory that contains one, checked first; the platform gem's bundled
+copy otherwise. The Go, TypeScript, Java, and OCaml implementations all
+check `HEGEL_LIBHEGEL_PATH` before falling back to their own bundled or
+downloaded engine.
+
+## Consequences
+
+No Intel-Mac gem can ship, since v0.32.5's release assets cover five
+platforms and Intel Mac is not one of them. That platform needs
+`HEGEL_LIBHEGEL_PATH` and a local build.
+
+Only the resolution step, `HEGEL_LIBHEGEL_PATH` then the bundled copy,
+depends on how libhegel reaches the gem. The rest of the library calls
+`Hegel::LibHegel` the same way, regardless of where the file came from.

data/docs/adr/0003-publish-as-hegeltest-require-as-hegel.md

@@ -0,0 +1,39 @@
+# 0003: Publish as hegeltest, require as hegel
+
+## Status
+
+Accepted
+
+## Context
+
+hegel-rust's `Cargo.toml` names the package `hegeltest` (`[package] name =
+"hegeltest"`) and the library `hegel` (`[lib] name = "hegel"`). `cargo add
+--dev hegeltest` installs it; source calls `use hegel::...`.
+
+The Go module is `hegel.dev/go/hegel`, imported as package `hegel`. The
+npm package is `@hegeldev/hegel`. The Java artifact is `dev.hegel:hegel`.
+The OCaml package is `hegel`. In each of these four, the published name
+and the code's own name match.
+
+As of 2026-08, neither `hegel` nor `hegeltest` is registered on
+RubyGems.org.
+
+## Decision
+
+Publish the gem as `hegeltest`, matching hegel-rust's crate name. Keep the
+require path and the namespace `hegel` and `Hegel`, matching hegel-rust's
+library name. `lib/hegeltest.rb` exists only to satisfy Bundler's automatic
+require, which is derived from the gem name; it requires `hegel.rb` and
+defines nothing of its own.
+
+## Consequences
+
+`require "hegel"` is the documented form. `require "hegeltest"` also
+works, because Bundler requires a gem automatically under its own name
+when the gem is listed in a Gemfile.
+
+The name `hegel` stays free on RubyGems.org for whoever publishes an
+official Ruby implementation.
+
+A reader who already knows the Rust implementation's naming pattern can
+guess this gem's install name and require path correctly.

data/docs/adr/0004-expose-generators-through-a-mixin-with-keyword-options.md

@@ -0,0 +1,42 @@
+# 0004: Expose generators through a mixin, with keyword options
+
+## Status
+
+Accepted
+
+## Context
+
+FactoryBot, a widely used Ruby test-data library, defines a module,
+`FactoryBot::Syntax::Methods`, holding methods such as `build` and
+`create`. Including it in a test makes those methods callable bare, with
+no `FactoryBot.` prefix. The same methods stay reachable through the
+module's own namespace for a caller who does not include it.
+
+hegel-rust and the Go implementation expose generators as builder-chain
+calls: `gs::integers::<i32>()` in Rust and `hegel.Integers[int](min, max)`
+in Go. Each is followed by chained methods, such as `min_size`, for
+further options. Neither Rust nor Go has native optional keyword
+arguments; Ruby does.
+
+## Decision
+
+Define `Hegel::Syntax::Methods`, a module of generator-constructing
+methods (`integers`, `text`, `arrays`, and so on), matching
+`FactoryBot::Syntax::Methods` in shape. A caller includes it, in an RSpec
+`config.include` or a Minitest test class, to call `integers` and `text`
+bare. The same generators stay reachable as `Hegel::Generators.integers`
+without the include.
+
+Generator options are keyword arguments, not a builder chain:
+`text(min_size: 1, alphabet: "abc")`.
+
+## Consequences
+
+A caller who already uses FactoryBot recognizes the include-a-methods-
+module pattern.
+
+A generator with several options reads as one call, such as
+`text(min_size: 1, max_size: 20)`, instead of a chain of setter calls.
+
+`Hegel::Syntax::Methods`, `Hegel::Generators`, and every generator remain
+to be written; only the naming decision is settled.

data/docs/adr/0005-name-drawn-values-from-the-callers-source-with-prism.md

@@ -0,0 +1,40 @@
+# 0005: Name drawn values from the caller's source with Prism
+
+## Status
+
+Accepted
+
+## Context
+
+A failure report is more useful when each drawn value has a name, instead
+of a position number. hegel-rust's `#[hegel::test]` macro rewrites, at
+compile time, `let x = tc.draw(gen)` inside a test function into `let x =
+tc.__draw_named(gen, "x", repeatable)`, so the failure report can print
+`let x = <value>;`. The Go implementation resolves the caller's source
+position at runtime with `runtime.Caller`, then parses that file with
+`go/ast` to recover the enclosing statement's text.
+
+Ruby has no macros. Prism, Ruby's parser, ships as a default gem starting
+with Ruby 3.3, and can parse a source file into a node tree with source
+locations. Parsing `n = tc.draw(gs.integers)` with Prism yields a
+`Prism::LocalVariableWriteNode` whose `name` is `:n`.
+
+## Decision
+
+Recover a drawn value's name at runtime, by parsing the caller's source
+file with Prism and reading the assignment target at the `draw` call's
+location. This mirrors the Go implementation's runtime-parse approach, in
+a language without Rust's compile-time macros.
+
+A `label:` argument to `draw` overrides the recovered name. When no name
+can be recovered, the value gets a number instead.
+
+## Consequences
+
+Ruby 3.3, the oldest supported Ruby, is also the oldest Ruby that ships
+Prism by default. The two floors were chosen together.
+
+No `draw` call, name recovery, or failure report exists in code yet.
+
+How far this recovery reaches into a heredoc, several `draw` calls on one
+line, or a method chain has not been checked.

data/docs/adr/0006-verify-the-binding-in-seven-layers-with-full-coverage.md

@@ -0,0 +1,51 @@
+# 0006: Verify the binding in seven layers, with full coverage
+
+## Status
+
+Accepted
+
+## Context
+
+hegel-rust's own `tests/` directory separates concerns.
+`tests/test_shrink_quality/` asserts an exact minimal counterexample for a
+given predicate; for example, shrinking a byte pair under a length
+constraint to `vec![0u8; 7]` and `vec![0u8; 8]`. This kind of assertion
+depends on how the engine's shrinker responds to span structure. A missing
+or misplaced span shows up there, as a counterexample larger than the
+minimal one. hegel-rust's own contributor documentation states that every
+invalid combination of builder values must be caught at draw time. It
+also states that a validation message is public API, asserted against by
+tests as a stable substring.
+
+The Java implementation enforces 100% instruction and branch coverage
+through its `jacoco-maven-plugin` configuration, `<minimum>1.00</minimum>`
+for both counters. Its `Libhegel` interface exists so the run loop can be
+tested against `FakeLibhegel`, without a real engine, exercising every
+error code libhegel can return.
+
+## Decision
+
+Verify the binding in seven layers:
+
+1. FFI, against a fake engine.
+2. Library resolution.
+3. Conformance, running every generator against the real engine.
+4. Shrink quality, ported from hegel-rust's `tests/test_shrink_quality`
+   result assertions.
+5. Generation quality, catching option-translation mistakes.
+6. Failure reports: Prism naming, blob replay, output format.
+7. Integration, running the Minitest and RSpec suites end to end.
+
+Enforce 100% line and branch coverage in CI. Ruby's coverage tooling
+counts lines where jacoco counts instructions, so the line counter is
+this project's nearest equivalent to the instruction bar quoted above.
+An excluded file carries a comment stating why.
+
+## Consequences
+
+A missing or misplaced span costs nothing at generation time. It shows up
+as a larger-than-minimal counterexample, the property the shrink-quality
+layer asserts against.
+
+Layer two, library resolution, is written and covered. The other six
+follow the code they test, so they arrive with it.