hegeltest 0.1.0 → 0.2.0

data/lib/hegel/stateful.rb

@@ -21,64 +21,84 @@ module Hegel
   module Stateful
     module_function
 
+    # The span label of one round, which at concurrency 1 runs one rule.
+    ROUND_LABEL = LibHegel.label_from_name("hegel-ruby.Hegel::Stateful.round")
+
+    # hegel-rust, hegel-go, and hegel-java all default a machine's step count
+    # to 50. The engine has no default of its own.
+    DEFAULT_STEP_COUNT = 50
+
     # +machine+ is a Hegel::StateMachine instance; +tc+ the running
-    # Hegel::TestCase.
+    # Hegel::TestCase. +step_count+ is the most rounds, and so the most
+    # rules, one test case runs. It must be at least 1, or the engine
+    # rejects it.
     #
     # Raises Hegel::Error before making any libhegel call when +machine+
     # declares no rules: hegel.h documents hegel_new_state_machine's
     # rule_names as required to be non-empty, and there is nothing useful to
     # run without one.
-    def run(machine, tc)
+    def run(machine, tc, step_count: DEFAULT_STEP_COUNT)
       rules = machine.class.rule_definitions
       raise Hegel::Error, "hegel: #{machine.class} has no rules; declare at least one with `rule`" if rules.empty?
 
       invariants = machine.class.invariant_definitions
-      rule_names = rules.keys
-      state_machine = tc.new_state_machine(rule_names, invariants.keys)
+      state_machine = tc.new_state_machine(
+        rules.keys, invariants.keys, invariants.values.map(&:always_run), step_count
+      )
       begin
         tc.note { "Initial invariant check." }
-        run_invariants(machine, invariants, tc)
-        drive(machine, rules, rule_names, invariants, state_machine, tc)
+        run_invariants(machine, invariants.values, tc)
+        drive(machine, rules, invariants.values, state_machine, tc)
+        tc.note { "Final invariant check." }
+        run_invariants(machine, invariants.values, tc)
       ensure
         tc.state_machine_free(state_machine)
       end
     end
 
-    # Repeatedly asks +state_machine+ for the next rule to run and applies
-    # it, until libhegel reports the step budget for this test case spent.
-    #
-    # Measured against libhegel 0.32.5, unseeded, on the capacity-2 stack
-    # shrink-quality test below (test/hegel/test_stateful.rb,
-    # test_stateful_run_shrinks_to_the_minimal_step_count_that_breaks_the_
-    # invariant): closing the HEGEL_LABEL_STATEFUL_RULE span with
-    # stop_span(discard: false) on the DONE branch, right before breaking
-    # out of this loop, and leaving it open instead (matching hegel-rust's
-    # own `run`, which never closes that last span) both shrink the same
-    # failure to the same 3-step counterexample every time, 20 runs each.
-    # This keeps hegel-rust's own choice -- an unclosed span at DONE --
-    # since nothing measured favours the extra stop_span call.
-    def drive(machine, rules, rule_names, invariants, state_machine, tc)
+    # Runs rounds until libhegel ends the machine. Each round asks for a
+    # group first, which the header requires before the first rule too, then
+    # pulls rules until the round ends. Between rounds, each invariant runs
+    # only when the engine samples it (see
+    # Hegel::TestCase#state_machine_should_check_invariant), as hegel-rust,
+    # hegel-go, and hegel-java do. The initial and final checks in #run are
+    # the ones that always happen.
+    def drive(machine, rules, invariants, state_machine, tc)
+      rule_names = rules.keys
       steps_attempted = 0
       loop do
-        tc.start_span(LibHegel::HEGEL_LABEL_STATEFUL_RULE)
-        rule_index = tc.state_machine_next_rule(state_machine)
-        break if rule_index == LibHegel::HEGEL_STATE_MACHINE_DONE
+        tc.start_span(ROUND_LABEL)
+        if tc.state_machine_next_group(state_machine) == LibHegel::HEGEL_STATE_MACHINE_DONE
+          tc.stop_span(discard: false)
+          break
+        end
+
+        rejected = false
+        loop do
+          rule_index = tc.state_machine_next_rule(state_machine)
+          break if rule_index == LibHegel::HEGEL_STATE_MACHINE_DONE
 
-        name = rule_names[rule_index]
-        steps_attempted += 1
-        tc.note { "Step #{steps_attempted}: #{name}" }
-        apply_rule(machine, rules.fetch(name), invariants, state_machine, tc)
+          name = rule_names[rule_index]
+          steps_attempted += 1
+          tc.note { "Step #{steps_attempted}: #{name}" }
+          rejected = true unless apply_rule(machine, rules.fetch(name), state_machine, tc)
+        end
+        tc.stop_span(discard: rejected)
+        run_sampled_invariants(machine, invariants, state_machine, tc)
       end
     end
 
