hecks 1.4.0 → 1.5.0

data/lib/hecks/fuzzing/form_census.rb

@@ -80,24 +80,68 @@ module Hecks
 
       module_function
 
+      # Reads an aggregate IR hash's own declared entities.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] the aggregate's own declared entities ("pieces"); `[]`
+      #   if it declares none
       def entities(aggregate)   = aggregate["entities"] || []
+
+      # Reads an aggregate IR hash's own declared commands.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] the aggregate's own declared commands; `[]` if it
+      #   declares none
       def commands(aggregate)   = aggregate["commands"] || []
 
       # One aggregate's commands, its pieces' included — a form carried by
       # an entity command is carried by the aggregate that owns it, the
       # same way `composite_piece`/`piece_lifecycle` already read pieces.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] `aggregate`'s own commands, plus every entity's own
       def every_command(aggregate) = commands(aggregate) + entities(aggregate).flat_map { |piece| commands(piece) }
 
+      # Answers whether a command IR hash declares a `corrects` mutation.
+      #
+      # @param verb [Hash] a string-keyed command IR hash
+      # @return [Boolean] true if `verb` declares a `corrects` mutation
       def corrects?(verb) = (verb["mutations"] || []).any? { |change| change["op"].to_s == "corrects" }
+
+      # Reads an aggregate IR hash's own declared attributes.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] the aggregate's own declared attributes; `[]` if it
+      #   declares none
       def attributes(aggregate) = aggregate["attributes"] || []
+
+      # Reads an aggregate IR hash's own declared queries.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] the aggregate's own declared queries; `[]` if it
+      #   declares none
       def queries(aggregate)    = aggregate["queries"] || []
+
+      # Answers whether an attribute IR hash's own declared type is a reference.
+      #
+      # @param attribute [Hash] a string-keyed attribute IR hash
+      # @return [Boolean] true if `attribute`'s own declared type is a reference
       def reference?(attribute) = attribute["type"].to_s.start_with?("Reference<")
 
+      # Answers whether any of an aggregate's own commands crosses a two-hop given.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Boolean] true if any command's own given crosses at least two
+      #   references (`TWO_HOP_GIVEN_PATH_LENGTH`)
       def two_hop_given?(aggregate)
         commands(aggregate).any? { |verb| (verb["givens"] || []).any? { |given| deep_lookup?(given["ast"]) } }
       end
 
       # A `where` whose field crosses two `/` — `member/sponsor/standing`.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Boolean] true if any query's own where clause crosses at least
+      #   two `/` hops
       def multi_hop_where?(aggregate)
         queries(aggregate).any? { |query| (query["wheres"] || []).any? { |where| where["field"].to_s.count("/") >= 2 } }
       end
@@ -106,6 +150,10 @@ module Hecks
       # own reference-typed attributes while carrying a different, non-
       # reference type — `attribute :member, Handle` against
       # `reference_to Member`.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Boolean] true if any command redeclares one of the aggregate's
+      #   own reference-typed attribute names under a non-reference type
       def revalued_reference?(aggregate)
         references = attributes(aggregate).select { |held| reference?(held) }.to_set { |held| held["name"].to_s }
         commands(aggregate).any? do |verb|
@@ -115,6 +163,11 @@ module Hecks
 
       # Walks a given's own exported AST for any `lookup` whose path is
       # long enough to have crossed two references.
+      #
+      # @param node [Hash, Array, Object] an AST node (or subtree) from an
+      #   exported given's `"ast"`
+      # @return [Boolean] true if any `lookup` node's own path is at least
+      #   `TWO_HOP_GIVEN_PATH_LENGTH` long
       def deep_lookup?(node)
         case node
         when Hash
@@ -129,21 +182,39 @@ module Hecks
       end
 
       # Every form, answered for one aggregate — the table above, applied.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Hash{String => Boolean}] every `FORMS` name mapped to whether
+      #   `aggregate` exhibits it
       def properties(aggregate)
         FORMS.transform_values { |form| form.call(aggregate) }
       end
 
       # Every unordered pair of forms, each rendered "left + right" in
       # alphabetical order — the key both gates' excuse tables use.
