hegeltest 0.1.0 → 0.2.0

data/lib/hegel/runner.rb

@@ -9,9 +9,15 @@ require_relative "test_case"
 module Hegel
   # Drives one Hegel.test run: this is the Ruby side of the per-test-case
   # lifecycle hegel-rust's src/run_lifecycle.rs calls `drive`. Ruby owns the
-  # loop; libhegel owns generation, shrinking, and (on failure) database
-  # replay, so a user's test body never has to cross into native code itself.
+  # loop; libhegel owns generation, shrinking, database replay, and the final
+  # replay of each failure, so a user's test body never has to cross into
+  # native code itself.
   module Runner
+    # One failure kept for its origin: the exception the body raised, and
+    # the entries the case recorded, or nil when the engine did not stamp
+    # the case for capture (see #run_case).
+    Capture = Struct.new(:exception, :entries)
+
     # #origin_for's fallback when an exception's backtrace has no first
     # location to build a real origin from. Named the way hegel-rust names
     # its own equivalent constant, "Panic at <unknown>", for a panic with no
@@ -62,9 +68,9 @@ module Hegel
     # many of those were discarded) the first time that origin's exception
     # was classified INTERESTING. That snapshot is the failure report's own
     # "Falsified after N test cases (M discarded)" line: the generation
-    # phase's counts, not the shrink phase's -- #drive's own comment
-    # measured the shrink phase at roughly 50x more iterations for a
-    # similarly sized run, and counting those into N would answer a
+    # phase's counts, not the shrink phase's. Measured against libhegel
+    # 0.45.0, a run that failed after 2 generated cases called the body 60
+    # to 75 times in all, and counting those into N would answer a
     # different question than the report claims to.
     class GenerationStats
       def initialize
@@ -73,8 +79,7 @@ module Hegel
         @snapshots = {}
       end
 
-      # Called once per case #drive receives (or, from #reproduce, exactly
-      # once for its own single case).
+      # Called once per case #drive receives.
       def record(status, origin)
         @test_cases += 1
         @discarded += 1 if status == LibHegel::HEGEL_STATUS_INVALID
@@ -82,7 +87,7 @@ module Hegel
       end
 
       # [test_cases, discarded] as of +origin+'s first INTERESTING
-      # appearance. No fallback: every origin #replay_failure asks for here
+      # appearance. No fallback: every origin #failure_report asks for here
       # came from a failure hegel_run_result reported, and that failure
       # exists only because this same #record already saw it live.
       def for(origin)
@@ -94,35 +99,29 @@ module Hegel
 
     # Runs +block+ as a Hegel property against +impl+, applying +test_cases+,
     # +seed+, +derandomize+, +verbosity+, +database+, +database_key+,
-    # +phases+, +suppress_health_check+, +report_multiple_failures+, and
-    # +stateful_step_count+ (see Hegel::Settings) to a fresh settings handle
-    # first. Returns nil on a passing run, re-raises the exception the
-    # smallest failing case's body raised on a failing run, and raises
-    # Hegel::Error for a run-level failure (ERROR status, a replay that
-    # could not reproduce the recorded failure, or more than one distinct
-    # failure -- see #replay).
+    # +phases+, +suppress_health_check+, and +report_multiple_failures+ (see
+    # Hegel::Settings) to a fresh settings handle first. Returns nil on a
+    # passing run, re-raises the exception the smallest failing case's body
+    # raised on a failing run, and raises Hegel::Error for a run-level
+    # failure (ERROR status, a blob that no longer reproduces, or more than
+    # one distinct failure -- see #report_failures).
     #
     # +database+ and +database_key+ follow the table
     # Hegel::Settings.apply_database documents; docs/adr/0009 has the
     # decision and the measurements behind it.
     #