+    # Returns false when the rule stopped on a failed assumption, and true
+    # when it completed.
+    #
     # standard:disable Lint/RescueException -- deliberate, the same reason
     # Hegel::Runner.classify's own `rescue Exception` is: Hegel::AssumeFailed
     # and Hegel::StopTest both descend from Exception, not StandardError, so
     # only `rescue Exception` sees every path a rule can take. Every branch
     # other than AssumeFailed re-raises what it caught unchanged -- this
     # never reclassifies an exception or swallows one, it only guarantees
-    # the span closes first, so a half-applied rule is never left mid-span
-    # when the exception unwinds past this method.
+    # the round's span closes first, so a half-applied rule is never left
+    # mid-span when the exception unwinds past this method.
     #
     # Hegel::FATAL_EXCEPTIONS goes first and closes no span. They say the
     # process is ending, so the span has no reader left to matter to, and
@@ -89,32 +109,40 @@ module Hegel
     #
     # tc.assume(false) inside a rule is not the same event as one raised
     # directly inside a Hegel.test block: it rejects only this rule (told to
-    # libhegel via #state_machine_rule_rejected, so the rejected attempt
+    # libhegel via #state_machine_rule_rejected, so the rejected round
     # does not count toward the step budget) and the loop keeps going, where
     # Hegel::Runner.classify's own AssumeFailed handling discards the whole
     # test case. Hegel::Runner.classify never sees this one: it is caught
     # and handled right here.
-    def apply_rule(machine, block, invariants, state_machine, tc)
+    def apply_rule(machine, block, state_machine, tc)
       machine.instance_exec(tc, &block)
+      true
     rescue *Hegel::FATAL_EXCEPTIONS
       raise
     rescue Hegel::AssumeFailed
       tc.state_machine_rule_rejected(state_machine)
-      tc.stop_span(discard: true)
       tc.note { "Rule stopped early due to violated assumption." }
+      false
     rescue Exception
       tc.stop_span(discard: false)
       raise
-    else
-      tc.stop_span(discard: false)
-      run_invariants(machine, invariants, tc)
     end
     # standard:enable Lint/RescueException
 
     # Runs every invariant, in declaration order, via #instance_exec -- same
     # argument contract as a rule block (Hegel::StateMachine.invariant).
     def run_invariants(machine, invariants, tc)
-      invariants.each_value { |block| machine.instance_exec(tc, &block) }
+      invariants.each { |invariant| machine.instance_exec(tc, &invariant.block) }
+    end
+
+    # Runs each invariant the engine samples at this join point, in
+    # declaration order.
+    def run_sampled_invariants(machine, invariants, state_machine, tc)
+      invariants.each_with_index do |invariant, index|
+        next unless tc.state_machine_should_check_invariant(state_machine, index)
+
+        machine.instance_exec(tc, &invariant.block)
+      end
     end
   end
 end

data/lib/hegel/syntax/methods.rb

@@ -25,8 +25,9 @@ module Hegel
       end
 
       # A double in [min_value, max_value]. allow_nan and allow_infinity
-      # both default to false.
-      def floats(min_value: nil, max_value: nil, allow_nan: false, allow_infinity: false, exclude_min: false,
+      # default to what the bounds imply: NaN when the caller passed
+      # neither bound, an infinity when the caller left either side open.
+      def floats(min_value: nil, max_value: nil, allow_nan: nil, allow_infinity: nil, exclude_min: false,
         exclude_max: false)
         Generators::FloatGenerator.new(
           min_value: min_value, max_value: max_value, allow_nan: allow_nan, allow_infinity: allow_infinity,

data/lib/hegel/test_case.rb

@@ -25,6 +25,12 @@ module Hegel
     # #name_for's fallback when a draw has no better name (see below).
     DEFAULT_DRAW_NAME = "draw"
 
+    # The method names that reach #record_draw: #draw_integer, #draw_boolean,
+    # and #draw below. Hegel::DrawName.for takes this as an argument rather
+    # than knowing the list itself, so that class -- not DrawName -- stays
+    # the one place a fourth draw method needs to be added.
+    DRAW_METHOD_NAMES = [:draw, :draw_integer, :draw_boolean].freeze
+
     # Frames from #name_for's own caller_locations call up to the user's own
     # source line: #record_draw's call to #name_for (1), the public
     # draw_integer/draw_boolean/draw call to #record_draw (2), and the
@@ -166,6 +172,9 @@ module Hegel
     # BooleanGenerator's own primitive; #draw_boolean is this plus
     # recording.
     def generate_boolean(p = 0.5)
+      # 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)
     end
 
@@ -214,8 +223,8 @@ module Hegel
       @impl.target(@ctx, @handle, value, label)
     end
 
-    # hegel_start_span, labelled with one of the Hegel::LibHegel::
-    # HEGEL_LABEL_* constants. Every compound Hegel::Generator (map, filter,
+    # 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)
@@ -422,25 +431,36 @@ 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)
-      @impl.new_state_machine(@ctx, @handle, rule_names, invariant_names)
+    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)
+    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)
     end
 
     # hegel_state_machine_next_rule: the index (into the +rule_names+
