hecks 1.4.0 → 1.5.1

data/lib/hecks/fuzzing/concurrent_dispatch.rb

@@ -18,7 +18,9 @@ module Hecks
     # domain, so the practice's own adversarial generator gets to pick the
     # conflict instead of a human picking it once and never again.
     #
-    # The mechanism, generalized from that spec rather than REDERIVED: a
+    # ## The mechanism
+    #
+    # Generalized from that spec rather than rederived: a
     # command step partway through a generated sequence is chosen as the
     # race step; every step before it is setup (replayed once, sequentially,
     # to bring a fresh disposable schema to the state the race step expects
@@ -26,7 +28,9 @@ module Hecks
     # each of two real, separate, forked OS processes racing against that
     # same schema, no artificial gating, whichever the scheduler favors.
     #
-    # The oracle is the same pair, dispatched sequentially, not a
+    # ## The oracle
+    #
+    # The same pair, dispatched sequentially, not a
     # hardcoded expectation — unlike the hand-authored spec (which can
     # assert `%w[refused succeeded]` because it knows its own fixture's
     # business rule), this module has no idea whether an arbitrary
@@ -42,7 +46,9 @@ module Hecks
     # (which real racer wins a genuine race is never controlled), the set
     # of outcomes does.
     #
-    # What a broken lock looks like here: the concurrent pair settling as
+    # ## What a broken lock looks like here
+    #
+    # The concurrent pair settling as
     # {"succeeded", "succeeded"} where the sequential oracle says
     # {"succeeded", "refused"} — two processes each hydrated the
     # pre-write state, neither saw the other's write, and the second
@@ -51,7 +57,9 @@ module Hecks
     # PostgresEra and `postgres_concurrent_dispatch_spec.rb` still
     # documents, unfixed, for plain Postgres.
     #
-    # Not a replacement for the hand-authored spec — that spec proves the
+    # ## Not a replacement for the hand-authored spec
+    #
+    # That spec proves the
     # mechanism once, precisely, with controlled gating so the assertion
     # is deterministic; this module proves the same mechanism holds for
     # whatever a real domain's own generated sequences throw at it, with
@@ -75,6 +83,15 @@ module Hecks
       # duration — the caller creates neither ahead of time (both are
       # wiped fresh by the boots below) and drops both afterward, the
       # same lifecycle `persistence_parity_schema` already has.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param steps [Array<Hash>] a generated sequence's own steps, any-keyed (normalized
+      #   to String keys internally)
+      # @param database [String] the shared, never-dropped scratch database to connect to
+      # @param race_schema [String] a disposable schema name for the two racing processes
+      # @param reference_schema [String] a disposable schema name for the sequential oracle
+      # @return [Array<Hash>] `[]` if nothing raceable was found or no divergence occurred;
+      #   otherwise one or more `field:`-keyed divergence findings
       def check(domain_path, steps, database:, race_schema:, reference_schema:)
         normalized = steps.map { |step| step.transform_keys(&:to_s) }
         lockable, probe_errors = lockable_verbs(domain_path, normalized, database: database, schema: reference_schema)
@@ -82,9 +99,9 @@ module Hecks
         unless race_index
           # `[]` here means "nothing to race", and must only ever mean that.
           # A sequence of pure queries/dry-runs is a legitimate clean