-    # +report_multiple_failures+ defaults to false, not nil: hegel-c/src/
-    # settings.rs itself defaults to true, but hegel-rust's own Rust API
-    # (src/runner.rs) and hegel-java both default to false, and hegel-java
-    # states the reason: one failure re-raised unaltered keeps the exception
-    # class and the stack trace a debugger reads, which a summary replaces
-    # with a count.
-    # That is this library's own central promise (#classify re-raises a
-    # body's exception with its class and backtrace intact), so the same
-    # reason applies here, and choosing to depart from the engine's own
-    # default is itself a decision worth stating explicitly with `false`
-    # rather than leaving it to a nil a reader could mistake for "no
-    # opinion".
+    # +report_multiple_failures+ defaults to false, the default libhegel,
+    # hegel-rust, and hegel-java share. It is passed as false rather than
+    # left nil, because hegel-java states why false is right: one failure
+    # re-raised unaltered keeps the exception class and the stack trace a
+    # debugger reads, which a summary replaces with a count. That is this
+    # library's own central promise (#classify re-raises a body's exception
+    # with its class and backtrace intact), so a hegel.toml profile or a
+    # HEGEL_* variable does not get to turn it off by accident.
     #
-    # +reproduce_failure+, when given, wins over everything above except
-    # +verbosity+: it skips the run loop entirely and replays a single case
-    # built from that blob (see #reproduce). +test_cases+ has no run to
-    # bound in that case.
+    # +reproduce_failure+, when given, starts the run from that blob instead
+    # (see LibHegel::Real#run_start_blob): the engine replays it rather than
+    # exploring, and the same loop below drives the replay.
     #
     # +output+ (default $stderr) is where a failure report is written,
     # unless +verbosity+ is :quiet, in which case none is written at all.
@@ -131,84 +130,72 @@ module Hegel
     # `ensure` by the code that opened it, innermost first: hegel_context_free
     # requires every other handle taken from the context to be freed first,
     # and Ruby's GC gives finalizers no ordering guarantee to rely on instead.
-    #
-    # +settings+ stays open through the whole run, not just through
-    # hegel_run_start. The header says a caller may free settings as soon as
-    # hegel_run_start returns, but that is only true for driving the loop: a
-    # failing run's replay calls hegel_test_case_from_blob against this same
-    # settings handle, so it must outlive the FAILED-status replay below, not
-    # just the loop above it.
     def run(impl:, 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,
+      phases: nil, suppress_health_check: nil, report_multiple_failures: false,
       output: $stderr, reproduce_failure: nil, &block)
       quiet = verbosity == :quiet
       LibHegel.with_context(impl) do |ctx|
         settings = impl.settings_new(ctx)
-        begin
+        run = begin
           Settings.apply(impl, ctx, settings, 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)
-
+            suppress_health_check: suppress_health_check, report_multiple_failures: report_multiple_failures)
           if reproduce_failure
-            reproduce(impl, ctx, settings, reproduce_failure, quiet: quiet, output: output, &block)
+            impl.run_start_blob(ctx, settings, reproduce_failure)
           else
-            run_and_finish(impl, ctx, settings, quiet: quiet, output: output, &block)
+            impl.run_start(ctx, settings)
           end
         ensure
+          # The header lets a caller free settings once the run has started:
+          # hegel_run_start copies them.
           impl.settings_free(ctx, settings)
         end
+        run_and_finish(impl, ctx, run, reproducing: !reproduce_failure.nil?, quiet: quiet, output: output, &block)
       end
     end
 
-    # The ordinary (non-reproduce_failure) path: starts a run, drives it,
-    # and hands its result to #finish. Split out of #run so that path and
-    # #reproduce's are two plain branches there, not one method doing both.
-    def run_and_finish(impl, ctx, settings, quiet:, output:, &block)
-      run = impl.run_start(ctx, settings)
-      begin
-        stats = GenerationStats.new
-        drive(impl, ctx, run, stats, &block)
+    # Drives +run+ and hands its result to #finish.
+    def run_and_finish(impl, ctx, run, reproducing:, quiet:, output:, &block)
+      stats = GenerationStats.new
+      captures = {}
+      drive(impl, ctx, run, stats, captures, &block)
 
