hecks 1.4.0 → 1.5.1

data/lib/hecks/fuzzing/properties/invariants_and_aggregation.rb

@@ -49,6 +49,11 @@ module Hecks
         #
         # Real target: SafeDepositBox's own Visit — `invariant("a written
         # note is not blank") { !note || !note.text.to_s.empty? }`.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every stored record satisfies its own
+        #   (and its own entities') declared invariants; otherwise a message
+        #   naming the record and the invariant it violates
         def stored_records_satisfy_declared_invariants(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -76,6 +81,12 @@ module Hecks
         # a.list? && a.type.to_s == entity.hecks_name }`), independently
         # reapplied here against a stored record's own plain Hash state
         # rather than a live `Instance`.
+        # @param owner_construct [Bluebook::Aggregate, Bluebook::Entity] the
+        #   construct whose own `list_of` entities to check
+        # @param owner_state [Hash] `owner_construct`'s own stored state
+        # @param key [String] the top-level record key, for the message
+        # @return [String, nil] a message naming the first violating piece found,
+        #   at any nesting depth; `nil` if every piece satisfies its invariants
         def check_piece_invariants(owner_construct, owner_state, key)
           owner_construct.entities.each do |entity|
             next if entity.invariants.empty?
@@ -122,6 +133,10 @@ module Hecks
         # a live or rehydrated instance sitting in a state the procedure
         # never declares is the saga-durability twin of
         # `lifecycle_values_are_declared` above.
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every saga instance holds a declared
+        #   state and its own memory survives a checkpoint round-trip; otherwise a
+        #   message naming the process manager, correlation, and problem
         def sagas_rehydrate_cleanly(history)
           bluebook = history.fetch(:bluebook)
           process_managers = bluebook.process_managers.to_h { |pm| [pm.name, pm] }
@@ -163,6 +178,10 @@ module Hecks
         # dispatch is the claim then, not "dispatched to zero rows," and a
         # policy that dispatched anyway despite a failing guard is as real
         # a finding as a row it skipped.
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every fan-out finding's actual dispatches
+        #   match its independently computed expected row set; otherwise a message
+        #   naming the policy, event, and disagreement
         def fanout_dispatches_once_per_matching_row(history)
           offenders = history.fetch(:fan_outs).filter_map do |finding|
             expected = finding[:expected_row_ids]
@@ -211,6 +230,10 @@ module Hecks
         # branch reads as its own precondition."
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/PerceivedComplexity
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every eligible count/median report answer
+        #   matches an independent recomputation; otherwise a message naming the
+        #   query and the disagreement
         def aggregation_matches_recompute(history)
           bluebook = history.fetch(:bluebook)
 
@@ -257,6 +280,11 @@ module Hecks
         # of count/median, nest_rows in place of recompute_median.
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/PerceivedComplexity
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every eligible group_by report answer matches
+        #   an independent recompute; otherwise a semicolon-joined message naming each
+        #   offending query
         def group_by_matches_recompute(history)
           bluebook = history.fetch(:bluebook)
 
@@ -290,6 +318,11 @@ module Hecks
         # per `group_by` field in declared order, leaf is the row with
         # every grouped field stripped (already spent, as the keys that
         # reached it).
+        # @param rows [Array<Hash>] materialized, symbol-keyed rows to nest
+        # @param fields [Array<Symbol>] the `group_by` fields, in declared order
+        # @return [Hash] one level of nesting per field, in order; the leaf under
+        #   each key path is the first row in that group with every grouped field
+        #   stripped
         def nest_rows(rows, fields)
           field, *rest = fields
           rows.group_by { |row| row[field] }.transform_values do |group|
@@ -305,6 +338,16 @@ module Hecks
         # finds the matching attribute, then narrowed by the report's own
         # `where` clauses via the same `InMemory.holds?` the interpreter's
         # `execute` calls.
+        # @param bluebook [Bluebook::Chapter] the bluebook the report belongs to
+        # @param instances [Hash] the snapshot to read rows from (`history[:instances]`
+        #   shape, or the query's own `instances_at`)
+        # @param domain [String] the domain name the reduced aggregate belongs to
+        # @param model [Bluebook::ReadModel] the report being recomputed
+        # @param reduced_head [Hash] the many-side aggregate head being reduced, from
+        #   `model.aggregate_heads`
+        # @param args [Hash] the query's own arguments, for FK matching and `where`
+        #   evaluation
+        # @return [Array<Hash>] every eligible row's own state, `id:` merged in
         def eligible_rows(bluebook, instances, domain, model, reduced_head, args)
           aggregate = bluebook.aggregate(reduced_head[:aggregate])
           prefix = "#{domain}::#{reduced_head[:aggregate]}#"
@@ -337,6 +380,11 @@ module Hecks
         # → the average of the two middle values, as a Float; empty → nil,
         # never zero, so a caller cannot mistake "nothing to average" for
         # "averaged to zero."
+        # @param rows [Array<Hash>] eligible rows, as returned by `#eligible_rows`
+        # @param field [Symbol] the field to average
+        # @return [Object, Float, nil] the true middle value for an odd count, the
+        #   Float average of the two middle values for an even count, or `nil` for
+        #   an empty `rows`
         def recompute_median(rows, field)
           values = rows.map { |state| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, field)) }
                        .compact.sort

