hegeltest 0.1.1 → 0.2.0

data/lib/hegel/lib_hegel/real.rb

@@ -33,7 +33,7 @@ module Hegel
       end
 
       class TimeStruct < FFI::Struct
-        layout :hour, :uint8, :minute, :uint8, :second, :uint8, :microsecond, :uint32
+        layout :hour, :uint8, :minute, :uint8, :second, :uint8, :nanosecond, :uint32
       end
 
       class DatetimeStruct < FFI::Struct
@@ -95,9 +95,6 @@ module Hegel
         @hegel_settings_set_database_fn = bind(
           "hegel_settings_set_database", [:pointer, :pointer, :string], :int32
         )
-        @hegel_settings_set_stateful_step_count_fn = bind(
-          "hegel_settings_set_stateful_step_count", [:pointer, :pointer, :int64], :int32
-        )
         @hegel_settings_set_report_multiple_failures_fn = bind(
           "hegel_settings_set_report_multiple_failures", [:pointer, :pointer, :bool], :int32
         )
@@ -114,7 +111,13 @@ module Hegel
         @hegel_run_start_fn = bind(
           "hegel_run_start", [:pointer, :pointer, :pointer, :pointer, :pointer], :int32
         )
+        @hegel_run_start_blob_fn = bind(
+          "hegel_run_start_blob", [:pointer, :pointer, :string, :pointer, :pointer, :pointer], :int32
+        )
         @hegel_next_test_case_fn = bind("hegel_next_test_case", [:pointer, :pointer, :pointer], :int32)
+        @hegel_test_case_should_capture_fn = bind(
+          "hegel_test_case_should_capture", [:pointer, :pointer, :pointer], :int32
+        )
         @hegel_run_free_fn = bind("hegel_run_free", [:pointer, :pointer], :int32)
         @hegel_test_case_free_fn = bind("hegel_test_case_free", [:pointer, :pointer], :int32)
         @hegel_mark_complete_fn = bind("hegel_mark_complete", [:pointer, :pointer, :uint32, :string], :int32)
@@ -135,9 +138,7 @@ module Hegel
         @hegel_failure_reproduction_blob_fn = bind(
           "hegel_failure_reproduction_blob", [:pointer, :pointer, :pointer], :int32
         )
-        @hegel_test_case_from_blob_fn = bind(
-          "hegel_test_case_from_blob", [:pointer, :pointer, :string, :pointer, :pointer, :pointer], :int32
-        )
+        @hegel_failure_caveat_fn = bind("hegel_failure_caveat", [:pointer, :pointer, :pointer], :int32)
 
         @hegel_generate_boolean_fn = bind(
           "hegel_generate_boolean", [:pointer, :pointer, :double, :bool, :bool, :pointer], :int32
@@ -171,13 +172,22 @@ module Hegel
 
         @hegel_new_state_machine_fn = bind(
           "hegel_new_state_machine",
-          [:pointer, :pointer, :pointer, :size_t, :pointer, :size_t, :pointer], :int32
+          [
+            :pointer, :pointer, :pointer, :pointer, :pointer, :size_t, :pointer, :pointer, :size_t,
+            :int64, :int64, :int64, :pointer, :pointer
+          ], :int32
+        )
+        @hegel_state_machine_next_group_fn = bind(
+          "hegel_state_machine_next_group", [:pointer, :pointer, :pointer, :pointer], :int32
         )
         @hegel_state_machine_next_rule_fn = bind(
-          "hegel_state_machine_next_rule", [:pointer, :pointer, :pointer, :pointer], :int32
+          "hegel_state_machine_next_rule", [:pointer, :pointer, :pointer, :int64, :pointer], :int32
         )
         @hegel_state_machine_rule_rejected_fn = bind(
-          "hegel_state_machine_rule_rejected", [:pointer, :pointer, :pointer], :int32
+          "hegel_state_machine_rule_rejected", [:pointer, :pointer, :pointer, :int64], :int32
+        )
+        @hegel_state_machine_should_check_invariant_fn = bind(
+          "hegel_state_machine_should_check_invariant", [:pointer, :pointer, :pointer, :int64, :pointer], :int32
         )
         @hegel_state_machine_free_fn = bind("hegel_state_machine_free", [:pointer, :pointer], :int32)
 
@@ -213,7 +223,7 @@ module Hegel
         )
 
         @hegel_string_generator_regex_fn = bind(
-          "hegel_string_generator_regex", [:pointer, :string, :bool, :pointer, :pointer], :int32
+          "hegel_string_generator_regex", [:pointer, :pointer, :size_t, :bool, :pointer, :pointer], :int32
         )
         @hegel_string_generator_email_fn = bind("hegel_string_generator_email", [:pointer, :pointer], :int32)
         @hegel_string_generator_url_fn = bind("hegel_string_generator_url", [:pointer, :pointer], :int32)
