hegeltest 0.3.4-aarch64-linux → 0.4.1-aarch64-linux

data/lib/hegel/syntax/methods.rb

@@ -27,26 +27,34 @@ module Hegel
       # A double in [min_value, max_value]. allow_nan and allow_infinity
       # default to what the bounds imply: NaN when the caller passed
       # neither bound, an infinity when the caller left either side open.
+      # allow_subnormal defaults to true whenever the bounds admit a
+      # subnormal.
       def floats(min_value: nil, max_value: nil, allow_nan: nil, allow_infinity: nil, exclude_min: false,
-        exclude_max: false)
+        exclude_max: false, allow_subnormal: nil)
         Generators::FloatGenerator.new(
           min_value: min_value, max_value: max_value, allow_nan: allow_nan, allow_infinity: allow_infinity,
-          exclude_min: exclude_min, exclude_max: exclude_max
+          exclude_min: exclude_min, exclude_max: exclude_max, allow_subnormal: allow_subnormal
         )
       end
 
-      # A Unicode string of [min_size, max_size] characters.
-      def text(min_size: 0, max_size: nil, codec: nil, min_codepoint: nil, max_codepoint: nil)
+      # A Unicode string of [min_size, max_size] characters; max_size
+      # defaults to 100, or min_size + 100 when min_size exceeds 100.
+      # +alphabet+ is a String of the permitted characters; it cannot be
+      # combined with the options after it.
+      def text(min_size: 0, max_size: nil, alphabet: nil, codec: nil, min_codepoint: nil, max_codepoint: nil,
+        categories: nil, exclude_categories: nil, include_characters: nil, exclude_characters: nil)
         Generators::TextGenerator.new(
-          min_size: min_size, max_size: max_size, codec: codec,
-          min_codepoint: min_codepoint, max_codepoint: max_codepoint
+          min_size: min_size, max_size: max_size, alphabet: alphabet, codec: codec,
+          min_codepoint: min_codepoint, max_codepoint: max_codepoint, categories: categories,
+          exclude_categories: exclude_categories, include_characters: include_characters,
+          exclude_characters: exclude_characters
         )
       end
 
       # An Array of values from +elements+, with [min_size, max_size]
-      # entries.
-      def arrays(elements, min_size: 0, max_size: nil)
-        Generators::ArrayGenerator.new(elements, min_size: min_size, max_size: max_size)
+      # entries. With unique: true, no two entries are equal.
+      def arrays(elements, min_size: 0, max_size: nil, unique: false)
+        Generators::ArrayGenerator.new(elements, min_size: min_size, max_size: max_size, unique: unique)
       end
 
       # Always +value+, drawing nothing.
@@ -59,6 +67,29 @@ module Hegel
         Generators::SampledFromGenerator.new(collection)
       end
 
+      # An Array holding every element of +elements+ (anything #sampled_from
+      # accepts) in an order the engine picks, shrinking towards the
+      # original one.
+      def permutations(elements)
+        Generators::PermutationsGenerator.new(elements)
+      end
+
+      # An Array holding [min_size, max_size] of the elements of +elements+,
+      # in their original order. Duplicate elements count as distinct.
+      def subsequences(elements, min_size: 0, max_size: nil)
+        Generators::SubsequencesGenerator.new(elements, min_size: min_size, max_size: max_size)
+      end
+
+      # An Array of [min_size, max_size] elements of +elements+. With
+      # +replacement+ (the default) each is drawn independently and the
+      # size is unbounded unless +max_size+ bounds it. Without it, each
+      # element is used at most once and the size is capped at the number
+      # of elements; hegel-rust names the two modes with_replacement and
+      # without_replacement.
+      def samples(elements, min_size: 0, max_size: nil, replacement: true)
+        Generators::SamplesGenerator.new(elements, min_size: min_size, max_size: max_size, replacement: replacement)
+      end
+
       # A value drawn from one of +generators+, picked at random.
       def one_of(*generators)
         Generators::OneOfGenerator.new(generators)