data/lib/hecks/fuzzing/properties/lifecycle_and_replay.rb

@@ -22,6 +22,10 @@ module Hecks
         # a coercion bug, a stale string surviving a rename, a default
         # that drifted from the declared set, would all show up here as a
         # value nothing upstream would have predicted.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every instance's lifecycle field holds a declared
+        #   state; otherwise a semicolon-joined message naming each offending instance
         def lifecycle_values_are_declared(history)
           bluebook = history.fetch(:bluebook)
           declared = {}
@@ -54,6 +58,11 @@ module Hecks
         # handler names would mean the runtime moved state the language
         # never authorized — the same trust ModelCheck's static reachability
         # rests on, checked here against what a run actually did.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every logged advance matches a declared
+        #   handler edge; otherwise a message naming the process manager and pair
+        #   that does not
         def saga_advances_follow_declared_handlers(history)
           bluebook = history.fetch(:bluebook)
           edges = Hash.new { |h, k| h[k] = [] }
@@ -86,6 +95,15 @@ module Hecks
         # comparison depended on, anything. Two independent replays, not a
         # cached one compared to itself, so a bug that corrupts the first
         # run's own bookkeeping cannot pass by agreeing with itself.
+        #
+        # @param domain_path [String] path to the domain directory to boot, such as
+        #   `"examples/pizzas"`
+        # @param steps [Array<Hash>] the step list to replay twice
+        # @param adapter [Symbol] persistence adapter to boot with (`:memory`,
+        #   `:postgres`, or `:postgres_era`)
+        # @return [true, String] true if both replays produce identical histories
+        #   (after stripping declared nondeterministic fields); otherwise a message
+        #   naming the step count that diverged
         def replay_is_deterministic(domain_path, steps, adapter: :memory)
           first  = Replay.call(domain_path, steps, adapter: adapter)
           second = Replay.call(domain_path, steps, adapter: adapter)

data/lib/hecks/fuzzing/properties/outbox.rb

@@ -10,6 +10,8 @@ module Hecks
       # capture, one entry per step whose dispatch enqueued at least one
       # row):
       #
+      # ## The two checks
+      #
       #   1. "delivery is inline by default" — a row this replay's own
       #      dispatch enqueued must not still be `pending`/`claimed` once
       #      that same call returns (nothing here ever simulates a
@@ -38,10 +40,9 @@ module Hecks
       #      it should have dispatched to) is `fanout_dispatches_once_
       #      per_matching_row`'s job, not this one's.
       #
-      # A `saga:` row has no equivalent second check, deliberately — this
-      # was the first shape this property shipped with, and it was wrong,
-      # caught live against `examples/banking` before this comment
-      # existed: `Fanout.sagas`' own `listens?` (starts_on/ends_on/
+      # ## Why a `saga:` row is exempt from check 2
+      #
+      # Deliberately: `Fanout.sagas`' own `listens?` (starts_on/ends_on/
       # handler_for matching the event name alone) says nothing about
       # whether a correlation resolves or a live instance exists, and
       # `begin_saga`/`end_saga` (saga_interpreter.rb) both have silent,