@@ -253,7 +263,9 @@ module Hegel
       # side. The result code is not translated: the header documents this
       # call as always returning HEGEL_OK, so there is nothing to raise.
       def context_free(ctx)
-        @hegel_context_free_fn.call(ctx)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_context_free_fn.call(ctx) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -269,13 +281,16 @@ module Hegel
       def version(ctx)
         out = FFI::MemoryPointer.new(:pointer)
         code = @hegel_version_fn.call(ctx, out)
-        LibHegel.check!(self, ctx, code)
+        # This call takes only ctx and this method's own out argument; neither
+        # makes the real engine return anything but HEGEL_OK.
+        LibHegel.check!(self, ctx, code) # mutineer:disable-line statement_removal
         utf8(out.read_pointer)
       end
 
-      # Returns a settings handle initialized with libhegel's defaults, or
-      # raises the exception LibHegel.check! translates this call's result
-      # code to.
+      # Returns a settings handle initialized from the engine's resolved
+      # profile, or raises the exception LibHegel.check! translates this
+      # call's result code to. Since libhegel 0.40 the call can fail: a
+      # malformed hegel.toml or HEGEL_* variable returns HEGEL_E_INVALID_ARG.
       def settings_new(ctx)
         out = FFI::MemoryPointer.new(:pointer)
         code = @hegel_settings_new_fn.call(ctx, out)
@@ -288,7 +303,9 @@ module Hegel
       # #context_free: the header documents this call as always returning
       # HEGEL_OK.
       def settings_free(ctx, s)
-        @hegel_settings_free_fn.call(ctx, s)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_settings_free_fn.call(ctx, s) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -326,12 +343,6 @@ module Hegel
         nil
       end
 
-      def settings_set_stateful_step_count(ctx, s, n)
-        code = @hegel_settings_set_stateful_step_count_fn.call(ctx, s, n)
-        LibHegel.check!(self, ctx, code)
-        nil
-      end
-
       def settings_set_report_multiple_failures(ctx, s, yes)
         code = @hegel_settings_set_report_multiple_failures_fn.call(ctx, s, yes)
         LibHegel.check!(self, ctx, code)
@@ -374,6 +385,29 @@ module Hegel
         out.read_pointer
       end
 
+      # Like #run_start, but the run replays +blob+ (from
+      # #failure_reproduction_blob) until a replay fails, under the engine's
+      # own bounded budget. A run with no failures means the blob no longer
+      # reproduces. Raises HEGEL_E_INVALID_ARG (via LibHegel.check!) for a
+      # blob that is corrupt, non-UTF-8, or from an incompatible Hegel
+      # version.
+      def run_start_blob(ctx, settings, blob)
+        out = FFI::MemoryPointer.new(:pointer)
+        code = @hegel_run_start_blob_fn.call(ctx, settings, blob, nil, nil, out)
+        LibHegel.check!(self, ctx, code)
+        out.read_pointer
+      end
+
+      # Whether the engine stamped +tc+ for capture: a failure on a stamped
+      # case is material for that failure's report. Read once, when the
+      # case starts.
+      def test_case_should_capture(ctx, tc)
+        out = FFI::MemoryPointer.new(:bool)
+        code = @hegel_test_case_should_capture_fn.call(ctx, tc, out)
+        LibHegel.check!(self, ctx, code)
+        out.read_uint8 != 0
+      end
+
       # Returns the next test case, or nil once the run has finished (the
       # header documents *out_test_case as NULL at that point, with a
       # HEGEL_OK result rather than an error).
