hegeltest 0.3.1-aarch64-linux → 0.4.0-aarch64-linux

data/docs/adr/0035-defer-concurrent-state-machines-and-the-engine-printer.md

@@ -0,0 +1,136 @@
+# 0035: Defer concurrent state machines and the engine printer
+
+## Status
+
+Accepted.
+
+## Context
+
+libhegel 0.47.2 offers two facilities that hegel-rust uses and this gem
+does not: concurrent state machines, and a printer that builds the failure
+report inside the engine. ADR 0015 counts a feature that this gem lacks as
+a divergence, so each needs a recorded reason. Paths and line numbers
+below are in hegeldev/hegel as of libhegel 0.47.2.
+
+### Concurrent state machines
+
+hegel-rust runs a `ConcurrentStateMachine` with `run_concurrent`
+(`frontends/rust/src/stateful.rs:989`). `hegel_new_state_machine` draws a
+concurrency level between `min_concurrency` and `max_concurrency`.
+`run_concurrent_machine` (`stateful.rs:1361`) spawns one thread per level
+inside `std::thread::scope` (`stateful.rs:1415`). Each round, it hands every
+worker a clone of the test case, `tc.clone()`, attributed to that worker
+with `set_worker` (`stateful.rs:1449-1450`). A `ConcurrentRule`'s `apply`
+takes `&M` (`stateful.rs:1097-1102`): the doc comment above it
+(`stateful.rs:1086-1096`) says the
+machine is "shared by reference across the worker threads, so any mutable
+model state needs interior mutability", and that the feature "is intended
+for advanced users. We otherwise discourage using it."
+
+The engine calls behind this are `hegel_test_case_clone`
+(`libhegel/include/hegel.h:1553`), which gives "an independent stream of the
+same test case" that "can be driven concurrently from different threads",
+and `hegel_test_case_set_worker` (`hegel.h:1614`), which prefixes each line
+the handle records with `[worker N +X.XXXms] `.
+
+Four things stand between this gem and a port:
+
+1. **Each worker needs its own context.** The threading section of
+   `hegel.h` (lines 101-117) says "A context must not be used concurrently
+   from multiple threads". hegel-rust keeps one context per thread in a
+   `thread_local!` (`frontends/rust/src/ffi.rs:72`). `Hegel::Runner.run`
+   opens one context for the whole run and threads it through every call,
+   so each worker would need a context of its own, and every handle
+   allocated from it freed before that context.
+2. **Ruby threads take turns.** `Hegel::LibHegel::Real#bind` builds each
+   `FFI::Function` without the `blocking:` option, so every engine call
+   holds the GVL for its duration. Between engine calls, Ruby threads
+   running pure-Ruby code switch on the VM's timer or at blocking I/O. A
+   short rule body that does no I/O then tends to run to completion before
+   another thread gets the GVL, and the interleavings a concurrent machine
+   exists to find seldom happen. A body that waits on I/O, a database, or a
+   C extension that releases the GVL would interleave.
+3. **Ractors cannot reach a shared machine.** Measured with ffi 1.17.4 on
+   Ruby 3.4.6: passing an unfrozen `FFI::Pointer` to `Ractor.new` raises
+   "cannot duplicate unbounded memory area", and passing an unfrozen
+   `FFI::Function` raises "cannot duplicate function instances". Both can
+   be made shareable with `Ractor.make_shareable`, and a shareable
+   `FFI::Function` is callable inside another Ractor. The handles are not
+   the obstacle. The machine is: hegel-rust's rules share one `&M`, and a
+   `Hegel::StateMachine` subclass instance with mutable state is an object
+   that only one Ractor can reach.
+4. **`CLAUDE.md` would change.** Its standing constraints say "The engine
+   is single-threaded. A context, a run, and a test case each belong to one
+   thread at a time." A concurrent runner needs that rule restated for
+   clones and per-thread contexts.
+
+`Hegel::LibHegel::Real#new_state_machine` passes a concurrency of exactly
+1, and ADR 0021 records the sequential machine this gem runs.
+
+### The engine printer
+
+hegel-rust prints each drawn value and note into the engine's document as
+the test body runs. `hegel_test_case_printer` (`hegel.h:3052`) gives a
+handle onto a test-case handle's print region, the `hegel_printer_*`
+calls (the comment above `hegel_printer_t`, `hegel.h:538-574`, describes
+the model) lay text out in groups that
+break to fit a width (default 79, `hegel.h:3073`), `hegel_printer_reflow`
+(`hegel.h:2910`) re-lays a flat debug string such as Ruby's `#inspect`, and
+`hegel_note` (`hegel.h:3079`) appends a line. A note written while a drawn
+value is mid-print is held back and placed after the value (`hegel.h`, the
+comment above `hegel_note`). `hegel_test_case_block` (`hegel.h:1589`)
+indents a section, and `hegel_test_case_set_worker` prefixes a worker's
+lines.
+
+This gem builds its report in Ruby. `Hegel::TestCase` records draws and
+notes on the cases the engine stamps for capture (ADR 0019),
+`Hegel::DrawName` names each draw from the caller's source (ADR 0005 and
+ADR 0014), and `Hegel::Report` renders the list. `Hegel::LibHegel::Real`
+passes a NULL output callback to `hegel_run_start`.
+
+## Decision
+
+**Concurrent state machines are not ported.** `Hegel::Stateful.run` stays
+sequential, at a concurrency of 1. This is a divergence under ADR 0015,
+recorded here. It is to be revisited when a caller asks for it, together
+with the engine printer: `hegel_test_case_set_worker` attributes
+`hegel_note` lines and lines started through a printer from
+`hegel_test_case_printer` (`hegel.h:1595-1599`), so a report that reads
+across workers comes from the engine document.
+
+**The engine printer is not adopted for draws.** `Hegel::Report` keeps
+building the report. Moving it into the engine would change two things
+that work today:
+
+- `Hegel::Report.assign_names` gives a name a counter only when that name
+  appears more than once among the whole case's draws (ADR 0014 decides
+  which draws get a name at all). At draw time, the rest of the case has
+  not run, so the printed name is not yet known.
+  `hegel_printer_deferred` could hold each name open until the case ends,
+  at the price of one hole per draw and a resolve step this gem does not
+  have.
+- The report's shape, which `test/hegel/test_report.rb` pins line by line,
+  and which a caller reads on every failure.
+
+The gains, width wrapping, a note placed after a value whose generation
+emitted it, indented step blocks, and worker prefixes, do not yet outweigh
+that.
+
+A narrower change stays open: `Hegel::Report` could lay out a long value
+through a standalone document, `hegel_printer_new` (`hegel.h:2746`), and
+`hegel_printer_reflow` over the value's `#inspect`, then read it back with
+`hegel_printer_value` (`hegel.h:3011`). That brings width wrapping without
+moving naming or the report into the engine.
+
+## Consequences
+
+A caller who wants to exercise concurrency can start Ruby threads inside a
+single rule. The engine then neither chooses nor shrinks the interleaving.
+
+A long drawn value prints on one line, as `#inspect` writes it.
+
+A later feature that wants an indented section of the report, the effect
+`hegel_test_case_block` gives in the engine document, builds that indent in
+`Hegel::Report`.
+
+A later record that ports either facility supersedes this one.