+      #
+      # @return [Array<String>] every unordered pair of `FORMS` names, as
+      #   `"left + right"`
       def pairs
         FORMS.keys.combination(2).map { |pair| pair_key(*pair) }
       end
 
+      # Renders two form names as one sorted pair key.
+      #
+      # @param left [String] a form name
+      # @param right [String] a form name
+      # @return [String] `left`/`right`, alphabetically ordered, joined as
+      #   `"left + right"`
       def pair_key(left, right) = [left, right].sort.join(" + ")
 
       # `held` is `[[aggregate_name, properties], ...]`. Answers which
       # pairs are met on one aggregate, and by which — a Hash from pair
       # key to the names carrying it, so a caller can say who.
+      #
+      # @param held [Array<Array(String, Hash)>] `[aggregate_name, properties]`
+      #   pairs, `properties` as returned by `#properties`
+      # @return [Hash{String => Array<String>}] every met pair key mapped to the
+      #   aggregate names that carry it
       def covered_pairs(held)
         held.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(name, shows), covered|
           shows.select { |_, present| present }.keys.combination(2).each do |left, right|
@@ -155,6 +226,12 @@ module Hecks
       # `[[\"Chapter::Aggregate\", properties], ...]` for every aggregate
       # a string-keyed chapter IR declares — the same walk the golden
       # spec makes over `spec/golden/ir/*.json`.
+      #
+      # @param chapter_ir [Hash] a string-keyed chapter IR hash, with `"name"` and
+      #   `"aggregates"`
+      # @return [Array<Array(String, Hash)>] `["Chapter::Aggregate", properties]`
+      #   pairs, one per declared aggregate, `properties` as returned by
+      #   `#properties`
       def aggregates_in(chapter_ir)
         (chapter_ir["aggregates"] || []).map do |aggregate|
           ["#{chapter_ir['name']}::#{aggregate['name']}", properties(aggregate)]
@@ -164,6 +241,10 @@ module Hecks
       # Where a domain path keeps its bluebooks — see
       # `Hecks::Corpus.bluebook_files`, the one definition every corpus
       # walk shares. `nil` when neither shape holds a bluebook.
+      #
+      # @param domain_path [String] path to a domain directory
+      # @return [Array<String>, nil] the domain's own `.bluebook` file paths, or
+      #   `nil` if it holds none
       def bluebook_files(domain_path)
         Hecks::Corpus.bluebook_files(domain_path)
       end
@@ -176,6 +257,11 @@ module Hecks
       # domain's own). Only the domain's own chapter is measured — the
       # first bluebook loaded, the same "target chapter is always first"
       # fact `bin/project_rust` relies on.
+      # @param domain_path [String] path to a domain directory
+      # @return [Array<Array(String, Hash)>] `["Chapter::Aggregate", properties]`
+      #   pairs, one per aggregate declared on `domain_path`'s own first-loaded
+      #   chapter (see `Hecks::Projector::Exporter.call`)
+      # @raise [ArgumentError] if `domain_path` has no bluebook files to measure
       def census(domain_path)
         root = File.expand_path("../../..", __dir__)
         files = bluebook_files(domain_path)

data/lib/hecks/fuzzing/generated_domain_check.rb

@@ -27,6 +27,27 @@ module Hecks
 
       module_function
 