-        result = impl.run_result(ctx, run)
-        begin
-          finish(impl, ctx, settings, result, stats, quiet: quiet, output: output, &block)
-        ensure
-          impl.run_result_free(ctx, result)
-        end
+      result = impl.run_result(ctx, run)
+      begin
+        finish(impl, ctx, result, stats, captures, reproducing: reproducing, quiet: quiet, output: output)
       ensure
-        # hegel_run_free only marks an in-progress case complete; per the
-        # header it does not free the test-case handle itself. That
-        # handle is this loop's own to release, which #run_case does via
-        # #with_test_case's own `ensure` on every path, including a fatal
-        # exception raised from inside #drive.
-        impl.run_free(ctx, run)
+        impl.run_result_free(ctx, result)
       end
+    ensure
+      # hegel_run_free only marks an in-progress case complete; per the
+      # header it does not free the test-case handle itself. That
+      # handle is this loop's own to release, which #run_case does via
+      # #with_test_case's own `ensure` on every path, including a fatal
+      # exception raised from inside #drive.
+      impl.run_free(ctx, run)
     end
 
     # Pulls test cases from +run+ until hegel_next_test_case reports none
     # left (a nil out-parameter, not an error). Never counts iterations
     # itself: test_cases bounds generation, not how many times shrinking
-    # calls the body afterwards. Measured against libhegel 0.32.5, a run
-    # configured for 20 test cases whose body always failed took 1003
-    # iterations. +stats+ does its own, different counting -- see
-    # GenerationStats above.
-    def drive(impl, ctx, run, stats, &block)
+    # and rejected cases call the body. Measured against libhegel 0.45.0, a
+    # run configured for 20 test cases whose body rejected nearly every case
+    # took 1040 to 1537 iterations. +stats+ does its own, different counting
+    # -- see GenerationStats above.
+    def drive(impl, ctx, run, stats, captures, &block)
       loop do
         tc = impl.next_test_case(ctx, run)
         break if tc.nil?
 
-        run_case(impl, ctx, tc, stats, &block)
+        run_case(impl, ctx, tc, stats, captures, &block)
       end
     end
 
     # Builds a Hegel::TestCase for +tc+ and yields it, then frees what it
     # opened: every pool it recorded (Hegel::TestCase#free_pools), then the
     # test-case handle itself, in that order, whether the block returns or
-    # raises. #run_case, #replay_failure, and #reproduce each need exactly
-    # this shape around their own call to #classify -- docs/adr/0011 decides
-    # a test case owns every pool built from it, and that pools free before
-    # the handle that owns them goes.
+    # raises. docs/adr/0011 decides a test case owns every pool built from
+    # it, and that pools free before the handle that owns them goes.
     #
     # The nested `ensure` is what keeps those two releases independent. A
     # raise out of #free_pools would otherwise carry past the handle's own
@@ -216,77 +203,97 @@ module Hegel
     # context to be freed first, so one skipped release does not stop at one
     # leak -- it fails the context's release too, at the end of a run that
     # had already gone wrong enough to raise in here.
-    def with_test_case(impl, ctx, tc, record: false)
-      test_case = TestCase.new(impl, ctx, tc, record: record)
+    #
+    # The case records its draws only when the engine stamped it for
+    # capture. The stamp is read in here, inside the `ensure`, so the handle
+    # is freed even when reading it raises.
+    def with_test_case(impl, ctx, tc)
+      test_case = TestCase.new(impl, ctx, tc, record: impl.test_case_should_capture(ctx, tc))
       yield test_case
     ensure
       begin
-        test_case.free_pools
+        test_case&.free_pools
       ensure
         impl.test_case_free(ctx, tc)
       end
     end
 
     # Runs +block+ against one test-case handle, classifies the outcome,