@@ -57,11 +58,18 @@ module Hecks
       # `saga_log` entries is therefore not a finding — only check 1
       # applies to it.
       #
-      # **Not a grammar construct** — `FEATURE_COVERAGE`'s own `dry_runs_
-      # leave_no_trace` precedent: the outbox is a runtime door
-      # (`Runtime::Outbox`), not a word a bluebook declares, so there is
-      # no feature string here to claim.
+      # ## Not a grammar construct
+      #
+      # `FEATURE_COVERAGE`'s own `dry_runs_leave_no_trace` precedent: the
+      # outbox is a runtime door (`Runtime::Outbox`), not a word a
+      # bluebook declares, so there is no feature string here to claim.
       module Outbox
+        # Checks every outbox row a replay's history recorded against the
+        # outbox's own contract (see this file's own header).
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every outbox row satisfies the contract; otherwise
+        #   a semicolon-joined message naming each offending row
         def outbox_rows_match_reactions(history)
           bluebooks = history.fetch(:bluebooks, {})
 
@@ -72,6 +80,17 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
+        # Checks one outbox row against the outbox's own contract.
+        #
+        # @param row [Hash] one `Runtime::Outbox::Row#to_h` entry, `trace[:rows]`'s shape:
+        #   at least `:status`, `:delivery_id`, `:consumer`, `:event`, and (when failed)
+        #   `:error`
+        # @param trace [Hash] this row's outbox trace entry, one of `history[:outbox_traces]`,
+        #   carrying `:rows` and `:reactions`
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @return [Array<String>] zero or one offending message naming what this row got
+        #   wrong; empty when the row is fine or its status names no check
         def outbox_row_offenders(row, trace, bluebooks)
           on = row.dig(:event, :name)
 
@@ -90,9 +109,20 @@ module Hecks
           end
         end
 
+        # Checks one delivered `policy:` outbox row for a missing `reaction_log` entry.
+        #
         # See this file's own header for why a `saga:` row is exempt: its
         # own `listens?` gives no such guarantee, unlike a policy's single,
         # deterministic `where` gate.
+        #
+        # @param row [Hash] the delivered outbox row being checked
+        # @param on [String] the row's event name, `row.dig(:event, :name)`
+        # @param trace [Hash] this row's outbox trace entry, carrying `:reactions`
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @return [Array<String>] zero or one offending message; empty when the row is
+        #   not a policy row, the policy is undeclared or fans out, or the policy's
+        #   `where` does not independently re-evaluate true
         def outbox_delivered_policy_offenders(row, on, trace, bluebooks)
           kind, fqn = row[:consumer].to_s.split(":", 2)
           return [] unless kind == "policy"
@@ -101,11 +131,14 @@ module Hecks
           return [] if trace[:reactions].any? { |entry| entry[:policy] == name && entry[:on] == on }
 
           policy = bluebooks[home]&.policies&.find { |candidate| candidate.name == name }
-          return [] unless policy # nothing declared under this name — inconclusive, not a claimed mismatch
-          return [] if policy.fans_out? # fan-out row count is fanout_dispatches_once_per_matching_row's job
+          # Nothing declared under this name — inconclusive, not a claimed mismatch.
+          return [] unless policy
+          # Fan-out row count is fanout_dispatches_once_per_matching_row's job.
+          return [] if policy.fans_out?
 
           held = independently_re_evaluate_policy_where(policy, row[:event])
-          return [] if held != true # false, or inconclusive (the where itself raised) — never a claimed mismatch
+          # False, or inconclusive (the where itself raised) — never a claimed mismatch.
+          return [] if held != true
 
           ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) drained as delivered, but no matching " \
            "reaction_log entry exists and the policy's own where clause independently re-evaluates true — " \
@@ -128,6 +161,11 @@ module Hecks
         # claimed pass or a claimed mismatch from a resolution this replay
         # cannot actually reproduce" discipline `build_guard_check`'s own
         # rescue clause already follows.