+      # Checks one generated domain over up to `seeds` generated sequences, stopping
+      # at the first divergence found.
+      #
+      # @param domain_path [String] path to the generated domain directory
+      # @param seeds [Integer] maximum number of seeds to try before declaring clean
+      # @param steps [Integer] steps to generate per seed
+      # @param adversarial [Float] fraction of command steps to mutate adversarially
+      # @param binary [String, nil] path to a compiled Rust conformance binary to
+      #   diff against, or `nil` for a Ruby-only check
+      # @param differ [Object, nil] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined; constructed ad hoc
+      #   by callers such as bin/qa_generated_domains), or `nil`
+      # @param match [Hash, nil] `{"mode" =>, "signature" =>}` from a parent
+      #   domain's own finding — only a divergence matching it counts, for
+      #   domain-level shrinking; `nil` accepts the first divergence found
+      # @param shrink_budget [Integer] step-level shrink attempts to spend on a
+      #   found finding; `0` skips shrinking
+      # @return [Hash] `{"status" => "invalid", "error" =>}` if the domain does not
+      #   boot; `{"status" => "clean", "seeds_run" =>}` if no seed diverged;
+      #   otherwise a finding merged with `{"status" => "found", "seeds_run" =>}`
+      #   (see `#finding`), plus `"shrunk_steps"` when `shrink_budget` is positive
       def run(domain_path, seeds:, steps:, adversarial:, binary: nil, differ: nil, match: nil, shrink_budget: 0)
         error = boot_error(domain_path)
         return { "status" => "invalid", "error" => error } if error
@@ -41,6 +62,11 @@ module Hecks
         { "status" => "clean", "seeds_run" => seeds }
       end
 
+      # Boots `domain_path` in an isolated copy, to find out whether it boots at all.
+      #
+      # @param domain_path [String] path to the domain directory to boot
+      # @return [String, nil] `nil` if the boot succeeds; otherwise the raising
+      #   exception's class and first message line
       def boot_error(domain_path)
         IsolatedBoot.call(domain_path) { |copy| Hecks.boot(copy) }
         nil
@@ -48,6 +74,20 @@ module Hecks
         "#{e.class}: #{e.message.lines.first&.strip}"
       end
 
+      # Generates one sequence for `seed` and checks it for a divergence.
+      #
+      # @param domain_path [String] path to the domain directory
+      # @param seed [Integer] RNG seed for `SequenceGenerator.generate`
+      # @param steps [Integer] steps to generate
+      # @param adversarial [Float] fraction of command steps to mutate adversarially
+      # @param binary [String, nil] path to a compiled Rust conformance binary, or
+      #   `nil` for a Ruby-only check
+      # @param differ [Object, nil] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined), or `nil`
+      # @param match [Hash, nil] `{"mode" =>, "signature" =>}` a divergence must
+      #   match to count, or `nil` to accept the first one found
+      # @return [Hash, nil] a finding (see `#finding`) if a matching divergence was
+      #   found, or if generation itself crashed; `nil` if the sequence was clean
       def check_seed(domain_path, seed, steps, adversarial, binary, differ, match)
         sequence = SequenceGenerator.generate(domain_path, seed: seed, steps: steps, adversarial: adversarial)
       rescue StandardError => e
@@ -60,6 +100,19 @@ module Hecks
         nil
       end
 
+      # Runs the comparison appropriate to whether a compiled binary is available:
+      # `Differential.diff` against Rust when `binary` is given, otherwise a
+      # Ruby-only replay checked for property and self-consistency divergences.
+      #
+      # @param domain_path [String] path to the domain directory
+      # @param sequence [Array<Hash>] the generated step sequence to replay
+      # @param binary [String, nil] path to a compiled Rust conformance binary, or
+      #   `nil` for a Ruby-only check
+      # @param differ [Object, nil] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined), or `nil`
+      # @return [Hash{Symbol => Array<Hash>}] one divergence list per mode checked;
+      #   `{ruby_only: [{field: "crash", detail:}]}` if the Ruby-only replay itself
+      #   raised
       def outcomes(domain_path, sequence, binary, differ)
         return Differential.diff(differ, domain_path, sequence, binary, modes: DIFFERENTIAL_MODES) if binary
 
@@ -70,6 +123,18 @@ module Hecks
         { ruby_only: [{ field: "crash", detail: "#{e.class}: #{e.message}" }] }
       end
 
