hecks 1.4.0 → 1.5.0

data/lib/hecks/fuzzing/shrinker.rb

@@ -11,14 +11,16 @@ module Hecks
     # Rust subprocess (or a real Postgres round trip), where `bin/fuzz`'s
     # only ever cost an in-process replay.
     #
-    # The caller owns "same finding". `call` is handed a block that
+    # ## Ownership of "same finding"
+    #
+    # The caller owns it. `call` is handed a block that
     # answers true when a candidate step list still reproduces what the
     # original did — `bin/fuzz` compares its own verdict signature,
     # `bin/qa_sweep` compares `Shrinker.signature` of one mode's
     # divergences. This module never replays anything itself, so it has
     # no idea which engine, adapter or comparison it is minimizing for.
     #
-    # **Two passes, in order**:
+    # ## Two passes, in order
     #
     #   1. Steps, chunks first. Removing one step at a time (what
     #      `bin/fuzz` did) costs O(n²) candidate checks on a sequence
@@ -32,6 +34,8 @@ module Hecks
     #      one key at a time from the step's current args, keep it dropped
     #      only while the finding still reproduces.
     #
+    # ## Budget
+    #
     # A budget, because a sweep has other targets waiting. `budget:` caps
     # how many candidate checks one call may spend (nil = unbounded, the
     # `bin/fuzz` behaviour). When it runs out the best candidate found so
@@ -42,6 +46,23 @@ module Hecks
 
       module_function
 
+      # Shrinks `steps` to the smallest step list the block still accepts as
+      # reproducing the original finding — pass 1 (steps), then pass 2
+      # (arguments), as this module's own header describes.
+      #
+      # @param steps [Array<Hash>] the step list to shrink, each step a command,
+      #   query, or read-model hash as `SequenceGenerator` produces
+      # @param budget [Integer, nil] maximum candidate checks to spend; nil for
+      #   unbounded
+      # @yield [candidate] tests whether a candidate step list still reproduces
+      #   the finding being shrunk
+      # @yieldparam candidate [Array<Hash>] a step-dropped or argument-trimmed
+      #   copy of `steps`
+      # @yieldreturn [Boolean] true if `candidate` still reproduces the finding
+      # @return [Fuzzing::Shrinker::Result] `steps:` the shrunk step list,
+      #   `attempts:` how many candidate checks were spent, `exhausted:` whether
+      #   the budget ran out before shrinking finished
+      # @raise [ArgumentError] if no block is given
       def call(steps, budget: nil, &reproduces)
         raise ArgumentError, "Shrinker.call needs a block answering whether a candidate reproduces" unless reproduces
 
@@ -51,6 +72,18 @@ module Hecks
         Result.new(steps: current, attempts: meter.used, exhausted: meter.exhausted?)
       end
 
+      # Runs pass 1 of the shrink: delta-debugging removal of step chunks,
+      # halving the chunk size each full pass until single steps are tried
+      # and nothing more can be dropped.
+      #
+      # @param steps [Array<Hash>] the step list to shrink
+      # @param meter [Fuzzing::Shrinker::Meter] the shared budget meter
+      # @yield [candidate] tests whether a candidate step list still reproduces
+      #   the finding being shrunk
+      # @yieldparam candidate [Array<Hash>] `steps` with one chunk removed
+      # @yieldreturn [Boolean] true if `candidate` still reproduces the finding
+      # @return [Array<Hash>] the smallest step list pass 1 could reach, or the
+      #   best found so far if the budget ran out first
       def drop_steps(steps, meter, &reproduces)
         current = steps
         chunk = [current.length / 2, 1].max
@@ -83,9 +116,23 @@ module Hecks
         current
       end
 
+      # Runs pass 2 of the shrink: drops one argument key at a time from
+      # each surviving step's args, keeping the drop only while the
+      # finding still reproduces.
+      #
       # See the module header's pass 2 — `args` is read by whichever
       # spelling the step actually carries (`key?` first, never `||`,
       # which cannot tell a stored `false` from an absent key).
+      #
+      # @param steps [Array<Hash>] the step list, already step-shrunk by `drop_steps`
+      # @param meter [Fuzzing::Shrinker::Meter] the shared budget meter
+      # @yield [candidate] tests whether a candidate step list still reproduces
+      #   the finding being shrunk
+      # @yieldparam candidate [Array<Hash>] `steps` with one step's one argument
+      #   key dropped
+      # @yieldreturn [Boolean] true if `candidate` still reproduces the finding
+      # @return [Array<Hash>] `steps` with every argument key `drop_arguments`
+      #   accepted dropped
       def drop_arguments(steps, meter, &reproduces)
         steps.each_index do |position|
           original = args_of(steps[position])
