hegeltest 0.3.4 → 0.4.0

data/docs/adr/0029-keep-notes-local-and-defer-run-error-kinds.md

@@ -0,0 +1,72 @@
+# 0029: Keep notes local, and defer run error kinds
+
+## Status
+
+Accepted. It records two calls that libhegel 0.47.2 offers and this gem does
+not bind into its public surface. Each is a decision to wait, with the
+condition that ends the wait.
+
+## Context
+
+`hegel_note` and `hegel_test_case_printer` both write to the document that
+the engine keeps for each test case. `hegel_test_case_printer` fetches a
+handle onto the test-case handle's print region. `hegel_note` appends a
+string to the same region, one output line for each line of the note, and
+the header says that notes and drawn values from one handle appear in the
+order they were appended. The document stays readable after
+`hegel_mark_complete`, so a client can assemble its output while drawing and
+read it back afterwards.
+
+`hegel_run_result_error_kind` reports why a run ended in
+`HEGEL_RUN_STATUS_ERROR`: a failed health check, which it names as a
+`hegel_health_check_t` value, a flaky or nondeterministic test, an
+unsatisfiable one, a misuse of libhegel at run scope, or an internal
+invariant. The header says the message from `hegel_run_result_error` is for
+people, and that a binding should choose which error to raise from the kind
+without parsing the message.
+
+`TestCase#note` records `[:note, message]` in the same entry list that
+`TestCase#record_draw` fills with `[:draw, name, value]`, and
+`Hegel::Report` renders both from that list when it assembles the failure
+report. This gem never opens the engine's printer, so the engine's document
+holds nothing.
+
+`Hegel::Runner` reads a run's error through `hegel_run_result_error` alone
+and raises `Hegel::Error` with that message. hegel-rust declares
+`hegel_run_result_error_kind` in its generated bindings,
+`frontends/rust/src/ffi/sys/fns.rs` and `frontends/rust/src/ffi/sys/types.rs`,
+and its safe wrapper in `frontends/rust/src/ffi.rs` reads a run's error
+through the message, with `hegel_run_result_error`.
+
+## Decision
+
+**`TestCase#note` stays on the Ruby side.** `hegel_note` writes into the
+engine's print document, and that document is only worth reading when the
+draws are written there too, through `hegel_test_case_printer`. Moving the
+notes alone would take them out of the entry list that `Hegel::Report`
+renders, so they would vanish from the report. It would also split the
+ordering the header promises, because a note in the engine's document and a
+draw in the Ruby list have no shared sequence. The two move together, when
+this gem adopts the printer for draws.
+
+**`hegel_run_result_error_kind` is not bound.** hegel-rust's frontend takes a
+run's error as a message, so a classified `Hegel::Error`, one subclass for a failed
+health check and another for an unsatisfiable run, would be a feature that
+this gem alone has. ADR 0015 calls that a divergence. The route is a
+proposal at hegeldev/hegel: if the shared interface settles on classified
+run errors, this gem takes the names and the semantics that were settled
+on, and binds the call then.
+
+## Consequences
+
+A note keeps its present cost: one entry in a Ruby array, in the cases that
+record.
+
+A caller who needs to tell a failed health check from an unsatisfiable run
+reads the message of the `Hegel::Error`, as before. The message wording may
+change between engine releases, and the header says so; that is the cost of
+waiting for the shared interface.
+
+Revisit the first decision together with the adoption of
+`hegel_test_case_printer`, and the second when hegeldev/hegel settles on
+classified run errors.

data/docs/adr/0030-represent-a-duration-as-integer-nanoseconds.md

