hegeltest 0.1.0

data/lib/hegel/lib_hegel.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "locate"
+require_relative "libhegel_version"
+
+module Hegel
+  # The libhegel binding boundary: the small set of methods a connection to
+  # the native engine must answer to, plus the result-code translation and
+  # context lifecycle shared by every implementation.
+  #
+  # Ruby has no interface construct, so this module carries the contract two
+  # ways: METHODS names every method an implementation must answer to, and
+  # a conformance test (test/hegel/test_lib_hegel.rb) asserts that every
+  # implementation responds to all of them. LibHegel::Real drives the C ABI;
+  # test/support/fake_lib_hegel.rb (not shipped in the gem) is a second,
+  # configurable implementation, so the logic built on top of this boundary
+  # 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
+    # name. HEGEL_OK is success; every other value is a negative error code.
+    HEGEL_OK = 0
+    HEGEL_E_STOP_TEST = -1
+    HEGEL_E_ASSUME = -2
+    HEGEL_E_BACKEND = -3
+    HEGEL_E_INVALID_HANDLE = -4
+    HEGEL_E_INVALID_ARG = -5
+    HEGEL_E_ALREADY_COMPLETE = -6
+    HEGEL_E_NOT_COMPLETE = -7
+    HEGEL_E_INTERNAL = -8
+    HEGEL_E_CONCURRENT_USE = -9
+
+    # 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
+    # header by number alone.
+    CODE_NAMES = {
+      HEGEL_OK => "HEGEL_OK",
+      HEGEL_E_STOP_TEST => "HEGEL_E_STOP_TEST",
+      HEGEL_E_ASSUME => "HEGEL_E_ASSUME",
+      HEGEL_E_BACKEND => "HEGEL_E_BACKEND",
+      HEGEL_E_INVALID_HANDLE => "HEGEL_E_INVALID_HANDLE",
+      HEGEL_E_INVALID_ARG => "HEGEL_E_INVALID_ARG",
+      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"
+    }.freeze
+
+    # hegel_status_t, named from hegel.h's enum of the same name. Passed to
+    # hegel_mark_complete to describe how a test case ended.
+    HEGEL_STATUS_VALID = 0
+    HEGEL_STATUS_INVALID = 1
+    HEGEL_STATUS_OVERRUN = 2
+    HEGEL_STATUS_INTERESTING = 3
+
+    # hegel_run_status_t, named from hegel.h's enum of the same name. Read
+    # via hegel_run_result_status once a run has finished.
+    HEGEL_RUN_STATUS_PASSED = 0
+    HEGEL_RUN_STATUS_FAILED = 1
+    HEGEL_RUN_STATUS_ERROR = 2
+
+    # hegel_verbosity_t, named from hegel.h's enum of the same name. Passed
+    # to hegel_settings_set_verbosity.
+    HEGEL_VERBOSITY_QUIET = 0
+    HEGEL_VERBOSITY_NORMAL = 1
+    HEGEL_VERBOSITY_VERBOSE = 2
+    HEGEL_VERBOSITY_DEBUG = 3
+
+    # 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.
+    HEGEL_PHASE_EXPLICIT = 1
+    HEGEL_PHASE_REUSE = 2
+    HEGEL_PHASE_GENERATE = 4
+    HEGEL_PHASE_TARGET = 8
+    HEGEL_PHASE_SHRINK = 16
+    HEGEL_PHASE_ALL = 31
+
+    # hegel_health_check_t, named from hegel.h's enum of the same name. A
+    # bitwise OR of these is passed to
+    # hegel_settings_set_suppress_health_check; the default is all
+    # enabled.
+    HEGEL_HC_FILTER_TOO_MUCH = 1
+    HEGEL_HC_TOO_SLOW = 2
+    HEGEL_HC_TEST_CASES_TOO_LARGE = 4
+    HEGEL_HC_LARGE_INITIAL_TEST_CASE = 8
+
+    # hegel_label_t, named from hegel.h's enum of the same name. Passed to
+    # hegel_start_span to identify what kind of structure a span groups.
+    # Copied through HEGEL_LABEL_SET_CHOICE (value 33). The header
+    # describes the last two, HEGEL_LABEL_FRESH_ID and
+    # HEGEL_LABEL_SET_CHOICE, as spans the engine opens itself around a
+    # hegel_pool_add / hegel_pool_generate call; a caller never passes
+    # either to hegel_start_span.
+    #
+    # The header documents that "Libraries may use any stable u64 to
+    # define their own spans." A caller building its own compound
+    # generator on top of this boundary can pick any u64 that does not
+    # collide with the reserved values below.
+    HEGEL_LABEL_LIST = 1
+    HEGEL_LABEL_LIST_ELEMENT = 2
+    HEGEL_LABEL_SET = 3
+    HEGEL_LABEL_SET_ELEMENT = 4
+    HEGEL_LABEL_MAP = 5
+    HEGEL_LABEL_MAP_ENTRY = 6
+    HEGEL_LABEL_TUPLE = 7
+    HEGEL_LABEL_ONE_OF = 8
+    HEGEL_LABEL_OPTIONAL = 9
+    HEGEL_LABEL_FIXED_DICT = 10
+    HEGEL_LABEL_FLAT_MAP = 11
+    HEGEL_LABEL_FILTER = 12
+    HEGEL_LABEL_MAPPED = 13
+    HEGEL_LABEL_SAMPLED_FROM = 14
+    HEGEL_LABEL_ENUM_VARIANT = 15
+    HEGEL_LABEL_FEATURE_FLAG = 16
+    HEGEL_LABEL_REGEX = 17
+    HEGEL_LABEL_EMAIL = 18
+    HEGEL_LABEL_URL = 19
+    HEGEL_LABEL_DOMAIN = 20
+    HEGEL_LABEL_DATE = 21
+    HEGEL_LABEL_TIME = 22
+    HEGEL_LABEL_DATETIME = 23
+    HEGEL_LABEL_UUID = 24
+    HEGEL_LABEL_IP_ADDRESS = 25
+    HEGEL_LABEL_INTEGER = 26
+    HEGEL_LABEL_FLOAT = 27
+    HEGEL_LABEL_BOOLEAN = 28
+    HEGEL_LABEL_BYTES = 29
+    HEGEL_LABEL_STRING = 30
+    HEGEL_LABEL_STATEFUL_RULE = 31
+    HEGEL_LABEL_FRESH_ID = 32
+    HEGEL_LABEL_SET_CHOICE = 33
+
+    # HEGEL_STATE_MACHINE_DONE, named from hegel.h's #define of the same
+    # name. hegel_state_machine_next_rule writes this to its
+    # out_rule_index parameter once the current test case's step budget
+    # is exhausted; see LibHegel::Real#state_machine_next_rule for why
+    # that raw sentinel is returned rather than translated to nil.
+    HEGEL_STATE_MACHINE_DONE = -1
+
+    # hegel_new_collection's max_size accepts UINT64_MAX to mean "no upper
+    # bound", in the header's own words. Ruby has no fixed-width integer
+    # type to read that constant off, so it is spelled out here as the
+    # value a 64-bit unsigned integer maxes out at.
+    HEGEL_COLLECTION_MAX_SIZE_UNBOUNDED = (2**64) - 1
+
+    # hegel_generate_float's smallest_nonzero_magnitude must be positive
+    # and finite. The header names 5e-324 as the width-64 value that
+    # places no restriction on which nonzero magnitudes get drawn.
+    HEGEL_FLOAT64_SMALLEST_NONZERO_MAGNITUDE_UNRESTRICTED = 5e-324
+
+    # The methods every implementation of this boundary (Real, Fake) must
+    # answer to. Held as data, not a Ruby interface/protocol, because Ruby
+    # has none; test/hegel/test_lib_hegel.rb asserts every implementation
+    # 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_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
+      run_result run_result_free run_result_status run_result_error
+      run_result_failure_count run_result_failure failure_free failure_origin
+      failure_reproduction_blob test_case_from_blob
+      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
+      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 settings_set_stateful_step_count
+      target
+      new_pool pool_add pool_generate pool_free
+      new_state_machine state_machine_next_rule state_machine_rule_rejected state_machine_free
+    ].freeze
+
+    module_function
+
+    # Runs the block with a context obtained from +impl.context_new+,
+    # freeing it via +impl.context_free+ whether the block returns or
+    # raises.
+    #
+    # A block is the only construct used here: hegel_context_free requires
+    # every other handle taking this context to be freed first, so the
+    # context must outlive them all, and Ruby's GC gives finalizers no
+    # ordering guarantee to rely on instead. The block's caller is the
+    # context's owner and holds it for exactly as long as the block runs.
+    def with_context(impl)
+      ctx = impl.context_new
+      yield ctx
+    ensure
+      impl.context_free(ctx)
+    end
+
+    # Raises the exception +code+ translates to, or returns without effect
+    # for HEGEL_OK. The message is read from +impl.context_last_error(ctx)+
+    # immediately, since libhegel's own buffer for it is invalidated by the
+    # next call taking the same context. By the time a caller further up
+    # the stack could read it, the buffer might already describe a
+    # different call.
+    def check!(impl, ctx, code)
+      return if code == HEGEL_OK
+
+      # An engine newer than the pinned one can return a code these bindings
+      # have no name for, which is the situation the version warning exists
+      # to announce. Naming it plainly beats failing to look it up, because a
+      # KeyError here would replace the engine's own diagnostic with a
+      # message about a missing hash key.
+      name = CODE_NAMES[code] || "unknown result code"
+      message = "#{name} (#{code}): #{impl.context_last_error(ctx)}"
+      case code
+      when HEGEL_E_STOP_TEST then raise StopTest, message
+      when HEGEL_E_ASSUME then raise AssumeFailed, message
+      else raise Hegel::Error, message
+      end
+    end
+
+    # Warns on +io+ when +impl.version(ctx)+ differs from the engine
+    # version these bindings were built for (Hegel::LIBHEGEL_VERSION), and
+    # does nothing when they match. Never raises: a mismatched engine is
+    # still usable, only untested against, so this is a warning rather than
+    # a load failure. +io+ defaults to $stderr and is overridable so a
+    # caller (and a test) can capture the warning instead.
+    def warn_on_version_mismatch(impl, ctx, io: $stderr)
+      loaded = impl.version(ctx)
+      return if loaded == Hegel::LIBHEGEL_VERSION
+
+      io.puts(<<~MESSAGE.chomp)
+        hegel: loaded libhegel #{loaded} but these bindings were built for #{Hegel::LIBHEGEL_VERSION}; behaviour may differ. Unset HEGEL_LIBHEGEL_PATH to use the bundled engine, or point it at a matching build.
+      MESSAGE
+    end
+
+    # hegel_generate_integer_big's own documented convention for
+    # min_value/max_value/out_value: two's-complement little-endian signed
+    # byte buffers. Pure Ruby arithmetic, no native marshalling, so this is
+    # unit-testable directly (test/hegel/test_lib_hegel.rb round-trips it)
+    # and shared unchanged between LibHegel::Real's bounds-encode and
+    # result-decode, kept out of real.rb so that direct testing stays
+    # possible.
+    #
+    # +n+'s minimal two's-complement byte length is n.bit_length / 8 + 1.
+    # Integer#bit_length reports one bit fewer at a negative power of two
+    # (-128 is 7 bits, 128 is 8), so this formula needs no separate
+    # sign-bit adjustment there; verified against a brute-force
+    # minimal-length search over both signs and the int32/int64/2**100
+    # boundaries.
+    def encode_integer_le(n)
+      byte_length = (n.bit_length / 8) + 1
+      byte_length.times.map { |i| (n >> (8 * i)) & 0xFF }.pack("C*")
+    end
+
+    # The inverse of .encode_integer_le. +bytes+ may be longer than the
+    # value's own minimal encoding -- the header documents hegel_generate_
+    # integer_big's out_value as sign-filled past that length, so a caller
+    # may decode the whole out_value_cap-sized buffer and still get the
+    # right answer -- so length here is read from +bytes+ itself, not
+    # assumed minimal.
+    def decode_integer_le(bytes)
+      length = bytes.bytesize
+      unsigned = bytes.each_byte.with_index.sum { |byte, i| byte << (8 * i) }
+      negative = (bytes.getbyte(length - 1) & 0x80) != 0
+      negative ? unsigned - (1 << (8 * length)) : unsigned
+    end
+  end
+end

