hegeltest 0.3.1 → 0.4.0

data/lib/hegel/lib_hegel.rb

@@ -18,7 +18,7 @@ module Hegel
   # is testable without the native engine. hegel-java makes the same split,
   # between its Libhegel interface, RealLibhegel, and FakeLibhegel.
   module LibHegel
-    # hegel_result_t, named from hegel-c/include/hegel.h's enum of the same
+    # hegel_result_t, named from libhegel/include/hegel.h's enum of the same
     # name. HEGEL_OK is success; every other value is a negative error code.
     HEGEL_OK = 0
     HEGEL_E_STOP_TEST = -1
@@ -30,6 +30,8 @@ module Hegel
     HEGEL_E_NOT_COMPLETE = -7
     HEGEL_E_INTERNAL = -8
     HEGEL_E_CONCURRENT_USE = -9
+    HEGEL_E_RETRY = -10
+    HEGEL_E_NOT_FOUND = -11
 
     # The hegel.h name for each code above, so a translated error message
     # names the code instead of leaving the reader to cross-reference the
@@ -44,7 +46,9 @@ module Hegel
       HEGEL_E_ALREADY_COMPLETE => "HEGEL_E_ALREADY_COMPLETE",
       HEGEL_E_NOT_COMPLETE => "HEGEL_E_NOT_COMPLETE",
       HEGEL_E_INTERNAL => "HEGEL_E_INTERNAL",
-      HEGEL_E_CONCURRENT_USE => "HEGEL_E_CONCURRENT_USE"
+      HEGEL_E_CONCURRENT_USE => "HEGEL_E_CONCURRENT_USE",
+      HEGEL_E_RETRY => "HEGEL_E_RETRY",
+      HEGEL_E_NOT_FOUND => "HEGEL_E_NOT_FOUND"
     }.freeze
 
     # hegel_status_t, named from hegel.h's enum of the same name. Passed to
@@ -67,6 +71,15 @@ module Hegel
     HEGEL_VERBOSITY_VERBOSE = 2
     HEGEL_VERBOSITY_DEBUG = 3
 
+    # hegel_nondeterminism_strictness_t
+    HEGEL_NONDETERMINISM_QUIET = 0
+    HEGEL_NONDETERMINISM_WARN = 1
+    HEGEL_NONDETERMINISM_ERROR = 2
+
+    # hegel_backend_t
+    HEGEL_BACKEND_DEFAULT = 1
+    HEGEL_BACKEND_URANDOM = 2
+
     # hegel_phase_t, named from hegel.h's enum of the same name. A bitwise
     # OR of these is passed to hegel_settings_set_phases; the default is
     # HEGEL_PHASE_ALL.
@@ -108,7 +121,8 @@ module Hegel
     # responds to each name here.
     METHODS = %i[
       context_new context_free context_last_error version
-      settings_new settings_free settings_set_test_cases settings_set_verbosity
+      settings_new settings_new_for_profile settings_register_profile set_default_profile
+      settings_free settings_set_test_cases settings_set_verbosity
       settings_set_seed settings_set_derandomize settings_set_database
       run_start next_test_case run_free test_case_free mark_complete
       generate_boolean generate_integer generate_integer_big
@@ -118,19 +132,30 @@ module Hegel
       start_span stop_span
       new_collection collection_more collection_reject collection_free
       generate_float
-      string_generator_text string_generator_free generate_string generate_string_result_free
+      string_generator_text string_generator_free generate_string owned_string_free
       generate_bytes generate_bytes_result_free
       string_generator_regex string_generator_email string_generator_url string_generator_domain
       generate_ipv4 generate_ipv6 generate_uuid
       generate_date generate_time generate_datetime
       settings_set_phases settings_set_suppress_health_check settings_set_report_multiple_failures
-      settings_set_database_key
-      target
-      new_pool pool_add pool_generate pool_free
+      settings_set_database_key settings_set_stop_on_first_failure settings_set_print_blob
+      settings_get_print_blob settings_set_show_statistics settings_set_nondeterminism_strictness
+      settings_set_backend settings_set_test_location
+      target event event_value
+      new_pool pool_add pool_generate pool_restore pool_free
       new_state_machine state_machine_next_group state_machine_next_rule state_machine_rule_rejected
       state_machine_should_check_invariant state_machine_free
+      grammar_builder_new grammar_builder_file grammar_builder_provide grammar_builder_free
+      grammar_new grammar_placeholder grammar_free generate_grammar
+      new_recursion recursion_branch recursion_leaf recursion_retry recursion_finish recursion_free
     ].freeze
 