-    # #new_state_machine was given) of the next rule to run, or
-    # LibHegel::HEGEL_STATE_MACHINE_DONE once this test case's step budget
-    # is spent.
+    # #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)
     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 it does not count toward the step budget.
+    # 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)
     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)
+    end
+
     # hegel_state_machine_free. Takes no test-case handle, unlike every
     # other #state_machine_* method here: the header documents a
     # state-machine handle as freeable through any handle of the same
@@ -517,7 +537,7 @@ module Hegel
       return label if label
 
       location = caller_locations(depth, 1)&.first
-      (location && DrawName.for(location.path, location.lineno)) || DEFAULT_DRAW_NAME
+      (location && DrawName.for(location.path, location.lineno, DRAW_METHOD_NAMES)) || DEFAULT_DRAW_NAME
     end
   end
 end

data/lib/hegel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hegel
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/hegel.rb

@@ -31,11 +31,11 @@ module Hegel
   # +test_cases+, +seed+, +derandomize+, +verbosity+, +phases+, and
   # +suppress_health_check+ all default to nil, which means the same thing
   # for each of them: do not call the matching libhegel setter, and let the
-  # engine's own default apply instead. See Hegel::Settings for the
-  # keyword-to-setter mapping, the verbosity Symbols it accepts, and the
-  # +phases+/+suppress_health_check+ Symbols each of those two accepts (as
-  # an Array; an empty Array raises Hegel::Error rather than silently
-  # meaning "none"). +verbosity: :quiet+ also silences the failure report
+  # engine's resolved settings profile apply instead (see docs/adr/0023).
+  # See Hegel::Settings for the keyword-to-setter mapping, the verbosity
+  # Symbols it accepts, and the +phases+/+suppress_health_check+ Symbols
+  # each of those two accepts (as an Array; an empty Array raises
+  # Hegel::Error rather than silently meaning "none"). +verbosity: :quiet+ also silences the failure report
   # itself, not just libhegel's own progress output.
   #
   # +database+ and +database_key+ opt a run into libhegel's example
@@ -51,14 +51,8 @@ module Hegel
   # behind it.
   #
   # +report_multiple_failures+ defaults to false, not nil, unlike every
-  # keyword above: see Hegel::Runner.run's own comment for why departing
-  # from libhegel's own default (true) is itself the decision here.
-  #
-  # +stateful_step_count+ bounds how many rules a Hegel::Stateful.run call
-  # applies per test case; left nil (the default) leaves libhegel's own
-  # default of 50 in place. hegel.h documents it as needing to be at least
-  # 1; like +tc.target+'s label, that requirement is left to the engine
-  # rather than re-checked here.
+  # keyword above: see Hegel::Runner.run's own comment for why it is always
+  # passed.
   #
   # +output+ (default $stderr) is where a failure report is written; a
   # caller passes its own IO to capture that report instead (tests do).
@@ -73,12 +67,12 @@ module Hegel
   # (#default_impl) only runs when +impl+ is not given, so a test that does
   # pass one never opens the native library at all.
   def test(test_cases: nil, seed: nil, derandomize: nil, verbosity: nil, database: nil, database_key: nil,
-    phases: nil, suppress_health_check: nil, report_multiple_failures: false, stateful_step_count: nil,
-    output: $stderr, reproduce_failure: nil, impl: default_impl, &block)
+    phases: nil, suppress_health_check: nil, report_multiple_failures: false, output: $stderr,
+    reproduce_failure: nil, impl: default_impl, &block)
     Runner.run(impl: impl, test_cases: test_cases, seed: seed, derandomize: derandomize, verbosity: verbosity,
       database: database, database_key: database_key, phases: phases, suppress_health_check: suppress_health_check,
-      report_multiple_failures: report_multiple_failures, stateful_step_count: stateful_step_count, output: output,
-      reproduce_failure: reproduce_failure, &block)
+      report_multiple_failures: report_multiple_failures, output: output, reproduce_failure: reproduce_failure,
+      &block)
   end
 
   # The Hegel::LibHegel::Real instance #test uses by default, built once and