-    # counts it into +stats+, and reports it with hegel_mark_complete. A
-    # fatal exception (#classify re-raises those before returning) skips
-    # both entirely and still reaches #with_test_case's own `ensure`, so the
-    # handle is freed either way; its owner is this loop, not hegel_run_free
-    # (see #run_and_finish's comment above).
-    def run_case(impl, ctx, tc, stats, &block)
+    # counts it into +stats+, keeps a failure in +captures+, and reports the
+    # outcome with hegel_mark_complete. Only a stamped case records its
+    # draws (see #with_test_case): a stamped case's failure is what a report
+    # shows, and naming a drawn value costs a read of the caller's source,
+    # which every shrink probe would otherwise pay for. A fatal
+    # exception (#classify re-raises those before returning) skips the rest
+    # and still reaches #with_test_case's own `ensure`, so the handle is
+    # freed either way; its owner is this loop, not hegel_run_free (see
+    # #run_and_finish's comment above).
+    def run_case(impl, ctx, tc, stats, captures, &block)
       with_test_case(impl, ctx, tc) do |test_case|
-        status, origin = classify(test_case, &block)
+        status, origin, exception, entries = classify(test_case, &block)
         stats.record(status, origin)
+        keep_capture(captures, origin, exception, entries) if status == LibHegel::HEGEL_STATUS_INTERESTING
         impl.mark_complete(ctx, tc, status, origin)
       end
     end
 
+    # Keeps the newest capture for each origin, except that an unstamped
+    # failure (+entries+ nil) never replaces a stamped one. The engine runs
+    # every failure it reports once more at the end of the run, stamped, so
+    # the last stamped capture is that final replay, and an earlier stamped
+    # one only stands in when the final replay was dry. An unstamped capture
+    # still gives the run an exception to re-raise when nothing was stamped.
+    # hegel-rust ranks its captures the same way: a newer capture replaces
+    # an older one of the same rank or lower.
+    def keep_capture(captures, origin, exception, entries)
+      return if entries.nil? && captures[origin]&.entries
+
+      captures[origin] = Capture.new(exception, entries)
+    end
+
     # Reads the finished run's status and acts on it. PASSED returns nil,
-    # ERROR raises Hegel::Error from hegel_run_result_error's message, and
-    # FAILED hands off to #replay. Any other status would mean this binding
-    # does not recognise a hegel_run_status_t value the loaded engine
-    # returned, mirroring how LibHegel.check! names an unrecognised result
-    # code instead of silently doing nothing with it.
-    def finish(impl, ctx, settings, result, stats, quiet:, output:, &block)
+    # unless the run was replaying a blob, where it means the blob no longer
+    # reproduces. ERROR raises Hegel::Error from hegel_run_result_error's
+    # message, and FAILED hands off to #report_failures. Any other status
+    # would mean this binding does not recognise a hegel_run_status_t value
+    # the loaded engine returned, mirroring how LibHegel.check! names an
+    # unrecognised result code instead of silently doing nothing with it.
+    def finish(impl, ctx, result, stats, captures, reproducing:, quiet:, output:)
       status = impl.run_result_status(ctx, result)
       case status
       when LibHegel::HEGEL_RUN_STATUS_PASSED
-        nil
+        raise Hegel::Error, not_reproduced_message if reproducing
       when LibHegel::HEGEL_RUN_STATUS_ERROR
         raise Hegel::Error, impl.run_result_error(ctx, result) || UNKNOWN_RUN_ERROR_MESSAGE
       when LibHegel::HEGEL_RUN_STATUS_FAILED
-        replay(impl, ctx, settings, result, stats, quiet: quiet, output: output, &block)
+        report_failures(impl, ctx, result, stats, captures, quiet: quiet, output: output)
       else
         raise Hegel::Error, "hegel: run finished with an unrecognized status (#{status})"
       end
     end
 