@@ -104,6 +151,11 @@ module Hecks
         steps
       end
 
+      # Reads a step's argument hash, whichever key spelling it uses.
+      #
+      # @param step [Hash] one step, string- or symbol-keyed
+      # @return [Hash, nil] the step's `"args"` value if the step is string-keyed,
+      #   else its `:args` value (nil if neither key is present)
       def args_of(step)
         step.key?("args") ? step["args"] : step[:args]
       end
@@ -131,6 +183,15 @@ module Hecks
 
       CRASH_FIELDS = %w[crash process generator_crash].freeze
 
+      # Computes which finding a set of divergences is — the stable identity
+      # a shrink candidate has to keep. See this method's own preceding
+      # comment for what each field kind contributes.
+      #
+      # @param divergences [Array<Hash>] divergence entries, each at least
+      #   `{field:, detail:}` plus whichever mode-specific keys carry the two
+      #   compared sides
+      # @return [Set<String>] stable identity strings: each divergence's `field`,
+      #   plus `detail_keys`' own per-field detail strings
       def signature(divergences)
         divergences.each_with_object(Set.new) do |divergence, keys|
           field = divergence[:field].to_s
@@ -139,6 +200,13 @@ module Hecks
         end
       end
 
+      # Extracts the finer-grained identity strings one divergence's field
+      # contributes beyond the field name itself.
+      #
+      # @param field [String] the divergence's `field`, stringified
+      # @param divergence [Hash] the divergence entry `field` came from
+      # @return [Array<String>] extra identity strings for `field`'s own kind
+      #   (list, `instances`, or crash/process); empty for any other field
       def detail_keys(field, divergence)
         left, right = divergence.except(:field, :detail).values.select { |v| v.is_a?(Array) || v.is_a?(Hash) }
         if LIST_FIELDS.include?(field) then list_keys(field, left, right)
@@ -149,15 +217,33 @@ module Hecks
         end
       end
 
+      # Names the rows present on one side of a list-field divergence and not
+      # the other.
+      #
+      # @param field [String] the divergence's field name, prefixed onto each key
+      # @param left [Array, nil] one side's list; a non-Array yields no keys
+      # @param right [Array, nil] the other side's list; a non-Array yields no keys
+      # @return [Array<String>] `"field:name"` for every row in the symmetric
+      #   difference of `left` and `right`; empty unless both are arrays
       def list_keys(field, left, right)
         return [] unless left.is_a?(Array) && right.is_a?(Array)
 
         ((left - right) + (right - left)).map { |row| "#{field}:#{named(row)}" }
       end
 
+      # Names the top-level keys the two sides of an `instances` divergence
+      # disagree on.
+      #
       # Instance keys are `Aggregate#id` on the wire — the id is whatever
       # the generator minted, so it names the record, not the finding;
       # keeping it would pin every creating step.
+      #
+      # @param left [Hash, nil] one side's instance snapshot; a non-Hash yields no keys
+      # @param right [Hash, nil] the other side's instance snapshot; a non-Hash
+      #   yields no keys
+      # @return [Array<String>] `"instances:Aggregate"` for every top-level key
+      #   the two sides disagree on, its `#id` suffix dropped; empty unless both
+      #   are hashes
       def instance_keys(left, right)
         return [] unless left.is_a?(Hash) && right.is_a?(Hash)
 
@@ -165,10 +251,26 @@ module Hecks
                                 .map { |key| "instances:#{key.to_s.split('#').first}" }
       end
 
+      # Checks that a candidate's own divergences still demonstrate the
+      # finding being shrunk.
+      #
+      # @param original_signature [Set<String>] the finding's own signature, as
+      #   returned by `signature`
+      # @param divergences [Array<Hash>] the candidate's own divergence entries,
+      #   in `signature`'s own shape
+      # @return [Boolean] true if `divergences` is non-empty and its signature is
+      #   a superset of `original_signature`
       def reproduces?(original_signature, divergences)
         !divergences.empty? && original_signature.subset?(signature(divergences))
       end
 
+      # Names one row from a list-field divergence, for `list_keys`.
+      #
+      # @param row [Object] one item from a list-field divergence's array;
+      #   typically a Hash carrying a `verb`, `query`, or `policy` key (string
+      #   or symbol)
+      # @return [String] `row`'s `verb`/`query`/`policy` value, stringified, if
+      #   `row` is a Hash carrying one of those keys; otherwise `row.to_s`
       def named(row)
         return row.to_s unless row.is_a?(Hash)
 
