hecks 1.3.0 → 1.5.0

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -1,30 +1,34 @@
 module Hecks
   module Fuzzing
-    # WHAT A SWEEP TARGET CAN ACTUALLY BE CHECKED FOR, read off the
+    # What a sweep target can actually be checked for, read off the
     # filesystem — never off a stored list.
     #
-    # `bin/qa_sweep` used to decide its ONE comparison mode inline: "is
-    # there a Cargo feature named after this directory? then
-    # `:differential`, else `:ruby_only`", and a separate hand-typed abort
-    # for `--persistence-parity` ("does any .hecksagon bind PostgresEra?").
-    # Every further mode the practice adds (era boundary, concurrency, a
-    # WASM front) would have grown one more inline `if`, each one a
+    # `bin/qa_sweep` does not decide its comparison modes with inline
+    # conditionals — "is there a Cargo feature named after this directory?
+    # then `:differential`, else `:ruby_only`", a separate hand-typed abort
+    # for `--persistence-parity` ("does any .hecksagon bind PostgresEra?"),
+    # and so on for every further mode the practice adds (era boundary,
+    # concurrency, a WASM front) — because each such inline `if` is a
     # policy decision hiding in a script. This module is those decisions
-    # as DATA: `MODE_REQUIREMENTS` says which capabilities each mode
+    # as data: `MODE_REQUIREMENTS` says which capabilities each mode
     # needs, `infer` says which capabilities a target's own directory
     # actually has, and `resolve` is the one rule that joins them —
     # `modes_to_run = enabled ∩ eligible`.
     #
-    # INFERENCE DECIDES; A STORED LIST ONLY RECORDS. `Target.capabilities`
-    # (qa/bluebook/quality_control.bluebook, once PR-1's era lands) is
-    # written by the runner from exactly this inference at release time
-    # so `Target.EligibleFor(mode)` can AUDIT the rotation from the
-    # ledger alone — but the runner re-infers every sweep, because a
-    # stored list that lags yesterday's Cargo feature is precisely the
-    # "quiet divergence" (the chapter's own opening comment) this whole
-    # practice exists to hunt. Nothing here ever reads the ledger.
+    # ## Inference decides; a stored list only records
     #
-    # EVERY REGEX IS ONE THE HARNESS ALREADY OWNED, moved here rather than
+    # `Target.capabilities` (qa/bluebook/quality_control.bluebook, once
+    # PR-1's era lands) is written by the runner from exactly this
+    # inference at release time so `Target.EligibleFor(mode)` can audit
+    # the rotation from the ledger alone — but the runner re-infers every
+    # sweep, because a stored list that lags yesterday's Cargo feature is
+    # precisely the "quiet divergence" (the chapter's own opening comment)
+    # this whole practice exists to hunt. Nothing here ever reads the
+    # ledger.
+    #
+    # ## Regex provenance
+    #
+    # Every regex is one the harness already owned, moved here rather than
     # re-derived, and each one's provenance is named beside it so a
     # future edit to the original site is a visible drift, not a silent
     # one: the Cargo feature line (`RustConformanceHelpers#build_rust_for`),
