hegeltest 0.3.1-aarch64-linux → 0.4.0-aarch64-linux

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.

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.