-    # Replays every recorded failure by running +block+ again against a test
-    # case rebuilt from its reproduction blob, in the same way #run_case
-    # classifies and completes a live one. Writes the report for every
-    # failure it collected to +output+ (unless +quiet+), then raises: one
-    # failure re-raises its own kept exception, unaltered; two or more raise
-    # Hegel::Error with #multiple_failures_message instead, since no single
-    # one of several kept exceptions is more the run's own verdict than
-    # another. hegel-rust's own src/run_lifecycle.rs (the
-    # HEGEL_RUN_STATUS_FAILED branch) makes the same choice: one panic
-    # re-raised as itself, several replaced by one panic carrying just the
-    # count.
+    # Reports every failure the run found from what #run_case captured for
+    # its origin, then raises: one failure re-raises its own kept exception,
+    # unaltered; two or more raise Hegel::Error with
+    # #multiple_failures_message instead, since no single one of several
+    # kept exceptions is more the run's own verdict than another.
+    # hegel-rust's own src/run_lifecycle.rs (the HEGEL_RUN_STATUS_FAILED
+    # branch) makes the same choice: one panic re-raised as itself, several
+    # replaced by one panic carrying just the count.
     #
-    # #finish only reaches here on a FAILED run, and a FAILED run this
-    # binding has actually seen always carries at least one failure to
-    # iterate below, so neither raise needs a zero-failures guard: that
-    # branch would need a run this binding has never observed to reach it.
-    # The report is written before either raise, not after: a host
+    # #finish only reaches here on a FAILED run, and a FAILED run always
+    # carries at least one failure, so neither raise needs a zero-failures
+    # guard. The report is written before either raise, not after: a host
     # framework that catches the re-raised exception would otherwise read
     # its own output before this one, out of order.
-    def replay(impl, ctx, settings, result, stats, quiet:, output:, &block)
-      kept_exception = nil
+    def report_failures(impl, ctx, result, stats, captures, quiet:, output:)
+      exceptions = []
       failures = []
       impl.run_result_failure_count(ctx, result).times do |index|
         failure = impl.run_result_failure(ctx, result, index)
         begin
-          kept_exception, report = replay_failure(impl, ctx, settings, failure, index, stats, &block)
+          exception, report = failure_report(impl, ctx, failure, stats, captures)
+          exceptions << exception
           failures << report
         ensure
           impl.failure_free(ctx, failure)
@@ -295,89 +302,34 @@ module Hegel
       output.puts(Report.render(failures)) unless quiet
       raise Hegel::Error, multiple_failures_message(failures.size) if failures.size > 1
 
-      raise kept_exception
+      raise exceptions.first
     end
 