@@ -45,10 +49,13 @@ module Hecks
       # domain-level default (`persisted_by "PostgresEra"`).
       POSTGRES_ERA_BINDING = /persisted_by\s*\(?\s*"PostgresEra"/
 
-      # `HecksagonBuilder#uses_framework` — the one line that attaches
-      # Governance's own `RoleAssignment` lookup to a domain's `role` checks
-      # (`CommandRules::Authorization#governance_attached?`).
-      GOVERNANCE_ATTACHED = /uses_framework\s*\(?\s*"Governance"/
+      # `HecksagonBuilder#uses_framework "X"` — captures which member a
+      # hecksagon attaches, whatever its name. Whether that member answers
+      # a role check is then read off its own declaration (`provides
+      # "authorization"`, via `Framework.providers_of`), the same rule
+      # `Registry#authorization_provider_for` applies at runtime — never a
+      # match on the literal "Governance".
+      FRAMEWORK_ATTACHED = /uses_framework\s*\(?\s*"([^"]+)"/
 
       # A command-level `role "..."` — the only construct
       # `refuse_role_mismatch` ever has anything to check a caller against.
@@ -61,21 +68,21 @@ module Hecks
 
       PROCESS_MANAGER = /^\s*process_manager\s+"/
 
-      # WHICH CAPABILITIES EACH MODE NEEDS BEFORE IT CAN SAY ANYTHING TRUE
-      # ABOUT A TARGET. An empty list means "any target at all" — every
+      # Which capabilities each mode needs before it can say anything true
+      # about a target. An empty list means "any target at all" — every
       # domain boots under Memory, so Ruby-only properties and the
       # self-consistency pass are always answerable. `ruby_only` is listed
-      # requirement-free on purpose and then EXCLUDED by `resolve` whenever
+      # requirement-free on purpose and then excluded by `resolve` whenever
       # `differential` resolved too: they are the same seat, and a compiled
       # Rust binary is strictly the better occupant (item 1 of the
-      # detection plan folded the Ruby-only property battery INTO the
+      # detection plan folded the Ruby-only property battery into the
       # differential seat, so nothing is lost by the exclusion).
       #
       # The four `false`-by-default modes in `QualityControlDials::MODES`
       # (`adapter_parity_postgres`, `era_boundary`, `concurrency`,
       # `wasm_front`) are named here with their requirements even though
       # nothing runs them yet — so `resolved modes:` can already say, per
-      # target, which of them WOULD be eligible the day a human flips the
+      # target, which of them would be eligible the day a human flips the
       # dial, and so flipping it is a one-line data change rather than a
       # code change plus a data change.
       MODE_REQUIREMENTS = {
@@ -92,7 +99,24 @@ module Hecks
         wasm_front:                 %w[rust]
       }.freeze
 
-      # MODES THAT NAME A SEPARATE, EXPENSIVE PASS OF THEIR OWN rather than
+      # Which of those modes `bin/qa_sweep` can actually run today.
+      # `MODE_REQUIREMENTS` above says what a mode needs; this says what
+      # exists to do it, and the two are not the same. Conflating them is
+      # how `qa/settings.yml` came to enable `wasm_front` and
+      # `adapter_parity_postgres` with nothing behind either — no seat, no
+      # check folded into the seed loop, no `MODE_EXPECTATIONS` entry — while
+      # `resolved modes:` still printed them per target, so the sweep
+      # advertised coverage it never performed. A mode named in
+      # `MODE_REQUIREMENTS` but absent here is one this practice wants and has
+      # not built: `bin/qa_sweep` refuses to start when a dial or `--modes`
+      # enables it, rather than resolving it into a line nobody can act on.
+      # `spec/qa_sweep_runnable_modes_spec.rb` keeps this list honest from
+      # both sides by grepping the runner itself.
+      RUNNABLE_MODES = %i[differential ruby_only self_consistency properties_in_differential
+                          structural_skip_report adapter_parity_sqlite persistence_parity
+                          era_boundary concurrency].freeze
+
+      # Modes that name a separate, expensive pass of their own rather than
       # an extra check folded into the ordinary per-seed loop —
       # `bin/qa_sweep` runs these only when asked by name (`--modes
       # persistence_parity`, or its older alias `--persistence-parity`) or
@@ -101,37 +125,66 @@ module Hecks
       # exists because that pass pays for real Postgres I/O per dispatch).
       DEFERRED_MODES = %i[persistence_parity adapter_parity_postgres era_boundary concurrency].freeze
 
+      # Reads a target directory to find out which capabilities it actually has.
+      #
       # Sorted, plain strings — comma-joined by the runner into the
       # `Target.Release(capabilities:)` value object and printed verbatim
       # on the `resolved modes:` line, so the same spelling is what a
       # human reads, what `--all` parses back, and what the ledger stores.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param rust_dir [String] path to the Rust project root, checked for a matching
+      #   Cargo feature; defaults to this repo's own `rust/` directory
+      # @return [Array<String>] the target's capabilities, sorted; a subset of
+      #   `sqlite`, `rust`, `postgres_era`, `translations`, `governance`, `role_gated`,
+      #   `tenant`, `sagas`
       def infer(domain_path, rust_dir: File.expand_path("../../../rust", __dir__))
         capabilities = %w[sqlite]
         capabilities << "rust" if rust_feature?(domain_path, rust_dir)
         capabilities << "postgres_era" if any_file?(domain_path, "*.hecksagon", POSTGRES_ERA_BINDING)
         capabilities << "translations" if Dir.glob(File.join(domain_path, "**", "translations", "*.bluebook")).any?
-        capabilities << "governance" if any_file?(domain_path, "*.hecksagon", GOVERNANCE_ATTACHED)
+        capabilities << "governance" if authorization_attached?(domain_path)
         capabilities << "role_gated" if any_file?(domain_path, "*.bluebook", ROLE_GATED)
         capabilities << "tenant" if any_file?(domain_path, "*.bluebook", TENANT_SCOPED)
         capabilities << "sagas" if any_file?(domain_path, "*.bluebook", PROCESS_MANAGER)
         capabilities.sort
       end
 
+      # Answers whether `mode` can run against a target with `capabilities`.
+      #
+      # @param mode [Symbol, String] a key of `MODE_REQUIREMENTS`, such as `:differential`
+      # @param capabilities [Array<String>] the target's capabilities, as `infer` returns
+      # @return [Boolean] whether `capabilities` covers every capability `mode` requires
+      # @raise [ArgumentError] if `mode` names no entry in `MODE_REQUIREMENTS`
       def eligible?(mode, capabilities)
         required = MODE_REQUIREMENTS.fetch(mode.to_sym) { raise ArgumentError, "unknown sweep mode #{mode.inspect}" }
         (required - capabilities).empty?
       end
 
-      # THE ONE RULE. `enabled` is whatever the dial (or `--modes`) turned
+      # The one rule. `enabled` is whatever the dial (or `--modes`) turned
       # on, in the dial's own declaration order — that order is preserved
       # so the printed line reads the same way the dial does. Then the
       # single exclusion named on `MODE_REQUIREMENTS`.
+      #
+      # @param enabled [Array<Symbol, String>] modes turned on, in the dial's own
+      #   declaration order
+      # @param capabilities [Array<String>] the target's capabilities, as `infer` returns
+      # @return [Array<Symbol>] `enabled`'s eligible modes, in `enabled`'s order, with
+      #   `:ruby_only` dropped whenever `:differential` is also eligible
       def resolve(enabled, capabilities)
         resolved = enabled.map(&:to_sym).select { |mode| eligible?(mode, capabilities) }
         resolved.delete(:ruby_only) if resolved.include?(:differential)
         resolved
       end
 
+      # Answers whether `rust_dir`'s Cargo.toml declares a feature named after
+      # `domain_path`'s own directory.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory;
+      #   its basename, lowercased, is the feature name looked up
+      # @param rust_dir [String] path to the Rust project root (holds `Cargo.toml`)
+      # @return [Boolean] whether a matching Cargo feature is declared; false if
+      #   `rust_dir` has no `Cargo.toml`
       def rust_feature?(domain_path, rust_dir)
         cargo_toml = File.join(rust_dir, "Cargo.toml")
         return false unless File.file?(cargo_toml)
@@ -141,6 +194,31 @@ module Hecks
         features.match?(/^#{Regexp.escape(feature)}\s*=\s*\[\]/)
       end
 
+      # Answers whether any `.hecksagon` under `domain_path` attaches a member
+      # that provides authorization.
+      #
+      # The capability label stays "governance" — it is the value
+      # `bin/qa_sweep` writes into the QualityControl ledger's
+      # `Target.capabilities`, and renaming it is a ledger change, not
+      # part of dropping the name check.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @return [Boolean] whether the domain attaches a member that provides the
+      #   `Bluebook::Capabilities::AUTHORIZATION` capability
+      def authorization_attached?(domain_path)
+        attached = Dir.glob(File.join(domain_path, "**", "*.hecksagon"))
+                      .flat_map { |path| File.read(path).scan(FRAMEWORK_ATTACHED).flatten }.uniq
+        providers = Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION)
+        attached.intersect?(providers)
+      end
+
+      # Answers whether any file under `domain_path` matching `glob` contains `pattern`.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param glob [String] a `Dir.glob` pattern relative to `domain_path`, such as
+      #   `"*.bluebook"`
+      # @param pattern [Regexp] the pattern each matching file's contents is tested against
+      # @return [Boolean] whether any matching file's contents match `pattern`
       def any_file?(domain_path, glob, pattern)
         Dir.glob(File.join(domain_path, "**", glob)).any? { |path| File.read(path).match?(pattern) }
       end

data/lib/hecks/fuzzing/value_generator.rb

@@ -4,7 +4,7 @@ module Hecks
   module Fuzzing
     # One attribute, one value — in the exact JSON shape the hand-written
     # corpus already uses (a value-object-typed attribute is a nested hash keyed
-    # by its own field names ; a reference is the BARE ID of the head it points
+    # by its own field names ; a reference is the bare ID of the head it points
     # at, because that is what a reference is). Everything
     # returned is a plain, JSON-safe Ruby value : String keys throughout, never
     # symbols, so a generated step can be dumped straight to JSON.
@@ -15,7 +15,7 @@ module Hecks
     # codebase," and a fixed corpus of a few dozen examples rarely happens to
     # exercise the boundary that actually breaks. But mostly not : an attribute
     # named `email`/`currency` almost always needs a specific shape just to get
-    # PAST its own invariant (`address.include?("@")`, `currency.size == 3`) —
+    # past its own invariant (`address.include?("@")`, `currency.size == 3`) —
     # banking's very first fuzz run never got past Customer.Register, because
     # no plain random word ever contains "@". Reaching deep state matters more
     # than edge-casing every single field every single time, so the "normal"
@@ -31,7 +31,7 @@ module Hecks
       # (lib/hecks/runtime/value/coercion.rb) has accepted a bare
       # `"large"` in place of `{"value" => "large"}` for any single-field
       # value object since 86727afd — but until this generator actually
-      # PRODUCES that shape, nothing exercises it: neither the adapter-
+      # produces that shape, nothing exercises it: neither the adapter-
       # agreement gate nor the Rust/WASM `from_json` codegen (rust/project/
       # json_codec.rb) can ever be caught drifting on a shape they're
       # never handed.
@@ -44,22 +44,22 @@ module Hecks
       # PRD 05 (numeric-boundary-coverage) — Bignum (`2**100`, past i64's
       # own ceiling, which Ruby's own `Integer` has no such ceiling for —
       # `rust/src/kernel/json.rs`'s own `integral_i64` doc comment names
-      # exactly this: a Rust kernel value CANNOT represent it, so this
+      # exactly this: a Rust kernel value cannot represent it, so this
       # exercises a real cross-runtime capability gap, not a Ruby-only
       # edge) and its negative twin. Both round-trip through Ruby's own
       # arithmetic/JSON cleanly (confirmed directly: `(2**100).clamp(...)`
       # and `JSON.generate(2**100)` both just work — Integer has no
-      # ceiling here), so nothing in THIS runtime needed a fix for these;
+      # ceiling here), so nothing in this runtime needed a fix for these;
       # they're included so a real generated sequence occasionally
       # produces the value at all, since nothing had, repo-wide, before.
       INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648, 2**100, -(2**100)].freeze
       # BUG#35 (QualityControl QA ledger, `lease-clock-json-precision`) —
       # a Bignum edge case (`2**100`, above) landing on an Integer-typed