data/docs/architecture.md

@@ -18,7 +18,7 @@ recorded, and prints a blob that `Hegel.test(reproduce_failure:)` replays.
 The report comes from the cases the engine stamps for capture during the
 run; see
 [ADR 0019](adr/0019-report-failures-from-the-cases-the-engine-stamps.md).
-The generator layer covers twenty-five generators composing through `map`
+The generator layer covers thirty-four generators composing through `map`
 and `filter`, reachable bare through `Hegel::Syntax::Methods`. A test case
 can discard itself with `tc.assume` or `tc.reject`. A run can be shaped by
 `phases:`, `suppress_health_check:`, `report_multiple_failures:`, and the
@@ -43,10 +43,13 @@ schedules it.
 
 ## Where meaning comes from
 
-libhegel is hegel-rust's native engine. hegel-rust's Cargo workspace builds
-it from the `hegel-c` directory, as the crate `hegeltest-c`, whose header is
-`hegel-c/include/hegel.h`. That header defines the ABI this gem calls: what
-each function does, what its error codes mean, and who owns each pointer.
+libhegel is the native engine of every Hegel frontend. Since 0.47.2, the
+hegeldev/hegel Cargo workspace builds it from the `libhegel` directory, as
+the crate `hegeltest-c`, whose header is `libhegel/include/hegel.h`. The
+same workspace holds the Rust frontend, hegel-rust, at `frontends/rust`.
+Releases up to 0.47.1 came from hegeldev/hegel-rust, where the engine was at
+`hegel-c`. The header defines the ABI this gem calls: what each function
+does, what its error codes mean, and who owns each pointer.
 
 The Java, Go, TypeScript, OCaml, and C++ implementations bind the same
 engine. Each works under a constraint hegel-rust does not have: a dynamic