@@ -88,20 +119,41 @@ module Hegel
 
       # A String of exactly one character, sharing #text's own alphabet
       # options.
-      def characters(codec: nil, min_codepoint: nil, max_codepoint: nil)
-        Generators::CharactersGenerator.new(codec: codec, min_codepoint: min_codepoint, max_codepoint: max_codepoint)
+      def characters(codec: nil, min_codepoint: nil, max_codepoint: nil, categories: nil, exclude_categories: nil,
+        include_characters: nil, exclude_characters: nil)
+        Generators::CharactersGenerator.new(
+          codec: codec, min_codepoint: min_codepoint, max_codepoint: max_codepoint, categories: categories,
+          exclude_categories: exclude_categories, include_characters: include_characters,
+          exclude_characters: exclude_characters
+        )
       end
 
-      # A byte String of [min_size, max_size] bytes.
+      # A byte String of [min_size, max_size] bytes; max_size defaults as
+      # in #text.
       def binary(min_size: 0, max_size: nil)
         Generators::BinaryGenerator.new(min_size: min_size, max_size: max_size)
       end
 
       # A String matching +pattern+ (Python `re` syntax, not Ruby's
       # Regexp syntax; see Generators::FromRegexGenerator). fullmatch
-      # requires the whole string to match, not just contain a match.
-      def from_regex(pattern, fullmatch: false)
-        Generators::FromRegexGenerator.new(pattern, fullmatch: fullmatch)
+      # (the default) requires the whole string to match, not just contain
+      # a match.
+      # +alphabet+ is a #characters generator limiting every character of the
+      # string.
+      def from_regex(pattern, fullmatch: true, alphabet: nil)
+        Generators::FromRegexGenerator.new(pattern, fullmatch: fullmatch, alphabet: alphabet)
+      end
+
+      # A String that +grammar+, written in the syntax of the Lark parsing
+      # library, accepts from its +start+ rule. +explicit+ maps terminal names
+      # to generators of the values drawn for them, +alphabet+ is a
+      # #characters generator limiting what terminal patterns draw, and
+      # +import_path+ is the directory %import reads files from.
+      def from_lark(grammar, start: nil, explicit: {}, alphabet: nil, max_size: nil, max_depth: nil, import_path: nil)
+        Generators::FromLarkGenerator.new(
+          grammar, start: start, explicit: explicit, alphabet: alphabet, max_size: max_size, max_depth: max_depth,
+          import_path: import_path
+        )
       end
 
       # An RFC 5321/5322 email address String.
@@ -152,6 +204,29 @@ module Hegel
         Generators::DatetimesGenerator.new(min_value: min_value, max_value: max_value)
       end
 
+      # A "YYYY-MM-DD" String, years 1 through 9999. Takes no options.
+      def date_strings
+        Generators::DateStringsGenerator.new
+      end
+
+      # An "HH:MM:SS" String, with ".fffffffff" appended when the
+      # nanosecond is not zero. Takes no options.
+      def time_strings
+        Generators::TimeStringsGenerator.new
+      end
+
+      # A "YYYY-MM-DDTHH:MM:SS[.fffffffff]" String, years 1 through 9999.
+      # Takes no options.
+      def datetime_strings
+        Generators::DatetimeStringsGenerator.new
+      end
+
+      # A duration as Integer nanoseconds in [min_value, max_value], up to
+      # 2**64 - 1 (see Generators::DurationsGenerator and docs/adr/0030).
+      def durations(min_value: 0, max_value: (2**64) - 1)
+        Generators::DurationsGenerator.new(min_value: min_value, max_value: max_value)
+      end
+
       # A value built from imperative code: +block+ receives a draw
       # surface and may call #draw on it any number of times to assemble
       # one value (see Generators::CompositeGenerator).
@@ -165,6 +240,15 @@ module Hegel
       def deferred
         Generators::DeferredGenerator.new
       end