data/lib/hegel/libhegel_version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Hegel
+  # The libhegel engine release these bindings target. This is independent of
+  # 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.32.5"
+end

data/lib/hegel/locate.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "errors"
+
+module Hegel
+  # Resolves the path to the native libhegel shared library.
+  #
+  # Resolution order:
+  #
+  # 1. +HEGEL_LIBHEGEL_PATH+: an explicit override, given as a file path or
+  #    a directory that contains the library under one of the three
+  #    basenames it is known to ship under (see find_override). This is
+  #    checked first because hegel-go, hegel-typescript, hegel-java, and
+  #    hegel-ocaml all give this same variable name priority over their own
+  #    fallback.
+  # 2. The copy bundled into the gem under +lib/hegel/libhegel/+.
+  #
+  # A sibling `../hegel-rust` checkout 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
+  # have would be an untested, unreachable branch under 100% coverage.
+  #
+  # Resolution knowledge is confined to this file. Every other file calls
+  # only Locate.resolve. A future change to the distribution method
+  # (bundled copy vs. runtime download) therefore has one place to change.
+  # This module never touches the network; only the development-only
+  # `libhegel:fetch` rake task downloads anything.
+  module Locate
+    # Env var that overrides resolution with an explicit path.
+    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.
+    ASSET_NAMES = {
+      "arm64-darwin" => "libhegel-darwin-arm64.dylib",
+      "x86_64-linux" => "libhegel-linux-amd64.so",
+      "aarch64-linux" => "libhegel-linux-arm64.so",
+      "x64-mingw-ucrt" => "libhegel-windows-amd64.dll",
+      "aarch64-mingw-ucrt" => "libhegel-windows-arm64.dll"
+    }.freeze
+
+    # Directory inside the gem where a platform build may be bundled.
+    GEM_LIBHEGEL_DIR = File.expand_path("libhegel", __dir__)
+
+    # Default lookup for the gem-bundled step: the asset file directly under
+    # +dir+, or nil if it is not there.
+    DEFAULT_FINDER = lambda do |dir, asset|
+      path = File.join(dir, asset)
+      File.file?(path) ? path : nil
+    end
+
+    module_function
+
+    # Resolves a usable libhegel path. Env, host, the gem-bundled directory,
+    # and the gem-bundled finder are all injectable so this is testable
+    # without a real native library or a real host match.
+    #
+    # Raises Hegel::Error if the host is unsupported, or if it is supported
+    # but no bundled library is found for it.
+    def resolve(env: ENV, host_cpu: RbConfig::CONFIG["host_cpu"], host_os: RbConfig::CONFIG["host_os"],
+      gem_dir: GEM_LIBHEGEL_DIR, finder: DEFAULT_FINDER)
+      overridden = from_env(env, host_cpu, host_os)
+      return overridden unless overridden.nil?
+
+      # Host support is checked before any filesystem lookup, so an
+      # unsupported host reports itself as unsupported rather than as a
+      # confusing "file not found" once the gem-bundled directory is missing
+      # or empty.
+      asset = asset_name(host_cpu: host_cpu, host_os: host_os)
+      finder.call(gem_dir, asset) || raise(Hegel::Error, missing_bundle_message(asset, gem_dir))
+    end
+
+    # The release asset name for the given host, or raises Hegel::Error if
+    # hegel-rust 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
+
+    # Step 1: the explicit override, or nil if unset or empty. An empty
+    # value is treated as unset (not as "use the current directory"), so
+    # exporting the variable empty in CI does not silently break resolution.
+    def from_env(env, host_cpu, host_os)
+      value = env[LIBRARY_PATH_ENV]
+      return nil if value.nil? || value.empty?
+
+      File.directory?(value) ? find_override(value, host_cpu, host_os) : value
+    end
+
+    # Searches +dir+ for the first of the three basenames a directory
+    # override may hold, in priority order, or raises Hegel::Error naming
+    # both the directory and every basename that was tried.
+    #
+    # 1. This host's release asset name (e.g. libhegel-darwin-arm64.dylib),
+    #    the name `rake libhegel:fetch` itself installs, so it is the most
+    #    likely match. Skipped, not raised, when the host is unsupported: a
+    #    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
+    #    crate (`[lib] name = "hegel_c"`) is built without renaming it.
+    # 3. libhegel.<ext>, a renamed copy, per the hegel-go and hegel-ocaml
+    #    READMEs.
+    def find_override(dir, host_cpu, host_os)
+      names = override_candidate_names(host_cpu, host_os)
+      names.each do |name|
+        path = File.join(dir, name)
+        return path if File.file?(path)
+      end
+      raise Hegel::Error, missing_override_message(dir, names)
+    end
+
+    # The basenames find_override tries, in priority order. release_asset_name
+    # is omitted (not just skipped later) when the host is unsupported, so an
+    # unsupported host never appears in the candidate list or its error message.
+    def override_candidate_names(host_cpu, host_os)
+      ext = ext_of_os(host_os)
+      [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
+    # directory override can treat an unsupported host as "skip this
+    # candidate" instead of an error.
+    def release_asset_name(host_cpu, host_os)
+      ASSET_NAMES[host_id(host_cpu, host_os)]
+    end
+
+    # "<host_cpu>-<host_os>", normalized to the form ASSET_NAMES keys on.
+    def host_id(host_cpu, host_os)
+      os = normalize_os(host_os)
+      "#{normalize_cpu(host_cpu, os)}-#{os}"
+    end
+
+    # RbConfig::CONFIG["host_os"] carries OS-version detail (e.g.
+    # "darwin25", "linux-gnu") that the asset-name table does not key on.
+    # An OS family this method does not recognize is passed through
+    # unchanged, so it deliberately fails the ASSET_NAMES lookup instead of
+    # being coerced into a false match.
+    def normalize_os(host_os)
+      case host_os
+      when /darwin/ then "darwin"
+      when /linux/ then "linux"
+      when /mingw|windows/ then "mingw-ucrt"
+      else host_os
+      end
+    end
+
+    # RubyGems abbreviates the "x86_64" config.guess CPU to "x64" only for
+    # Windows platform strings (the "x64-mingw-ucrt" gem platform); every
+    # other OS keeps the raw host_cpu value, matching this project's own
+    # Gemfile.lock entry "arm64-darwin-25" on an Apple Silicon Mac.
+    def normalize_cpu(host_cpu, normalized_os)
+      (normalized_os == "mingw-ucrt" && host_cpu == "x86_64") ? "x64" : host_cpu
+    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
+    # 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.
+    def ext_of_os(host_os)
+      case host_os
+      when /darwin/ then "dylib"
+      when /mingw|windows/ then "dll"
+      else "so"
+      end
+    end
+
+    def unsupported_host_message(host_cpu, host_os)
+      "libhegel has no published build for host \"#{host_cpu}-#{host_os}\". " \
+        "Set #{LIBRARY_PATH_ENV} to a local libhegel build."
+    end
+
+    def missing_bundle_message(asset, gem_dir)
+      "libhegel not found: expected #{asset} under #{gem_dir}. " \
+        "Set #{LIBRARY_PATH_ENV} to a local libhegel build, or run `rake libhegel:fetch`."
+    end
+
+    def missing_override_message(dir, names)
+      "libhegel not found under #{dir} (from #{LIBRARY_PATH_ENV}). Looked for: #{names.join(", ")}."
+    end
+  end
+end

data/lib/hegel/report.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Hegel
+  # Turns a failing run's recorded entries into the text a caller sees on
+  # failure, and the blob Hegel.test(reproduce_failure:) accepts. Formatted
+  # after hegel-rust's own failure report, so a reader moving between the
+  # two bindings recognises the shape.
+  #
+  # This module only formats data it is handed; it does not know how a run
+  # was driven, and does not write anywhere itself (see Hegel::Runner for
+  # both).
+  module Report
+    # 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 final replay 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.
+    Failure = Struct.new(:test_cases, :discarded, :entries, :blob)
+
+    module_function
+
+    # Assigns each :draw entry its display name: the name it was recorded
+    # under, suffixed with a 1-based, per-name counter only when that name
+    # occurs more than once among the :draw entries (their own relative
+    # order, unchanged). A single "n" stays "n"; two draws both named "draw"
+    # (the fallback every unlabelled draw shares) become "draw_1" and
+    # "draw_2", the same way hegel-rust's `__draw_named` disambiguates a
+    # repeated `repeatable`. :note entries carry no name to disambiguate and
+    # pass through unchanged, in the position they were recorded.
+    def assign_names(entries)
+      counts = entries.each_with_object(Hash.new(0)) do |entry, tally|
+        tally[entry[1]] += 1 if entry[0] == :draw
+      end
+      seen = Hash.new(0)
+      entries.map do |entry|
+        next entry unless entry[0] == :draw
+
+        _tag, name, value = entry
+        if counts[name] > 1
+          seen[name] += 1
+          [:draw, "#{name}_#{seen[name]}", value]
+        else
+          entry
+        end
+      end
+    end
+
+    # Renders one failure's block: its "Falsified after" header, its
+    # entries in call order (:draw #inspect'd, :note #to_s'd -- both here,
+    # on report assembly, not when Hegel::TestCase recorded them), and how
+    # to reproduce it. 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.
+    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}"
+        else
+          _tag, message = entry
+          lines << "  #{message}"
+        end
+      end
+      lines << ""
+      lines << "To reproduce this failure, pass the blob below to Hegel.test:"
+      lines << "    reproduce_failure: #{failure.blob.inspect}"
+      lines.join("\n")
+    end
+
+    # Renders every failure, in the order given. A single failure is just
+    # its own block. More than one gets hegel-rust's own distinct-failures
+    # count first, with a blank line (the join separator) before every
+    # block, including the first, matching the decided report shape.
+    def render(failures)
+      blocks = failures.map { |failure| render_failure(failure) }
+      return blocks.first if blocks.size == 1
+
+      (["Property-based test failed with #{blocks.size} distinct failures."] + blocks).join("\n\n")
+    end
+  end
+end