+    # label_combine answers from this table: a recursive generator builds a
+    # fresh branch generator at every node it draws, and each one combines
+    # the same few labels again. Measured on the 30-leaf shrink in
+    # test_recursive_engine.rb, hashing the labels was a third of the run.
+    COMBINED_LABELS = {}
+
     module_function
 
     # Runs the block with a context obtained from +impl.context_new+,
@@ -200,7 +225,7 @@ module Hegel
     end
 
     def label_combine(labels)
-      fnv1a(labels.pack("Q<*").bytes)
+      COMBINED_LABELS[labels] ||= fnv1a(labels.pack("Q<*").bytes)
     end
 
     def fnv1a(bytes)

data/lib/hegel/libhegel_version.rb

@@ -5,5 +5,5 @@ module Hegel
   # Hegel::VERSION (the gem's own release): hegel-go and hegel-typescript keep
   # the two separate too, so bumping the pinned engine can land as its own
   # commit without also releasing a new gem version.
-  LIBHEGEL_VERSION = "0.45.7"
+  LIBHEGEL_VERSION = "0.48.0"
 end

data/lib/hegel/locate.rb

@@ -16,7 +16,7 @@ module Hegel
   #    fallback.
   # 2. The copy bundled into the gem under +lib/hegel/libhegel/+.
   #
-  # A sibling `../hegel-rust` checkout is deliberately not searched. The env
+  # A sibling engine checkout (`../hegel`) is deliberately not searched. The env
   # override already covers local-engine-build workflows without depending
   # on any particular checkout layout, and `rake libhegel:fetch` covers the
   # rest; a rule that depends on a layout this repo's own checkout does not
@@ -32,10 +32,10 @@ module Hegel
     LIBRARY_PATH_ENV = "HEGEL_LIBHEGEL_PATH"
 
     # Published release asset name for each supported "<host_cpu>-<host_os>"