+
+      # A recursively defined value, such as a tree: either a value from
+      # +leaf+, or what the block's generator builds from sub-values of the
+      # same kind (see Generators::RecursiveGenerator). The block receives
+      # the generator of those sub-values and is called afresh for each
+      # branch.
+      def recursive(leaf, max_depth: 32, max_leaves: 100, &branch)
+        Generators::RecursiveGenerator.new(leaf, max_depth: max_depth, max_leaves: max_leaves, &branch)
+      end
     end
   end
 

data/lib/hegel/test_case.rb

@@ -46,6 +46,16 @@ module Hegel
     # loudly.
     DRAW_CALLER_DEPTH = 3
 
+    # The largest minimum length #repeat draws for its loop: 2**40, the
+    # bound hegel-rust's TestCase::repeat draws its own minimum under
+    # (max_safe_min_size).
+    REPEAT_MAX_MIN_SIZE = 2**40
+
+    # How many columns further #repeat indents the entries one iteration
+    # records: the indent hegel-rust's TestCase::repeat gives the block
+    # handle it runs each iteration under.
+    REPEAT_INDENT = 2
+
     # +impl+ and +ctx+ are carried alongside +handle+ so each draw call can
     # reach the same LibHegel implementation and context the run loop opened,
     # without this class knowing anything about the native binding layer or
@@ -54,17 +64,26 @@ module Hegel
     # +record+ defaults to false: recording is Hegel::Runner's decision, made
     # only for the one, already-shrunk replay that produces a failure report
     # (see #record_draw for why every other iteration skips it).
-    def initialize(impl, ctx, handle, record: false)
+    #
+    # +grammars+ is the run's Hegel::GrammarCache, which Hegel::Runner
+    # passes; a test case built without one compiles a grammar for each draw.
+    def initialize(impl, ctx, handle, record: false, grammars: nil)
       @impl = impl
       @ctx = ctx
       @handle = handle
       @record = record
       @entries = record ? [] : nil
       @pools = []
+      @grammars = grammars
+      # Only declares the ivar: an unset one already reads as nil.
+      @poison = nil # mutineer:disable-line statement_removal
+      @indent = 0
     end
 
-    # The [:draw, name, value] / [:note, message] entries recorded so far, in
-    # call order, or nil when this instance was not built to record.
+    # The [:draw, name, value, indent] / [:note, message, indent] entries
+    # recorded so far, in call order, or nil when this instance was not
+    # built to record. +indent+ is how many columns further in the report
+    # puts the entry; #repeat raises it around each iteration.
     # Hegel::Runner reads this once, after the block that owns this test
     # case has run to completion or raised. One tagged list rather than a
     # draws list and a separate notes list, so a note recorded between two
@@ -151,21 +170,56 @@ module Hegel
 
       return unless @record
 
-      @entries << [:note, has_message ? message : yield]
+      @entries << [:note, has_message ? message : yield, @indent]
+    end
+
+    # Runs the block over and over, for as long as the engine keeps the
+    # loop going, and never returns normally: when the engine ends the loop
+    # it raises Hegel::LoopDone, which Hegel::Runner.classify reports as a
+    # passing case. A `break` in the block ends the loop early and returns
+    # from this method instead; hegel-rust's TestCase::repeat has no
+    # counterpart, since a Rust closure cannot break its caller's loop.
+    # docs/adr/0034 records both decisions.
+    #
+    # The loop is a collection whose minimum length is drawn first, from 0
+    # up to REPEAT_MAX_MIN_SIZE, with no maximum, the way hegel-rust draws
+    # it. Each iteration notes "// Repetition #N", then records what the
+    # block records REPEAT_INDENT columns further in. An iteration whose
+    # assumption failed is skipped rather than discarding the whole case;
+    # any other exception ends the loop (see #repeat_iteration).
+    #
+    # The minimum length is drawn with no span around it. hegel-rust's
+    # draw_silent opens one around every draw, and this library opens a
+    # span only around a generator that makes more than one native call
+    # (.claude/skills/new-generator), which one generate_integer is not.
+    def repeat(&block)
+      min_size = generate_integer(0, REPEAT_MAX_MIN_SIZE)
+      collection = new_collection(min_size, LibHegel::HEGEL_COLLECTION_MAX_SIZE_UNBOUNDED)
+      begin
+        iteration = 0
+        while collection_more(collection)
+          iteration += 1
+          note { "// Repetition ##{iteration}" }
+          repeat_iteration(&block)
+        end
+      ensure
+        collection_free(collection)
+      end
+      raise Hegel::LoopDone, "hegel: repeat finished its loop"
     end
 
     # hegel_generate_integer, without recording. Hegel::Generators::
     # IntegerGenerator's own primitive; #draw_integer is this plus
     # recording.
     def generate_integer(min_value, max_value)