+      # Builds a reported finding from a mode's divergences, unless `divergences`
+      # is empty or `match` names a different signature.
+      #
+      # @param seed [Integer] the seed that produced `sequence`
+      # @param mode [Symbol] the comparison mode the divergences came from
+      # @param divergences [Array<Hash>] divergence entries for `mode`
+      # @param sequence [Array<Hash>] the generated step sequence
+      # @param match [Hash, nil] `{"mode" =>, "signature" =>}` the finding must
+      #   match, or `nil` to accept any
+      # @return [Hash, nil] `{"seed" =>, "mode" =>, "signature" =>, "steps" =>,
+      #   "divergences" =>}` if `divergences` is non-empty and matches `match`;
+      #   `nil` otherwise
       def finding(seed, mode, divergences, sequence, match)
         return nil if divergences.empty?
 
@@ -82,6 +147,17 @@ module Hecks
 
       # The step-level half of shrinking, in this same process: the domain
       # is already as small as the parent could make it.
+      #
+      # @param domain_path [String] path to the (already domain-shrunk) domain
+      #   directory
+      # @param found [Hash] the finding to shrink, as returned by `#finding`
+      # @param binary [String, nil] path to a compiled Rust conformance binary, or
+      #   `nil` for a Ruby-only check
+      # @param differ [Object, nil] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined), or `nil`
+      # @param budget [Integer] step-level shrink attempts to spend
+      # @return [Array<Hash>] the smallest step list found that still reproduces
+      #   `found`'s divergence signature
       def shrink(domain_path, found, binary, differ, budget)
         original = Set.new(found["signature"])
         mode = found["mode"].to_sym

data/lib/hecks/fuzzing/invalid_value_generator.rb

@@ -32,6 +32,16 @@ module Hecks
         null
       ].freeze
 
+      # Builds one value of the wrong shape for `attribute`, chosen from the
+      # confusions that are actually meaningful for its declared type.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute the corrupted value is
+      #   handed to
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares
+      #   `attribute` (and any value objects it references)
+      # @param random [Random] the seeded RNG to draw the kind and value from
+      # @return [Object] a value of the wrong shape for `attribute` — an Integer,
+      #   Float, String, Array, Hash, or boolean, depending on the kind drawn
       def corrupt(attribute, aggregate, random:)
         kind = kinds_for(attribute, aggregate).sample(random: random)
         build(kind, attribute, aggregate, random: random)
@@ -41,6 +51,13 @@ module Hecks
       # `scalar_for_object` for a plain Integer would just be a second spelling of
       # `numeral_string`, and a kind that cannot be wrong for the attribute it is
       # handed teaches the corpus nothing.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to find applicable
+      #   confusions for
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares
+      #   `attribute` (and any value objects it references)
+      # @return [Array<Symbol>] the subset of `KINDS` that are a real confusion for
+      #   `attribute`'s declared type
       def kinds_for(attribute, aggregate)
         value_object = aggregate.value_object(attribute.type.to_s)
         return %i[scalar_for_object array_for_scalar null] if value_object
@@ -49,6 +66,16 @@ module Hecks
         %i[object_for_scalar array_for_scalar boolean_for_string null]
       end
 
+      # Builds the actual corrupted value for one already-chosen `kind`.
+      #
+      # @param kind [Symbol] one of `KINDS`
+      # @param attribute [Bluebook::Attribute] the attribute the value will be
+      #   handed to
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares
+      #   `attribute` (and any value objects it references)
+      # @param random [Random] the seeded RNG to draw the value from
+      # @return [Object, nil] the corrupted value for `kind`; `nil` if `kind` is not
+      #   one `KINDS` declares
       def build(kind, attribute, aggregate, random:)
         case kind
         when :object_for_scalar then { "cents" => random.rand(1..1000) }
@@ -64,6 +91,15 @@ module Hecks
       # legitimately accepts one (that is the standing-in rule every domain relies
       # on), so the interesting case is a value object with several fields, where a
       # scalar cannot stand for anything and the refusal has to say so.
+      # @param attribute [Bluebook::Attribute] the value-object-typed attribute to
+      #   build a bare scalar for
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares
+      #   `attribute`'s value object
+      # @param random [Random] accepted for a uniform call signature with `#build`;
+      #   this method draws nothing from it
+      # @return [String, Hash] `"a bare scalar"` when a scalar would legitimately be
+      #   accepted (a single-field value object); otherwise a Hash corrupting the
+      #   sole field's own type instead
       def scalar_for(attribute, aggregate, random:)
         value_object = aggregate.value_object(attribute.type.to_s)
         sole = value_object&.sole_attribute