-    # pair, mirroring the artifacts hegel-rust publishes for the pinned
-    # LIBHEGEL_VERSION. Hosts absent from this table (e.g. x86_64-darwin,
-    # Intel Mac) are unsupported because hegel-rust does not publish a build
-    # for them.
+    # pair, mirroring the artifacts the libhegel release of the pinned
+    # LIBHEGEL_VERSION publishes. Hosts absent from this table (e.g.
+    # x86_64-darwin, Intel Mac) are unsupported because that release does not
+    # publish a build for them.
     ASSET_NAMES = {
       "arm64-darwin" => "libhegel-darwin-arm64.dylib",
       "x86_64-linux" => "libhegel-linux-amd64.so",
@@ -76,7 +76,7 @@ module Hegel
     end
 
     # The release asset name for the given host, or raises Hegel::Error if
-    # hegel-rust does not publish a build for it.
+    # the libhegel release does not publish a build for it.
     def asset_name(host_cpu:, host_os:)
       release_asset_name(host_cpu, host_os) || raise(Hegel::Error, unsupported_host_message(host_cpu, host_os))
     end
@@ -101,7 +101,7 @@ module Hegel
     #    directory override is how an unsupported host (e.g. x86_64-darwin)
     #    points at a local build in the first place, so treating it as an
     #    error here would close off that path.
-    # 2. libhegel_c.<ext>, the name cargo gives the library when hegel-c's
+    # 2. libhegel_c.<ext>, the name cargo gives the library when libhegel's
     #    crate (`[lib] name = "hegel_c"`) is built without renaming it.
     # 3. libhegel.<ext>, a renamed copy, per the hegel-go and hegel-ocaml
     #    READMEs.
@@ -122,8 +122,8 @@ module Hegel
       [release_asset_name(host_cpu, host_os), "libhegel_c.#{ext}", "libhegel.#{ext}"].compact
     end
 
-    # The release asset name for the given host, or nil if hegel-rust does
-    # not publish a build for it. Split from asset_name (which raises) so a
+    # The release asset name for the given host, or nil if the libhegel
+    # release does not publish a build for it. Split from asset_name (which raises) so a
     # directory override can treat an unsupported host as "skip this
     # candidate" instead of an error.
     def release_asset_name(host_cpu, host_os)
@@ -159,7 +159,7 @@ module Hegel
     end
 
     # Shared-library extension for host_os alone, independent of whether the
-    # specific host_cpu is one hegel-rust publishes a build for. This lets
+    # specific host_cpu is one libhegel publishes a build for. This lets
     # an explicit directory override (step 1) resolve on an otherwise
     # unsupported host (e.g. x86_64-darwin), matching a local libhegel build
     # that always produces the OS-native extension.

data/lib/hegel/report.rb

@@ -13,9 +13,10 @@ module Hegel
     # One failure's rendered ingredients. +test_cases+ and +discarded+ are
     # the generation phase's own counts up to that failure's first
     # appearance (see Hegel::Runner::GenerationStats), not the shrink
-    # phase's. +entries+ is the [:draw, name, value] / [:note, message] list
-    # Hegel::TestCase recorded on the stamped case that produced this
-    # failure, in call order, still un-#inspect'd/un-#to_s'd (see
+    # phase's. +entries+ is the [:draw, name, value, indent] /
+    # [:note, message, indent] list Hegel::TestCase recorded on the stamped
+    # case that produced this failure, in call order, still
+    # un-#inspect'd/un-#to_s'd (see
     # Hegel::TestCase#record_draw and #note for why). +blob+ is the string
     # Hegel.test(reproduce_failure:) accepts to replay this same failure, or
     # nil when the engine produced none. +caveat+ is the engine's own account
@@ -41,10 +42,10 @@ module Hegel
       entries.map do |entry|
         next entry unless entry[0] == :draw
 
-        _tag, name, value = entry
+        _tag, name, value, indent = entry
         if counts[name] > 1
           seen[name] += 1
-          [:draw, "#{name}_#{seen[name]}", value]
+          [:draw, "#{name}_#{seen[name]}", value, indent]
         else
           entry
         end
@@ -60,17 +61,19 @@ module Hegel
     # the same. A :note shares the :draw lines' 2-space indent
     # deliberately: both belong to the same block, and a different indent
     # would read as a different kind of thing instead of the same
-    # call-order list.
+    # call-order list. Each entry's own indent goes on top of those 2
+    # columns, which is how an iteration of Hegel::TestCase#repeat sits
+    # under its "// Repetition #N" line.
     def render_failure(failure)
       cases = "#{failure.test_cases} test #{(failure.test_cases == 1) ? "case" : "cases"}"
       lines = ["Falsified after #{cases} (#{failure.discarded} discarded):", ""]
       assign_names(failure.entries).each do |entry|
         if entry[0] == :draw
-          _tag, name, value = entry
-          lines << "  #{name} = #{value.inspect}"
+          _tag, name, value, indent = entry
+          lines << "  #{" " * indent}#{name} = #{value.inspect}"
         else
-          _tag, message = entry
-          lines << "  #{message}"
+          _tag, message, indent = entry
+          lines << "  #{" " * indent}#{message}"
         end
       end
       lines.push("", "note: #{failure.caveat}") if failure.caveat

data/lib/hegel/runner.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "grammar_cache"
 require_relative "lib_hegel"
 require_relative "report"
 require_relative "settings"
@@ -97,10 +98,8 @@ module Hegel
 
     module_function
 
-    # Runs +block+ as a Hegel property against +impl+, applying +test_cases+,
-    # +seed+, +derandomize+, +verbosity+, +database+, +database_key+,
-    # +phases+, +suppress_health_check+, and +report_multiple_failures+ (see
-    # Hegel::Settings) to a fresh settings handle first. Returns nil on a
+    # Runs +block+ as a Hegel property against +impl+, applying the
+    # settings keywords (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
@@ -119,6 +118,13 @@ module Hegel
     # with its class and backtrace intact), so a hegel.toml profile or a
     # HEGEL_* variable does not get to turn it off by accident.
     #
+    # +profile+ names the engine profile the settings start from; nil starts
+    # from the default profile. The keywords apply on top either way, so one
+    # passed explicitly beats the profile's value.
+    #
+    # +test_location+ is a Hegel::TestLocation. It is identity rather than a
+    # setting, so it goes to the engine here and not through Settings.apply.
+    #
     # +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.
@@ -130,16 +136,27 @@ 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.
-    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,
+    #
+    # The grammars the run compiled are freed after the run and before the
+    # context (docs/adr/0033).
+    def run(impl:, test_location:, profile: nil, test_cases: nil, seed: nil, derandomize: nil, verbosity: nil, database: nil, database_key: nil,
+      phases: nil, suppress_health_check: nil, report_multiple_failures: false, stop_on_first_failure: nil,
+      print_blob: nil, show_statistics: nil, nondeterminism_strictness: nil, backend: nil,
       output: $stderr, reproduce_failure: nil, &block)
       quiet = verbosity == :quiet
       LibHegel.with_context(impl) do |ctx|
-        settings = impl.settings_new(ctx)
+        settings = Settings.new_handle(impl, ctx, profile)
         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)
