hegeltest 0.1.0

data/docs/adr/0007-ship-a-thin-ruby-skill-shaped-for-donation.md

@@ -0,0 +1,56 @@
+# 0007: Ship a thin Ruby skill, shaped for donation
+
+## Status
+
+Accepted. The content arrives once milestone A lands a user-facing API.
+
+## Context
+
+The Hegel maintainers publish [hegel-skill](https://github.com/hegeldev/hegel-skill),
+a Claude Code plugin that teaches agents to write property-based tests. Its
+`skills/hegel/SKILL.md` carries language-agnostic methodology: how to find a
+property worth testing, how to keep a generator from being over-constrained,
+and a catalogue of property patterns. Step 1 of its workflow reads "load the
+corresponding reference from `references/<language>/reference.md`".
+
+That directory holds one subdirectory per language, and the front matter names
+the set: Rust, Go, C++, TypeScript, Java, and OCaml. Each language contributes
+two files. `reference.md` documents that language's API: setup, test
+structure, settings, `TestCase` methods, every generator, the combinator
+methods, composite generators, and gotchas. `porting.md` maps another
+property-testing library onto Hegel; the TypeScript one covers fast-check,
+jsverify, and testcheck-js.
+
+Ruby has its own property-testing libraries. By RubyGems download count they
+run rantly, prop_check, rubycheck, pbt, and propr.
+
+Two shapes were available. A self-contained skill would copy hegel-skill's
+methodology, which is MIT licensed, so that one install covers everything. A
+thin skill carries only the Ruby half.
+
+## Decision
+
+Publish `skills/hegel-ruby/` holding a thin `SKILL.md` alongside
+`references/ruby/reference.md` and `references/ruby/porting.md`, written in
+the same shape hegel-skill uses for its six languages. The methodology stays
+where its authors maintain it.
+
+Write the content when milestone A lands `Hegel.test` and the first
+generators, and grow it as each later generator arrives. A reference that
+documents an API nobody has built yet records a guess.
+
+Distribute it two ways. The gem already packages `skills/`, the way the
+rubydex gem packages its own. A `.claude-plugin/` manifest makes the same
+directory installable through the Claude Code marketplace.
+
+## Consequences
+
+Somebody who installs this skill alone gets the Ruby API and reaches
+hegel-skill for the methodology. The `SKILL.md` says so.
+
+The two reference files sit in the layout hegel-skill expects, so they can
+move upstream unchanged if the Hegel maintainers ever want a Ruby entry.
+
+A generator is finished when its entry in `reference.md` exists, which puts
+the documentation next to the code that motivates it rather than at the end
+of the milestone.

data/docs/adr/0008-revisit-the-binding-after-milestone-c-on-measurement.md

@@ -0,0 +1,81 @@
+# 0008: Revisit the binding after milestone C, on measurement
+
+## Status
+
+Accepted, and carried out.
+[ADR 0013](0013-bind-libhegel-through-the-ffi-gem.md)
+records the measurement this scheduled and the decision it produced.
+
+## Context
+
+[ADR 0001](0001-bind-libhegel-through-fiddle.md) chose Fiddle over the `ffi`
+gem, on the reading that Fiddle adds no third-party runtime dependency while
+both avoid a compiler at install time. Building against it has since produced
+evidence that decision could not have had.
+
+**Fiddle has no struct-by-value argument.** `Fiddle::Function` converts each
+argument type with `NUM2INT`, so a struct type cannot be expressed. Three ABI
+draws take their bounds that way. They are reached by packing an eight-byte
+all-integer struct into the register the ABI would have used for it, which is
+sound for those three and is not a general technique: it puts the ABI
+classification in this gem's own code, duplicates field offsets by hand,
+cannot follow a struct holding a float, cannot express a struct return, and
+diverges on Win64 for the sixteen-byte case. `ffi` has `FFI::Struct.by_value`
+and lets libffi classify.
+
+**Fiddle::Closure is still unverified here.** The engine's output callback is
+passed as NULL, which the ABI documents as leaving output on stderr, so
+nothing depends on the closure yet. Wiring the callback would put weight on a
+Fiddle feature this project has never exercised across the fiddle versions
+Ruby 3.3 through 4.0 ship.
+
+**Ruby implementations.** `ffi` runs on JRuby and TruffleRuby; the Fiddle
+choice scoped this gem to CRuby.
+
+Against that: `ffi` is a runtime dependency, and this project's dependency
+rule asks for a reason and an explicit decision before one is added.
+
+None of the above is about speed, and speed is what a property-based testing
+library spends. A run configured for twenty test cases was measured making
+over a thousand iterations while shrinking, each with its own draws, so the
+per-call cost of the binding is multiplied by a large and unpredictable
+factor.
+
+## Decision
+
+Measure the two bindings against each other once milestone C is complete, and
+choose on the result.
+
+Measure a realistic property run, not a microbenchmark: a failing property
+over `arrays(integers)` that shrinks, which is the shape that multiplies
+per-call cost, plus a passing run of the same size for the no-shrink case.
+Report wall-clock for each binding on the same machine, same engine build,
+same seed, with the database disabled.
+
+Library load time is measured too and reported separately. It happens once
+per process and should not be added to the per-call figure.
+
+A difference that shows on that run decides it. A difference visible only in
+a tight loop around one native call does not: this gem's callers pay the
+former and never the latter.
+
+Milestone C is the trigger because it adds the last of the binding surface:
+the example database, targeted testing, stateful testing, and pools. A
+measurement taken before it would cover a fraction of the calls, and a
+rewrite after it would be smaller than one before.
+
+## Consequences
+
+The binding stays Fiddle through milestones B and C, and the packing
+technique carries the three struct-taking draws until then.
+
+A switch stays cheap because of the seam: `Hegel::LibHegel::Real` is the only
+file that names Fiddle, and a conformance test already holds both it and the
+Fake to one method list. The cost is confined to that file, the gemspec,
+and this record's supersession. The twenty-odd files built on top of the
+seam do not need to change.
+
+If the measurement favours `ffi`, adding it is still a dependency decision
+under this project's own rule, and the reason recorded here is the argument
+that decision would weigh: not `ffi` alone, but `ffi` together with
+struct-by-value, an exercised closure, and JRuby and TruffleRuby.

data/docs/adr/0009-turn-the-example-database-on-with-a-key.md

@@ -0,0 +1,89 @@
+# 0009: Turn the example database on with a key
+
+## Status
+
+Accepted. It replaces the interim rule that every run disables the example
+database, which stood while milestone C was still deciding this.
+
+## Context
+
+libhegel can store a failing test case and replay it first on the next run.
+Three settings govern it: `hegel_settings_set_database` chooses a directory
+(NULL leaves the default `./.hegel/examples/`, `""` disables storage
+entirely), `hegel_settings_set_database_key` scopes what a run stores and
+replays, and the engine turns the whole feature off by itself under CI.
+
+Until now every `Hegel.test` call passed `""`, because a run that left the
+default in place looked like it would write into a contributor's working
+copy and nowhere else. That is the hardest version of that mistake to
+notice.
+
+Measurement against 0.32.5 shows the hazard is narrower than that. A run
+with the path left at its default and **no key set** wrote nothing at all:
+no `./.hegel/`, under that name or any other, in a fresh empty directory,
+across two runs of a property that did find and report a failure. The same
+run with `hegel_settings_set_database_key(ctx, s, "probe")` produced
+`.hegel/examples/` with three hash directories and twenty-nine files, and a
+second run in that directory replayed the stored failure as its first and
+only test case. A third run with a different key behaved like a fresh
+search.
+
+So the key, not the path, is what makes the database do anything.
+`hegel_settings_set_database_key`'s own header entry describes NULL as
+clearing the key. What a cleared key does to storage is what the measurement
+above supplies.
+
+The two implementations that ship this feature both leave the path at the
+engine default and get a key from a name they already have: hegel-go passes
+Go's own `t.Name()`, and hegel-java passes the `name` its `Settings` carries.
+`Hegel.test` has no such name. It is a bare method call, not a named test,
+so Ruby has nothing to key a run by unless the caller supplies one.
+
+## Decision
+
+`Hegel.test` gains two keywords.
+
+`database_key:` is the switch. Given a String, the run stores and replays
+examples under that key. Left nil, which is the default, the run passes `""`
+to `hegel_settings_set_database` and stores nothing.
+
+`database:` chooses the directory, and only means something alongside a key.
+Given a String, the run uses that directory. Left nil, a keyed run leaves the
+engine's own default in place, which is `./.hegel/examples/` outside CI and
+disabled inside it. Given without `database_key:`, it raises `Hegel::Error`
+rather than silently storing nothing.
+
+Disabling explicitly rather than relying on the measurement above is
+deliberate. "No key means nothing is written" is behaviour this project
+measured, not behaviour the ABI promises, and the cost of being wrong is
+directories appearing in working copies that never asked for them. Passing
+`""` costs one call per run and depends on a documented sentence instead.
+
+CI detection stays the engine's. hegel-go and hegel-java each run their own
+check of the same environment variables; here, a run reaching the engine
+default in CI is already disabled by the engine, and a run passing an
+explicit path means the caller asked for that path.
+
+## Consequences
+
+An unkeyed run behaves exactly as every run behaved before this record, so
+the change is invisible to a caller who does not ask for it.
+
+A caller who wants replay writes the key themselves:
+
+```ruby
+Hegel.test(database_key: "sorting is idempotent") { |tc| ... }
+```
+
+That is more typing than hegel-go or hegel-java need, and the difference is
+the name those two already have. A future integration that knows the
+enclosing test's name, such as a Minitest or RSpec adapter, can supply the
+key from it and close the gap. Nothing here forecloses that, because the
+keyword takes any String.
+
+Keying by hand also means two properties can collide by being given the same
+key, which a name derived from a test could not do. The header describes the
+key as what scopes stored and replayed examples, so two properties sharing a
+key share one scope; what the engine then does with a case stored by one and
+replayed against the other has not been measured here. The keyword's
+documentation says to make the key unique, and this is the reason.

data/docs/adr/0010-declare-stateful-rules-with-a-class-macro.md

@@ -0,0 +1,113 @@
+# 0010: Declare stateful rules with a class macro
+
+## Status
+
+Accepted.
+
+## Context
+
+A stateful test hands libhegel a list of rule names, then runs whichever rule
+the engine picks, step after step, until the engine says the test case's step
+budget is spent. The engine owns the choice and the shrinking. What a binding
+decides is how its own users write the rules.
+
+The four implementations that ship this each answered in their own language's
+terms. hegel-rust's `StateMachine` trait returns `Vec<Rule<Self>>` from
+`rules()`, and hegel-cpp does the same from a virtual `rules()`. hegel-go
+finds methods by reflection, taking every method whose name begins with `Rule`
+or `Invariant`. hegel-ocaml takes rules as a list argument to `Stateful.run`,
+each built by `Rule.create ~name ~step`. All four then run the machine from
+inside an ordinary test body rather than from a separate entry point.
+
+Ruby has two idioms that fit, and they point at different answers. Minitest
+finds tests by their `test_` prefix, which is hegel-go's shape. RSpec, Rake,
+and ActiveRecord register work through class-level macros taking blocks, which
+is closer to hegel-rust's explicit list. Being Ruby-like does not decide it.
+
+What decides it is what happens to a mistake. Under prefix discovery, a rule
+written `rules_push` instead of `rule_push` is not a rule. Nothing raises, the
+machine runs with one fewer action, and the test passes: the suite reports
+that a behaviour holds when the behaviour was never exercised. hegel-go keeps
+that from happening by rejecting a method that takes a `TestCase` without the
+prefix. In Ruby the same guard means reading parameter lists to infer intent,
+where a declared name raises on the spot.
+
+Writing all three shapes out inside a real Minitest file surfaced a second
+difference that the shapes alone did not. Rules want their framework's
+assertions. A machine written as its own class reaches neither the generator
+methods nor `assert_equal` without saying so, because `Hegel::Syntax::Methods`
+was included into `Minitest::Test` and the machine is not one.
+
+## Decision
+
+A machine is a class that inherits `Hegel::StateMachine` and declares its
+rules and invariants with class-level macros:
+
+```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) }
+```
+
+Each block runs against the machine instance, so a rule reads and writes
+instance variables like any method. Both macros pass the test case to the
+block; an invariant that does not want it declares no parameter, since a Ruby
+block ignores arguments it does not name.
+
+`Hegel::StateMachine` includes `Hegel::Syntax::Methods`, so a generator is
+callable inside a rule without the machine repeating the include its test
+class already has.
+
+Declaring the same name twice in one class raises `Hegel::Error`. A subclass
+declaring an inherited name replaces it, the way a redefined method does.
+Silently keeping the last of two same-named rules would reintroduce exactly
+the disappearing-rule failure this record exists to avoid, while a subclass
+overriding one is the ordinary reason to write the name again.
+
+`Hegel::Stateful.run(machine, tc)` runs it from inside an ordinary `Hegel.test`
+body, as all four sibling implementations do. Nothing about a stateful test
+takes over the run, so a body can draw values before or after running a
+machine.
+
+## Consequences
+
+The typo that a Ruby prefix convention would swallow now raises. `rule :psuh`
+registers a rule named `psuh`, the engine picks it, and the call fails on
+whatever the block does. A `rule_` prefix over Ruby methods has no such
+moment, because the misspelled method is simply not a rule. hegel-go closes
+that gap in its own language, by rejecting a method that takes a `TestCase`
+without the prefix.
+
+The machine still has to reach its framework's assertions itself, with
+`include Minitest::Assertions` or the RSpec equivalent, and that boilerplate
+is real. This library does not include either one for a caller: it takes no
+test framework as a dependency, and guessing which one is loaded would make
+the base class behave differently depending on load order. A rule can also
+just `raise`, which needs nothing, and the examples here do.
+
+Rules registered on a class, rather than found on an instance, means a
+machine built some other way has no supported path. That other way could
+be rules assembled at run time, or a machine that is not a class. Nothing
+here forecloses adding one; the engine only ever receives a list of names
+and a way to invoke each, which a later record can decide how else to
+supply.

data/docs/adr/0011-let-the-test-case-own-every-pool-drawn-from-it.md

@@ -0,0 +1,83 @@
+# 0011: Let the test case own every pool drawn from it
+
+## Status
+
+Accepted. It builds on
+[ADR 0010](0010-declare-stateful-rules-with-a-class-macro.md), which decided
+how a state machine declares its rules.
+
+## Context
+
+A pool lets one rule act on a value an earlier rule produced. Without it, a
+rule that frees a resource can only draw an arbitrary integer, and almost none
+of those name a resource anything created. The engine tracks the pool as a set
+of variable ids, chooses which id a draw returns, and shrinks that choice; the
+caller keeps its own map from id to the value it generated.
+
+`hegel_new_pool` hands back a handle that `hegel_pool_free` releases, and, like
+every other free in this ABI, that call takes the context. So the context has
+to outlive the pool. This project already answered the general form of that
+question: release handles in an `ensure` in the code that owns the run, because
+Ruby's garbage collector gives finalizer ordering no guarantee worth relying
+on.
+
+The difficulty is that a pool is created by the caller's own code, inside a
+rule, and that code has no `ensure` wrapped around the run. Whoever writes
+`Pool.new` is not in a position to free it.
+
+hegel-ocaml, the other binding whose language collects garbage on its own
+schedule, answers this by registering each pool on the test case that created
+it and freeing them all when that case completes (`lib/internal.ml`,
+`new_pool` and `free_owned_pools`). That is the same shape this library already
+uses for the test-case handle itself.
+
+## Decision
+
+`Hegel::Stateful::Pool.new(tc)` creates a pool. The `Hegel::TestCase` records
+every pool created from it, and `Hegel::Runner` frees them in the same `ensure`
+that already frees the test-case handle, before that handle goes.
+
+A finalizer backs nothing up here. The standing constraint allows one as a
+backstop against a leak, but it must do nothing when the handle is already
+free, and the three places that free a test case all run their `ensure` on
+every path including a fatal exception. Adding a finalizer would add a second
+owner for no case the first one misses.
+
+A pool draws from the test case, so it must be built during one. The natural
+place is the machine's own constructor, with the test case passed in from the
+block that has it:
+
+```ruby
+Hegel.test { |tc| Hegel::Stateful.run(ResourceMachine.new(tc), tc) }
+```
+
+`Pool#add` records a value against a fresh variable id. Drawing goes through
+two generators, not through the pool directly: `values_reusable` yields a
+value and leaves it in the pool, `values_consumed` removes the value it
+yields. Both are drawn with `tc.draw`, so the chosen value is named in the
+failure report and its choice shrinks like any other draw. hegel-rust says
+the same of its own two in `src/stateful.rs`, and this record follows
+hegel-rust on meaning. hegel-ocaml builds its two the same way, as generators
+(`Make_pool.pool_values` in `lib/generators_core.ml`). Those generators carry
+no printer, so the choice shrinks like any other draw and the report leaves it
+unnamed.
+
+Drawing from an empty pool raises `Hegel::AssumeFailed`, translated from the
+engine's own `HEGEL_E_ASSUME` by the existing result-code check. Inside a rule
+that rejects the rule and the loop draws another, which is exactly what a rule
+that frees a resource should do when nothing has been allocated yet.
+
+## Consequences
+
+A caller never frees a pool, and cannot leak one by forgetting to.
+
+A caller also cannot outlive a pool past its test case on purpose. Holding one
+in an instance variable and reusing it on the next case would reach a freed
+handle; the machine is rebuilt per case for the same reason the model state is,
+so the ordinary way of writing one does not run into this.
+
+The engine records a pool draw as the chosen variable id rather than as an
+index into the pool's current contents, so shrinking away an earlier `add`
+never changes which variable a recorded choice refers to. The Ruby-side map
+follows from that for free: an `add` that shrinks away never runs, so its id is
+never in the map, and no draw can return it.

data/docs/adr/0012-build-a-failure-origin-from-the-callers-own-frame.md

@@ -0,0 +1,72 @@
+# 0012: Build a failure origin from the caller's own frame
+
+## Status
+
+Accepted.
+
+## Context
+
+libhegel groups failures by the origin string a caller passes to
+`hegel_mark_complete`. The header is explicit: two failures with identical
+origins are the same bug and get shrunk together, and each new origin is a new
+bug. So the origin decides both how many failures a run reports and which
+failures the shrinker minimises as one.
+
+`Hegel::Runner.origin_for` built that string from the exception's first
+backtrace frame. For a `raise` written in the caller's own test body, that is
+the right line. For an assertion, it is not, because an assertion library
+raises from inside itself. Measured against minitest 5.27.0 and
+rspec-expectations 3.13.5:
+
+```
+assert_equal 0, 1   ->  Raised at .../minitest-5.27.0/lib/minitest/assertions.rb:176
+expect(1).to eq(0)  ->  Raised at .../rspec-support-3.13.7/lib/rspec/support.rb:110
+```
+
+Those two lines do not vary. Every failing assertion in a suite produced the
+same origin as every other one, whichever property raised it and whichever
+line the caller wrote. libhegel therefore saw one bug where there were
+several, and shrank them together.
+
+This gem exists to be driven from RSpec and Minitest, so that is not an edge
+case; it is the ordinary path.
+
+hegel-rust answers this at compile time: Rust's assertion macros expand at the
+call site, so a panic already carries the caller's own location. hegel-java
+meets the same problem this gem meets, and answers it in
+`Runner.originOf` by walking the stack for the first frame that is not
+infrastructure, where infrastructure is a list of class-name prefixes: its
+own package, JUnit, opentest4j, and the JDK.
+
+## Decision
+
+Build the origin from the first backtrace frame that belongs to neither this
+library, nor an installed gem, nor Ruby's own standard library. Keep the
+exception's class out of it, as before.
+
+Identifying infrastructure by location rather than by name is where this
+departs from hegel-java. A name list needs an entry per framework, and this
+gem is driven from frameworks it does not enumerate. Ruby offers location as
+a handle that a name list does not need: Bundler installs a framework under a
+gem directory and loads a caller's own `path:` or `git:` code from the working
+copy, so one rule reaches every framework.
+
+When every frame is filtered out, the first frame is used after all. An origin
+that is merely coarse still groups consistently, where no origin at all would
+lose the failure's identity entirely.
+
+## Consequences
+
+Two failures raised from one line in a caller's own code stay one bug. That is
+the intended behaviour. A ternary that raises two different messages is one
+line and one origin, and splitting it across an `if`/`else` is what makes it
+two.
+
+A caller whose code under test is itself an installed gem now gets their own
+test line as the origin, rather than the line inside that gem. Two distinct
+bugs in one installed dependency therefore group as one if the caller reaches
+them from a single line. Distinguishing them is the caller's own to do, by
+calling from separate lines, and the shrinker still reports the failure.
+
+The origin string holds an absolute path, so it differs between machines. That
+costs nothing: libhegel compares origins only within a single run.

data/docs/adr/0013-bind-libhegel-through-the-ffi-gem.md

@@ -0,0 +1,102 @@
+# 0013: Bind libhegel through the ffi gem
+
+## Status
+
+Accepted. Supersedes
+[ADR 0001](0001-bind-libhegel-through-fiddle.md), and carries out the
+measurement [ADR 0008](0008-revisit-the-binding-after-milestone-c-on-measurement.md)
+scheduled for the end of milestone C.
+
+## Context
+
+ADR 0001 chose Fiddle over the `ffi` gem, on two grounds: Fiddle ships with
+Ruby, so it adds no third-party runtime dependency, and neither one needs a
+compiler at install time. ADR 0008 then recorded three things that building
+against Fiddle had since shown: no struct-by-value argument, an unexercised
+`Fiddle::Closure`, and no JRuby or TruffleRuby. It scheduled a measurement
+rather than deciding on them, because none of those is about speed, and speed
+is what a property-based testing library spends.
+
+The whole binding surface exists now, so the measurement ran. An `ffi`
+implementation of `Hegel::LibHegel` was written for the calls a failing
+`arrays(integers)` property reaches, and checked against the Fiddle one before
+anything was timed: same property, same seed, both bindings. The body call
+count, every drawn value, the raised message, the failure report, and the
+reproduction blob all matched. The two answer identically, so their times are
+comparable.
+
+Measured on Ruby 4.0.6, arm64-darwin, libhegel 0.32.5, `test_cases: 500`, same
+seed, twelve reps, minimum of each:
+
+| property | fiddle | ffi | ratio |
+|---|---|---|---|
+| 800-element fixed-length array, shrinking | 2140 ms | 727 ms | 2.9x |
+| plain `arrays(integers)`, passing | 17.6 ms | 6.6 ms | 2.7x |
+| plain `arrays(integers)`, shrinking | 3.4 ms | 2.0 ms | 1.7x |
+
+The ratio varies with how many native calls a property makes per case, which
+is what the first row exaggerates on purpose and the other two do not. The
+direction does not vary. ADR 0008 asked for a difference visible on a
+realistic property run rather than in a tight loop around one call, and 1.7x
+to 2.9x on whole-run wall clock is that.
+
+Two of ADR 0008's three non-speed items settled the same way. `FFI::Struct`
+with `.by_value` expresses `hegel_date_t`, `hegel_time_t`, and
+`hegel_datetime_t` directly, and a degenerate draw with every field distinct
+round-tripped exactly for all three. The Fiddle binding, by contrast, packs
+those structs into integer registers by hand, and its sixteen-byte case has
+stayed unverified on Win64, since that ABI passes anything over eight bytes
+by reference. An `FFI::Function` connected to `hegel_run_start`'s output
+callback, the run completed, and six lines of engine output arrived in Ruby;
+the Fiddle binding passes NULL there and has never exercised
+`Fiddle::Closure`.
+
+The third, JRuby and TruffleRuby, was not measured: neither is installed here.
+`ffi` publishes a `java` platform build, and this remains a claim about
+packaging rather than something this project has run.
+
+Against all of that, `ffi` is a third-party runtime dependency. Two facts
+narrow the gap ADR 0001 saw. Fiddle became a bundled gem rather than a default
+one, so `hegeltest.gemspec` already declares `fiddle` as a dependency. The
+change is which binding gem is declared, not whether one is. And `ffi` 1.17.4
+publishes precompiled binary gems for every platform this gem targets:
+`x86_64-linux-gnu`, `aarch64-linux-gnu`, both `-musl` variants, `arm64-darwin`,
+`x86_64-darwin`, `x64-mingw-ucrt`, `aarch64-mingw-ucrt`, and `java`. Installing
+still needs no compiler.
+
+## Decision
+
+Bind libhegel through the `ffi` gem. `Hegel::LibHegel::Real` is written
+against `ffi` alone, with nothing left over from the Fiddle binding: the
+hand-packed date, time, and datetime structs become `FFI::Struct` definitions
+passed by value, and the tests that pinned those packings by field offset go
+with them, because `ffi` is what computes the layout now.
+
+Every raw binding call stays confined to that one file, as ADR 0001 decided
+and this record keeps. That confinement is why this switch costs one file
+rather than twenty: the conformance test holds `Real` and the Fake to a single
+method list, and every other file in the library talks to that list.
+
+The gemspec declares `ffi` with a pessimistic constraint, and `Gemfile.lock`
+pins the exact version, matching how this project already handles a
+dependency.
+
+## Consequences
+
+The struct-by-value entry in this project's open questions closes. There is no
+longer a hand-computed field offset to drift from the header, and no Win64
+divergence to confirm, because libffi classifies the argument.
+
+The `Fiddle::Closure` open question closes too, by no longer being about
+anything: nothing in this library uses Fiddle. Wiring the engine's output
+callback is now possible rather than merely plausible, though this record does
+not wire it. Output stays on stderr until something asks for it.
+
+`ffi` reaches JRuby and TruffleRuby where Fiddle did not. That widening is
+untested here, and naming it in a release note before someone has run the
+suite on either would claim more than has been shown.
+
+A caller now installs a gem with a native component. `ffi` publishes builds
+for the platforms above, so the ordinary install compiles nothing; a platform
+outside that list falls back to compiling `ffi` from source, which the Fiddle
+binding never asked of anyone.