@@ -77,6 +113,9 @@ module Hecks
       # An attribute the command never declared. `refuse_unknown_arguments` is a
       # real dispatch step (Vocabulary::AggregateDispatchOrder), and nothing
       # generated had ever exercised it.
+      # @param random [Random] the seeded RNG to draw the name and value from
+      # @return [Array(String, String)] a `[name, value]` pair naming an argument
+      #   no command declares
       def undeclared_argument(random:)
         name = %w[colour flavour rank note].sample(random: random)
         [name, %w[red loud third scribbled].sample(random: random)]

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -6,6 +6,8 @@ module Hecks
   module Fuzzing
     # A fresh, in-process adapter for every ephemeral boot.
     #
+    # ## Why rebind at all
+    #
     # Fuzzing/replay copies a domain to a tmpdir and boots from there
     # specifically to get zero-history state — `rm_rf`ing the copy's own
     # `data/` achieves that for a file-based adapter (Memory,
@@ -25,16 +27,18 @@ module Hecks
     # one ephemeral copy answers through changes. What the domain is
     # bound to for real deployment is never touched — only this tmp copy.
     #
-    # `adapter:` (PRD 02) — Memory is the default and the only mode every
-    # existing caller still gets with no change. `:sqlite` rebinds to the
-    # real SQLite adapter instead of the in-memory one, for exactly the
-    # same reason PRD 02 exists: 15 declared properties (properties.rb)
-    # and every fuzz/replay run has only ever been checked against
-    # Memory's own hand-written repository, never against a real,
-    # persisted, SQL-backed one — and `spec/adapters/query_agreement_spec
-    # .rb` already found 4 shipped query bugs from exactly that
-    # comparison, on a fixed corpus far smaller than what the fuzzer
-    # generates. `:sqlite` rewrites to `"SqlitePersistence"` — the name
+    # ## `adapter:` modes
+    #
+    # `adapter:` (PRD 02) picks which real persistence one ephemeral boot
+    # answers through. `:memory` is the default and the only mode every
+    # caller that passes no `adapter:` still gets. `:sqlite` rebinds to
+    # the real SQLite adapter instead of the in-memory one: 15 declared
+    # properties (properties.rb) and every fuzz/replay run only ever
+    # exercised Memory's own hand-written repository until this mode
+    # existed, and `spec/adapters/query_agreement_spec.rb` already found 4
+    # shipped query bugs from exactly that comparison, on a fixed corpus
+    # far smaller than what the fuzzer generates. `:sqlite` rewrites to
+    # `"SqlitePersistence"` — the name
     # `lib/hecks/adapters/driven/sqlite.adapter` actually registers under
     # (`Sqlite` is the class; `SqlitePersistence` is a thin subclass
     # that's the one real port binding names) — and needs no `.world`
@@ -44,18 +48,16 @@ module Hecks
     # `root:`, which `Hecks.boot(copy)` passes as this ephemeral copy's
     # own directory — a fresh, empty `data/` per run, exactly like
     # Memory's own zero-history guarantee, just backed by a real SQLite