@@ -180,13 +282,23 @@ module Hecks
       class Meter
         attr_reader :used
 
+        # @param budget [Integer, nil] maximum candidate checks to allow; nil for unbounded
         def initialize(budget)
           @budget = budget
           @used   = 0
         end
 
+        # Reports whether this meter's budget has been fully spent.
+        #
+        # @return [Boolean] true if a budget is set and every allotted check has
+        #   been used
         def exhausted? = !@budget.nil? && @used >= @budget
 
+        # Spends one candidate check against the budget and runs the block.
+        #
+        # @yield runs the candidate check being counted
+        # @yieldreturn [Object] the block's own result
+        # @return [Object] whatever the block returns
         def try
           @used += 1
           yield

data/lib/hecks/fuzzing/structural_skips.rb

@@ -12,16 +12,24 @@ module Hecks
     # `QualityControlDials::STRUCTURAL_REFUSAL_BOUNDARY`.
     #
     # The construct comes straight from the manifest entry, written by the
-    # generator branch that made the skip (`Projector::SkipReason`). This
-    # module used to guess it from the Ruby declaration's `to_h` keys, which
-    # was coarser than codegen's own decision and could drift from it.
+    # generator branch that made the skip (`Projector::SkipReason`), rather
+    # than guessed from the Ruby declaration's `to_h` keys, which is coarser
+    # than codegen's own decision and can drift from it.
     module StructuralSkips
       module_function
 
+      # Attributes each skipped verb to the construct family its manifest
+      # entry names.
+      #
       # One entry per skipped verb: `{ verb:, constructs: [...] }`, sorted by
       # verb so the printed observation is stable across seeds and runs. A
       # verb the manifest doesn't declare answers `unknown`, which no
       # boundary admits.
+      #
+      # @param gaps [Fuzzing::RustGapManifest] the binary's not-generated manifest entries
+      # @param verbs [Array<String>] the skipped query/read-model verbs to attribute
+      # @return [Array<Hash{Symbol => Object}>] one `{ verb: String, constructs: Array<String> }`
+      #   per verb, in sorted-verb order
       def attribute(gaps, verbs)
         verbs.sort.map do |verb|
           entry = gaps.not_generated(verb)
@@ -29,7 +37,13 @@ module Hecks
         end
       end
 
-      # Every skipped verb whose constructs are not all inside `boundary`.
+      # Selects the attributed entries whose constructs are not all inside `boundary`.
+      #
+      # @param attributed [Array<Hash{Symbol => Object}>] entries as returned by `attribute`
+      # @param boundary [Array<String, Symbol>] the construct families the documented codegen
+      #   boundary admits
+      # @return [Array<Hash{Symbol => Object}>] the subset of `attributed` naming an
+      #   unadmitted construct, or no construct at all
       def outside_boundary(attributed, boundary)
         admitted = boundary.map(&:to_s)
         attributed.select { |entry| entry[:constructs].empty? || (entry[:constructs] - admitted).any? }

data/lib/hecks/fuzzing/sweep_depth.rb

@@ -40,6 +40,14 @@ module Hecks
       # streak does not exceed wins — rows are read in order, so the table
       # must be ascending, and the last row's `Float::INFINITY` is what
       # makes it the ceiling rather than a gap.
+      #
+      # @param streak [Integer] `Target.clean_streak`, the number of consecutive clean sweeps
+      # @param tiers [Array<Hash{Symbol => Numeric}>] ascending `{ upto:, seeds:, steps: }` rows;
+      #   defaults to `DEFAULT_TIERS`
+      # @return [Array(Integer, Integer)] `[seeds, steps]` for the first row `streak` fits under
+      # @raise [ArgumentError] if `streak` is negative
+      # @raise [ArgumentError] if no row in `tiers` covers `streak` (the last row must declare
+      #   `upto: Float::INFINITY`)
       def for_streak(streak, tiers: DEFAULT_TIERS)
         raise ArgumentError, "streak must not be negative" if streak.negative?
 

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -3,26 +3,30 @@ module Hecks
     # 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
     # 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
+    #
+    # `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
@@ -121,10 +125,19 @@ 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)
@@ -137,6 +150,12 @@ module Hecks
         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?
@@ -146,12 +165,26 @@ module Hecks
       # 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)
@@ -161,10 +194,17 @@ 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
@@ -172,6 +212,13 @@ module Hecks
         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

@@ -100,11 +100,11 @@ 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
+      # 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
@@ -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?
@@ -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,10 +295,20 @@ 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
 
@@ -239,11 +318,20 @@ module Hecks
       # 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