@@ -0,0 +1,48 @@
+# 0030: Represent a duration as Integer nanoseconds
+
+## Status
+
+Accepted.
+
+## Context
+
+hegel-rust draws a `std::time::Duration` from `durations()`, by drawing a
+`u64` of nanoseconds and converting it. The largest duration it can
+generate is `u64::MAX` nanoseconds, about 584 years. `max_value` saturates
+at that limit, and a `min_value` above it is a usage error at draw time,
+because no generatable value could satisfy it.
+
+Ruby has no duration type in its standard library. The nearest things are
+a `Float` count of seconds, which is what `Time#-` and
+`Process.clock_gettime` return by default, a `Rational` count of seconds,
+and `ActiveSupport::Duration`, which is not part of Ruby. The engine draws
+a nanosecond count as an integer, and `integers` already routes a bound
+above int64 to `hegel_generate_integer_big`.
+
+## Decision
+
+`durations(min_value: 0, max_value: 2**64 - 1)` returns an `Integer` count
+of nanoseconds, drawn through `integers`. Its bounds are nanoseconds too.
+
+An `Integer` is exact over the whole range, where a `Float` of seconds
+loses nanoseconds past about 104 days, and a property that compares two
+durations stays free of rounding. It composes with
+`Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`, the one
+way Ruby reads elapsed time without converting. Under a `Rational` of
+seconds a caller needs a conversion before every use as a sleep or a
+timeout, and the shrunk value reads as a fraction.
+
+The validation follows hegel-rust. `max_value` saturates at `2**64 - 1`.
+A `min_value` above it raises with hegel-rust's wording, and so does
+`max_value < min_value`. A negative `min_value` raises as well. Rust's
+unsigned type cannot hold one, so its message has no Rust counterpart.
+
+## Consequences
+
+A caller who wants a `Float` of seconds divides by `1_000_000_000.0`. A
+change to the unit or the type belongs upstream first, as
+[ADR 0015](0015-follow-the-hegeldev-interface-and-take-changes-upstream-first.md)
+requires. The unit differs from `times` and `datetimes`, which keep
+microseconds, per [ADR 0022](0022-keep-microsecond-times-over-a-nanosecond-engine.md):
+those return a formatted String or a `Time`, and a duration is a bare
+number with nothing to format.

data/docs/adr/0031-take-the-alphabet-options-from-hegel-rust.md

@@ -0,0 +1,52 @@
+# 0031: Take the alphabet options from hegel-rust
+
+## Status
+
+Accepted.
+
+## Context
+
+`text` and `characters` took `codec:`, `min_codepoint:`, and
+`max_codepoint:`, and `from_regex` took no alphabet. hegel-rust's
+`text()` and `characters()` also take `categories`, `exclude_categories`,
+`include_characters`, and `exclude_characters`. `text()` takes `alphabet`,
+and `from_regex()` takes `alphabet`. ADR 0015 makes the shared interface
+the target for names, defaults, and meaning.
+
+hegel-rust differs from what a Ruby caller might expect in three places.
+
+- `alphabet` on `text()` is a string of characters, and `alphabet` on
+  `from_regex()` is a `characters()` generator.
+- When `categories` is given, `exclude_categories` is dropped.
+- It rejects the categories `Cs` and `C`, because a Rust string cannot hold
+  a surrogate, and it adds `Cs` to the exclusions otherwise. `hegel.h`
+  already says that surrogates are always removed from a text generator.
+
+## Decision
+
+The options carry hegel-rust's names and meanings. A `String` alphabet on
+`text` is what hegel-rust's `alphabet(&str)` is: no categories, with the
+string as `include_characters`. A value that is not a `String` raises at draw
+time, since Ruby has no type to make the case unrepresentable. `from_regex`
+takes a `characters` generator, as hegel-rust does.
+
+`categories` wins over `exclude_categories`, as in hegel-rust. `Cs` and `C`
+are rejected in `categories`. `Cs` is not added to the exclusions, since the
+engine removes surrogates itself and a handle is built on every draw.
+
+An unknown codec is rejected in Ruby with hegel-rust's message, at draw time
+as ADR 0015 and `CLAUDE.md` require of every validation. The other
+constraints that leave no characters are the engine's to report, as in
+hegel-rust.
+
+`from_regex` builds its alphabet as a text handle sized 0 to 0, as hegel-rust
+does, so an empty alphabet builds and the engine decides whether the pattern
+can still match. The handle is built on each draw and freed after the regex
+handle made from it, like the handle `text` builds.
+
+## Consequences
+
+An alphabet handle is one more native construction on each `from_regex`
+draw. Measured against libhegel 0.47.2 over 5000 draws, `from_regex` took
+about 35 microseconds a draw without an alphabet and 47 with one, and
+`text(max_size: 5)` took about 31 without categories and 51 with two.