-      # CLOCK or COUNT reading fires the already-catalogued `Json::Num`/
+      # clock or count reading fires the already-catalogued `Json::Num`/
       # f64 precision-loss class (`rust/src/kernel/json.rs`'s
       # `parse_number` parses every number through `s.parse::<f64>()`
       # before any target-type conversion runs, and `Json::Num` is a
-      # plain `f64` end to end — see that file's own header) on a NEW
+      # plain `f64` end to end — see that file's own header) on a new
       # site every time a new clock/count-shaped field is authored,
       # without adding any new coverage: both engines already refuse
       # (`TypeMismatch`, out of `i64` range either way) for this shape,
@@ -83,7 +83,7 @@ module Hecks
       # as a clock or a count is capped to a narrower, still-real
       # edge-case pool below (still exercises the ordinary i32
       # boundaries, just never a value past f64's own 2**53 exact-
-      # integer ceiling) — every OTHER Integer-typed field (a money
+      # integer ceiling) — every other Integer-typed field (a money
       # amount, an identity sequence, anything not clock/count-shaped)
       # still draws from the full `INTEGER_EDGE_CASES` pool above,
       # unchanged.
@@ -100,12 +100,12 @@ module Hecks
       CLOCK_OR_COUNT_NAME_PATTERN = /clock|instant|expir|ttl|\bnow\b|timestamp|epoch|count/i
       # NaN and +/-Infinity — the real find (see `spec/runtime/
       # numeric_boundary_spec.rb`): `Value::Coercion#check_numeric_fields`