+        #
+        # @param policy [Bluebook::Policy] the policy whose `where` clause is re-evaluated
+        # @param event [Hash] the outbox row's own recorded event, read for `:payload`
+        # @return [Boolean, nil] whether `policy`'s `where` holds against `event`'s payload,
+        #   or nil if the where clause cannot be re-evaluated from it
         def independently_re_evaluate_policy_where(policy, event)
           return true if policy.where.to_s.empty?
 

data/lib/hecks/fuzzing/properties/querying.rb

@@ -21,20 +21,24 @@ module Hecks
         # drifted before — an adapter that accepts what the reference says
         # matches nothing, or orders what it refuses to order, shows up
         # here as a finding no self-referential adapter spec could see.
-        # M23 — `Replay` now runs the native and reference engines
-        # independently (each in its own begin/rescue — see that file's own
-        # comment at the capture site), so this property can tell apart what
-        # used to be indistinguishable: "both engines refused" (fine — the
-        # ask was genuinely bad, nothing to compare) from "one refused and
-        # the other did not" (a real divergence — the two engines disagree
-        # about whether the ask was even valid, never mind what it answers).
-        # `native_refused`/`reference_refused` are read by key presence, not
-        # truthiness — `Replay` only ever adds `:error`/`:reference_error`
-        # to an entry when that side actually raised, so an absent key is an
-        # unambiguous "this side answered." A read-model ask (no reference
-        # twin attempted at all, `asked[:query]` without "::") is skipped
-        # entirely, same as always — there is no second engine to disagree
-        # with.
+        # M23 — `Replay` runs the native and reference engines independently
+        # (each in its own begin/rescue — see that file's own comment at the
+        # capture site), so this property can tell apart "both engines
+        # refused" (fine — the ask was genuinely bad, nothing to compare)
+        # from "one refused and the other did not" (a real divergence — the
+        # two engines disagree about whether the ask was even valid, never
+        # mind what it answers). `native_refused`/`reference_refused` are
+        # read by key presence, not truthiness — `Replay` only ever adds
+        # `:error`/`:reference_error` to an entry when that side actually
+        # raised, so an absent key is an unambiguous "this side answered." A
+        # read-model ask (no reference twin attempted at all, `asked[:query]`
+        # without "::") is skipped entirely, same as always — there is no
+        # second engine to disagree with.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every native/reference query answer, and every
+        #   refusal of one, agrees; otherwise a message naming the offending query, its
+        #   args, and how the two engines disagreed
         def query_answers_match_reference(history)
           offenders = history.fetch(:queries).filter_map do |asked|
             next unless asked[:query].is_a?(String) && asked[:query].include?("::")
@@ -83,6 +87,11 @@ module Hecks
         # `skipped`/`expected` across method boundaries as params/returns
         # for a sequence that's only ever computed once, in this order.
         # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every paged query's real answer matches an