@@ -389,7 +423,9 @@ module Hegel
       # no-op-on-NULL contract; not translated, for the same reason as
       # #context_free.
       def run_free(ctx, run)
-        @hegel_run_free_fn.call(ctx, run)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_run_free_fn.call(ctx, run) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -397,7 +433,9 @@ module Hegel
       # no-op-on-NULL contract; not translated, for the same reason as
       # #context_free.
       def test_case_free(ctx, tc)
-        @hegel_test_case_free_fn.call(ctx, tc)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_test_case_free_fn.call(ctx, tc) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -439,7 +477,9 @@ module Hegel
       # no-op-on-NULL contract; not translated, for the same reason as
       # #context_free.
       def run_result_free(ctx, r)
-        @hegel_run_result_free_fn.call(ctx, r)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_run_result_free_fn.call(ctx, r) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -474,7 +514,7 @@ module Hegel
 
       # +index+ must be less than #run_result_failure_count's value, per the
       # header. Returns a caller-owned failure handle, released separately
-      # with #failure_free. Measured against libhegel 0.32.5: an
+      # with #failure_free. Measured against libhegel 0.45.0: an
       # out-of-range +index+ comes back HEGEL_E_INVALID_ARG, even though
       # the header's Returns line for this call names only HEGEL_OK.
       def run_result_failure(ctx, r, index)
@@ -488,7 +528,9 @@ module Hegel
       # no-op-on-NULL contract; not translated, for the same reason as
       # #context_free.
       def failure_free(ctx, f)
-        @hegel_failure_free_fn.call(ctx, f)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_failure_free_fn.call(ctx, f) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -512,28 +554,18 @@ module Hegel
         nullable_out_string(out)
       end
 
-      # Replays +blob+ (from #failure_reproduction_blob) against +settings+
-      # with no run handle and no run loop involved, per the header.
-      # callback and user_data are always NULL here, for the same reason as
-      # #run_start. +blob+ is declared :string, the same as
-      # #settings_set_database's own const char* argument. Raises
-      # HEGEL_E_INVALID_ARG (via LibHegel.check!) for a blob that is
-      # corrupt, non-UTF-8, or from an incompatible Hegel version.
-      #
-      # A blob whose choices no longer match the caller's generators is a
-      # different case, and the header places it elsewhere: it "returns
-      # HEGEL_E_STOP_TEST from the draw that overruns", so the replay is
-      # built here and fails later, inside the body. Measured against
-      # 0.32.5, replaying a two-draw blob against a five-draw body builds
-      # fine and overruns at a draw.
-      def test_case_from_blob(ctx, settings, blob)
+      # Returns how reliably +f+ reproduced under the run's nondeterministic
+      # handling, quoting the engine's own replay evidence, or nil for a
+      # deterministic failure. See #nullable_out_string for the shared
+      # ownership note.
+      def failure_caveat(ctx, f)
         out = FFI::MemoryPointer.new(:pointer)
-        code = @hegel_test_case_from_blob_fn.call(ctx, settings, blob, nil, nil, out)
+        code = @hegel_failure_caveat_fn.call(ctx, f, out)
         LibHegel.check!(self, ctx, code)
-        out.read_pointer
+        nullable_out_string(out)
       end
 
-      # Forcing has to agree with +p+. Measured against libhegel 0.32.5:
+      # Forcing has to agree with +p+. Measured against libhegel 0.45.0:
       # forcing true at p = 0.0 and forcing false at p = 1.0 both come back
       # HEGEL_E_INVALID_ARG ("generate_boolean: cannot force ..."), while
       # forcing either way succeeds at any p between them. The header
@@ -589,8 +621,8 @@ module Hegel
         LibHegel.decode_integer_le(out_value.read_bytes(len))
       end
 