-      # used to let all three sail through untyped-checked (each really
-      # is a Float), reaching either `CommandRules::Arithmetic#clamp`
-      # (raw `ArgumentError`, not a domain refusal) or `JSON.generate`
+      # type-checks all three (each really is a Float) before they can
+      # reach either `CommandRules::Arithmetic#clamp` (raw
+      # `ArgumentError`, not a domain refusal) or `JSON.generate`
       # (`JSON::GeneratorError`, also not a domain refusal) — both fixed
-      # at the source now, so these are safe to generate. -0.0 is
-      # deliberately included too even though it was ALREADY safe
+      # at the source, so these are safe to generate. -0.0 is
+      # deliberately included too even though it was already safe
       # (finite, round-trips through JSON as `-0.0` cleanly) — a signed
       # zero is exactly the kind of boundary a hand-written corpus never
       # happens to type, and the fuzzer existing to cover it is the
@@ -125,6 +125,18 @@ module Hecks
       # just named "address"; the VO's own name is where "email" lives. A
       # combined hint catches both spellings without needing to guess which
       # level a domain happened to name the thing on.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to generate a value for
+      # @param aggregate [Bluebook::Aggregate] the aggregate `attribute` belongs to;
+      #   resolves a same-chapter identity value object
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param known_ids [Hash{String => Array<String>}] known real ids, keyed by
+      #   aggregate or entity name; a reference draws from this pool
+      # @param context [String, nil] the enclosing value object's own declared name,
+      #   for name-aware primitive generation; nil at the top level
+      # @return [String, Integer, Float, Boolean, Hash] a JSON-safe value in the corpus's
+      #   own shape: a nested Hash for a value-object-typed attribute, a bare id String
+      #   for a reference, or a plain primitive otherwise
       def value_for(attribute, aggregate, random:, known_ids: {}, context: nil)
         return reference_value(attribute, random: random, known_ids: known_ids) if attribute.reference?
 