-          # result; a probe that raised for every verb is not — that one
-          # used to produce the identical `[]` and be logged as a clean
-          # concurrency Check (see `lockable_verbs`).
+          # result; a probe that raised for every verb is not — see
+          # `lockable_verbs`, whose own `probe_errors` half exists so this
+          # branch can tell the two apart rather than answering `[]` for both.
           return [] if probe_errors.empty?
 
           return [{ field:  "concurrency_unraceable",
@@ -103,7 +120,7 @@ module Hecks
         [{ field: "process", detail: "#{e.class}: #{e.message}" }]
       end
 
-      # The command step CLOSEST to the middle of the sequence — not the
+      # The command step closest to the middle of the sequence — not the
       # first (racing a bare identity-creation with no setup at all is a
       # legitimate, useful case, so index 0 is not excluded) and not
       # chosen for any domain-specific reason: a mid-sequence step has, on
@@ -120,6 +137,12 @@ module Hecks
       # Racing anything outside that set is not a legitimate race at
       # all — nil when nothing eligible is left, same as the "no command
       # step" case, never a finding of its own.
+      #
+      # @param steps [Array<Hash>] a normalized (String-keyed) generated sequence
+      # @param lockable_verbs [Array<String>, nil] the verbs eligible to race, as
+      #   `lockable_verbs` returns; nil to consider every command step eligible
+      # @return [Integer, nil] the index of the chosen race step, or nil if no eligible
+      #   command step exists
       def pick_race_index(steps, lockable_verbs = nil)
         command_indices = steps.each_index.select { |i| COMMAND_STEP.call(steps[i]) }
         command_indices = command_indices.select { |i| lockable_verbs.include?(steps[i]["verb"]) } if lockable_verbs
@@ -170,6 +193,14 @@ module Hecks
       # `lockable` came back empty, `check` returned `[]`, and the sweep
       # logged a clean concurrency Check for a race that never happened.
       # `check` reports that case now instead of holding it.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param steps [Array<Hash>] a normalized (String-keyed) generated sequence
+      # @param database [String] the shared, never-dropped scratch database to connect to
+      # @param schema [String] a disposable schema name for the structural-inspection boot
+      # @return [Array(Array<String>, Array<String>)] `[lockable, probe_errors]` — the
+      #   command verbs bound to a `:cross_process_lock`-declaring adapter, and one
+      #   `"verb: Class: message"` entry per verb whose resolution raised
       def lockable_verbs(domain_path, steps, database:, schema:)
         verbs = steps.select { |step| COMMAND_STEP.call(step) }.map { |step| step["verb"] }.uniq
         lockable = []
@@ -183,6 +214,15 @@ module Hecks
         [lockable, probe_errors]
       end
 
+      # Answers whether `verb`'s own resolved repository declares a cross-process lock.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted,
+      #   structural-inspection-only runtime to resolve `verb` against
+      # @param verb [String] the command verb to check
+      # @param probe_errors [Array<String>] mutated in place: appended with
+      #   `"verb: Class: message"` if resolving `verb` raises
+      # @return [Boolean] whether `verb`'s aggregate resolves and declares
+      #   `:cross_process_lock`; false (with an appended probe error) if resolution raises
       def verb_cross_process_lockable?(runtime, verb, probe_errors = [])
         domain, aggregate_name, = Naming.split_verb(verb)
         return false unless domain && aggregate_name
@@ -200,6 +240,17 @@ module Hecks
         false
       end
 
+      # Compares the sequential oracle's outcomes against the two racing
+      # processes' own outcomes, and reports any crash or disagreement.
+      #
+      # @param race_step [Hash] the race step, String-keyed
+      # @param reference [Array<String>] the sequential oracle's two outcomes,
+      #   `"succeeded"`, `"refused"`, or `"crashed:..."`
+      # @param concurrent [Array<String>] the two racing processes' own outcomes,
+      #   the same shape as `reference`
+      # @return [Array<Hash>] `[]` if the two multisets agree and neither side crashed;
+      #   otherwise one or more `field:`-keyed divergence findings (`"concurrency_crash"`
+      #   or `"concurrency_race"`)
       def divergences_for(race_step, reference, concurrent)
         crashes = (reference + concurrent).select { |outcome| outcome.start_with?("crashed:") }.uniq
         return crashes.map { |c| { field: "concurrency_crash", verb: race_step["verb"], detail: c } } if crashes.any?
@@ -216,6 +267,14 @@ module Hecks
       # twice in immediate succession. Nothing else ever touches this
       # schema while this runs, so whatever the domain itself settles on
       # is correct by construction, not asserted.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param setup_steps [Array<Hash>] the normalized steps replayed once, sequentially,
+      #   before the race step
+      # @param race_step [Hash] the normalized step dispatched twice in immediate succession
+      # @param database [String] the shared, never-dropped scratch database to connect to
+      # @param schema [String] this oracle's own disposable schema name
+      # @return [Array<String>] the two outcomes `dispatch_one` recorded, in dispatch order
       def reference_outcomes(domain_path, setup_steps, race_step, database:, schema:)
         outcomes = []
         IsolatedBoot.call(domain_path, adapter: :postgres_era, database: database, schema: schema) do |copy|
@@ -256,6 +315,15 @@ module Hecks
       # method's own code. `bin/qa_concurrency_racer` is this method's own
       # worker, one real `ruby` process per racer — read that script's own
       # header for the rest of this reasoning.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param setup_steps [Array<Hash>] the normalized steps replayed once, sequentially,
+      #   before the two racers spawn
+      # @param race_step [Hash] the normalized step both racer processes dispatch
+      # @param database [String] the shared, never-dropped scratch database to connect to
+      # @param schema [String] this race's own disposable schema name, shared by both racers
+      # @return [Array<String>] the two racers' own outcomes, in `Process.wait` order;
+      #   `"crashed:no output from bin/qa_concurrency_racer"` for a racer that printed nothing
       def concurrent_outcomes(domain_path, setup_steps, race_step, database:, schema:)
         IsolatedBoot.call(domain_path, adapter: :postgres_era, database: database, schema: schema) do |copy|
           dispatch_all!(Hecks.boot(copy), setup_steps)
@@ -286,6 +354,11 @@ module Hecks
       # give), anything else escaping is "crashed:<class>: <message>", a
       # genuine finding this module's own caller surfaces rather than lets
       # kill a forked racer silently.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+      #   to dispatch against
+      # @param step [Hash] the normalized (String-keyed) step to dispatch
+      # @return [String] `"succeeded"`, `"refused"`, or `"crashed:<class>: <message>"`
       def dispatch_one(runtime, step)
         args = (step["args"] || {}).transform_keys(&:to_sym)
         runtime.dispatch_flat(step["verb"], args)
@@ -296,12 +369,21 @@ module Hecks
         "crashed:#{e.class}: #{e.message}"
       end
 
+      # Dispatches every step in order, raising the first time one crashes.
+      #
       # Setup tolerates an ordinary refusal (a generated sequence's own
       # earlier step can legitimately refuse — every other mode in this
       # practice already replays a prefix that way) but never a crash: an
       # unexpected exception during setup means the schema this race is
       # about to run against is in an unknown state, which is itself
       # worth surfacing, not silently racing anyway.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
+      #   to dispatch against
+      # @param steps [Array<Hash>] the normalized steps to dispatch, in order
+      # @return [void]
+      # @raise [RuntimeError] if any step's own `dispatch_one` outcome is a crash, naming
+      #   the step's verb and outcome
       def dispatch_all!(runtime, steps)
         steps.each do |step|
           outcome = dispatch_one(runtime, step)
@@ -309,6 +391,9 @@ module Hecks
         end
       end
 
+      # Boots a `PostgresEra`-rebound copy of the domain against an
+      # existing schema, without wiping it first.
+      #
       # The same copy-and-rebind `IsolatedBoot.call(..., adapter:
       # :postgres_era, ...)` does, minus the schema wipe — deliberately
       # not reusing `IsolatedBoot.rebind_to_postgres_era!` itself, which
@@ -322,6 +407,14 @@ module Hecks
       # this writes is duplicated from it, not re-derived, because the
       # shape a `PostgresEra`-bound copy's `.world` needs is exactly that
       # method's own, one step short.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param database [String] the PostgresEra database name to bind the copy to
+      # @param schema [String] the existing PostgresEra schema name to bind the copy to,
+      #   left exactly as found
+      # @yield [copy] runs against the rebound copy
+      # @yieldparam copy [String] filesystem path to the rebound domain copy
+      # @return [Object] the block's own result
       def boot_preserving_schema(domain_path, database:, schema:)
         Dir.mktmpdir("hecks-concurrency") do |tmp|
           copy = File.join(tmp, File.basename(domain_path))
@@ -333,6 +426,14 @@ module Hecks
         end
       end
 
+      # Writes a `.world` file binding every hecksagon-named member in
+      # `copy` to `database`/`schema`, replacing any other `.world` file
+      # the copy already carries.
+      #
+      # @param copy [String] filesystem path to the domain copy to rewrite
+      # @param database [String] the PostgresEra database name to write into the `.world` file
+      # @param schema [String] the PostgresEra schema name to write into the `.world` file
+      # @return [void]
       def write_postgres_era_world!(copy, database:, schema:)
         Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
           names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten.uniq

data/lib/hecks/fuzzing/coverage_campaign.rb

@@ -3,23 +3,27 @@ module Hecks
     # What one sweep has already reached, and where the next seed starts.
     #
     # `SequenceGenerator` steers within one sequence (an unexercised verb is
-    # weighted up — picker.rb's `steer`), but every seed of a sweep used to
-    # start from nothing and forget everything the seeds before it reached.
-    # Roughly half of the QA ledger's bugs are refusal-kind splits (BUG#2–4,
+    # weighted up — picker.rb's `steer`), but without this, every seed of a
+    # sweep would start from nothing and forget everything the seeds before
+    # it reached. Roughly half of the QA ledger's bugs are refusal-kind splits (BUG#2–4,
     # 7, 8, 14–16, 19–21, 23, 27, 28, 36–38, 41, 54, 56): a particular verb,
     # in a particular state, with a particular malformed argument, refused
     # one way on Ruby and another on Rust. BUG#11 was found by hand because
     # a 25-step random walk never reached `Annotate` at all. Uniform seeds
     # reach those corners by luck; this makes the sweep remember.
     #
-    # The coverage unit is a tuple, not a verb — `verb | step kind |
-    # lifecycle state before | adversarial mutation | outcome` (see
-    # `SequenceGenerator#coverage_tuple`). "Renew refused LifecycleRefused
-    # from free" and "Renew ok from held" are different places a runtime can
-    # be wrong, where a verb-level count calls them the same.
+    # ## The coverage unit
     #
-    # Two levers, both expressed as plain generator arguments so a seed
-    # stays reproducible from one call:
+    # A tuple, not a verb — `verb | step kind | lifecycle state before |
+    # adversarial mutation | outcome` (see `SequenceGenerator#coverage_tuple`).
+    # "Renew refused LifecycleRefused from free" and "Renew ok from held" are
+    # different places a runtime can be wrong, where a verb-level count
+    # calls them the same.
+    #
+    # ## Two levers
+    #
+    # Both expressed as plain generator arguments so a seed stays
+    # reproducible from one call:
     #
     #   1. Splicing (`prefix:`). A sequence that reached a new tuple joins
     #      the corpus, cut at its last new tuple. A later seed may start by
@@ -32,18 +36,37 @@ module Hecks
     #      including declared verbs it has never hit at all — are weighted
     #      up for the next seed.
     #
+    # ## Reproducibility
+    #
     # Nothing here is random at the campaign's own level beyond
     # `Random.new(seed)` per plan, and a plan is printed with every finding
     # (`bin/qa_sweep`'s `reproduce:` line), so no finding depends on
     # re-running the whole campaign to get back to it.
     class CoverageCampaign
+      # One seed's generation instructions, printable and reproducible.
       Plan = Struct.new(:prefix, :favor, keyword_init: true) do
+        # Renders this plan as the keyword arguments a generator call accepts.
+        #
+        # @return [Hash{Symbol => Object}] `{ prefix:, favor: }`, the keyword arguments
+        #   `SequenceGenerator.generate` and `.trace` accept for this plan
         def generator_options = { prefix: prefix, favor: favor }
+
+        # Answers whether this plan starts from a spliced corpus prefix.
+        #
+        # @return [Boolean] whether this plan starts from a spliced corpus prefix
         def spliced? = !prefix.nil?
       end
 
       attr_reader :corpus
 
+      # @param splice_probability [Float, Integer] chance, per seed with a non-empty
+      #   corpus, of splicing a corpus entry's prefix instead of generating fresh
+      # @param favor_count [Integer, Float] how many rare verbs to favor per plan; 0
+      #   or non-positive disables favoring entirely
+      # @param corpus_limit [Integer] maximum corpus entries kept; the oldest is
+      #   dropped once this is exceeded
+      # @param max_prefix_depth [Integer] maximum nested-prefix depth a new corpus
+      #   entry may reach before splicing stops extending it further
       def initialize(splice_probability:, favor_count:, corpus_limit: 64, max_prefix_depth: 6)
         @splice_probability = splice_probability.to_f
         @favor_count        = favor_count.to_i
@@ -58,6 +81,13 @@ module Hecks
         @seeds_with_new     = 0
       end
 
+      # Builds this seed's generation plan — a possible splice, plus which
+      # verbs to favor.
+      #
+      # @param seed [Integer] the seed this plan is for; drives the splice-or-not
+      #   coin flip and, when splicing, which corpus entry and prefix length are drawn
+      # @return [Fuzzing::CoverageCampaign::Plan] the plan `SequenceGenerator.generate`
+      #   or `.trace` should be run with for this seed
       def plan(seed)
         random = Random.new(seed)
         prefix = nil
@@ -68,9 +98,15 @@ module Hecks
         Plan.new(prefix: prefix, favor: rare_verbs)
       end
 
-      # `trace` is `SequenceGenerator.trace`'s answer: `coverage` is
-      # `[[attempt_index, tuple], ...]`, `verbs` every verb the booted
-      # catalog offered.
+      # Folds one seed's generation results into the campaign's running
+      # coverage, and admits its corpus entry if it reached anything new.
+      #
+      # @param seed [Integer] the seed this trace was generated from
+      # @param plan [Fuzzing::CoverageCampaign::Plan] the plan that seed was generated with
+      # @param trace [Fuzzing::SequenceGenerator::Trace] `SequenceGenerator.trace`'s answer:
+      #   `coverage` is `[[attempt_index, tuple], ...]`, `verbs` every verb the booted
+      #   catalog offered
+      # @return [void]
       def record(seed, plan, trace)
         @seeds   += 1
         @spliced += 1 if plan.spliced?
@@ -86,8 +122,15 @@ module Hecks
         admit(seed, plan, new_at.max + 1)
       end
 
+      # Counts the distinct coverage tuples this campaign has reached so far.
+      #
+      # @return [Integer] the number of distinct coverage tuples seen
       def tuples_seen = @seen.size
 
+      # Renders the campaign's running totals as one human-readable line.
+      #
+      # @return [String] a one-line summary of tuples seen, seeds run, seeds that
+      #   reached something new, and how many were spliced from the corpus
       def summary
         "coverage: #{@seen.size} distinct (verb, kind, state, mutation, outcome) tuple(s) over #{@seeds} seed(s); " \
           "#{@seeds_with_new} seed(s) reached something new; #{@spliced} spliced from a corpus of #{@corpus.size}"

data/lib/hecks/fuzzing/differential.rb

@@ -45,6 +45,16 @@ module Hecks
       # tolerated verb Rust nonetheless answered with a query row: the
       # manifest says "not generated" but the binary disagrees, so the
       # tolerance itself is wrong and must not silently hold.
+      # @param gaps [Hecks::Fuzzing::RustGapManifest] the compiled binary's manifest
+      # @param ruby_refusals [Array<Hash>] Ruby's own refusal rows for this history
+      # @param rust_refusals [Array<Hash>] the Rust binary's own refusal rows
+      # @param ruby_queries [Array<Hash>] Ruby's own query rows for this history
+      # @param rust_queries [Array<Hash>] the Rust binary's own query rows
+      # @return [Hash] `ruby_refusals:`/`rust_refusals:`/`ruby_queries:`/
+      #   `rust_queries:` (each with tolerated verbs removed), `skipped:` (a
+      #   `Set<String>` of every tolerated verb this history actually reached),
+      #   and `stale:` (an `Array<Hash>` divergence per tolerated verb the Rust
+      #   binary nonetheless answered)
       def manifest_partition(gaps, ruby_refusals:, rust_refusals:, ruby_queries:, rust_queries:)
         verb_of  = ->(row) { row.key?("verb") ? row["verb"] : row["query"] }
         declared = ->(row) { gaps.not_generated?(verb_of.call(row)) }
@@ -60,11 +70,22 @@ module Hecks
           skipped: reached.to_set(&verb_of), stale: stale }
       end
 
+      # Runs the standard property battery and reports every one that failed.
+      #
+      # @param history [Hash] a replayed history as returned by `Replay.call`
+      # @return [Array<Hash>] one `{field:, detail:}` entry per failed property
       def property_divergences(history)
         Properties.check(history).reject { |_, result| result == true }
                   .map { |name, message| { field: name.to_s, detail: message } }
       end
 
+      # Flattens `history[:self_consistency]`'s own per-check divergence lists.
+      #
+      # @param history [Hash] a replayed history as returned by `Replay.call`,
+      #   optionally carrying `:self_consistency` (`Replay.call`'s own
+      #   `self_consistency: true`)
+      # @return [Array<Hash>] every self-consistency divergence recorded; empty if
+      #   `history` carries no `:self_consistency`
       def self_consistency_divergences(history)
         return [] unless history[:self_consistency]
 
@@ -75,6 +96,19 @@ module Hecks
       # rubocop:disable-next Metrics/CyclomaticComplexity
       # rubocop:disable-next Metrics/PerceivedComplexity
       # rubocop:disable-next Metrics/MethodLength
+      # @param differ [Object] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined)
+      # @param domain_path [String] path to the domain directory to replay
+      # @param steps [Array<Hash>] the step sequence to replay on both engines
+      # @param binary [String] path to the compiled Rust conformance binary to run
+      # @param modes [Array<Symbol>] which comparisons to run — any of
+      #   `:differential` (always run), `:self_consistency`,
+      #   `:properties_in_differential`, `:adapter_parity_sqlite`
+      # @param adapter_parity_sqlite [Proc, nil] callable answering the
+      #   `:adapter_parity_sqlite` mode's own comparison, or `nil` to skip it
+      #   even when named in `modes`
+      # @return [Hash{Symbol => Array<Hash>}] one divergence list per active mode,
+      #   keyed by the mode name; `:differential` is always present
       def diff(differ, domain_path, steps, binary, modes:, adapter_parity_sqlite: nil)
         self_consistency = modes.include?(:self_consistency)
         ruby_result    = Replay.call(domain_path, steps, self_consistency: self_consistency)