+            suppress_health_check: suppress_health_check, report_multiple_failures: report_multiple_failures,
+            stop_on_first_failure: stop_on_first_failure, print_blob: print_blob, show_statistics: show_statistics,
+            nondeterminism_strictness: nondeterminism_strictness, backend: backend)
+          impl.settings_set_test_location(ctx, settings, test_location.file, test_location.begin_line,
+            test_location.class_name, test_location.function)
+          # Read back rather than taken from the keyword, so that a profile
+          # or HEGEL_PRINT_BLOB decides when the keyword is nil.
+          print_blob = impl.settings_get_print_blob(ctx, settings)
           if reproduce_failure
             impl.run_start_blob(ctx, settings, reproduce_failure)
           else
@@ -150,19 +167,26 @@ module Hegel
           # 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)
+        grammars = GrammarCache.new
+        begin
+          run_and_finish(impl, ctx, run, grammars, reproducing: !reproduce_failure.nil?, quiet: quiet,
+            print_blob: print_blob, output: output, &block)
+        ensure
+          grammars.free_all(impl, ctx)
+        end
       end
     end
 
     # Drives +run+ and hands its result to #finish.
-    def run_and_finish(impl, ctx, run, reproducing:, quiet:, output:, &block)
+    def run_and_finish(impl, ctx, run, grammars, reproducing:, quiet:, print_blob:, output:, &block)
       stats = GenerationStats.new
       captures = {}
-      drive(impl, ctx, run, stats, captures, &block)
+      drive(impl, ctx, run, grammars, stats, captures, &block)
 
       result = impl.run_result(ctx, run)
       begin
-        finish(impl, ctx, result, stats, captures, reproducing: reproducing, quiet: quiet, output: output)
+        finish(impl, ctx, result, stats, captures, reproducing: reproducing, quiet: quiet, print_blob: print_blob,
+          output: output)
       ensure
         impl.run_result_free(ctx, result)
       end
@@ -178,16 +202,16 @@ module Hegel
     # 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
-    # and rejected cases call the body. Measured against libhegel 0.45.7, a
+    # and rejected cases call the body. Measured against libhegel 0.48.0, a
     # run configured for 20 test cases whose body rejected nearly every case
-    # took 913 to 1818 iterations. +stats+ does its own, different counting
+    # took 782 to 2047 iterations over 30 runs. +stats+ does its own, different counting
     # -- see GenerationStats above.
-    def drive(impl, ctx, run, stats, captures, &block)
+    def drive(impl, ctx, run, grammars, stats, captures, &block)
       loop do
         tc = impl.next_test_case(ctx, run)
         break if tc.nil?
 
-        run_case(impl, ctx, tc, stats, captures, &block)
+        run_case(impl, ctx, tc, grammars, stats, captures, &block)
       end
     end
 
@@ -207,8 +231,8 @@ module Hegel
     # 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))
+    def with_test_case(impl, ctx, tc, grammars)
+      test_case = TestCase.new(impl, ctx, tc, record: impl.test_case_should_capture(ctx, tc), grammars: grammars)
       yield test_case
     ensure
       begin
@@ -228,8 +252,8 @@ module Hegel
     # 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|