@@ -143,6 +155,20 @@ module Hecks
         primitive(attribute.type.to_s, random: random, name: "#{context} #{attribute.name}")
       end
 
+      # Generates a nested value for a whole value object: a random admitted
+      # row for a closed set, or a value per declared attribute otherwise —
+      # occasionally unwrapped to a bare scalar for a genuinely single-field
+      # value object.
+      #
+      # @param value_object [Bluebook::ValueObject] the value object to generate a value for
+      # @param aggregate [Bluebook::Aggregate] the aggregate `value_object` is reached
+      #   from, forwarded to nested `value_for` calls
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param known_ids [Hash{String => Array<String>}] known real ids, keyed by
+      #   aggregate or entity name, forwarded to nested `value_for` calls
+      # @return [Hash, Object] `{field name => value, ...}` for each declared attribute
+      #   or closed-set member; unwrapped to that lone value directly when the value
+      #   object has exactly one field and the bare-scalar draw hits
       def object_for(value_object, aggregate, random:, known_ids:)
         fields =
           if value_object.closed_set? && !value_object.members.empty?
@@ -157,10 +183,10 @@ module Hecks
             end
           end
 
-        # `fields.size == 1` — the SAME test `Behaviour::ValueObject#
+        # `fields.size == 1` — the same test `Behaviour::ValueObject#
         # sole_attribute` names: a genuinely single-field value object,
         # not merely "this particular closed-set member happened to pick