-    # file instead of a Hash. Stale as of this paragraph's original
-    # writing — both `Postgres` (PRD 02, docs/prds/02-fuzzer-real-
-    # adapters.md) and `PostgresEra` (this mode's own header, below,
-    # `rebind_to_postgres_era!`) since gained real `adapter:` modes here.
-    # Each writes its own fresh `.world` per `.hecksagon` rather than
-    # relying on the zero-config default Sqlite/Memory get, and each
-    # needs a real, reachable Postgres server — but "no place to source a
-    # connection safely" turned out not to be true: `:postgres` sources
-    # one shared, permanent scratch database/schema this module itself
-    # owns (see `FUZZ_POSTGRES_DATABASE`'s own header); `:postgres_era`
-    # instead requires the caller to supply (and own the lifecycle of) its
-    # own throwaway `database:`/`schema:`, since its only caller
+    # file instead of a Hash. `:postgres` (PRD 02, docs/prds/02-fuzzer-
+    # real-adapters.md) and `:postgres_era` (`rebind_to_postgres_era!`'s
+    # own header, below) are the two real-Postgres modes. Each writes its
+    # own fresh `.world` per `.hecksagon` rather than relying on the
+    # zero-config default Sqlite/Memory get, and each needs a real,
+    # reachable Postgres server: `:postgres` sources one shared,
+    # permanent scratch database/schema this module itself owns (see
+    # `FUZZ_POSTGRES_DATABASE`'s own header); `:postgres_era` instead
+    # requires the caller to supply (and own the lifecycle of) its own
+    # throwaway `database:`/`schema:`, since its only caller
     # (`bin/qa_sweep --persistence-parity`) already has to manage a
     # disposable database of its own, never a shared one this module could
     # safely default to.
@@ -83,6 +85,20 @@ module Hecks
       # signature per adapter) keeps `SequenceGenerator`/`Replay`'s own
       # single passthrough (`adapter:`, now joined by these two) uniform
       # across all four modes.
+      #
+      # @param domain_path [String] path to the real domain directory to copy and isolate
+      # @param adapter [Symbol] which persistence the copy answers through: `:memory`
+      #   (default), `:sqlite`, `:postgres`, or `:postgres_era`
+      # @param database [String, nil] the database name, required only for
+      #   `adapter: :postgres_era`; ignored by every other adapter
+      # @param schema [String, nil] the schema name, required only for
+      #   `adapter: :postgres_era`; ignored by every other adapter
+      # @yield [String] the freshly rebound copy's root directory, ready to boot
+      # @yieldreturn [Object] anything; becomes this method's own return value
+      # @return [Object] whatever the given block returns
+      # @raise [ArgumentError] if `adapter` is not `:memory`, `:sqlite`, `:postgres`, or
+      #   `:postgres_era`, or if `adapter: :postgres_era` is given without both
+      #   `database:` and `schema:`
       def call(domain_path, adapter: :memory, database: nil, schema: nil)
         Dir.mktmpdir("hecks-fuzz") do |tmp|
           copy = File.join(tmp, File.basename(domain_path))
@@ -113,6 +129,10 @@ module Hecks
       # what an isolated boot wants: the copy has to stand alone, since
       # rebind! rewrites files in it and must not reach back through a
       # link into the real tree.
+      #
+      # @param source [String] the real domain directory to copy
+      # @param destination [String] the tmpdir path to copy it into; created if missing
+      # @return [void]
       def copy_dereferencing(source, destination)
         FileUtils.mkdir_p(destination)
         Dir.glob(File.join(source, "**", "*"), File::FNM_DOTMATCH).each do |path|
@@ -136,6 +156,11 @@ module Hecks
         end
       end
 
+      # Rewrites every `.hecksagon` in the copy to bind through Memory and drops its
+      # `.world` files, so the boot needs no settings at all.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
       def rebind_to_memory!(copy)
         rewrite_bindings!(copy, "Memory")
         strip_translations!(copy)
@@ -162,6 +187,9 @@ module Hecks
       # needed" property Memory has. `data/` itself is left for Sqlite to
       # recreate on first write, same as it always was for Memory/Heki —
       # nothing here creates it up front.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
       def rebind_to_sqlite!(copy)
         rewrite_bindings!(copy, "SqlitePersistence")
         strip_translations!(copy)
@@ -193,6 +221,11 @@ module Hecks
       FUZZ_POSTGRES_DATABASE = "hecks_fuzz".freeze
       FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz".freeze
 
+      # Rewrites every `.hecksagon` in the copy to bind through Postgres, against the
+      # shared `FUZZ_POSTGRES_DATABASE`/`FUZZ_POSTGRES_SCHEMA` scratch schema.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
       def rebind_to_postgres!(copy)
         require "pg"
         rewrite_bindings!(copy, "Postgres")