+    def run_case(impl, ctx, tc, grammars, stats, captures, &block)
+      with_test_case(impl, ctx, tc, grammars) do |test_case|
         status, origin, exception, entries = classify(test_case, &block)
         stats.record(status, origin)
         keep_capture(captures, origin, exception, entries) if status == LibHegel::HEGEL_STATUS_INTERESTING
@@ -258,7 +282,7 @@ module Hegel
     # 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:)
+    def finish(impl, ctx, result, stats, captures, reproducing:, quiet:, print_blob:, output:)
       status = impl.run_result_status(ctx, result)
       case status
       when LibHegel::HEGEL_RUN_STATUS_PASSED
@@ -266,7 +290,7 @@ module Hegel
       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
-        report_failures(impl, ctx, result, stats, captures, quiet: quiet, output: output)
+        report_failures(impl, ctx, result, stats, captures, quiet: quiet, print_blob: print_blob, output: output)
       else
         raise Hegel::Error, "hegel: run finished with an unrecognized status (#{status})"
       end
@@ -286,13 +310,13 @@ module Hegel
     # 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 report_failures(impl, ctx, result, stats, captures, quiet:, output:)
+    def report_failures(impl, ctx, result, stats, captures, quiet:, print_blob:, output:)
       exceptions = []
       failures = []
       impl.run_result_failure_count(ctx, result).times do |index|
         failure = impl.run_result_failure(ctx, result, index)
         begin
-          exception, report = failure_report(impl, ctx, failure, stats, captures)
+          exception, report = failure_report(impl, ctx, failure, stats, captures, print_blob: print_blob)
           exceptions << exception
           failures << report
         ensure
@@ -310,13 +334,13 @@ module Hegel
     # 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)
+    def failure_report(impl, ctx, failure, stats, captures, print_blob:)
       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)
+        blob: (impl.failure_reproduction_blob(ctx, failure) if print_blob), caveat: impl.failure_caveat(ctx, failure)
       )
       [capture.exception, report]
     end
@@ -344,10 +368,20 @@ module Hegel
       [LibHegel::HEGEL_STATUS_VALID, nil, nil, nil]
     rescue *Hegel::FATAL_EXCEPTIONS
       raise
-    rescue Hegel::AssumeFailed
+    # A LeafBudgetExceeded gets here only when a body swallowed the
+    # exception that replaced it mid-unwind and then drew again. It is
+    # library control flow, not a property failing, and its attempt never
+    # reached hegel_recursion_retry, so the case is discarded.
+    rescue Hegel::AssumeFailed, Hegel::LeafBudgetExceeded
       [LibHegel::HEGEL_STATUS_INVALID, nil, nil, nil]
     rescue Hegel::StopTest
       [LibHegel::HEGEL_STATUS_OVERRUN, nil, nil, nil]
+    rescue Hegel::LoopDone
+      # Hegel::TestCase#repeat ran until the engine stopped it, with no
+      # failure; hegel-rust's run lifecycle maps its LoopDone to VALID too.
+      # .mutineer.yml ignores the mutants of its last two elements by id, for
+      # the reason given at the first VALID above.
+      [LibHegel::HEGEL_STATUS_VALID, nil, nil, nil]
     rescue Exception => e
       [LibHegel::HEGEL_STATUS_INTERESTING, origin_for(e), e, test_case.entries]
     end

data/lib/hegel/settings.rb

@@ -41,11 +41,22 @@ module Hegel
       large_initial_test_case: LibHegel::HEGEL_HC_LARGE_INITIAL_TEST_CASE
     }.freeze
 
+    NONDETERMINISM_STRICTNESS_CODES = {
+      quiet: LibHegel::HEGEL_NONDETERMINISM_QUIET,
+      warn: LibHegel::HEGEL_NONDETERMINISM_WARN,
+      error: LibHegel::HEGEL_NONDETERMINISM_ERROR
+    }.freeze
+
+    BACKEND_CODES = {
+      default: LibHegel::HEGEL_BACKEND_DEFAULT,
+      urandom: LibHegel::HEGEL_BACKEND_URANDOM
+    }.freeze
+
     module_function
 
     # Applies every one of Hegel.test's settings keywords to +settings+ via