-    # Rebuilds one failure's test case from its reproduction blob and runs
-    # +block+ against it, through the same #classify used by the live loop,
-    # recording its entries for the report (see Hegel::TestCase). Returns
-    # [exception, Hegel::Report::Failure] on success.
-    #
-    # Flaky means any outcome other than INTERESTING, which is broader than
-    # "the body did not raise": #classify's other two non-INTERESTING
-    # outcomes both matter here. A body that raises nothing
-    # on replay is the textbook flaky case. A blob whose choices no longer
-    # match the caller's generators is the other one: the header puts that
-    # at "the draw that overruns", so the body raises Hegel::StopTest and
-    # #classify turns it into OVERRUN. Re-raising either as its original
-    # class would leak a control exception meant only for code driving a
-    # test case into the host test framework. This classify-then-check
-    # step exists to prevent exactly that.
-    def replay_failure(impl, ctx, settings, failure, index, stats, &block)
-      blob = impl.failure_reproduction_blob(ctx, failure)
-      raise Hegel::Error, "hegel: failure #{index} has no reproduction blob" if blob.nil?
-
-      tc = build_replay_case(impl, ctx, settings, blob)
-      with_test_case(impl, ctx, tc, record: true) do |test_case|
-        status, origin, exception, entries = classify(test_case, &block)
-        raise Hegel::Error, flaky_message unless status == LibHegel::HEGEL_STATUS_INTERESTING
-
-        # The libhegel reference documents blob replay as ended by the
-        # caller's own hegel_mark_complete. Skipping it might not crash
-        # hegel_test_case_free, but not crashing is not the same as correct.
-        impl.mark_complete(ctx, tc, status, origin)
-        test_cases, discarded = stats.for(origin)
-        [exception, Report::Failure.new(test_cases: test_cases, discarded: discarded, entries: entries, blob: blob)]
-      end
-    end
-
-    # Hegel.test(reproduce_failure:)'s own path: starts no run loop, and
-    # replays exactly one case built from +blob+, through the same
-    # classify-then-check contract #replay_failure uses. That case is
-    # already the "final" replay a report needs, so recording is on for it
-    # -- unconditionally 1 test case, 0 discarded, since a body that raised
-    # Hegel::AssumeFailed here would already have failed the status check
-    # below before either count could matter.
-    #
-    # Builds the replay's test case, converting a control exception raised
-    # while building it into an ordinary error.
-    #
-    # The header attributes HEGEL_E_STOP_TEST to "the draw that overruns"
-    # rather than to this call, and replaying a two-draw blob against a
-    # five-draw body does build a case and then overrun at a draw, measured
-    # against 0.32.5. This guard is therefore defence rather than a
-    # documented path: a control exception escaping into the caller's test
-    # is the one outcome this whole design exists to prevent, and both
-    # replay paths go through here so neither can grow the hole
-    # independently.
-    def build_replay_case(impl, ctx, settings, blob)
-      impl.test_case_from_blob(ctx, settings, blob)
-    rescue Hegel::StopTest
-      raise Hegel::Error, flaky_message
-    end
-
-    def reproduce(impl, ctx, settings, blob, quiet:, output:, &block)
-      tc = build_replay_case(impl, ctx, settings, blob)
-      with_test_case(impl, ctx, tc, record: true) do |test_case|
-        status, origin, exception, entries = classify(test_case, &block)
-        raise Hegel::Error, flaky_message unless status == LibHegel::HEGEL_STATUS_INTERESTING
-
-        impl.mark_complete(ctx, tc, status, origin)
-        report = Report::Failure.new(test_cases: 1, discarded: 0, entries: entries, blob: blob)
-        output.puts(Report.render([report])) unless quiet
-        raise exception
-      end
+    # [exception, Hegel::Report::Failure] for one failure. The engine groups
+    # a failure under the origin #run_case reported, and #run_case saw every
+    # case the run produced, so every failure has a capture under its origin.
+    # A capture with no entries came from an unstamped case, whose draws
+    # went unrecorded, so its report lists no values.
+    def failure_report(impl, ctx, failure, stats, captures)
+      origin = impl.failure_origin(ctx, failure)
+      capture = captures.fetch(origin)
+      test_cases, discarded = stats.for(origin)
+      report = Report::Failure.new(
+        test_cases: test_cases, discarded: discarded, entries: capture.entries || [],
+        blob: impl.failure_reproduction_blob(ctx, failure), caveat: impl.failure_caveat(ctx, failure)
+      )
+      [capture.exception, report]
     end
 
     # Runs +block+ against +test_case+ (a Hegel::TestCase #with_test_case
     # already built, at whatever +record:+ it was given) and classifies the
-    # outcome into the [hegel_status_t, origin, exception, entries]
-    # #run_case, #replay_failure, and #reproduce all need. +entries+ is only
-    # ever non-nil when +test_case+ was built to record and the outcome was
-    # INTERESTING, since that is the only combination any caller here reads
-    # it for. Order matters: a fatal exception must be re-raised before it
-    # reaches the library's own control exceptions, which must themselves be
-    # told apart from an ordinary exception before the catch-all below.
+    # outcome into the [hegel_status_t, origin, exception, entries] #run_case
+    # needs. +entries+ is only ever non-nil when +test_case+ was built to
+    # record and the outcome was INTERESTING, since that is the only
+    # combination #run_case reads it for. Order matters: a fatal exception
+    # must be re-raised before it reaches the library's own control
+    # exceptions, which must themselves be told apart from an ordinary
+    # exception before the catch-all below.
     #
     # standard:disable Lint/RescueException -- `rescue Exception` is
     # deliberate: Minitest::Assertion and RSpec's ExpectationNotMetError both
@@ -386,6 +338,9 @@ module Hegel
     # being reported as a Hegel failure.
     def classify(test_case, &block)
       block.call(test_case)