-      # Opens a span labelled +label+ (one of the HEGEL_LABEL_* constants,
-      # or a caller-defined value that avoids them). Must be paired with
+      # Opens a span labelled +label+, an opaque u64 naming the generator
+      # (see LibHegel.label_from_name). Must be paired with
       # exactly one #stop_span call, per the header.
       def start_span(ctx, tc, label)
         code = @hegel_start_span_fn.call(ctx, tc, label)
@@ -643,7 +675,9 @@ module Hegel
       # call takes no test-case handle: the header documents a collection
       # as independent of the test case and run it was created under.
       def collection_free(ctx, collection)
-        @hegel_collection_free_fn.call(ctx, collection)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_collection_free_fn.call(ctx, collection) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -691,7 +725,9 @@ module Hegel
       # no-op-on-NULL contract; not translated, for the same reason as
       # #context_free.
       def pool_free(ctx, pool)
-        @hegel_pool_free_fn.call(ctx, pool)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_pool_free_fn.call(ctx, pool) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -699,12 +735,21 @@ module Hegel
       # with #state_machine_free. +rule_names+ and +invariant_names+ are
       # each an Array of Ruby Strings, packed into the const char *const *
       # arguments hegel_new_state_machine expects by #pack_name_array; see
-      # that method's own comment for how and why. Validating
-      # +rule_names+ as non-empty (the header's own requirement) is left
-      # to the caller, the same division of labor #new_collection leaves
-      # to the caller for its own min_size/max_size ordering.
-      def new_state_machine(ctx, tc, rule_names, invariant_names)
+      # that method's own comment for how and why. +always_check+ holds one
+      # flag per invariant name. Validating +rule_names+ as non-empty (the
+      # header's own requirement) is left to the caller, the same division
+      # of labor #new_collection leaves to the caller for its own
+      # min_size/max_size ordering.
+      #
+      # The machine is always sequential: one concurrency group, equal rule
+      # weights, and a concurrency of exactly 1, so the engine draws no
+      # concurrency level and the drawn level needs no reading. These
+      # bindings drive the engine from one thread, and a concurrent machine
+      # needs one worker thread per drawn level. For the same reason the
+      # rule calls below pass worker index 0, the only worker there is.
+      def new_state_machine(ctx, tc, rule_names, invariant_names, always_check, step_count)
         out = FFI::MemoryPointer.new(:pointer)
+        out_concurrency = FFI::MemoryPointer.new(:int64)
         # _rule_pointers / _invariant_pointers are unread past the call
         # below, the same shape #generate_integer_big's own
         # min_value_ptr/max_value_ptr already have; keeping them as local
@@ -714,46 +759,69 @@ module Hegel
         # same way it would for a block argument the block never reads.
         rule_names_ptr, _rule_pointers = pack_name_array(rule_names)
         invariant_names_ptr, _invariant_pointers = pack_name_array(invariant_names)
+        # A fresh MemoryPointer is zero-filled, which puts every rule in
+        # group 0.
+        rule_groups = FFI::MemoryPointer.new(:int64, rule_names.size)
 
         code = @hegel_new_state_machine_fn.call(
-          ctx, tc, rule_names_ptr, rule_names.size, invariant_names_ptr, invariant_names.size, out
+          ctx, tc, rule_names_ptr, rule_groups, nil, rule_names.size,
+          invariant_names_ptr, pack_flags(always_check), invariant_names.size,
+          1, 1, step_count, out, out_concurrency
         )
         LibHegel.check!(self, ctx, code)
         out.read_pointer
       end
 