+        #   independent order/offset/limit recomputation over its eligible rows;
+        #   otherwise a message naming the query, its args, and the two answers
         def paging_offset_partitions_correctly(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -119,6 +128,13 @@ module Hecks
         # corpus site yet, and the "one many-side head, one aggregate,
         # no FK-join" shape #query_eligible_rows assumes doesn't hold for
         # one.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @param verb [String] the asked verb, `"Domain::Aggregate.Query"`
+        # @return [Bluebook::Query, nil] the declared query, or nil if `verb` names an
+        #   entity-level query path, or a domain, aggregate, or query not found among
+        #   `bluebooks`
         def query_for_verb(bluebooks, verb)
           domain, aggregate_name, query_path = Naming.split_verb(verb)
           return nil unless query_path && !query_path.include?(".")
@@ -128,6 +144,9 @@ module Hecks
           aggregate&.query(query_path)
         end
 
+        # Independently recomputes which of an aggregate's own stored rows a
+        # query's `wheres` admit.
+        #
         # A query's own rows — unlike #eligible_rows (a ReadModel's
         # reduced/grouped many-side head, possibly FK-joined against a
         # root), a Query always asks about its own owning aggregate
@@ -149,6 +168,18 @@ module Hecks
         # nil, and declared every genuinely-eligible row ineligible — a
         # false property violation against a correct runtime answer,
         # reproducible on an untouched main with this same 4-step script.
+        #
+        # @param instances [Hash{String => Hash}] `history[:instances]`, or an
+        #   `:instances_at` snapshot from a replayed query entry
+        # @param domain [String] the domain name the target aggregate belongs to
+        # @param aggregate_name [String] the target aggregate's own declared name
+        # @param wheres [Array<QuerySpecification::Common::WhereClause>] the clauses
+        #   every returned row must satisfy
+        # @param args [Hash] the query's own call args, for a clause whose value is a
+        #   Symbol naming one
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain, keyed
+        #   by domain name; needed only to resolve a `/` hop clause
+        # @return [Array<Hash>] each admitted row's own state, merged with its `id:`
         def query_eligible_rows(instances, domain, aggregate_name, wheres, args, bluebooks: {})
           aggregate = bluebooks[domain]&.aggregate(aggregate_name)
           prefix = "#{domain}::#{aggregate_name}#"
@@ -166,6 +197,9 @@ module Hecks
           end
         end
 
+        # Resolves one hop of a `/`-chained clause into a local `in` clause against
+        # the target aggregate's own ids.
+        #
         # `Runtime::ReferenceHop#fold`, independently restated over the
         # replay's own `:instances_at` snapshot instead of live
         # repositories — the same shape every other recompute in this
@@ -180,6 +214,20 @@ module Hecks
         # live fold builds. A clause with no `/`, or one whose head this
         # aggregate's declarations cannot resolve, passes through
         # untouched and evaluates locally as it always did.
+        #
+        # @param instances [Hash{String => Hash}] `history[:instances]`, or an
+        #   `:instances_at` snapshot from a replayed query entry
+        # @param domain [String] the domain name `aggregate` belongs to
+        # @param aggregate [Bluebook::Aggregate, nil] the aggregate `clause` is
+        #   evaluated against; nil skips hop resolution entirely
+        # @param clause [QuerySpecification::Common::WhereClause] the clause to resolve
+        # @param args [Hash] the query's own call args, passed through to the inner
+        #   hop's own `query_eligible_rows` recursion
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain, keyed
+        #   by domain name
+        # @return [QuerySpecification::Common::WhereClause] `clause` unchanged if it has
+        #   no resolvable hop head; otherwise a local `in` clause over the matching
+        #   target ids
         def resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
           return clause unless aggregate && QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
 
@@ -194,9 +242,15 @@ module Hecks
           QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
         end
 
+        # Resolves a declared limit/offset value against the query's own call args.
+        #
         # `QueryInterpreter#resolve_query_value`, reproduced: a declared
         # limit/offset is either a literal or a Symbol naming an argument
         # the caller supplied.
+        #
+        # @param value [Integer, Symbol] the declared limit/offset value
+        # @param args [Hash] the query's own call args
+        # @return [Object] `value` unchanged if not a Symbol; otherwise `args[value]`
         def resolve_paging_value(value, args)
           value.is_a?(Symbol) ? args[value] : value
         end

data/lib/hecks/fuzzing/properties.rb

@@ -22,11 +22,15 @@ module Hecks
     # any history a valid domain produces, independent of which seed
     # produced it.
     #
+    # ## Property shape
+    #
     # Each property is `name => ->(history) { true/false, or a message
     # string naming what broke }` — a truthy return (including `true`)
     # is a pass; a String return is a failure, and the string is the
     # finding. `history` is Replay's return shape.
     #
+    # ## Feature coverage
+    #
     # Every property declares the language feature it covers, in
     # `FEATURE_COVERAGE` below — a "Construct#attribute" pair spelled
     # exactly as `Bluebook::MetaValidator.grammar_registry` names it,
@@ -161,18 +165,19 @@ module Hecks
       # Not a place to hide a real gap — a feature belongs here only once
       # the specific enforcing code path has been read and confirmed, the
       # same discipline `spec/fuzzing/meta_domain_coverage_spec.rb` demands
-      # of `KNOWN_GAPS` in the other direction. `Entity#identified_by` was
-      # checked for this category once before and found not to qualify —
-      # `command_interpreter.rb`'s `AlreadyExists` refusal was given to
-      # every creating aggregate command uniformly, and MutationApplier
-      # (command_interpreter/mutation_applier.rb) had no matching check on
-      # an entity's own append. It does now: #check_entity_collision runs
-      # unconditionally on both branches an entity identity can arrive by
-      # (caller-supplied, or composite — the two the auto-mint branch
-      # doesn't cover), the same way command_interpreter#hydrate's own
-      # check is unconditional for every creating aggregate command. Real,
-      # confirmed live before the fix (SafeDepositBox's Visit/KeyIssuance —
-      # see spec/runtime/safe_deposit_box_spec.rb).
+      # of `KNOWN_GAPS` in the other direction. `Entity#identified_by`
+      # illustrates the discipline: `command_interpreter.rb`'s
+      # `AlreadyExists` refusal covers every creating aggregate command
+      # uniformly, but nothing else on its own covers an entity's own
+      # append — so this entry names the path that actually does,
+      # `MutationApplier#check_entity_collision` (command_interpreter/
+      # mutation_applier.rb), which runs unconditionally on both branches
+      # an entity identity can arrive by (caller-supplied, or composite —
+      # the two the auto-mint branch doesn't cover), the same way
+      # `command_interpreter#hydrate`'s own check is unconditional for
+      # every creating aggregate command. The collision this closes is
+      # real, not hypothetical: SafeDepositBox's Visit/KeyIssuance entities
+      # reproduce it, confirmed by spec/runtime/safe_deposit_box_spec.rb.
       GUARANTEED_BY_CONSTRUCTION = {
         "Aggregate#attributes"    => "every field's pattern/closed-set/type passes through Value.build's one coercion " \
                                      "door (value/coercion.rb#check_patterns, value/admission.rb) before it can exist " \
@@ -230,9 +235,13 @@ module Hecks
         "Member#pairs"            => "one level into ValueObject#rows — same door"
       }.freeze
 
-      # The standard battery, run over one replayed history — everything
-      # except determinism, which needs to replay twice itself and so
-      # takes the steps directly rather than a single history.
+      # Runs the standard property battery over one replayed history —
+      # everything except determinism, which needs to replay twice itself
+      # and so takes the steps directly rather than a single history.
+      #
+      # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+      # @return [Hash{Symbol => true, String}] each property name mapped to `true`
+      #   (passed) or a message string naming what broke
       def check(history)
         { lifecycle_values_are_declared:                    lifecycle_values_are_declared(history),
           saga_advances_follow_declared_handlers:           saga_advances_follow_declared_handlers(history),

data/lib/hecks/fuzzing/qa_settings.rb

@@ -83,6 +83,13 @@ module Hecks
       DEFAULT_PATH = File.expand_path("../../../qa/settings.yml", __dir__)
 
       class << self
+        # Loads and validates `qa/settings.yml` (or `path`), returning a frozen instance.
+        #
+        # @param path [String] path to the YAML settings file; defaults to `DEFAULT_PATH`
+        # @return [Hecks::Fuzzing::QaSettings] the validated, frozen settings
+        # @raise [ArgumentError] if `path` does not exist, is not valid YAML, is not a
+        #   YAML mapping at the top level, is missing a required key, declares an
+        #   unknown key, or gives a value the wrong type for its dial
         def load(path = DEFAULT_PATH)
           raise ArgumentError, "qa settings file not found: #{path}" unless File.file?(path)
 
@@ -97,6 +104,11 @@ module Hecks
         end
       end
 
+      # @param raw [Hash] parsed YAML settings keyed by symbol, one entry per dial in
+      #   `EXPECTED_TYPES`
+      # @param path [String] path to the settings file, used only in error messages
+      # @raise [ArgumentError] if `raw` is missing a required key, declares an unknown
+      #   key, or gives a value the wrong type for its dial
       def initialize(raw, path)
         missing = EXPECTED_TYPES.keys - raw.keys
         raise ArgumentError, "#{path} is missing #{missing.sort.join(', ')}" if missing.any?