-    # +impl+. +test_cases+, +seed+, +derandomize+, +verbosity+, +phases+, and
-    # +suppress_health_check+ all skip their setter when left nil.
+    # +impl+. Every keyword skips its setter when nil, except
+    # database/database_key and report_multiple_failures (below).
     # +database+/+database_key+ follow #apply_database's own table, called
     # unconditionally since even the nil/nil case has a setter to call (see
     # its comment). +report_multiple_failures+ is called unconditionally too,
@@ -53,26 +64,96 @@ module Hegel
     # 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.
-    def apply(impl, ctx, settings, test_cases:, seed:, derandomize:, verbosity:, database:, database_key:, phases:,
-      suppress_health_check:, report_multiple_failures:)
+    def apply(impl, ctx, settings, database:, database_key:, report_multiple_failures:, **keywords)
+      apply_shared(impl, ctx, settings, **keywords)
+      apply_database(impl, ctx, settings, database: database, database_key: database_key)
+      impl.settings_set_report_multiple_failures(ctx, settings, report_multiple_failures)
+    end
+
+    # The keywords a run and a registered profile have in common. The example
+    # database key and report_multiple_failures are left to the callers:
+    # a run always passes the latter, and a profile snapshot carries no key.
+    def apply_shared(impl, ctx, settings, test_cases:, seed:, derandomize:, verbosity:, phases:,
+      suppress_health_check:, stop_on_first_failure:, print_blob:, show_statistics:,
+      nondeterminism_strictness:, backend:)
       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?
       apply_verbosity(impl, ctx, settings, verbosity) unless verbosity.nil?
-      apply_database(impl, ctx, settings, database: database, database_key: database_key)
       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)
+      unless stop_on_first_failure.nil?
+        impl.settings_set_stop_on_first_failure(ctx, settings, stop_on_first_failure)
+      end
+      impl.settings_set_print_blob(ctx, settings, print_blob) unless print_blob.nil?
+      impl.settings_set_show_statistics(ctx, settings, show_statistics) unless show_statistics.nil?
+      unless nondeterminism_strictness.nil?
+        code = lookup(NONDETERMINISM_STRICTNESS_CODES, nondeterminism_strictness, "nondeterminism_strictness")
+        impl.settings_set_nondeterminism_strictness(ctx, settings, code)
+      end
+      impl.settings_set_backend(ctx, settings, lookup(BACKEND_CODES, backend, "backend")) unless backend.nil?
+    end
+
+    # A settings handle for a run or a profile: from the default profile when
+    # +profile+ is nil, from the named one otherwise.
+    def new_handle(impl, ctx, profile)
+      profile.nil? ? impl.settings_new(ctx) : impl.settings_new_for_profile(ctx, profile)
+    end
+
+    # Registers the settings built from +profile+ (nil: the default profile)
+    # and the keywords as the profile +name+, for the whole process. A later
+    # Hegel.test(profile: name) or set_default_profile(name) starts from them.
+    # Registration is not retroactive and replaces an earlier one of the same
+    # name. The keywords are Hegel.test's, each nil for "leave the starting
+    # value", minus database_key, which the engine leaves out of a snapshot,
+    # and with +database+ passed straight to the engine ("" disables it) and
+    # report_multiple_failures applied only when given: Hegel.test always
+    # passes its own, so a profile's value for that one never reaches a run
+    # (docs/adr/0028).
+    #
+    # The profile table is process-wide state in the engine, not on +impl+'s
+    # context, so a registration made here outlives the context this opens.
+    def register_profile(name, profile: nil, test_cases: nil, seed: nil, derandomize: nil, verbosity: nil,
+      database: nil, phases: nil, suppress_health_check: nil, report_multiple_failures: nil,
+      stop_on_first_failure: nil, print_blob: nil, show_statistics: nil, nondeterminism_strictness: nil,
+      backend: nil, impl: Hegel.default_impl)
+      LibHegel.with_context(impl) do |ctx|
+        settings = new_handle(impl, ctx, profile)
+        begin
+          apply_shared(impl, ctx, settings, test_cases: test_cases, seed: seed, derandomize: derandomize,
+            verbosity: verbosity, phases: phases, suppress_health_check: suppress_health_check,
+            stop_on_first_failure: stop_on_first_failure, print_blob: print_blob, show_statistics: show_statistics,
+            nondeterminism_strictness: nondeterminism_strictness, backend: backend)
+          impl.settings_set_database(ctx, settings, database) unless database.nil?
+          unless report_multiple_failures.nil?
+            impl.settings_set_report_multiple_failures(ctx, settings, report_multiple_failures)
+          end
+          impl.settings_register_profile(ctx, name, settings)
+        ensure
+          impl.settings_free(ctx, settings)
+        end
+      end
+      nil
+    end
+
+    # Makes +name+ the profile a nil +profile+ resolves to, for the whole
+    # process, ahead of HEGEL_DEFAULT_PROFILE and hegel.toml. "" clears it.
+    # The name need not be registered yet.
+    def set_default_profile(name, impl: Hegel.default_impl)
+      LibHegel.with_context(impl) { |ctx| impl.set_default_profile(ctx, name) }
+      nil
     end
 
     # Split from #apply so the VERBOSITY_CODES lookup (one of several
     # keywords that can fail) is not buried inside the top-level sequence.
     def apply_verbosity(impl, ctx, settings, verbosity)