-      # Returns the index (in 0...num_rules) of the next stateful-testing
-      # rule to run, or HEGEL_STATE_MACHINE_DONE (-1) once +state_machine+'s
-      # step budget is exhausted -- returned as the raw sentinel value, not
-      # translated to nil. Unlike #next_test_case's out-parameter, which is
-      # NULL (no value) at the equivalent boundary, the header documents
-      # this out-parameter as holding a real value, -1, at that point; a
-      # caller comparing against HEGEL_STATE_MACHINE_DONE is the layer that
-      # should decide what that value means, the same way #run_result_status
-      # hands back its raw HEGEL_RUN_STATUS_* value unexamined.
+      # Starts the machine's next round. Returns the round's group id, or
+      # HEGEL_STATE_MACHINE_DONE once the machine is done, as the raw
+      # value: the caller compares against the sentinel, the same way
+      # #run_result_status hands back its raw HEGEL_RUN_STATUS_* value
+      # unexamined.
+      def state_machine_next_group(ctx, tc, state_machine)
+        out = FFI::MemoryPointer.new(:int64)
+        code = @hegel_state_machine_next_group_fn.call(ctx, tc, state_machine, out)
+        LibHegel.check!(self, ctx, code)
+        out.read_int64
+      end
+
+      # Returns the index (in 0...num_rules) of the next rule to run this
+      # round, or HEGEL_STATE_MACHINE_DONE once the round is over, as the
+      # raw value for the reason #state_machine_next_group gives.
       def state_machine_next_rule(ctx, tc, state_machine)
         out = FFI::MemoryPointer.new(:int64)
-        code = @hegel_state_machine_next_rule_fn.call(ctx, tc, state_machine, out)
+        code = @hegel_state_machine_next_rule_fn.call(ctx, tc, state_machine, 0, out)
         LibHegel.check!(self, ctx, code)
         out.read_int64
       end
 
       # Reports the rule most recently returned by #state_machine_next_rule
-      # as rejected (an assumption failed before it completed), so it does
-      # not count toward the step budget. Raises HEGEL_E_INVALID_ARG (via
-      # LibHegel.check!, translated to Hegel::Error) when no rule is
+      # as rejected (an assumption failed before it completed), so its round
+      # does not count toward the step budget. Raises HEGEL_E_INVALID_ARG
+      # (via LibHegel.check!, translated to Hegel::Error) when no rule is
       # outstanding, per the header.
       def state_machine_rule_rejected(ctx, tc, state_machine)
-        code = @hegel_state_machine_rule_rejected_fn.call(ctx, tc, state_machine)
+        code = @hegel_state_machine_rule_rejected_fn.call(ctx, tc, state_machine, 0)
         LibHegel.check!(self, ctx, code)
         nil
       end
 
+      # Whether to run the invariant at +index+ at this join point: always
+      # true for an invariant flagged at creation, otherwise a recorded draw
+      # that is true with probability 1 / step_count.
+      def state_machine_should_check_invariant(ctx, tc, state_machine, index)
+        out = FFI::MemoryPointer.new(:bool)
+        code = @hegel_state_machine_should_check_invariant_fn.call(ctx, tc, state_machine, index, out)
+        LibHegel.check!(self, ctx, code)
+        out.read_uint8 != 0
+      end
+
       # No-op when +state_machine+ is nil, matching
       # hegel_state_machine_free's documented no-op-on-NULL contract; not
       # translated, for the same reason as #context_free.
       def state_machine_free(ctx, state_machine)
-        @hegel_state_machine_free_fn.call(ctx, state_machine)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_state_machine_free_fn.call(ctx, state_machine) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -793,7 +861,9 @@ module Hegel
       # hegel_string_generator_free's documented no-op-on-NULL contract;
       # not translated, for the same reason as #context_free.
       def string_generator_free(ctx, generator)
-        @hegel_string_generator_free_fn.call(ctx, generator)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_string_generator_free_fn.call(ctx, generator) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -828,7 +898,9 @@ module Hegel
       # contract (also safe on an already-freed, zeroed struct); not
       # translated, for the same reason as #context_free.
       def generate_string_result_free(ctx, result)
-        @hegel_generate_string_result_free_fn.call(ctx, result)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_generate_string_result_free_fn.call(ctx, result) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -864,7 +936,9 @@ module Hegel
       # contract (also safe on an already-freed, zeroed struct); not
       # translated, for the same reason as #context_free.
       def generate_bytes_result_free(ctx, result)
-        @hegel_generate_bytes_result_free_fn.call(ctx, result)
+        # Removing this call only leaks native memory; Ruby has no way to
+        # observe the leak.
+        @hegel_generate_bytes_result_free_fn.call(ctx, result) # mutineer:disable-line statement_removal
         nil
       end
 