-      @impl.generate_integer(@ctx, @handle, min_value, max_value)
+      @impl.generate_integer(@ctx, live_handle, min_value, max_value)
     end
 
     # hegel_generate_integer_big, without recording. Hegel::Generators::
     # IntegerGenerator's own primitive for bounds outside int64_t's range,
     # used instead of #generate_integer only then; see IntegerGenerator#do_draw.
     def generate_integer_big(min_value, max_value)
-      @impl.generate_integer_big(@ctx, @handle, min_value, max_value)
+      @impl.generate_integer_big(@ctx, live_handle, min_value, max_value)
     end
 
     # hegel_generate_boolean, without recording. Hegel::Generators::
@@ -175,14 +229,14 @@ module Hegel
       # has_forced is false, so the engine ignores the forced argument's value.
       # .mutineer.yml ignores that mutant by id, since a line marker would also
       # hide the killed mutant of has_forced.
-      @impl.generate_boolean(@ctx, @handle, p, false, false)
+      @impl.generate_boolean(@ctx, live_handle, p, false, false)
     end
 
     # hegel_generate_float. Hegel::Generators::FloatGenerator's own
     # primitive.
     def generate_float(width, min_value, max_value, allow_nan:, allow_infinity:, exclude_min:, exclude_max:,
       smallest_nonzero_magnitude:)