+      # No caller reads a VALID, INVALID, or OVERRUN tuple past its first two
+      # elements. .mutineer.yml ignores the mutants of the last two by id, since
+      # a line marker would also hide the killed mutant of the second.
       [LibHegel::HEGEL_STATUS_VALID, nil, nil, nil]
     rescue *Hegel::FATAL_EXCEPTIONS
       raise
@@ -435,17 +390,14 @@ module Hegel
         path.start_with?(STDLIB_DIR)
     end
 
-    # Mirrors the intent of hegel-rust's FLAKY_DIAGNOSTIC in English, not its
-    # exact wording: the same generated data produced a different outcome on
-    # replay, which usually means the body depends on something outside
-    # libhegel's control.
-    def flaky_message
-      "hegel: this failure did not reproduce against the same generated data. " \
-        "The test body likely depends on state outside libhegel's control, " \
-        "such as a global variable, wall-clock time, or an external source of randomness."
+    # A replayed blob that never failed. Like hegel-rust's own message for
+    # the same outcome, it names both explanations.
+    def not_reproduced_message
+      "hegel: the blob passed to reproduce_failure did not reproduce a failure. " \
+        "Either the bug is fixed, or the test body is nondeterministic and the failure did not recur."
     end
 
-    # #replay's own multi-failure raise, and Report.render's multi-failure
+    # #report_failures' own multi-failure raise, and Report.render's multi-failure
     # heading, must stay the same sentence: a caller who greps the printed
     # report for this text should find the same string in the exception it
     # catches. Report.render builds that heading itself rather than calling
@@ -453,10 +405,10 @@ module Hegel
     # and does not know how a run ended (see its own class comment); the
     # sentence is duplicated here as the coupling between the two, not
     # factored into a shared helper neither module already depends on.
-    # Deliberately carries no "hegel: " prefix, unlike #flaky_message and
+    # Deliberately carries no "hegel: " prefix, unlike #not_reproduced_message and
     # the other messages this module composes itself (UNKNOWN_RUN_ERROR_
-    # MESSAGE, the unrecognized-status message, the no-reproduction-blob
-    # message), to stay that same sentence.
+    # MESSAGE and the unrecognized-status message), to stay that same
+    # sentence.
     def multiple_failures_message(count)
       "Property-based test failed with #{count} distinct failures."
     end

data/lib/hegel/settings.rb

@@ -5,13 +5,13 @@ require_relative "lib_hegel"
 
 module Hegel
   # Copies Hegel.test's keyword arguments onto a libhegel settings handle.
-  # Most keywords follow one rule: nil means "leave libhegel's own default in
-  # place", so a caller of Hegel.test who passes none of them gets exactly
-  # the engine's untouched defaults (100 test cases, a random seed, no
-  # derandomize, every phase, every health check). +database+ and
-  # +database_key+ follow the table #apply_database documents instead, and
-  # +report_multiple_failures+ has no nil case at all -- see #apply's own
-  # comment for why.
+  # Most keywords follow one rule: nil means "call no setter", so a caller of
+  # Hegel.test who passes none of them gets the settings profile the engine
+  # resolved: libhegel's own defaults, unless a hegel.toml, a HEGEL_*
+  # environment variable, or the engine's ci profile on a CI server says
+  # otherwise (see docs/adr/0023). +database+ and +database_key+ follow the
+  # table #apply_database documents instead, and +report_multiple_failures+
+  # has no nil case at all -- see #apply's own comment for why.
   module Settings
     # Hegel.test's verbosity: values, mapped to hegel.h's hegel_verbosity_t.
     VERBOSITY_CODES = {
@@ -52,13 +52,9 @@ module Hegel
     # with no nil case: Hegel.test defaults it to false rather than leaving
     # it nil, so this method never sees nil for it -- see Hegel::Runner.run's
     # own comment for why that default departs from every other keyword's
-    # nil-means-engine-default rule. +stateful_step_count+ follows the same
-    # nil-means-engine-default rule as +test_cases+/+seed+/and so on: the
-    # header documents the engine's own default (50) and requires the value
-    # be at least 1, and, like +tc.target+'s own label, that requirement is
-    # left to the engine rather than re-checked here.
+    # nil-means-engine-default rule.
     def apply(impl, ctx, settings, test_cases:, seed:, derandomize:, verbosity:, database:, database_key:, phases:,
-      suppress_health_check:, report_multiple_failures:, stateful_step_count:)
+      suppress_health_check:, report_multiple_failures:)
       impl.settings_set_test_cases(ctx, settings, test_cases) unless test_cases.nil?
       impl.settings_set_seed(ctx, settings, seed, true) unless seed.nil?
       impl.settings_set_derandomize(ctx, settings, derandomize) unless derandomize.nil?