@@ -874,10 +948,15 @@ module Hegel
       # generator handle (built via #string_generator_text, scoped with
       # Hegel::TestCase#with_text_generator) whose character set constrains the
       # padding and wildcard characters; nil (the default) marshals to NULL,
-      # the header's documented "no particular alphabet" case.
+      # the header's documented "no particular alphabet" case. The pattern
+      # goes over as UTF-8 bytes with a length rather than as a C string, so
+      # a NUL character in it reaches the engine instead of ending it.
       def string_generator_regex(ctx, pattern, fullmatch, alphabet = nil)
         out = FFI::MemoryPointer.new(:pointer)
-        code = @hegel_string_generator_regex_fn.call(ctx, pattern, fullmatch, alphabet, out)
+        bytes = pattern.encode(Encoding::UTF_8)
+        code = @hegel_string_generator_regex_fn.call(
+          ctx, bytes_to_pointer(bytes), bytes.bytesize, fullmatch, alphabet, out
+        )
         LibHegel.check!(self, ctx, code)
         out.read_pointer
       end
@@ -888,7 +967,9 @@ module Hegel
       def string_generator_email(ctx)
         out = FFI::MemoryPointer.new(:pointer)
         code = @hegel_string_generator_email_fn.call(ctx, out)
-        LibHegel.check!(self, ctx, code)
+        # This call takes only ctx and this method's own out argument; neither
+        # makes the real engine return anything but HEGEL_OK.
+        LibHegel.check!(self, ctx, code) # mutineer:disable-line statement_removal
         out.read_pointer
       end
 
@@ -897,7 +978,9 @@ module Hegel
       def string_generator_url(ctx)
         out = FFI::MemoryPointer.new(:pointer)
         code = @hegel_string_generator_url_fn.call(ctx, out)
-        LibHegel.check!(self, ctx, code)
+        # This call takes only ctx and this method's own out argument; neither
+        # makes the real engine return anything but HEGEL_OK.
+        LibHegel.check!(self, ctx, code) # mutineer:disable-line statement_removal
         out.read_pointer
       end
 
@@ -947,7 +1030,7 @@ module Hegel
       # 8-4-4-4-12 hex String is left to Hegel::Generators::UuidsGenerator,
       # the same division of labor #generate_ipv4/#generate_ipv6 already
       # follow for their own byte-to-address conversion. An out-of-range
-      # +version+ is not checked here: measured against libhegel 0.32.5, the
+      # +version+ is not checked here: measured against libhegel 0.45.0, the
       # engine itself returns HEGEL_E_INVALID_ARG for one, which
       # LibHegel.check! already translates.
       def generate_uuid(ctx, tc, version, has_version)
@@ -965,7 +1048,7 @@ module Hegel
       # the same division of labor #generate_ipv4/#generate_uuid already
       # follow, returning raw values for a generator one layer up to turn
       # into the caller-facing type. This layer does not validate
-      # year/month/day itself: measured against libhegel 0.32.5, an
+      # year/month/day itself: measured against libhegel 0.45.0, an
       # invalid date (month 13, say) already comes back
       # HEGEL_E_INVALID_ARG, translated by LibHegel.check! below, even
       # though the header's Returns line for this call names only
@@ -979,7 +1062,7 @@ module Hegel
       end
 
       # hegel_generate_time. +min_value+/+max_value+ are each an
-      # [hour, minute, second, microsecond] Array; same struct-passing,
+      # [hour, minute, second, nanosecond] Array; same struct-passing,
       # return shape, and validation division of labor as #generate_date
       # above, for Hegel::Generators::TimesGenerator.
       def generate_time(ctx, tc, min_value, max_value)
@@ -991,10 +1074,10 @@ module Hegel
 
       # hegel_generate_datetime. +min_date+/+max_date+ are each a
       # [year, month, day] Array; +min_time+/+max_time+ are each an
-      # [hour, minute, second, microsecond] Array -- hegel_datetime_t is a
+      # [hour, minute, second, nanosecond] Array -- hegel_datetime_t is a
       # hegel_date_t followed by a hegel_time_t (see DatetimeStruct's own
       # layout, above #initialize). Returns a