@@ -118,6 +121,12 @@ test-case handle, in nested `ensure`s so a failure releasing one cannot skip
 the other. See
 [ADR 0011](adr/0011-let-the-test-case-own-every-pool-drawn-from-it.md).
 
+A compiled grammar outlives the test case that compiled it, since compiling
+costs far more than drawing. `Hegel::Runner.run` keeps the run's grammars
+in a `Hegel::GrammarCache` and frees them after the run and before the
+context. See
+[ADR 0033](adr/0033-cache-compiled-grammars-for-the-length-of-a-run.md).
+
 ## A rule's own control flow
 
 Inside a stateful rule, `tc.assume(false)` means something narrower than it
@@ -132,6 +141,15 @@ exception can be raised inside an open span, which is why
 than beside the run loop: two `rescue Exception` sites need it now, and both
 have to let those four straight through before anything else.
 
+## An abandoned recursive attempt
+
+`recursive` unwinds through open spans on purpose. When an attempt outgrows its leaf budget, `Hegel::TestCase` raises
+`Hegel::LeafBudgetExceeded` and holds it until `hegel_recursion_retry`.
+Meanwhile `stop_span` makes no native call, so the retry can discard the
+spans the attempt opened, and every other call that takes the test-case
+handle raises the held exception again instead of reaching the engine. See
+[ADR 0032](adr/0032-suppress-span-closes-while-an-abandoned-recursion-attempt-unwinds.md).
+
 ## Generator validation happens at draw time
 
 hegel-rust's own contributor documentation states the rule for its
@@ -171,12 +189,16 @@ fields.
 
 ## Answered
 
-A drawn string arrives as a pointer and a length, is not NUL-terminated,
-and can hold interior NUL bytes, because the drawn alphabet can include
-U+0000. Read by length. Measured against 0.45.0: an alphabet pinned to
-U+0000 produces a three-byte draw that reads as `""` when taken up to the
-first NUL and as three NUL bytes when taken by its reported length. Every
-string observed reports `valid_encoding?` after `force_encoding(UTF-8)`.
+A drawn string arrives as a pointer and a length, and can hold interior
+NUL bytes, because the drawn alphabet can include U+0000. Read by length.
+Before libhegel 0.46 the string had no NUL terminator. Since 0.46 every
+string the engine hands back is a `hegel_string_t` with a trailing NUL that
+its length excludes, but an interior NUL still ends the string early for a
+reader that stops at the first NUL. Measured against 0.45.0: an alphabet
+pinned to U+0000 produces a three-byte draw that reads as `""` when taken
+up to the first NUL and as three NUL bytes when taken by its reported
+length. Every string observed reports `valid_encoding?` after
+`force_encoding(UTF-8)`.
 
 Prism recovers a draw's assignment target through a method chain, an
 instance-variable assignment, and an assignment spanning several lines.

data/lib/hegel/errors.rb

@@ -31,6 +31,30 @@ module Hegel
   # Descends from Exception for the same reason as StopTest above.
   class AssumeFailed < Exception; end
 
+  # Raised for HEGEL_E_RETRY from hegel_recursion_leaf: the attempt at a
+  # recursive value outgrew its leaf budget and must unwind to the
+  # Generators::RecursiveGenerator that owns +recursion+, which retries it.
+  # Internal to this library. See docs/adr/0032.
+  class LeafBudgetExceeded < Exception # :nodoc:
+    attr_reader :recursion
+
+    def initialize(recursion)
+      super("hegel: a recursive draw outgrew its leaf budget; the attempt is retried")
+      @recursion = recursion
+    end
+  end
+
+  # Raised by Hegel::TestCase#repeat when the engine ends its loop: the
+  # repetition ran as long as the engine wanted it to and nothing failed,
+  # so Hegel::Runner.classify reports the case VALID. hegel-rust raises its
+  # own LoopDone at the same point, and its run lifecycle maps it to VALID
+  # the same way.
+  #
+  # Descends from Exception for the same reason as StopTest above: a
+  # `rescue => e` written after the loop must not turn the end of the loop
+  # into ordinary control flow. See docs/adr/0034.
+  class LoopDone < Exception; end
+
   # standard:enable Lint/InheritException
 
   # Say the process is ending, not that a property failed. Every

data/lib/hegel/generator.rb