@@ -67,7 +63,6 @@ module Hegel
       apply_phases(impl, ctx, settings, phases) unless phases.nil?
       apply_suppress_health_check(impl, ctx, settings, suppress_health_check) unless suppress_health_check.nil?
       impl.settings_set_report_multiple_failures(ctx, settings, report_multiple_failures)
-      impl.settings_set_stateful_step_count(ctx, settings, stateful_step_count) unless stateful_step_count.nil?
     end
 
     # Split from #apply so the VERBOSITY_CODES lookup (one of several

data/lib/hegel/state_machine.rb

@@ -23,6 +23,10 @@ module Hegel
     # class's.
     include Syntax::Methods
 
+    # One declared invariant: its block, and whether it runs after every
+    # round rather than when the engine samples it.
+    Invariant = Data.define(:block, :always_run)
+
     class << self
       # Declares a rule named +name+: an action the engine may pick to run
       # at any step. +block+ runs via #instance_exec against the machine
@@ -33,11 +37,14 @@ module Hegel
         declare(:@rules, "rule", name, block)
       end
 
-      # Declares an invariant named +name+, checked once before the first
-      # rule runs and again after every rule that completes without its own
-      # assumption failing. Same block/argument contract as #rule.
-      def invariant(name, &block)
-        declare(:@invariants, "invariant", name, block)
+      # Declares an invariant named +name+, checked before the first rule
+      # runs, after the last, and in between at the join points where the
+      # engine samples it: each one with probability 1 / step_count, so
+      # about once per full-length test case. +always_run+ checks it at
+      # every join point instead, the name hegel-rust and hegel-java give
+      # the same option. Same block/argument contract as #rule.
+      def invariant(name, always_run: false, &block)
+        declare(:@invariants, "invariant", name, Invariant.new(block: block, always_run: always_run))
       end
 
       # name => block, in declaration order, this class's own declarations
@@ -47,7 +54,7 @@ module Hegel
         merged_definitions(:@rules, :rule_definitions)
       end
 
-      # The invariant analogue of #rule_definitions.
+      # The invariant analogue of #rule_definitions: name => Invariant.
       def invariant_definitions
         merged_definitions(:@invariants, :invariant_definitions)
       end
@@ -62,12 +69,12 @@ module Hegel
       # reads an ancestor's table, so a subclass re-declaring an inherited
       # name is the ordinary "redefine a method" case the ADR calls out,
       # not this one.
-      def declare(ivar, kind, name, block)
+      def declare(ivar, kind, name, definition)
         table = instance_variable_get(ivar) || instance_variable_set(ivar, {})
         name = name.to_s
         raise Hegel::Error, "hegel: #{kind} #{name.inspect} is already declared on #{self}" if table.key?(name)
 
-        table[name] = block
+        table[name] = definition
       end
 
       # Shared by #rule_definitions/#invariant_definitions: this class's own

data/lib/hegel/stateful/pool.rb

@@ -71,7 +71,6 @@ module Hegel
       # of this library's own public generator vocabulary.
       class ValuesReusable < Generator
         def initialize(pool, values)
-          super()
           @pool = pool
           @values = values
         end
@@ -94,7 +93,6 @@ module Hegel
       # pre-checking emptiness.
       class ValuesConsumed < Generator
         def initialize(pool, values)
-          super()
           @pool = pool
           @values = values
         end