data/lib/tasks/libhegel.rake

@@ -18,6 +18,13 @@ module Hegel
 
     module_function
 
+    # Since libhegel 0.42.1, hegel-rust tags an engine release
+    # libhegel-v<version>. The plain v<version> tags belong to its hegeltest
+    # crate, whose version numbers differ from the engine's.
+    def release_base(version)
+      "#{RELEASE_BASE}/libhegel-v#{version}"
+    end
+
     # Fetches the host's pinned asset into <root>/<version>/<asset>,
     # skipping the download if it is already there. `downloader` is
     # injectable so the orchestration (skip-if-present, checksum parsing,
@@ -29,7 +36,7 @@ module Hegel
       dest = File.join(root, version, asset)
       return dest if File.file?(dest)
 
-      base = "#{RELEASE_BASE}/v#{version}"
+      base = release_base(version)
       bytes = downloader.call("#{base}/#{asset}")
       checksum_line = downloader.call("#{base}/#{asset}.sha256")
       verify_and_install(bytes, expected_sha256(checksum_line), dest)
@@ -66,7 +73,7 @@ module Hegel
     # each published platform just to have asset_name recompute the asset
     # name it already is.
     def fetch_all_assets(version: Hegel::LIBHEGEL_VERSION, root: DEFAULT_ROOT, downloader: method(:http_get))
-      base = "#{RELEASE_BASE}/v#{version}"
+      base = release_base(version)
       Hegel::Locate::ASSET_NAMES.values.map do |asset|
         dest = File.join(root, version, asset)
         next dest if File.file?(dest)

data/sig/hegel.rbs

@@ -12,11 +12,12 @@ module Hegel
   class AssumeFailed < Exception
   end
 
-  def self.test: (?test_cases: Integer?, ?seed: Integer?, ?derandomize: bool?, ?verbosity: Symbol?, ?database: String?, ?database_key: String?, ?phases: Array[Symbol]?, ?suppress_health_check: Array[Symbol]?, ?report_multiple_failures: bool, ?stateful_step_count: Integer?, ?output: untyped, ?reproduce_failure: String?, ?impl: untyped) { (TestCase) -> void } -> nil
+  def self.test: (?test_cases: Integer?, ?seed: Integer?, ?derandomize: bool?, ?verbosity: Symbol?, ?database: String?, ?database_key: String?, ?phases: Array[Symbol]?, ?suppress_health_check: Array[Symbol]?, ?report_multiple_failures: bool, ?output: untyped, ?reproduce_failure: String?, ?impl: untyped) { (TestCase) -> void } -> nil
   def self.default_impl: () -> untyped
 
   class TestCase
     DEFAULT_DRAW_NAME: String
+    DRAW_METHOD_NAMES: Array[Symbol]
     DRAW_CALLER_DEPTH: Integer
 
     def initialize: (untyped impl, untyped ctx, untyped handle, ?record: bool) -> void
@@ -61,14 +62,19 @@ module Hegel
     def pool_generate: (untyped pool, bool consume) -> Integer
     def pool_free: (untyped pool) -> nil
     def free_pools: () -> void
-    def new_state_machine: (Array[String] rule_names, Array[String] invariant_names) -> untyped
+    def new_state_machine: (Array[String] rule_names, Array[String] invariant_names, Array[bool] always_check, Integer step_count) -> untyped
+    def state_machine_next_group: (untyped state_machine) -> Integer
     def state_machine_next_rule: (untyped state_machine) -> Integer
     def state_machine_rule_rejected: (untyped state_machine) -> nil
+    def state_machine_should_check_invariant: (untyped state_machine, Integer index) -> bool
     def state_machine_free: (untyped state_machine) -> nil
   end
 
   class Generator
+    def self.label: () -> Integer
+    def self.label_of: (untyped part) -> Integer
     def do_draw: (untyped tc) -> untyped
+    def label: () -> Integer
     def map: () { (untyped) -> untyped } -> Generator
     def filter: () { (untyped) -> boolish } -> Generator
 
@@ -86,6 +92,9 @@ module Hegel
   end
 
   module Generators