@@ -244,6 +277,8 @@ module Hecks
       # .available?` already uses) ; the schema inside it is dropped and
       # recreated on every call, which is what actually isolates one
       # ephemeral boot's data from the next.
+      #
+      # @return [void]
       def ensure_fuzz_schema!
         # `Adapters::Postgres#initialize` opens one real `PG::Connection`
         # per aggregate and never explicitly closes it — fine for a
@@ -322,6 +357,12 @@ module Hecks
       # keyword arguments (never a fallback constant) is what keeps that
       # ownership from silently drifting back onto this module the way
       # `:postgres`'s own `FUZZ_POSTGRES_DATABASE` already has.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @param database [String] the caller-owned throwaway database name
+      # @param schema [String] the caller-owned throwaway schema name
+      # @return [void]
+      # @raise [ArgumentError] if `database` or `schema` is empty
       def rebind_to_postgres_era!(copy, database:, schema:)
         require "pg"
         if database.to_s.empty? || schema.to_s.empty?
@@ -400,6 +441,11 @@ module Hecks
       # again is the caller's own job (its name and lifecycle belong to
       # the caller — see `rebind_to_postgres_era!`'s own header), not
       # something this per-ephemeral-boot helper should ever do mid-sweep.
+      #
+      # @param database [String] the caller-owned database name, created if it does not
+      #   already exist
+      # @param schema [String] the caller-owned schema name, dropped and recreated
+      # @return [void]
       def ensure_postgres_era_schema!(database:, schema:)
         GC.start
 
@@ -467,10 +513,21 @@ module Hecks
       # an ephemeral boot, deleted outright) — never called for
       # `:postgres_era` itself, where the bound adapter genuinely is
       # lineage-capable and the edge causes no refusal to begin with.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
       def strip_translations!(copy)
         Dir.glob(File.join(copy, "**", "translations", "*.bluebook")).each { |path| File.delete(path) }
       end
 
+      # Rewrites every `persisted_by` bind — aggregate-scoped or bare at the
+      # hecksagon's own root — in the copy's `.hecksagon` files to name `adapter_name`,
+      # and drops every `projected_by` bind outright.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @param adapter_name [String] the port binding name to rewrite every
+      #   `persisted_by` to, such as `"Memory"` or `"SqlitePersistence"`
+      # @return [void]
       def rewrite_bindings!(copy, adapter_name)
         Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |path|
           lines = File.readlines(path).grep_v(/\bprojected_by\s*\(?\s*"/)

data/lib/hecks/fuzzing/nondeterministic.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Fuzzing
-    # The one declared set of FIELDS that leave a comparison — partition,
+    # The one declared set of `FIELDS` that leave a comparison — partition,
     # not filter. Every comparison in lib/hecks/fuzzing that drops a field
     # before comparing two histories names a group here instead of writing
     # its own literal `except(...)` list, so the reason for dropping a field
@@ -48,17 +48,29 @@ module Hecks
 
       module_function
 
+      # Lists the nondeterministic field names declared for one comparison group.
+      #
+      # @param group [Symbol] a key of `FIELDS`, such as `:query_row` or `:event`
+      # @return [Array<Symbol>] the field names declared for `group`
+      # @raise [KeyError] if `group` names no declared group
       def names(group)
         FIELDS.fetch(group).keys
       end
 
       # Every declared name, across every group.
+      #
+      # @return [Array<Symbol>] the union of every group's field names, deduplicated
       def all_names
         FIELDS.values.flat_map(&:keys).uniq
       end
 
       # `hash` without `group`'s fields — symbol keys, the shape every
       # Ruby-side history carries.
+      #
+      # @param hash [Hash] a symbol-keyed row, event, or history hash to compare
+      # @param group [Symbol] a key of `FIELDS` naming which fields to drop
+      # @return [Hash] `hash` with `group`'s declared fields removed
+      # @raise [KeyError] if `group` names no declared group
       def strip(hash, group)
         hash.except(*names(group))
       end