-        # one field." Unwrapping ONLY here, not in `invalid_member`
+        # one field." Unwrapping only here, not in `invalid_member`
         # above — a deliberately-wrong combination stays a Hash so its
         # own wrongness is what gets exercised, not a second, unrelated
         # shape question.
@@ -172,17 +198,31 @@ module Hecks
       # A combination that (almost certainly) isn't one of the closed set's
       # admitted rows — deliberately, to exercise the refusal a `one_of`
       # exists to enforce, not just its happy path.
+      #
+      # @param value_object [Bluebook::ValueObject] the closed-set value object to
+      #   generate a non-admitted combination for
+      # @param random [Random] the RNG driving every draw this call makes
+      # @return [Hash] `{field name => value, ...}` for every declared attribute, each
+      #   drawn independently rather than sampled from an admitted row
       def invalid_member(value_object, random:)
         value_object.attributes.to_h do |field|
           [field.name.to_s, primitive(field.type.to_s, random: random, name: field.name.to_s)]
         end
       end
 
-      # THE ID ITSELF. This minted `{"value" => id}` back when a reference was
-      # stored wrapped ; the payload gate refuses that shape now, so a fuzzer
-      # still emitting it would have every generated reference refused and
-      # the SILENT guard would report the fuzzer broken rather than
-      # the runtime.
+      # The ID itself, unwrapped: the payload gate refuses a reference stored
+      # wrapped as `{"value" => id}`, so a fuzzer emitting that shape would
+      # have every generated reference refused and the silent guard would
+      # report the fuzzer broken rather than the runtime.
+      #
+      # @param attribute [Bluebook::Attribute] the reference-typed attribute to
+      #   generate a value for
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param known_ids [Hash{String => Array<String>}] known real ids, keyed by
+      #   aggregate or entity name; looked up under `attribute.type.target_name`
+      # @return [String] a real id drawn from the matching pool most of the time; a
+      #   fabricated `"missing-..."` id when the pool is empty or the invalid-reference
+      #   draw hits
       def reference_value(attribute, random:, known_ids:)
         pool = known_ids[attribute.type.target_name.to_s] || []
         return "missing-#{random.bytes(4).unpack1('H*')}" if pool.empty? || random.rand < INVALID_REFERENCE_PROBABILITY
@@ -190,6 +230,16 @@ module Hecks
         pool.sample(random: random)
       end
 