@@ -18,6 +18,41 @@ module Hegel
       raise NotImplementedError, "#{self.class} must implement #do_draw"
     end
 
+    # The span label of one attempt at a filtered draw, shared by every
+    # generator that runs attempts.
+    FILTER_ATTEMPT_LABEL = LibHegel.label_from_name("hegel-ruby.Hegel::Generator.filter_attempt")
+
+    # Draws one value that +predicate+ accepts, the draw behind #filter, which
+    # calls this on its source generator. The default makes up to
+    # Filtered::MAX_ATTEMPTS attempts, each a #do_draw in a span of its own
+    # that closes as discarded when the predicate rejects the value, then
+    # discards the test case (Hegel::AssumeFailed).
+    #
+    # A generator whose draws have effects a rejected value must not keep
+    # overrides this and runs the attempts itself, as
+    # Hegel::Stateful::Pool::ValuesConsumed does. One that only forwards
+    # #do_draw to another generator forwards this too, so that a filter around
+    # it still reaches the other generator's attempts.
+    def do_draw_filtered(tc, predicate)
+      Filtered::MAX_ATTEMPTS.times do
+        # Each variable is set again before it is read, or stays nil, which
+        # acts like false (!nil == !false).
+        # The initializer also shows intent: discard the span when an
+        # exception skips the reassignment.
+        accepted = false # mutineer:disable-line statement_removal
+        value = nil # mutineer:disable-line statement_removal, boolean_literal
+        tc.start_span(FILTER_ATTEMPT_LABEL)
+        begin
+          value = do_draw(tc)
+          accepted = predicate.call(value)
+        ensure
+          tc.stop_span(discard: !accepted)
+        end
+        return value if accepted
+      end
+      raise Hegel::AssumeFailed
+    end
+
     # The span label naming this generator's draws to the engine, which
     # treats two spans with one label as draws of one generator when it
     # shrinks. A generator built from others overrides this and combines
@@ -30,7 +65,7 @@ module Hegel
     # The class name, prefixed with this binding's name as hegel.h asks, to
     # keep clear of the engine's own hegel.<kind> labels.
     def self.label
-      LibHegel.label_from_name("hegel-ruby.#{name}")
+      @label ||= LibHegel.label_from_name("hegel-ruby.#{name}")
     end
 
     # Combines this generator's class label with the labels of +parts+, the
@@ -92,13 +127,17 @@ module Hegel
       end
     end
 
-    # Generator#filter's result. Retries the source generator, each
-    # attempt in its own span, up to MAX_ATTEMPTS times before discarding
-    # the test case (Hegel::AssumeFailed) -- the same budget hegel-rust's
-    # Filtered spends before calling assume(false)
-    # (src/generators/generators.rs), ported here rather than reinvented so
-    # a predicate that (almost) never holds fails the same way in both
-    # bindings.
+    # Generator#filter's result. Hands its predicate to the source
+    # generator's #do_draw_filtered, which makes up to MAX_ATTEMPTS attempts
+    # before discarding the test case (Hegel::AssumeFailed) -- the same
+    # budget hegel-rust's Filtered spends before calling assume(false)
+    # (frontends/rust/src/generators/generators.rs), ported here rather than
+    # reinvented so a predicate that (almost) never holds fails the same way
+    # in both bindings.
+    #
+    # A filter over a filter combines the two predicates into one draw, so
+    # the pair spends MAX_ATTEMPTS attempts between them, not that many per
+    # level.
     #
     # A predicate that never holds does not loop forever: libhegel's own
     # health check aborts a run that discards too many test cases in a
@@ -116,23 +155,11 @@ module Hegel
       attr_reader :label
 
       def do_draw(tc)
-        MAX_ATTEMPTS.times do
-          # Each variable is set again before it is read, or stays nil, which
-          # acts like false (!nil == !false).
-          # The initializer also shows intent: discard the span when an
-          # exception skips the reassignment.
-          accepted = false # mutineer:disable-line statement_removal
-          value = nil # mutineer:disable-line statement_removal, boolean_literal
-          tc.start_span(label)
-          begin
-            value = @source.do_draw(tc)
-            accepted = @block.call(value)
-          ensure
-            tc.stop_span(discard: !accepted)
-          end
-          return value if accepted
-        end
-        raise Hegel::AssumeFailed
+        @source.do_draw_filtered(tc, @block)
+      end
+
+      def do_draw_filtered(tc, predicate)
+        @source.do_draw_filtered(tc, ->(value) { @block.call(value) && predicate.call(value) })
       end
     end
   end