data/docs/adr/0032-suppress-span-closes-while-an-abandoned-recursion-attempt-unwinds.md

@@ -0,0 +1,147 @@
+# 0032: Suppress span closes while an abandoned recursion attempt unwinds
+
+## Status
+
+Accepted.
+
+## Context
+
+libhegel 0.47.2 draws a recursively defined value, such as a tree, through a
+recursion handle: `hegel_new_recursion`, then `hegel_recursion_branch` for
+each sub-value, `hegel_recursion_leaf` before each leaf, and
+`hegel_recursion_finish` once the root is complete. The engine owns the
+branch probabilities and the depth and leaf budgets, so a recursive value is
+distributed the same way in every frontend.
+
+An attempt can outgrow its leaf budget. `hegel_recursion_leaf` then answers
+`HEGEL_E_RETRY`, and `hegel.h` asks the caller to unwind out of its
+generators "without drawing anything further", back to where it called
+`hegel_new_recursion`, and to call `hegel_recursion_retry`. The retry closes
+the spans the attempt left open and marks them discarded:
+`libhegel/src/native/draws/mod.rs` records the span depth when the
+recursion starts, and `recursion_retry` stops spans with `discard` set until
+the depth is back there. After `RECURSION_MAX_ATTEMPTS`, 9, the retry
+answers `HEGEL_E_ASSUME` and the test case is invalid. `hegel_recursion_finish`
+can answer `HEGEL_E_RETRY` as well, when the finished value was mispriced;
+the engine has then discarded the attempt itself, and the caller draws
+again from the root without calling the retry.
+
+hegel-rust unwinds with a panic (`frontends/rust/src/generators/recursive.rs`).
+Its `draw_silent` closes a span only when the draw returns, so a panic
+sends no `stop_span`, and the spans the attempt opened are still open when
+the retry discards them.
+
+Every compound generator in this gem closes its span in `ensure`. An
+exception unwinding through them sends `stop_span(discard: false)` for each
+span the abandoned attempt opened, and `discard: true` from a `filter`. By
+the time the retry runs, those spans are closed and kept, and it finds
+nothing above the recursion's depth to discard.
+
+## Decision
+
+`Hegel::TestCase#recursion_leaf` raises `Hegel::LeafBudgetExceeded` when the
+leaf answers `HEGEL_E_RETRY`, and the test case keeps that exception until
+`#recursion_retry`. While it holds it:
+
+- `#stop_span` makes no native call, so the retry discards the spans the
+  attempt opened.
+- Every other method that takes the test-case handle raises the same
+  exception again before any native call. A body that rescues `Exception`
+  and draws on therefore cannot extend an attempt the engine is about to
+  discard.
+- A call that takes only the context still runs: `collection_free`,
+  `string_generator_free`, and `recursion_free`. hegel-rust's `Drop` runs the
+  same frees while its panic unwinds.
+
+`LeafBudgetExceeded` descends from `Exception`, as `Hegel::StopTest` does,
+and carries the recursion it belongs to. `RecursiveGenerator` rescues only
+its own, so one raised in an outer recursive draw passes through an inner
+one. After each attempt the generator asks the test case whether that
+attempt was abandoned, rather than relying on having rescued the exception.
+A body that swallowed it and returned a value is caught the same way, and
+the value, built from draws the engine is about to discard, is dropped.
+
+`#recursion_retry` reaches the engine with the raw handle. `HEGEL_OK` clears
+the held exception. `HEGEL_E_ASSUME` or `HEGEL_E_STOP_TEST` ends the test
+case, and its exception takes the held one's place, so a later call raises
+that verdict without reaching the engine. hegel-rust's data source
+short-circuits the same way once a test case is aborted
+(`libhegel/src/native/data_source.rs`).
+
+The held exception can reach the run loop only when something replaced it
+mid-unwind, such as an `ensure` that raised, and the body rescued that and
+drew again. `Hegel::Runner.classify` then marks the case INVALID. It is the
+library's own control flow, and its attempt never reached the retry, so it
+is not reported as a counterexample.
+
+A subtree generator drawn after the recursive draw that made it has ended
+raises `Hegel::Error`, since its recursion handle is already freed.
+
+## Alternatives rejected
+
+- **Roll the span depth back after `ensure` has closed the spans.** The
+  closes have already reached the engine as kept spans, and the ABI has no
+  call that reopens a span or marks a closed one discarded.
+- **Close spans only when a draw returns, as hegel-rust does.** That changes
+  every exception path through every compound generator: a failed
+  assumption, an overrun, a failing assertion, and the span handling of a
+  stateful rule, which is written around closing in `ensure`.
+- **Let draws return made-up values while the attempt is abandoned.** The
+  caller's code would run on values the engine never drew, could fail or
+  loop on them, and the header says to draw nothing further.
+- **Unwind with `throw` and `catch`.** `throw` passes a `rescue Exception`
+  by, but it runs `ensure` blocks just as an exception does, so the span
+  closes still have to be suppressed. CLAUDE.md requires the library's
+  control flow to use exceptions descending from `Exception`, and with the
+  held exception in place a swallowed unwind cannot reach the engine anyway,
+  so `throw` adds nothing.
+
+## Spans
+
+hegel-rust draws each leaf and each branch generator through `draw_silent`,
+which wraps it in a span labelled with that generator's label. This gem
+opens a span only around a generator that makes more than one native call
+itself (ADR 0020 and the `new-generator` skill), so the leaf and branch
+spans were settled by measurement. Against libhegel 0.47.2, six
+shrink-quality tests ported from `frontends/rust/tests/test_recursive.rs`
+(shrink to a leaf, the minimal empty branch, the minimal binary branch, the
+deep witness hoisted to the root at `max_depth` 3, the rare one at
+`max_depth` 4, and the saturated budget) each shrank to the expected value
+in 10 of 10 runs both with those spans and without them. The draw opens
+neither.
+
+The spans that remain are the recursive generator's own span, and a span
+around every non-root subtree, all labelled with the recursive generator's
+label. hegel-rust gives every depth that label so the shrinker can replace a
+tree with one of its subtrees. `tuples` here opens no span per element, so
+without the subtree's own span a subtree inside a `tuples` branch would
+carry no span with that label. Under `arrays` the element span and the
+subtree span nest with the same label.
+
+None of the six tests shows these spans doing their job on this engine.
+With the subtree span removed, with subtrees labelled apart from the
+recursive generator, with the recursive generator's own span removed, and
+with every `start_span` and `stop_span` in the library made a no-op, each
+test still passed 10 of 10. Over eight seeded runs of the rare deep witness,
+the number of test-body calls stayed within 3% of the same total
+(14,488 to 14,899) across all of those variants. The span tests against the
+Fake pin where the spans go, as they do for the other compound generators.
+
+## Consequences
+
+An attempt that outgrows its leaf budget costs one raised exception and its
+backtrace, and the engine allows at most 9 attempts per draw. Each call
+that takes the test-case handle checks one instance variable first.
+
+Against libhegel 0.47.2, the port of hegel-rust's large-tree test, a tree of
+`arrays` branches shrunk to exactly 30 leaves, called the body about 17,000
+to 19,500 times and took 30 to 40 seconds. Each draw made about 240 native
+calls, about 100 of them span opens and closes, and the time inside the
+engine was about a quarter of the total.
+
+The real-engine tests of `recursive` live in
+`test/hegel/test_recursive_engine.rb`, which `rake mutation` leaves out.
+With them in, the file took longer than mutineer's 10-second limit for one
+mutant, and 16 of the mutants on the new lines timed out without a verdict.
+The tests against the Fake, in `test/hegel/test_recursive.rb`, pin the
+generator's calls exactly and stay in the mutation run.