-      code = VERBOSITY_CODES.fetch(verbosity) do
-        raise Hegel::Error,
-          "hegel: unknown verbosity #{verbosity.inspect}; expected one of #{VERBOSITY_CODES.keys.inspect}"
+      impl.settings_set_verbosity(ctx, settings, lookup(VERBOSITY_CODES, verbosity, "verbosity"))
+    end
+
+    def lookup(codes, value, keyword)
+      codes.fetch(value) do
+        raise Hegel::Error, "hegel: unknown #{keyword} #{value.inspect}; expected one of #{codes.keys.inspect}"
       end
-      impl.settings_set_verbosity(ctx, settings, code)
     end
 
     # docs/adr/0009-turn-the-example-database-on-with-a-key.md decides this
@@ -148,12 +229,7 @@ module Hegel
           "hegel: #{keyword} expects one or more of #{codes.keys.inspect}, got an empty Array"
       end
 
-      values.reduce(0) do |mask, value|
-        code = codes.fetch(value) do
-          raise Hegel::Error, "hegel: unknown #{keyword} #{value.inspect}; expected one of #{codes.keys.inspect}"
-        end
-        mask | code
-      end
+      values.reduce(0) { |mask, value| mask | lookup(codes, value, keyword) }
     end
   end
 end

data/lib/hegel/state_machine.rb

@@ -23,6 +23,9 @@ module Hegel
     # class's.
     include Syntax::Methods
 
+    # One declared rule: its block, and its selection weight.
+    Rule = Data.define(:block, :weight)
+
     # 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)
@@ -33,8 +36,17 @@ module Hegel
       # instance being tested, and is handed the running Hegel::TestCase as
       # its one argument -- ignored if the block declares no parameter, the
       # ordinary Ruby block rule.
-      def rule(name, &block)
-        declare(:@rules, "rule", name, block)
+      #
+      # +weight+ hints how often the engine picks this rule against the
+      # others: a positive, finite number, 1.0 by default. It is a guide, not
+      # a distribution: the engine enables a random subset of the rules in
+      # each test case, so a rule's frequency also depends on which others
+      # are enabled. The engine rejects a weight that is not finite and
+      # positive when the machine runs.
+      def rule(name, weight: 1.0, &block)
+        raise Hegel::Error, "hegel: rule weight must be a real number, got #{weight.inspect}" unless weight.is_a?(Numeric) && weight.real?
+
+        declare(:@rules, "rule", name, Rule.new(block: block, weight: weight))
       end
 
       # Declares an invariant named +name+, checked before the first rule
@@ -47,9 +59,10 @@ module Hegel
         declare(:@invariants, "invariant", name, Invariant.new(block: block, always_run: always_run))
       end
 
-      # name => block, in declaration order, this class's own declarations
+      # name => Rule, in declaration order, this class's own declarations
       # merged over its ancestors'. Hegel::Stateful.run reads this directly
-      # to build the ordered rule-name list libhegel indexes by position.
+      # to build the ordered rule-name and weight lists libhegel indexes by
+      # position.
       def rule_definitions
         merged_definitions(:@rules, :rule_definitions)
       end