+    def self.first_nanosecond: (Array[Integer] parts) -> Array[Integer]
+    def self.last_nanosecond: (Array[Integer] parts) -> Array[Integer]
+
     class BooleanGenerator < Generator
       def initialize: (p: Float) -> void
       def do_draw: (untyped tc) -> bool
@@ -102,7 +111,7 @@ module Hegel
     class FloatGenerator < Generator
       WIDTH: Integer
 
-      def initialize: (min_value: Float?, max_value: Float?, allow_nan: bool, allow_infinity: bool, exclude_min: bool, exclude_max: bool) -> void
+      def initialize: (min_value: Float?, max_value: Float?, allow_nan: bool?, allow_infinity: bool?, exclude_min: bool, exclude_max: bool) -> void
       def do_draw: (untyped tc) -> Float
     end
 
@@ -157,6 +166,7 @@ module Hegel
     end
 
     class HashGenerator < Generator
+      ENTRY_LABEL: Integer
       def initialize: (Generator keys, Generator values, min_size: Integer, max_size: Integer?) -> void
       def do_draw: (untyped tc) -> Hash[untyped, untyped]
 
@@ -262,16 +272,26 @@ module Hegel
     include Syntax::Methods
 
     def self.rule: (Symbol | String name) { (TestCase) -> untyped } -> void
-    def self.invariant: (Symbol | String name) { (TestCase) -> untyped } -> void
+    def self.invariant: (Symbol | String name, ?always_run: bool) { (TestCase) -> untyped } -> void
     def self.rule_definitions: () -> Hash[String, Proc]
-    def self.invariant_definitions: () -> Hash[String, Proc]
+    def self.invariant_definitions: () -> Hash[String, Invariant]
+
+    class Invariant
+      attr_reader block: Proc
+      attr_reader always_run: bool
+      def initialize: (block: Proc, always_run: bool) -> void
+    end
   end
 
   module Stateful
-    def self.run: (StateMachine machine, TestCase tc) -> void
-    def self.drive: (StateMachine machine, Hash[String, Proc] rules, Array[String] rule_names, Hash[String, Proc] invariants, untyped state_machine, TestCase tc) -> void
-    def self.apply_rule: (StateMachine machine, Proc block, Hash[String, Proc] invariants, untyped state_machine, TestCase tc) -> void
-    def self.run_invariants: (StateMachine machine, Hash[String, Proc] invariants, TestCase tc) -> void
+    ROUND_LABEL: Integer
+    DEFAULT_STEP_COUNT: Integer
+
+    def self.run: (StateMachine machine, TestCase tc, ?step_count: Integer) -> void
+    def self.drive: (StateMachine machine, Hash[String, Proc] rules, Array[StateMachine::Invariant] invariants, untyped state_machine, TestCase tc) -> void
+    def self.apply_rule: (StateMachine machine, Proc block, untyped state_machine, TestCase tc) -> bool
+    def self.run_invariants: (StateMachine machine, Array[StateMachine::Invariant] invariants, TestCase tc) -> void
+    def self.run_sampled_invariants: (StateMachine machine, Array[StateMachine::Invariant] invariants, untyped state_machine, TestCase tc) -> void
 
     class Pool
       def initialize: (TestCase tc) -> void
@@ -297,7 +317,7 @@ module Hegel
     module Methods
       def booleans: (?p: Float) -> Generators::BooleanGenerator
       def integers: (?min_value: Integer?, ?max_value: Integer?) -> Generators::IntegerGenerator
-      def floats: (?min_value: Float?, ?max_value: Float?, ?allow_nan: bool, ?allow_infinity: bool, ?exclude_min: bool, ?exclude_max: bool) -> Generators::FloatGenerator
+      def floats: (?min_value: Float?, ?max_value: Float?, ?allow_nan: bool?, ?allow_infinity: bool?, ?exclude_min: bool, ?exclude_max: bool) -> Generators::FloatGenerator
       def text: (?min_size: Integer, ?max_size: Integer?, ?codec: String?, ?min_codepoint: Integer?, ?max_codepoint: Integer?) -> Generators::TextGenerator
       def arrays: (Generator elements, ?min_size: Integer, ?max_size: Integer?) -> Generators::ArrayGenerator
       def just: (untyped value) -> Generators::JustGenerator
@@ -326,7 +346,7 @@ module Hegel
   module DrawName
     ASSIGNMENT_NODE_TYPES: Array[untyped]
 
-    def self.for: (String path, Integer lineno) -> String?
+    def self.for: (String path, Integer lineno, Array[Symbol] call_names) -> String?
     def self.reset_cache: () -> void
     def self.parse: (String path) -> untyped
     def self.cache: () -> Hash[String, untyped]