data/docs/adr/0033-cache-compiled-grammars-for-the-length-of-a-run.md

@@ -0,0 +1,80 @@
+# 0033: Cache compiled grammars for the length of a run
+
+## Status
+
+Accepted.
+
+## Context
+
+`from_lark` draws strings of a grammar written in Lark's syntax. The engine
+compiles the grammar into a `hegel_grammar_t` with `hegel_grammar_new`,
+after a `hegel_grammar_builder_t` has gathered the grammar and every file
+its `%import`s name. `hegel.h` calls the compiled grammar immutable, safe to
+share across test cases, and freed with `hegel_grammar_free`, which takes the
+context. Every draw then reads it through `hegel_generate_grammar`.
+
+Compiling costs far more than drawing. Measured against libhegel 0.47.2 on
+x86_64 Linux, compiling `start: INT ("," INT)*` with `%import common.INT`,
+which reads the bundled `common.lark`, took about 446 microseconds. With the
+grammar already compiled, a test case that drew one string of it, capped at
+20 characters, took about 38 microseconds, where a case that drew one integer
+took 15. A grammar with no imports compiled in about 46 microseconds.
+
+hegel-rust compiles once per generator: `LarkGenerator` keeps the grammar in
+a `OnceLock`, and Rust's `Drop` frees it when the generator goes. Ruby has no
+scope exit to hang that free on, and `CLAUDE.md` asks for every native
+handle to be freed in an `ensure` in the code that owns the run, before the
+context.
+
+## Decision
+
+`Hegel::Runner.run` creates a `Hegel::GrammarCache` inside the context's
+block and hands it to every `Hegel::TestCase` of the run, the replay of a
+`reproduce_failure:` blob included. An `ensure` frees every grammar in it
+after `hegel_run_free` and before `hegel_context_free`. Freeing carries on
+past a free that raises and raises the first error once every grammar has
+been tried, so one failure does not leave the rest alive when the context
+goes.
+
+The cache is keyed by value: the grammar text, the start rule, `max_size`,
+`max_depth`, the alphabet's options, the explicit terminal names in order,
+and the import path as a string. That is everything the compilation reads.
+The explicit generators are not in the key, since only their names reach the
+engine. The generator builds the key when it is built, as ADR 0020 asks of a
+label, so a draw writes nothing to it. Two generators equal by value share
+one grammar, so a `from_lark` built inside the test body compiles once per
+run as well.
+
+A compilation that raises stores nothing, and frees what it had built. A
+`Hegel::TestCase` built without a cache, as a unit test builds one, compiles
+for each draw and frees the grammar after it.
+
+The new-generator skill's rule that a native handle is never cached on the
+generator still holds. This cache belongs to the run, and is the route a
+handle that is worth keeping across draws takes.
+
+Four alternatives were rejected.
+
+- **Compile on every draw.** `CLAUDE.md` records a run configured for 20
+  test cases calling the body up to 1847 times, and an array of grammar
+  strings draws once per element. At 446 microseconds a compilation, that
+  dominates the run.
+- **Cache per test case.** It still compiles once per case, so it saves
+  only the draws after the first within one case.
+- **Cache on the generator, freed by a finalizer.** `CLAUDE.md` allows a
+  finalizer only as a backstop to an `ensure`. The free needs the context
+  the grammar came from, which is gone by the time a finalizer runs, and a
+  new context can reuse its address. A frozen generator cannot take a cache
+  written at draw time either.
+- **Cache for the process on a long-lived context.** No code owns that
+  context with an `ensure` around it, and the engine's contexts are
+  single-threaded, so two threads running properties would share one.
+
+## Consequences
+
+An imported file is read once per run for each key, so a change to it shows
+in the next run, not partway through one.
+
+A grammar whose text is built from drawn data gets a new key for each
+distinct text, and each stays compiled until the run ends. Such a run holds
+one live grammar per distinct text it drew.