-      # [[year, month, day], [hour, minute, second, microsecond]] pair, for
+      # [[year, month, day], [hour, minute, second, nanosecond]] pair, for
       # Hegel::Generators::DatetimesGenerator to build its own Time from.
       def generate_datetime(ctx, tc, min_date, min_time, max_date, max_time)
         out = DatetimeStruct.new
@@ -1011,7 +1094,12 @@ module Hegel
       # FFI::Function, the direct form #initialize's own comment explains
       # the choice of.
       def bind(symbol, arg_types, ret_type)
-        FFI::Function.new(ret_type, arg_types, @handle.find_function(symbol))
+        # find_function answers nil for a symbol the library lacks, and
+        # FFI::Function.new then fails with a TypeError that names no
+        # symbol. An engine built from another release is the usual cause.
+        function = @handle.find_function(symbol) or
+          raise Hegel::Error, "libhegel has no #{symbol}; these bindings need libhegel #{Hegel::LIBHEGEL_VERSION}"
+        FFI::Function.new(ret_type, arg_types, function)
       end
 
       # Copies +bytes+ into a freshly allocated buffer, for
@@ -1050,7 +1138,9 @@ module Hegel
       # factory method, not in a method whose only job is packing an
       # Array into a buffer.
       def pack_name_array(names)
-        return [nil, []] if names.empty?
+        # An empty array acts the same as NULL with length 0:
+        # hegel_new_state_machine reads zero names either way.
+        return [nil, []] if names.empty? # mutineer:disable-line statement_removal
 
         pointers = names.map { |name| FFI::MemoryPointer.from_string(name) }
         array = FFI::MemoryPointer.new(:pointer, names.size)
@@ -1058,6 +1148,15 @@ module Hegel
         [array, pointers]
       end
 
+      # Packs +flags+ (an Array of true/false) into a const bool * buffer,
+      # one byte each. An empty Array packs to a zero-length buffer, which the
+      # engine reads zero flags from.
+      def pack_flags(flags)
+        buffer = FFI::MemoryPointer.new(:uint8, flags.size)
+        buffer.write_array_of_uint8(flags.map { |flag| flag ? 1 : 0 })
+        buffer
+      end
+
       # Writes +value+ (a [year, month, day] Array) into +struct+'s own
       # :year/:month/:day fields. Shared by #date_struct, which builds a
       # standalone DateStruct, and #datetime_struct, which writes the same
@@ -1072,13 +1171,13 @@ module Hegel
       end
 
       # The #write_date/#date_struct counterpart for a [hour, minute,
-      # second, microsecond] Array.
+      # second, nanosecond] Array.
       def write_time(struct, value)
-        hour, minute, second, microsecond = value
+        hour, minute, second, nanosecond = value
         struct[:hour] = hour
         struct[:minute] = minute
         struct[:second] = second
-        struct[:microsecond] = microsecond
+        struct[:nanosecond] = nanosecond
       end
 
       # A standalone DateStruct built from +value+, for #generate_date's
@@ -1118,16 +1217,16 @@ module Hegel
       end
 
       # The #read_date counterpart for a struct's :hour/:minute/:second/
-      # :microsecond fields.
+      # :nanosecond fields.
       def read_time(struct)
-        [struct[:hour], struct[:minute], struct[:second], struct[:microsecond]]
+        [struct[:hour], struct[:minute], struct[:second], struct[:nanosecond]]
       end
 
       # Reads +out+'s const char* out-parameter into a Ruby String, or
-      # returns nil if libhegel left it NULL. Shared by #run_result_error
-      # and #failure_reproduction_blob, the two out-parameters the header
-      # documents as nullable, so both branches only need to be exercised
-      # once between the two call sites rather than at each one.
+      # returns nil if libhegel left it NULL. Shared by #run_result_error,
+      # #failure_reproduction_blob, and #failure_caveat, the out-parameters
+      # the header documents as nullable, so both branches only need to be
+      # exercised once between the call sites rather than at each one.
       def nullable_out_string(out)
         ptr = out.read_pointer
         ptr.null? ? nil : utf8(ptr)