@@ -337,11 +357,12 @@ module Hegel
 
   module Report
     class Failure
-      def initialize: (test_cases: Integer, discarded: Integer, entries: Array[[:draw, String, untyped] | [:note, untyped]], blob: String) -> void
+      def initialize: (test_cases: Integer, discarded: Integer, entries: Array[[:draw, String, untyped] | [:note, untyped]], blob: String?, caveat: String?) -> void
       def test_cases: () -> Integer
       def discarded: () -> Integer
       def entries: () -> Array[[:draw, String, untyped] | [:note, untyped]]
-      def blob: () -> String
+      def blob: () -> String?
+      def caveat: () -> String?
     end
 
     def self.assign_names: (Array[[:draw, String, untyped] | [:note, untyped]] entries) -> Array[[:draw, String, untyped] | [:note, untyped]]
@@ -354,7 +375,7 @@ module Hegel
     PHASE_CODES: Hash[Symbol, Integer]
     HEALTH_CHECK_CODES: Hash[Symbol, Integer]
 
-    def self.apply: (untyped impl, untyped ctx, untyped settings, test_cases: Integer?, seed: Integer?, derandomize: bool?, verbosity: Symbol?, database: String?, database_key: String?, phases: Array[Symbol]?, suppress_health_check: Array[Symbol]?, report_multiple_failures: bool, stateful_step_count: Integer?) -> void
+    def self.apply: (untyped impl, untyped ctx, untyped settings, test_cases: Integer?, seed: Integer?, derandomize: bool?, verbosity: Symbol?, database: String?, database_key: String?, phases: Array[Symbol]?, suppress_health_check: Array[Symbol]?, report_multiple_failures: bool) -> void
     def self.apply_verbosity: (untyped impl, untyped ctx, untyped settings, Symbol verbosity) -> void
     def self.apply_database: (untyped impl, untyped ctx, untyped settings, database: String?, database_key: String?) -> void
     def self.apply_phases: (untyped impl, untyped ctx, untyped settings, Array[Symbol] phases) -> void
@@ -370,25 +391,31 @@ module Hegel
     INSTALLED_GEM_DIRS: Array[String]
     STDLIB_DIR: String
 
+    class Capture
+      attr_reader exception: Exception
+      attr_reader entries: Array[[:draw, String, untyped] | [:note, untyped]]?
+      def initialize: (Exception exception, Array[[:draw, String, untyped] | [:note, untyped]]? entries) -> void
+    end
+
     class GenerationStats
       def initialize: () -> void
       def record: (Integer status, String? origin) -> void
       def for: (String? origin) -> [Integer, Integer]
     end
 
-    def self.run: (impl: untyped, ?test_cases: Integer?, ?seed: Integer?, ?derandomize: bool?, ?verbosity: Symbol?, ?database: String?, ?database_key: String?, ?phases: Array[Symbol]?, ?suppress_health_check: Array[Symbol]?, ?report_multiple_failures: bool, ?stateful_step_count: Integer?, ?output: untyped, ?reproduce_failure: String?) { (TestCase) -> void } -> nil
-    def self.run_and_finish: (untyped impl, untyped ctx, untyped settings, quiet: bool, output: untyped) { (TestCase) -> void } -> nil
-    def self.drive: (untyped impl, untyped ctx, untyped run, GenerationStats stats) { (TestCase) -> void } -> void
-    def self.with_test_case: [R] (untyped impl, untyped ctx, untyped tc, ?record: bool) { (TestCase) -> R } -> R
-    def self.run_case: (untyped impl, untyped ctx, untyped tc, GenerationStats stats) { (TestCase) -> void } -> void
-    def self.finish: (untyped impl, untyped ctx, untyped settings, untyped result, GenerationStats stats, quiet: bool, output: untyped) { (TestCase) -> void } -> nil
-    def self.replay: (untyped impl, untyped ctx, untyped settings, untyped result, GenerationStats stats, quiet: bool, output: untyped) { (TestCase) -> void } -> bot
-    def self.replay_failure: (untyped impl, untyped ctx, untyped settings, untyped failure, Integer index, GenerationStats stats) { (TestCase) -> void } -> [Exception, Report::Failure]
-    def self.reproduce: (untyped impl, untyped ctx, untyped settings, String blob, quiet: bool, output: untyped) { (TestCase) -> void } -> bot
+    def self.run: (impl: untyped, ?test_cases: Integer?, ?seed: Integer?, ?derandomize: bool?, ?verbosity: Symbol?, ?database: String?, ?database_key: String?, ?phases: Array[Symbol]?, ?suppress_health_check: Array[Symbol]?, ?report_multiple_failures: bool, ?output: untyped, ?reproduce_failure: String?) { (TestCase) -> void } -> nil
+    def self.run_and_finish: (untyped impl, untyped ctx, untyped run, reproducing: bool, quiet: bool, output: untyped) { (TestCase) -> void } -> nil
+    def self.drive: (untyped impl, untyped ctx, untyped run, GenerationStats stats, Hash[String, Capture] captures) { (TestCase) -> void } -> void
+    def self.with_test_case: [R] (untyped impl, untyped ctx, untyped tc) { (TestCase) -> R } -> R
+    def self.run_case: (untyped impl, untyped ctx, untyped tc, GenerationStats stats, Hash[String, Capture] captures) { (TestCase) -> void } -> void
+    def self.keep_capture: (Hash[String, Capture] captures, String origin, Exception exception, Array[[:draw, String, untyped] | [:note, untyped]]? entries) -> void
+    def self.finish: (untyped impl, untyped ctx, untyped result, GenerationStats stats, Hash[String, Capture] captures, reproducing: bool, quiet: bool, output: untyped) -> nil
+    def self.report_failures: (untyped impl, untyped ctx, untyped result, GenerationStats stats, Hash[String, Capture] captures, quiet: bool, output: untyped) -> bot
+    def self.failure_report: (untyped impl, untyped ctx, untyped failure, GenerationStats stats, Hash[String, Capture] captures) -> [Exception, Report::Failure]
     def self.classify: (TestCase test_case) { (TestCase) -> void } -> [Integer, String?, Exception?, Array[[:draw, String, untyped] | [:note, untyped]]?]
     def self.origin_for: (Exception exception) -> String
     def self.infrastructure?: (String path) -> bool