data/docs/adr/0034-repeat-a-test-body-with-a-ruby-side-indent.md

@@ -0,0 +1,120 @@
+# 0034: Repeat a test body with a Ruby-side indent
+
+## Status
+
+Accepted.
+
+## Context
+
+hegel-rust's `TestCase::repeat` (`frontends/rust/src/test_case.rs:808` in
+hegeldev/hegel) runs a closure "logically infinitely": until the engine
+ends the loop, or until the closure fails. Under ADR 0015 this gem takes
+the same name and the same meaning. Four parts of the Rust version need a
+Ruby construction, because Ruby reaches the engine and reports a failure
+differently.
+
+What the Rust version does:
+
+1. It draws the loop's minimum length silently, from `integers` up to
+   `max_safe_min_size`, which is `2**40` (`test_case.rs:811`). It opens a
+   collection with that minimum and no maximum, and loops while the
+   collection wants another element.
+2. Each iteration notes `// Repetition #N` (`test_case.rs:819`) and runs
+   the closure under `enter_block(2)`, a handle from
+   `hegel_test_case_block`. The doc comment above the function says
+   `// Loop iteration N`; the code and the snapshots in
+   `frontends/rust/tests/test_loop.rs` say `// Repetition #N`, and this gem
+   follows the code.
+3. A closure that panicked with `AssumeFailed` goes on to the next
+   iteration. `StopTest`, `InvalidArgument`, and `InternalError` unwind
+   unchanged. Any other panic draws one silent boolean and then unwinds.
+4. When the collection says no more, it raises `LoopDone`
+   (`test_case.rs:842`). The function's return type is `!`: it never
+   returns. `run_lifecycle.rs:318` maps `LoopDone` to a VALID test case.
+
+`hegel_test_case_block` (`libhegel/include/hegel.h:1589`) gives a handle
+whose print region is a block nested in the parent's, each line indented
+further. It indents what reaches the engine printer, and nothing else:
+"everything printed or noted through the handle ... lands there". This gem
+builds its failure report in Ruby (`Hegel::Report`, with names from
+ADR 0005), and neither notes nor draws reach the engine printer. A block
+handle would change nothing a caller sees.
+
+## Decision
+
+**`TestCase#repeat` never returns from the loop's end.** It raises
+`Hegel::LoopDone`, a control exception beside `Hegel::StopTest` and
+`Hegel::AssumeFailed`. It descends from `Exception`, as `CLAUDE.md` requires
+of every control exception, so that a `rescue => e` written around the loop
+cannot catch the end of it. `Hegel::Runner.classify` maps it to VALID, after
+the four fatal exceptions and in the same group as the other control
+exceptions.
+
+**One iteration rescues in this order.** First the fatal exceptions
+(`Hegel::FATAL_EXCEPTIONS`), `Hegel::StopTest`, `Hegel::LoopDone`, and
+`Hegel::Error`: each re-raises unchanged. `Hegel::LoopDone` here is the
+end of a nested loop, which ends the outer loop too, as the inner
+`LoopDone` unwinds through the outer loop in Rust. `Hegel::Error` stands
+where `InvalidArgument` and `InternalError` stand, since this gem raises
+both kinds of error as `Hegel::Error`. Next `Hegel::AssumeFailed`, which
+skips to the next iteration. Last, any other `Exception`: one boolean is
+drawn, without recording, and the exception re-raises. The collection is
+freed in an `ensure`, on every path out of the loop.
+
+**The indent lives in the recorded entries.** Each entry
+`Hegel::TestCase` records carries an indent, in columns:
+`[:draw, name, value, indent]` and `[:note, message, indent]`.
+`TestCase#repeat` raises the indent by 2 around each iteration's block,
+after the `// Repetition #N` note, and `Hegel::Report` puts that many
+spaces before the line. The rendered report reads:
+
+```
+  // Repetition #1
+    n = 5
+```
+
+The indent is the one `enter_block(2)` gives. Nested loops add up, as
+blocks do.
+
+**`break` ends the loop.** A Ruby block can `break`, and Rust's closure has
+no way to. The `break` returns from `TestCase#repeat` with its value. The
+collection is freed and the indent restored on the way out, and the test
+body goes on after the loop. Forbidding `break` would turn the ordinary way
+out of a Ruby loop into an error. Taking it as the end of the loop gives it
+the meaning it has in `loop`, `each`, and `while`.
+
+Two smaller choices follow this gem's own rules:
+
+- The minimum length is drawn with no span around it. hegel-rust's
+  `draw_silent` opens a span around every draw. This gem opens one only
+  around a generator that makes more than one native call
+  (`.claude/skills/new-generator`), and one `hegel_generate_integer` is a
+  single call.
+- Draw names are suffixed over the whole test case, as
+  `Hegel::Report.assign_names` decides: a name gets a counter only when it
+  appears more than once in the report. A draw named `x` that appears once
+  stays `x`. hegel-rust's snapshots show `x_1` for the same case, because
+  its macro marks every draw inside a nested block as repeatable
+  (`frontends/rust/macros/src/common.rs:180`), and a repeatable name always
+  takes a counter.
+
+## Consequences
+
+A test body can hold a sequence of operations whose length the engine
+chooses and shrinks, without a state machine. The tests in
+`test/hegel/test_repeat.rb` port the four snapshots and the two run tests of
+`test_loop.rs`, and pin the rescue order against the Fake.
+
+The entry format has an indent in every entry. A later feature that wants
+an indented section, such as a stateful rule's body under its step line,
+can raise the same indent.
+
+`break` is a construction this gem has and hegel-rust lacks. ADR 0015 keeps
+mechanism outside its rule, and `break` is the loop exit a Ruby block
+already has, so this record treats it as mechanism. If upstream settles a
+way to end the loop early, this gem takes that and this record gets a
+successor.
+
+If this gem moves its report into the engine printer, `TestCase#repeat`
+can open a `hegel_test_case_block` handle for each iteration in place of
+the recorded indent.