+      # Generates a value for one Ruby-primitive-typed attribute.
+      #
+      # @param type_name [String] the primitive type name: `"String"`, `"Integer"`,
+      #   `"Float"`, `"TrueClass"`, or `"FalseClass"`
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param name [String, nil] a name hint (attribute name, optionally
+      #   context-prefixed) that draws an email-/currency-shaped string or a
+      #   clock/count-shaped integer
+      # @return [String, Integer, Float, Boolean] a value of the type `type_name` names
+      # @raise [ArgumentError] if `type_name` names anything else
       def primitive(type_name, random:, name: nil)
         case type_name
         when "String"  then string_value(random, name: name)
@@ -200,6 +250,14 @@ module Hecks
         end
       end
 
+      # Generates a String value, name-aware for the couple of shapes that
+      # need to look a specific way to get past their own invariant.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param name [String, nil] a name hint; an `"email"` or `"currency"` match
+      #   draws a shaped value instead of random words
+      # @return [String] an edge-case string, an email address, a currency code, or
+      #   1-3 random words joined by spaces
       def string_value(random, name: nil)
         return STRING_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
         return email_value(random) if name&.match?(/email/i)
@@ -208,15 +266,26 @@ module Hecks
         Array.new(random.rand(1..3)) { WORDS.sample(random: random) }.join(" ")
       end
 
+      # Generates a fabricated, syntactically valid email address.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @return [String] a `"word@word.example"` address
       def email_value(random)
         "#{WORDS.sample(random: random)}@#{WORDS.sample(random: random)}.example"
       end
 
+      # Generates an Integer value, skewed positive.
+      #
       # Skewed positive : `cents.positive?`/`!cents.negative?`-style
       # invariants are common across this codebase's example domains, and a
       # sequence that can never get past one never reaches the state a deeper
       # bug would need. Zero and negative are still real, reachable outcomes —
       # via the edge-case pool, deliberately, not by starving them entirely.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param name [String, nil] a name hint; a clock/count-shaped match narrows
+      #   the edge-case pool to `SAFE_INTEGER_EDGE_CASES`
+      # @return [Integer] an edge-case integer sometimes, else a random count in 1..1000
       def integer_value(random, name: nil)
         if random.rand < EDGE_CASE_PROBABILITY
           pool = clock_or_count_shaped?(name) ? SAFE_INTEGER_EDGE_CASES : INTEGER_EDGE_CASES
@@ -226,24 +295,43 @@ module Hecks
         random.rand(1..1000)
       end
 
+      # Reports whether a field name reads as a clock reading or a
+      # policy-capped count, per `CLOCK_OR_COUNT_NAME_PATTERN`'s own comment.
+      #
+      # @param name [String, nil] the name to test
+      # @return [Boolean] true if `name` matches the clock/count name pattern
       def clock_or_count_shaped?(name)
         name.to_s.match?(CLOCK_OR_COUNT_NAME_PATTERN)
       end
 
+      # Generates a Float value.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @return [Float] an edge-case float sometimes, else a random value in
+      #   0.01..1000.0, rounded to 2 decimal places
       def float_value(random)
         return FLOAT_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
 
         random.rand(0.01..1000.0).round(2)
       end
 
-      # The bare scalar a generated IDENTITY value stands for, for recording into
+      # The bare scalar a generated identity value stands for, for recording into
       # `known_ids`. An identity is declared as a value object, so this opens one ;
       # a reference pointing at this record is already that scalar and needs no
-      # opening at all. The two used to be the same reading and are not any more.
+      # opening at all — the two are different readings, not interchangeable.
+      #
+      # @param identity_value [Hash, Object] a generated identity value, as `value_for`
+      #   produced it — a Hash for a multi-field value object, or the bare scalar already
+      #   for a single-field one
+      # @return [String] the identity's bare scalar, stringified
       def scalar_of(identity_value)
         identity_value.is_a?(Hash) ? identity_value.values.first.to_s : identity_value.to_s
       end
 
+      # Generates a fabricated id unrelated to anything `known_ids` tracks.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @return [String] a `"gen-"`-prefixed id with 8 random hex characters
       def random_id(random)
         "gen-#{random.bytes(4).unpack1('H*')}"
       end

data/lib/hecks/fuzzing.rb

@@ -8,11 +8,16 @@ end
 require_relative "fuzzing/value_generator"
 require_relative "fuzzing/invalid_value_generator"
 require_relative "fuzzing/sequence_generator"
+require_relative "fuzzing/nondeterministic"
 require_relative "fuzzing/replay"
+require_relative "fuzzing/shrinker"
 require_relative "fuzzing/properties"
+require_relative "fuzzing/qa_settings"
 require_relative "fuzzing/rotation_priority"
 require_relative "fuzzing/sweep_depth"
 require_relative "fuzzing/persistence_parity"
 require_relative "fuzzing/form_census"
 require_relative "fuzzing/target_capabilities"
+require_relative "fuzzing/rust_gap_manifest"
 require_relative "fuzzing/structural_skips"
+require_relative "fuzzing/coverage_campaign"