-    def self.flaky_message: () -> String
+    def self.not_reproduced_message: () -> String
     def self.multiple_failures_message: (Integer count) -> String
   end
 
@@ -432,8 +459,8 @@ module Hegel
     HEGEL_RUN_STATUS_PASSED: Integer
     HEGEL_RUN_STATUS_FAILED: Integer
     HEGEL_RUN_STATUS_ERROR: Integer
-    HEGEL_VERBOSITY_QUIET: Integer
     HEGEL_VERBOSITY_NORMAL: Integer
+    HEGEL_VERBOSITY_QUIET: Integer
     HEGEL_VERBOSITY_VERBOSE: Integer
     HEGEL_VERBOSITY_DEBUG: Integer
     HEGEL_PHASE_EXPLICIT: Integer
@@ -446,39 +473,6 @@ module Hegel
     HEGEL_HC_TOO_SLOW: Integer
     HEGEL_HC_TEST_CASES_TOO_LARGE: Integer
     HEGEL_HC_LARGE_INITIAL_TEST_CASE: Integer
-    HEGEL_LABEL_LIST: Integer
-    HEGEL_LABEL_LIST_ELEMENT: Integer
-    HEGEL_LABEL_SET: Integer
-    HEGEL_LABEL_SET_ELEMENT: Integer
-    HEGEL_LABEL_MAP: Integer
-    HEGEL_LABEL_MAP_ENTRY: Integer
-    HEGEL_LABEL_TUPLE: Integer
-    HEGEL_LABEL_ONE_OF: Integer
-    HEGEL_LABEL_OPTIONAL: Integer
-    HEGEL_LABEL_FIXED_DICT: Integer
-    HEGEL_LABEL_FLAT_MAP: Integer
-    HEGEL_LABEL_FILTER: Integer
-    HEGEL_LABEL_MAPPED: Integer
-    HEGEL_LABEL_SAMPLED_FROM: Integer
-    HEGEL_LABEL_ENUM_VARIANT: Integer
-    HEGEL_LABEL_FEATURE_FLAG: Integer
-    HEGEL_LABEL_REGEX: Integer
-    HEGEL_LABEL_EMAIL: Integer
-    HEGEL_LABEL_URL: Integer
-    HEGEL_LABEL_DOMAIN: Integer
-    HEGEL_LABEL_DATE: Integer
-    HEGEL_LABEL_TIME: Integer
-    HEGEL_LABEL_DATETIME: Integer
-    HEGEL_LABEL_UUID: Integer
-    HEGEL_LABEL_IP_ADDRESS: Integer
-    HEGEL_LABEL_INTEGER: Integer
-    HEGEL_LABEL_FLOAT: Integer
-    HEGEL_LABEL_BOOLEAN: Integer
-    HEGEL_LABEL_BYTES: Integer
-    HEGEL_LABEL_STRING: Integer
-    HEGEL_LABEL_STATEFUL_RULE: Integer
-    HEGEL_LABEL_FRESH_ID: Integer
-    HEGEL_LABEL_SET_CHOICE: Integer
     HEGEL_STATE_MACHINE_DONE: Integer
     HEGEL_COLLECTION_MAX_SIZE_UNBOUNDED: Integer
     HEGEL_FLOAT64_SMALLEST_NONZERO_MAGNITUDE_UNRESTRICTED: Float