data/docs/adr/0035-defer-concurrent-state-machines-and-the-engine-printer.md

@@ -0,0 +1,136 @@
+# 0035: Defer concurrent state machines and the engine printer
+
+## Status
+
+Accepted.
+
+## Context
+
+libhegel 0.47.2 offers two facilities that hegel-rust uses and this gem
+does not: concurrent state machines, and a printer that builds the failure
+report inside the engine. ADR 0015 counts a feature that this gem lacks as
+a divergence, so each needs a recorded reason. Paths and line numbers
+below are in hegeldev/hegel as of libhegel 0.47.2.
+
+### Concurrent state machines
+
+hegel-rust runs a `ConcurrentStateMachine` with `run_concurrent`
+(`frontends/rust/src/stateful.rs:989`). `hegel_new_state_machine` draws a
+concurrency level between `min_concurrency` and `max_concurrency`.
+`run_concurrent_machine` (`stateful.rs:1361`) spawns one thread per level
+inside `std::thread::scope` (`stateful.rs:1415`). Each round, it hands every
+worker a clone of the test case, `tc.clone()`, attributed to that worker
+with `set_worker` (`stateful.rs:1449-1450`). A `ConcurrentRule`'s `apply`
+takes `&M` (`stateful.rs:1097-1102`): the doc comment above it
+(`stateful.rs:1086-1096`) says the
+machine is "shared by reference across the worker threads, so any mutable
+model state needs interior mutability", and that the feature "is intended
+for advanced users. We otherwise discourage using it."
+
+The engine calls behind this are `hegel_test_case_clone`
+(`libhegel/include/hegel.h:1553`), which gives "an independent stream of the
+same test case" that "can be driven concurrently from different threads",
+and `hegel_test_case_set_worker` (`hegel.h:1614`), which prefixes each line
+the handle records with `[worker N +X.XXXms] `.
+
+Four things stand between this gem and a port:
+
+1. **Each worker needs its own context.** The threading section of
+   `hegel.h` (lines 101-117) says "A context must not be used concurrently
+   from multiple threads". hegel-rust keeps one context per thread in a
+   `thread_local!` (`frontends/rust/src/ffi.rs:72`). `Hegel::Runner.run`
+   opens one context for the whole run and threads it through every call,
+   so each worker would need a context of its own, and every handle
+   allocated from it freed before that context.
+2. **Ruby threads take turns.** `Hegel::LibHegel::Real#bind` builds each
+   `FFI::Function` without the `blocking:` option, so every engine call
+   holds the GVL for its duration. Between engine calls, Ruby threads
+   running pure-Ruby code switch on the VM's timer or at blocking I/O. A
+   short rule body that does no I/O then tends to run to completion before
+   another thread gets the GVL, and the interleavings a concurrent machine
+   exists to find seldom happen. A body that waits on I/O, a database, or a
+   C extension that releases the GVL would interleave.
+3. **Ractors cannot reach a shared machine.** Measured with ffi 1.17.4 on
+   Ruby 3.4.6: passing an unfrozen `FFI::Pointer` to `Ractor.new` raises
+   "cannot duplicate unbounded memory area", and passing an unfrozen
+   `FFI::Function` raises "cannot duplicate function instances". Both can
+   be made shareable with `Ractor.make_shareable`, and a shareable
+   `FFI::Function` is callable inside another Ractor. The handles are not
+   the obstacle. The machine is: hegel-rust's rules share one `&M`, and a
+   `Hegel::StateMachine` subclass instance with mutable state is an object
+   that only one Ractor can reach.
+4. **`CLAUDE.md` would change.** Its standing constraints say "The engine
+   is single-threaded. A context, a run, and a test case each belong to one
+   thread at a time." A concurrent runner needs that rule restated for
+   clones and per-thread contexts.
+
+`Hegel::LibHegel::Real#new_state_machine` passes a concurrency of exactly
+1, and ADR 0021 records the sequential machine this gem runs.
+
+### The engine printer
+
+hegel-rust prints each drawn value and note into the engine's document as
+the test body runs. `hegel_test_case_printer` (`hegel.h:3052`) gives a
+handle onto a test-case handle's print region, the `hegel_printer_*`
+calls (the comment above `hegel_printer_t`, `hegel.h:538-574`, describes
+the model) lay text out in groups that
+break to fit a width (default 79, `hegel.h:3073`), `hegel_printer_reflow`
+(`hegel.h:2910`) re-lays a flat debug string such as Ruby's `#inspect`, and
+`hegel_note` (`hegel.h:3079`) appends a line. A note written while a drawn
+value is mid-print is held back and placed after the value (`hegel.h`, the
+comment above `hegel_note`). `hegel_test_case_block` (`hegel.h:1589`)
+indents a section, and `hegel_test_case_set_worker` prefixes a worker's
+lines.
+
+This gem builds its report in Ruby. `Hegel::TestCase` records draws and
+notes on the cases the engine stamps for capture (ADR 0019),
+`Hegel::DrawName` names each draw from the caller's source (ADR 0005 and
+ADR 0014), and `Hegel::Report` renders the list. `Hegel::LibHegel::Real`
+passes a NULL output callback to `hegel_run_start`.
+
+## Decision
+
+**Concurrent state machines are not ported.** `Hegel::Stateful.run` stays
+sequential, at a concurrency of 1. This is a divergence under ADR 0015,
+recorded here. It is to be revisited when a caller asks for it, together
+with the engine printer: `hegel_test_case_set_worker` attributes
+`hegel_note` lines and lines started through a printer from
+`hegel_test_case_printer` (`hegel.h:1595-1599`), so a report that reads
+across workers comes from the engine document.
+
+**The engine printer is not adopted for draws.** `Hegel::Report` keeps
+building the report. Moving it into the engine would change two things
+that work today:
+
+- `Hegel::Report.assign_names` gives a name a counter only when that name
+  appears more than once among the whole case's draws (ADR 0014 decides
+  which draws get a name at all). At draw time, the rest of the case has
+  not run, so the printed name is not yet known.
+  `hegel_printer_deferred` could hold each name open until the case ends,
+  at the price of one hole per draw and a resolve step this gem does not
+  have.
+- The report's shape, which `test/hegel/test_report.rb` pins line by line,
+  and which a caller reads on every failure.
+
+The gains, width wrapping, a note placed after a value whose generation
+emitted it, indented step blocks, and worker prefixes, do not yet outweigh
+that.
+
+A narrower change stays open: `Hegel::Report` could lay out a long value
+through a standalone document, `hegel_printer_new` (`hegel.h:2746`), and
+`hegel_printer_reflow` over the value's `#inspect`, then read it back with
+`hegel_printer_value` (`hegel.h:3011`). That brings width wrapping without
+moving naming or the report into the engine.
+
+## Consequences
+
+A caller who wants to exercise concurrency can start Ruby threads inside a
+single rule. The engine then neither chooses nor shrinks the interleaving.
+
+A long drawn value prints on one line, as `#inspect` writes it.
+
+A later feature that wants an indented section of the report, the effect
+`hegel_test_case_block` gives in the engine document, builds that indent in
+`Hegel::Report`.
+
+A later record that ports either facility supersedes this one.