-      @impl.generate_float(@ctx, @handle, width, min_value, max_value, allow_nan, allow_infinity, exclude_min,
+      @impl.generate_float(@ctx, live_handle, width, min_value, max_value, allow_nan, allow_infinity, exclude_min,
         exclude_max, smallest_nonzero_magnitude)
     end
 
@@ -220,33 +274,49 @@ module Hegel
     # this class makes. Writing the same check on this side would only
     # give one mistake two messages to drift apart from each other.
     def target(value, label: "")
-      @impl.target(@ctx, @handle, value, label)
+      @impl.target(@ctx, live_handle, value, label)
+    end
+
+    def event(label)
+      @impl.event(@ctx, live_handle, label)
+    end
+
+    # No finite check here: hegel_event_value's HEGEL_E_INVALID_ARG reaches
+    # the caller through LibHegel.check!, as it does for #target.
+    def event_value(label, value)
+      @impl.event_value(@ctx, live_handle, label, value)
     end
 
     # hegel_start_span, labelled with a generator's label (see
     # Hegel::Generator#label). Every compound Hegel::Generator (map, filter,
     # arrays) opens one of these around its own draw; see #stop_span.
     def start_span(label)
-      @impl.start_span(@ctx, @handle, label)
+      @impl.start_span(@ctx, live_handle, label)
     end
 
     # hegel_stop_span, closing the span #start_span most recently opened.
     # +discard+ true marks it rejected (a filter predicate that did not
     # hold), so libhegel retries from before the span opened.
+    #
+    # Makes no native call while an abandoned recursive attempt unwinds:
+    # hegel_recursion_retry discards the spans that attempt left open, and
+    # closing them here first would keep them. See docs/adr/0032.
     def stop_span(discard: false)
+      return if @poison
+
       @impl.stop_span(@ctx, @handle, discard)
     end
 
     # hegel_new_collection: Hegel::Generators::ArrayGenerator's own sizing
     # primitive, paired with #collection_more and #collection_free.
     def new_collection(min_size, max_size)
-      @impl.new_collection(@ctx, @handle, min_size, max_size)
+      @impl.new_collection(@ctx, live_handle, min_size, LibHegel.max_size_arg(max_size))
     end
 
     # hegel_collection_more: whether to draw another element into
     # +collection+.
     def collection_more(collection)
-      @impl.collection_more(@ctx, @handle, collection)
+      @impl.collection_more(@ctx, live_handle, collection)
     end
 
     # hegel_collection_reject: tells libhegel the element most recently
@@ -255,7 +325,7 @@ module Hegel
     # #collection_more call offers another attempt at the same slot instead
     # of treating the collection as one element closer to done.
     def collection_reject(collection, why: nil)
-      @impl.collection_reject(@ctx, @handle, collection, why)
+      @impl.collection_reject(@ctx, live_handle, collection, why)
     end
 
     # hegel_collection_free.
@@ -270,15 +340,17 @@ module Hegel
     # read the same way as #with_regex_generator/#with_email_generator/
     # #with_url_generator/#with_domain_generator below, each named for its
     # own hegel_string_generator_* call.
-    def with_text_generator(**kwargs, &block)
-      with_generator_handle(@impl.string_generator_text(@ctx, **kwargs), &block)
+    def with_text_generator(max_size:, **kwargs, &block)
+      handle = @impl.string_generator_text(@ctx, max_size: LibHegel.max_size_arg(max_size), **kwargs)
+      with_generator_handle(handle, &block)
     end
 
     # Runs the block with a regex-matching string generator handle built
-    # from +pattern+/+fullmatch+ (see #string_generator_regex), freeing it
-    # via #with_generator_handle whether the block returns or raises.
-    def with_regex_generator(pattern, fullmatch:, &block)
-      with_generator_handle(string_generator_regex(pattern, fullmatch), &block)
+    # from +pattern+/+fullmatch+/+alphabet+ (see #string_generator_regex),
+    # freeing it via #with_generator_handle whether the block returns or
+    # raises. +alphabet+ stays the caller's to free.
+    def with_regex_generator(pattern, fullmatch:, alphabet: nil, &block)
+      with_generator_handle(string_generator_regex(pattern, fullmatch, alphabet), &block)
     end
 
     # Runs the block with an email-address string generator handle (see
@@ -304,26 +376,26 @@ module Hegel
     # #with_regex_generator, #with_email_generator, #with_url_generator, or
     # #with_domain_generator).
     def generate_string(generator)
-      @impl.generate_string(@ctx, @handle, generator)
+      @impl.generate_string(@ctx, live_handle, generator)
     end
 
     # hegel_generate_bytes. A future Hegel::Generators::BinaryGenerator's
     # own primitive, the bytes counterpart to #generate_string.
     def generate_bytes(min_size, max_size)
-      @impl.generate_bytes(@ctx, @handle, min_size, max_size)
+      @impl.generate_bytes(@ctx, live_handle, min_size, LibHegel.max_size_arg(max_size))
     end
 
     # hegel_generate_ipv4, returning the address's 4 raw bytes. Converting
     # to a caller-facing address type (IPAddr or similar) is left to the
     # generator built on top of this call.
     def generate_ipv4
-      @impl.generate_ipv4(@ctx, @handle)
+      @impl.generate_ipv4(@ctx, live_handle)
     end
 
     # hegel_generate_ipv6, returning the address's 16 raw bytes. Same
     # division of labor as #generate_ipv4.
     def generate_ipv6
-      @impl.generate_ipv6(@ctx, @handle)
+      @impl.generate_ipv6(@ctx, live_handle)
     end
 
     # hegel_generate_uuid, returning 16 raw bytes. Hegel::Generators::
@@ -331,7 +403,7 @@ module Hegel
     # hex String is that generator's job, the same division of labor
     # #generate_ipv4/#generate_ipv6 already follow.
     def generate_uuid(version, has_version)
-      @impl.generate_uuid(@ctx, @handle, version, has_version)
+      @impl.generate_uuid(@ctx, live_handle, version, has_version)
     end
 
     # hegel_string_generator_regex. +alphabet+ is an optional string
@@ -385,7 +457,7 @@ module Hegel
     # Hegel::Stateful::Pool.new cannot forget it and leak the handle --
     # docs/adr/0011 has the ownership decision behind this.
     def new_pool
-      pool = @impl.new_pool(@ctx, @handle)
+      pool = @impl.new_pool(@ctx, live_handle)
       @pools << pool
       pool
     end
@@ -394,7 +466,7 @@ module Hegel
     # associate with the value it just generated. Hegel::Stateful::Pool#add's
     # own primitive.
     def pool_add(pool)
-      @impl.pool_add(@ctx, @handle, pool)
+      @impl.pool_add(@ctx, live_handle, pool)
     end
 
     # hegel_pool_generate: the variable id libhegel chose from +pool+ (and
@@ -405,7 +477,13 @@ module Hegel
     # translates that to Hegel::AssumeFailed, the same as every other
     # assumption failure.
     def pool_generate(pool, consume)
-      @impl.pool_generate(@ctx, @handle, pool, consume)
+      @impl.pool_generate(@ctx, live_handle, pool, consume)
+    end
+
+    # hegel_pool_restore: puts back +variable_id+, a consuming
+    # #pool_generate's answer that the caller is throwing away unused.
+    def pool_restore(pool, variable_id)
+      @impl.pool_restore(@ctx, live_handle, pool, variable_id)
     end
 
     # hegel_pool_free. Not called directly by a caller of
@@ -431,34 +509,34 @@ module Hegel
     # here rather than on that module, the same reason every other native
     # call is a method on this class: Hegel::Stateful never touches @impl or
     # @ctx directly, only this handle-scoped surface.
-    def new_state_machine(rule_names, invariant_names, always_check, step_count)
-      @impl.new_state_machine(@ctx, @handle, rule_names, invariant_names, always_check, step_count)
+    def new_state_machine(rule_names, rule_weights, invariant_names, always_check, step_count)
+      @impl.new_state_machine(@ctx, live_handle, rule_names, rule_weights, invariant_names, always_check, step_count)
     end
 
     # hegel_state_machine_next_group: starts the next round, or returns
     # LibHegel::HEGEL_STATE_MACHINE_DONE once the machine is done.
     def state_machine_next_group(state_machine)
-      @impl.state_machine_next_group(@ctx, @handle, state_machine)
+      @impl.state_machine_next_group(@ctx, live_handle, state_machine)
     end
 
     # hegel_state_machine_next_rule: the index (into the +rule_names+
     # #new_state_machine was given) of the next rule to run this round, or
     # LibHegel::HEGEL_STATE_MACHINE_DONE once the round is over.
     def state_machine_next_rule(state_machine)
-      @impl.state_machine_next_rule(@ctx, @handle, state_machine)
+      @impl.state_machine_next_rule(@ctx, live_handle, state_machine)
     end
 
     # hegel_state_machine_rule_rejected: tells libhegel the rule most
     # recently returned by #state_machine_next_rule stopped early on a
     # failed assumption, so its round does not count toward the step budget.
     def state_machine_rule_rejected(state_machine)
-      @impl.state_machine_rule_rejected(@ctx, @handle, state_machine)
+      @impl.state_machine_rule_rejected(@ctx, live_handle, state_machine)
     end
 
     # hegel_state_machine_should_check_invariant: whether to run the
     # invariant at +index+ at this join point.
     def state_machine_should_check_invariant(state_machine, index)
-      @impl.state_machine_should_check_invariant(@ctx, @handle, state_machine, index)
+      @impl.state_machine_should_check_invariant(@ctx, live_handle, state_machine, index)
     end
 
     # hegel_state_machine_free. Takes no test-case handle, unlike every
@@ -470,11 +548,69 @@ module Hegel
       @impl.state_machine_free(@ctx, state_machine)
     end
 
+    # A hegel_new_recursion handle, and whether #recursion_free has
+    # released it.
+    Recursion = Struct.new(:handle, :freed)
+
+    # hegel_new_recursion. Hegel::Generators::RecursiveGenerator's own
+    # scope, freed by #recursion_free in that generator's `ensure`.
+    def new_recursion(max_depth, max_leaves)
+      Recursion.new(@impl.new_recursion(@ctx, live_handle, max_depth, max_leaves), false)
+    end
+
+    # hegel_recursion_branch: whether the sub-value at +depth+ is a branch.
+    def recursion_branch(recursion, depth)
+      @impl.recursion_branch(@ctx, live_handle, recursion.handle, depth)
+    end
+
+    # hegel_recursion_leaf. Raises Hegel::LeafBudgetExceeded when the
+    # attempt outgrew its leaf budget, and keeps it until #recursion_retry:
+    # every call that takes the test-case handle raises it again instead of
+    # reaching the engine, so a body that rescues it cannot draw on into an
+    # attempt the engine is about to discard.
+    def recursion_leaf(recursion)
+      return if @impl.recursion_leaf(@ctx, live_handle, recursion.handle)
+
+      @poison = LeafBudgetExceeded.new(recursion)
+      raise @poison
+    end
+
+    # True while the attempt +recursion+ abandoned through #recursion_leaf
+    # still waits for #recursion_retry.
+    def abandoned_by?(recursion)
+      @poison.is_a?(LeafBudgetExceeded) && @poison.recursion.equal?(recursion)
+    end
+
+    # hegel_recursion_retry, which reaches the engine with the raw handle
+    # while an attempt is abandoned. HEGEL_E_ASSUME or HEGEL_E_STOP_TEST ends the
+    # test case, so its exception takes the abandoned attempt's place and
+    # later calls raise it without reaching the engine.
+    def recursion_retry(recursion)
+      @impl.recursion_retry(@ctx, @handle, recursion.handle)
+      @poison = nil
+    rescue AssumeFailed, StopTest => e
+      @poison = e
+      raise
+    end
+
+    # hegel_recursion_finish: false when the engine discarded the finished
+    # attempt, which the caller then draws again from the root.
+    def recursion_finish(recursion)
+      @impl.recursion_finish(@ctx, live_handle, recursion.handle)
+    end
+
+    # hegel_recursion_free. Takes no test-case handle, so it runs while an
+    # attempt is abandoned.
+    def recursion_free(recursion)
+      recursion.freed = true
+      @impl.recursion_free(@ctx, recursion.handle)
+    end
+
     # hegel_generate_date, without recording. Hegel::Generators::
     # DatesGenerator's own primitive. +min_value+/+max_value+ are each a
     # [year, month, day] Array; the return value is the same shape.
     def generate_date(min_value, max_value)
-      @impl.generate_date(@ctx, @handle, min_value, max_value)
+      @impl.generate_date(@ctx, live_handle, min_value, max_value)
     end
 
     # hegel_generate_time, without recording. Hegel::Generators::
@@ -482,7 +618,7 @@ module Hegel
     # [hour, minute, second, microsecond] Array; the return value is the
     # same shape.
     def generate_time(min_value, max_value)
-      @impl.generate_time(@ctx, @handle, min_value, max_value)
+      @impl.generate_time(@ctx, live_handle, min_value, max_value)
     end
 
     # hegel_generate_datetime, without recording. Hegel::Generators::
@@ -491,11 +627,97 @@ module Hegel
     # [hour, minute, second, microsecond] Array; the return value is a
     # [[year, month, day], [hour, minute, second, microsecond]] pair.
     def generate_datetime(min_date, min_time, max_date, max_time)
-      @impl.generate_datetime(@ctx, @handle, min_date, min_time, max_date, max_time)
+      @impl.generate_datetime(@ctx, live_handle, min_date, min_time, max_date, max_time)
+    end
+
+    # Yields the Hegel::GrammarCache::Compiled under +key+ in the run's
+    # cache, calling +build+ to compile it on the first draw. Without a
+    # cache, it compiles one for this draw alone and frees it afterwards.
+    def with_grammar(key, build)
+      return yield @grammars.fetch(key, &build) if @grammars
+
+      compiled = build.call
+      begin
+        yield compiled
+      ensure
+        grammar_free(compiled.grammar)
+      end
+    end
+
+    def grammar_builder_new(text)
+      @impl.grammar_builder_new(@ctx, text)
+    end
+
+    def grammar_builder_file(builder, index)
+      @impl.grammar_builder_file(@ctx, builder, index)
+    end
+
+    def grammar_builder_provide(builder, index, text)
+      @impl.grammar_builder_provide(@ctx, builder, index, text)
+    end
+
+    def grammar_builder_free(builder)
+      @impl.grammar_builder_free(@ctx, builder)
+    end
+
+    def grammar_new(builder, start, max_size, max_depth, alphabet, names)
+      @impl.grammar_new(@ctx, builder, start, max_size, max_depth, alphabet, names)
+    end
+
+    def grammar_placeholder(grammar, name)
+      @impl.grammar_placeholder(@ctx, grammar, name)
+    end
+
+    def grammar_free(grammar)
+      @impl.grammar_free(@ctx, grammar)
+    end
+
+    # hegel_generate_grammar, without recording.
+    def generate_grammar(grammar, max_size)
+      @impl.generate_grammar(@ctx, live_handle, grammar, max_size)
     end
 
     private
 
+    def live_handle
+      raise @poison if @poison
+
+      @handle
+    end
+
+    # Runs one #repeat iteration with the indent raised by REPEAT_INDENT.
+    # hegel-rust indents an iteration's output through hegel_test_case_block,
+    # which indents only what the engine printer prints. This library
+    # renders its report itself (Hegel::Report, docs/adr/0005), so the
+    # indent is kept on this side and recorded with each entry.
+    #
+    # The rescue order follows hegel-rust's TestCase::repeat, after the
+    # fatal exceptions every `rescue Exception` here lets through first. The
+    # library's own control exceptions, a nested #repeat's Hegel::LoopDone
+    # among them, and Hegel::Error, which stands where hegel-rust's
+    # InvalidArgument and InternalError stand, re-raise unchanged. A failed
+    # assumption skips to the next iteration. Anything else is a failure:
+    # one boolean is drawn before it re-raises, as hegel-rust draws one.
+    #
+    # standard:disable Lint/RescueException -- the same reason as
+    # Hegel::Runner.classify: a failing assertion descends from Exception.
+    def repeat_iteration
+      @indent += REPEAT_INDENT
+      begin
+        yield
+      ensure
+        @indent -= REPEAT_INDENT
+      end
+    rescue *Hegel::FATAL_EXCEPTIONS, Hegel::StopTest, Hegel::LoopDone, Hegel::Error
+      raise
+    rescue Hegel::AssumeFailed
+      # Skips this iteration; #repeat goes on to the next one.
+    rescue Exception
+      generate_boolean
+      raise
+    end
+    # standard:enable Lint/RescueException
+
     # Runs the block with +generator+, freeing it via #string_generator_free
     # whether the block returns or raises. The one #ensure
     # #with_regex_generator/#with_email_generator/#with_url_generator/
@@ -522,7 +744,7 @@ module Hegel
     def record_draw(label, value)
       return unless @record
 
-      @entries << [:draw, name_for(label, DRAW_CALLER_DEPTH), value]
+      @entries << [:draw, name_for(label, DRAW_CALLER_DEPTH), value, @indent]
     end
 
     # The single place a draw's name is decided, tried in this order: the