@@ -487,6 +481,8 @@ module Hegel
     def self.with_context: [R] (untyped impl) { (untyped) -> R } -> R
     def self.check!: (untyped impl, untyped ctx, Integer code) -> void
     def self.warn_on_version_mismatch: (untyped impl, untyped ctx, ?io: untyped) -> void
+    def self.label_from_name: (String name) -> Integer
+    def self.label_combine: (Array[Integer] labels) -> Integer
     def self.encode_integer_le: (Integer n) -> String
     def self.decode_integer_le: (String bytes) -> Integer
 
@@ -503,12 +499,13 @@ module Hegel
       def settings_set_seed: (untyped ctx, untyped s, Integer seed, bool has_seed) -> nil
       def settings_set_derandomize: (untyped ctx, untyped s, bool derandomize) -> nil
       def settings_set_database: (untyped ctx, untyped s, String? database) -> nil
-      def settings_set_stateful_step_count: (untyped ctx, untyped s, Integer n) -> nil
       def settings_set_report_multiple_failures: (untyped ctx, untyped s, bool yes) -> nil
       def settings_set_database_key: (untyped ctx, untyped s, String? key) -> nil
       def settings_set_phases: (untyped ctx, untyped s, Integer phases) -> nil
       def settings_set_suppress_health_check: (untyped ctx, untyped s, Integer checks) -> nil
       def run_start: (untyped ctx, untyped settings) -> untyped
+      def run_start_blob: (untyped ctx, untyped settings, String blob) -> untyped
+      def test_case_should_capture: (untyped ctx, untyped tc) -> bool
       def next_test_case: (untyped ctx, untyped run) -> untyped?
       def run_free: (untyped ctx, untyped run) -> nil
       def test_case_free: (untyped ctx, untyped tc) -> nil
@@ -526,7 +523,7 @@ module Hegel
       def failure_free: (untyped ctx, untyped f) -> nil
       def failure_origin: (untyped ctx, untyped f) -> String
       def failure_reproduction_blob: (untyped ctx, untyped f) -> String?
-      def test_case_from_blob: (untyped ctx, untyped settings, String blob) -> untyped
+      def failure_caveat: (untyped ctx, untyped f) -> String?
       def start_span: (untyped ctx, untyped tc, Integer label) -> nil
       def stop_span: (untyped ctx, untyped tc, bool discard) -> nil
       def new_collection: (untyped ctx, untyped tc, Integer min_size, Integer max_size) -> untyped
@@ -537,9 +534,11 @@ module Hegel
       def pool_add: (untyped ctx, untyped tc, untyped pool) -> Integer
       def pool_generate: (untyped ctx, untyped tc, untyped pool, bool consume) -> Integer
       def pool_free: (untyped ctx, untyped pool) -> nil
-      def new_state_machine: (untyped ctx, untyped tc, Array[String] rule_names, Array[String] invariant_names) -> untyped
+      def new_state_machine: (untyped ctx, untyped tc, Array[String] rule_names, Array[String] invariant_names, Array[bool] always_check, Integer step_count) -> untyped
+      def state_machine_next_group: (untyped ctx, untyped tc, untyped state_machine) -> Integer
       def state_machine_next_rule: (untyped ctx, untyped tc, untyped state_machine) -> Integer
       def state_machine_rule_rejected: (untyped ctx, untyped tc, untyped state_machine) -> nil
+      def state_machine_should_check_invariant: (untyped ctx, untyped tc, untyped state_machine, Integer index) -> bool
       def state_machine_free: (untyped ctx, untyped state_machine) -> nil
       def generate_float: (untyped ctx, untyped tc, Integer width, Float min_value, Float max_value, bool allow_nan, bool allow_infinity, bool exclude_min, bool exclude_max, Float smallest_nonzero_magnitude) -> Float
       def string_generator_text: (untyped ctx, min_size: Integer, max_size: Integer, ?codec: String?, ?min_codepoint: Integer, ?max_codepoint: Integer) -> untyped