hecks 1.4.0 → 1.5.1

data/lib/hecks/fuzzing/persistence_parity.rb

@@ -4,7 +4,9 @@ require_relative "nondeterministic"
 
 module Hecks
   module Fuzzing
-    # **The second differential axis** — bin/qa_sweep's own `diff_ruby_vs_rust`
+    # ## The second differential axis
+    #
+    # bin/qa_sweep's own `diff_ruby_vs_rust`
     # compares two different engines (the Ruby interpreter vs the compiled
     # Rust kernel) against the same persistence (Memory, always — see
     # `SequenceGenerator`'s own header: sequence generation stays
@@ -27,6 +29,8 @@ module Hecks
     # Memory, unconditionally, no matter what `directory.world` itself
     # declares.
     #
+    # ## A separate axis, not a replacement
+    #
     # Not a replacement for `bin/qa_sweep`'s own Ruby-vs-Rust differential
     # mode — a genuinely separate axis, opt-in (`--persistence-parity`),
     # because this one pays for a real `PG.connect` and real SQL per
@@ -34,7 +38,9 @@ module Hecks
     # own `--persistence-parity` handling for the seed-count dial that
     # keeps that cost bounded.
     #
-    # Generalized to `left:`/`right:` — originally hardcoded to Memory vs
+    # ## `left:`/`right:`
+    #
+    # Generalized — originally hardcoded to Memory vs
     # PostgresEra (the only pairing that existed), now any two of
     # `IsolatedBoot`'s own adapter symbols (`:memory`, `:sqlite`,
     # `:postgres`, `:postgres_era`). Defaults preserve the original
@@ -49,7 +55,9 @@ module Hecks
     # loop instead of needing a deferred wave of its own the way
     # PostgresEra does.
     #
-    # `database:`/`schema:` — required only when `:postgres_era` is one of
+    # ## `database:`/`schema:`
+    #
+    # Required only when `:postgres_era` is one of
     # the two adapters (the caller — today, only `bin/qa_sweep` — owns the
     # disposable database's whole lifecycle: created before the sweep,
     # dropped after — see that script's own comment, and the discipline
@@ -81,6 +89,21 @@ module Hecks
       # sides identically (a `Runtime::Value`, a `Symbol` key, a `Time`
       # nobody asked for — none of that survives an accidental leak into
       # this comparison unnoticed).
+      #
+      # @param domain_path [String] path to the domain directory to boot
+      # @param steps [Array<Hash>] the step list to replay against both adapters
+      # @param left [Symbol] the first adapter to replay against, one of
+      #   `IsolatedBoot`'s adapter symbols (`:memory`, `:sqlite`, `:postgres`,
+      #   `:postgres_era`)
+      # @param right [Symbol] the second adapter to replay against, same set as `left`
+      # @param database [String, nil] connection identity for `:postgres_era`; required
+      #   when `left` or `right` is `:postgres_era`, ignored otherwise
+      # @param schema [String, nil] disposable schema name for `:postgres_era`; required
+      #   when `left` or `right` is `:postgres_era`, ignored otherwise
+      # @return [Array<Hash>] divergence entries, each `{field: String, left => Object,
+      #   right => Object}` — `left`'s and `right`'s own adapter symbols become the
+      #   entry's own keys, holding each side's JSON-shaped value for that field; empty
+      #   if both sides agree on every field
       def diff(domain_path, steps, left: :memory, right: :postgres_era, database: nil, schema: nil)
         left_result  = Replay.call(domain_path, steps, adapter: left, database: database, schema: schema)
         right_result = Replay.call(domain_path, steps, adapter: right, database: database, schema: schema)
@@ -95,8 +118,25 @@ module Hecks
         divergences
       end
 
+      # Round-trips `value` through JSON, the same wire-precision reduction
+      # `diff_ruby_vs_rust` uses so `Hash#==`/`Array#==` compares plain,
+      # JSON-shaped data on both sides.
+      #
+      # @param value [Object] any JSON-serializable value from a replay result
+      # @return [Object] `value`, JSON-round-tripped: Symbol keys become Strings,
+      #   and any non-JSON-native value surfaces as its own JSON form
       def as_json(value) = JSON.parse(JSON.generate(value))
 
+      # Compares both sides' stored instances.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "instances", left => Object, right => Object}`
+      #   entry if the two sides' JSON-shaped instances differ; empty otherwise
       def diff_instances(left_result, right_result, left, right)
         l = as_json(left_result[:instances])
         r = as_json(right_result[:instances])
@@ -105,6 +145,16 @@ module Hecks
         [{ field: "instances", left => l, right => r }]
       end
 
+      # Compares both sides' emitted events.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "events", left => Object, right => Object}`
+      #   entry if the two sides' JSON-shaped events differ; empty otherwise
       def diff_events(left_result, right_result, left, right)
         l = as_json(left_result[:events])
         r = as_json(right_result[:events])
@@ -113,11 +163,22 @@ module Hecks
         [{ field: "events", left => l, right => r }]
       end
 
+      # Compares both sides' refusals.
+      #
       # `verb:`/`kind:` normalized to plain strings the same way
       # `diff_ruby_vs_rust`'s own `ruby_refusals` mapping does — both
       # sides here already answer strings (`Replay#refusal_kind` always
       # returns one), so this is belt-and-suspenders consistency with the
       # sibling mode's own shape, not a real coercion.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "refusals", left => Object, right => Object}`
+      #   entry if the two sides' normalized refusals differ; empty otherwise
       def diff_refusals(left_result, right_result, left, right)
         normalize = lambda do |refusals|
           refusals.map { |r| { "verb" => r[:verb].to_s, "kind" => r[:kind].to_s, "error" => r[:error] } }
@@ -129,9 +190,20 @@ module Hecks
         [{ field: "refusals", left => l, right => r }]
       end
 
+      # Compares both sides' query answers.
+      #
       # `Nondeterministic`'s `query_row` group dropped from every entry —
       # the same group `Differential.diff` drops, for the reason declared
       # there (already covered by `diff_instances` above).
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "queries", left => Object, right => Object}`
+      #   entry if the two sides' stripped, JSON-shaped queries differ; empty otherwise
       def diff_queries(left_result, right_result, left, right)
         strip = ->(rows) { rows.map { |row| Nondeterministic.strip(row, :query_row) } }
         l = as_json(strip.call(left_result[:queries]))
@@ -141,6 +213,16 @@ module Hecks
         [{ field: "queries", left => l, right => r }]
       end
 
+      # Compares both sides' saga logs.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "sagas", left => Object, right => Object}`
+      #   entry if the two sides' JSON-shaped sagas differ; empty otherwise
       def diff_sagas(left_result, right_result, left, right)
         l = as_json(left_result[:sagas])
         r = as_json(right_result[:sagas])
@@ -149,6 +231,16 @@ module Hecks
         [{ field: "sagas", left => l, right => r }]
       end
 
+      # Compares both sides' reaction logs.
+      #
+      # @param left_result [Hash] `left`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param right_result [Hash] `right`'s replay result, as returned by `Fuzzing::Replay.call`
+      # @param left [Symbol] the adapter `left_result` was replayed against; becomes
+      #   this entry's own key
+      # @param right [Symbol] the adapter `right_result` was replayed against; becomes
+      #   this entry's own key
+      # @return [Array<Hash>] one `{field: "reactions", left => Object, right => Object}`
+      #   entry if the two sides' JSON-shaped reactions differ; empty otherwise
       def diff_reactions(left_result, right_result, left, right)
         l = as_json(left_result[:reactions])
         r = as_json(right_result[:reactions])

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

@@ -45,6 +45,11 @@ module Hecks
         # mutation is invisible to both doors today — this property is the
         # only thing anywhere, on either engine, that would ever catch one
         # going wrong.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every event emitted by a `corrects`-bearing
+        #   command has a matching, strictly earlier corrected event in the same
+        #   history; otherwise a message listing every unmatched correction
         def corrections_reference_an_emitted_event(history)
           violations = []
 
@@ -72,6 +77,17 @@ module Hecks
           violations.empty? || violations.uniq.join("; ")
         end
 
+        # Finds every occurrence of `produced_event_name`, on `aggregate_key`, with no
+        # matching `corrected_event` for the same id appearing earlier in `events`.
+        #
+        # @param events [Array<Hash>] `history[:events]`, in occurrence order
+        # @param aggregate_key [String] `"domain::AggregateName"` the events belong to
+        # @param produced_event_name [String] name of the event a `corrects` mutation's
+        #   command emits
+        # @param corrected_event [String] name of the event the mutation claims to correct
+        # @param command_name [String] the command's own `hecks_name`, for the message
+        # @return [Array<String>] one message per occurrence with no matching earlier
+        #   corrected event; empty when every occurrence is matched
         def unmatched_corrections(events, aggregate_key, produced_event_name, corrected_event, command_name)
           own_events = events.each_with_index.select do |event, _index|
             event[:name] == produced_event_name && event[:aggregate] == aggregate_key
@@ -90,6 +106,15 @@ module Hecks
           end
         end
 
+        # Yields every command declared on `owner`, then recurses into each of its
+        # entities to yield theirs too, at any nesting depth (ADR 0026, S17).
+        #
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity] the aggregate or entity
+        #   whose own commands, and whose entities' commands, to walk
+        # @yield [command] once per declared command, aggregate-level or nested
+        # @yieldparam command [Bluebook::Command] a command declared on `owner` or one
+        #   of its entities
+        # @return [void]
         def each_command_including_entities(owner, &block)
           owner.commands.each(&block)
           owner.entities.each { |entity| each_command_including_entities(entity, &block) }

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

@@ -16,6 +16,12 @@ module Hecks
       # hand-built history, an older corpus) are skipped, not failed: no
       # claim, no finding.
       module DryRuns
+        # Checks that every dry-run step left neither the event count nor any
+        # instance's state changed.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every dry-run trace shows no change; otherwise
+        #   a semicolon-joined message naming each offending dry run
         def dry_runs_leave_no_trace(history)
           offenders = Array(history[:dry_run_traces]).filter_map do |entry|
             before = entry[:before]
@@ -67,7 +73,8 @@ module Hecks
         # argument binding on a fan-out dispatch that produces a perfectly
         # normal-looking log entry (`delivered: true`) and would only ever
         # surface as a downstream assertion failure, if it surfaces at
-        # all" — PR #325's own defect class, one level over.
+        # all" — a defect class one level over from what
+        # `fanout_dispatches_once_per_matching_row` already catches.
         #
         # Real targets: Settlement (mixed literal/correlation-head/event-
         # payload/memory-fallback bindings across three legs, plus a
@@ -75,6 +82,11 @@ module Hecks
         # the forward Credit leg carries), ExternalSettlement, Onboarding
         # (no compensation leg, by design — nothing to check there beyond
         # the forward leg's own event-payload binding).
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every saga and policy dispatch's own bound args
+        #   match an independent re-derivation of their `with_spec`; otherwise a
+        #   semicolon-joined message naming each offending dispatch
         def dispatch_binding_fidelity(history)
           saga_offenders = history.fetch(:saga_dispatches, []).filter_map do |entry|
             expected = resolve_dispatch_binding(entry)
@@ -102,6 +114,11 @@ module Hecks
         # the current triggering event's own payload, or — the fallback —
         # the saga's own carried memory (seeded from the starting event's
         # payload, at begin_saga).
+        #
+        # @param entry [Hash] one `history[:saga_dispatches]` entry: at least
+        #   `:with_spec`, `:correlation_head`, `:instance`, `:event_payload`, and `:memory`
+        # @return [Hash{Symbol => Object}] the resolved, materialized args `with_spec`
+        #   should produce, keyed by symbol
         def resolve_dispatch_binding(entry)
           entry[:with_spec].to_h do |key, value|
             resolved = if !value.is_a?(Symbol) then value
@@ -117,6 +134,11 @@ module Hecks
         # policy holds no correlation and no memory, so `payload` (the
         # triggering event's own payload, already merged with a fan-out
         # row's id when there is one) is the whole source.
+        #
+        # @param entry [Hash] one `history[:policy_dispatches]` entry: at least
+        #   `:with_spec` and `:payload`
+        # @return [Hash{Symbol => Object}] the resolved, materialized args `with_spec`
+        #   should produce, keyed by symbol
         def resolve_trigger_binding(entry)
           entry[:with_spec].to_h do |key, value|
             resolved = value.is_a?(Symbol) ? entry[:payload][value] : value
@@ -209,6 +231,14 @@ module Hecks
         # corpus shape).
         RECOMPUTABLE_MUTATION_OPS = %i[append remove multiply clamp set].freeze
 
+        # Checks that every recomputable mutation an entity-owned command
+        # applied landed on the same after-state an independent
+        # recomputation of the same rule produces.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every recomputable mutation's after-state
+        #   matches an independent recomputation; otherwise a semicolon-joined message
+        #   naming each offending mutation
         def mutations_match_recompute(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -249,6 +279,12 @@ module Hecks
         # value-object type against the root's own namespace only, the
         # same reason `EntityElement#locate_chain` threads `root_aggregate`
         # through every hop separately from each hop's own `owner`.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @param verb [String] the dispatched verb to resolve
+        # @return [Bluebook::Aggregate, nil] the root aggregate `verb`'s domain and
+        #   aggregate name, or nil if `verb` names no domain
         def aggregate_for_verb(bluebooks, verb)
           domain_name, aggregate_name, = Naming.split_verb(verb)
           return nil unless domain_name
@@ -268,6 +304,15 @@ module Hecks
         # each hop's own `owner`. Re-derived independently from
         # `entry[:verb]` alone, the same reasoning `aggregate_for_verb`'s
         # own comment gives.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @param verb [String] the dispatched verb to resolve
+        # @return [Bluebook::Aggregate, Bluebook::Entity, nil] the construct that
+        #   declares the mutation's own target: the root aggregate for an
+        #   aggregate-owned command, or the owning entity for a dot-shaped
+        #   (entity-owned) command; nil if `verb` names no command path or no
+        #   resolvable aggregate
         def owner_for_verb(bluebooks, verb)
           domain_name, aggregate_name, command_path = Naming.split_verb(verb)
           return nil unless command_path
@@ -280,6 +325,21 @@ module Hecks
           aggregate.entities.find { |candidate| candidate.hecks_name == entity_name }
         end
 
+        # Dispatches to the recompute rule for `mutation.op`.
+        #
+        # @param mutation [Bluebook::Mutation] the mutation to recompute
+        # @param current [Object] the target field's before-value, as captured in
+        #   `entry[:before]`
+        # @param args [Hash] the step's own raw args, as captured in `entry[:args]`
+        # @param before_scope [Hash] the entity element's own before-state
+        #   (`entry[:before]`), the source an append's caller-omitted field resolves against
+        # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+        #   namespace resolution
+        # @param command [Bluebook::Command] the command that declared `mutation`
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity] the construct that
+        #   declares `mutation.target`; defaults to `aggregate`
+        # @return [Object, Symbol] the recomputed after-value for `mutation.op`, or
+        #   `:unrecomputable` if the raw material doesn't fit the op's own contract
         def recompute_mutation(mutation, current, args, before_scope, aggregate, command, owner = aggregate)
           case mutation.op
           when :append
@@ -312,19 +372,16 @@ module Hecks
         # (the root aggregate, for value-object namespace resolution
         # only — `value_object_for(aggregate, attribute.type)` — the
         # same aggregate/owner split `owner_for_verb`'s own comment
-        # explains for `recompute_append`). An earlier version of this
-        # method mirrored `MutationApplier#apply`'s `:set` branch instead
-        # (StateRef-aware, coerced against `aggregate.attribute` rather
-        # than `owner.attribute`) and false-positived on every real
-        # entity-owned `sets` in the corpus — `NestedPieces::Workspace.
-        # Board.Label` (`sets :label`) has no `:label` attribute on
-        # `Workspace` at all, so `Value.for(aggregate, :label, raw)`
-        # silently passed the raw, uncoerced String through instead of
-        # wrapping it as `BoardLabel`, and the comparison below then
-        # disagreed with the real, correctly-coerced `after` state on
-        # every single run — caught immediately by running this against
-        # `qa/stress_domains/nested_pieces` before this comment existed,
-        # not by inspection alone.
+        # explains for `recompute_append`). Coercing against
+        # `owner.attribute` rather than `aggregate.attribute` matters
+        # concretely: `NestedPieces::Workspace.Board.Label` (`sets
+        # :label`) has no `:label` attribute on `Workspace` at all, so
+        # coercing against the aggregate would silently pass the raw,
+        # uncoerced String through instead of wrapping it as
+        # `BoardLabel`, and the comparison below would then disagree with
+        # the real, correctly-coerced `after` state on every single run —
+        # a real false positive, confirmed by running this against
+        # `qa/stress_domains/nested_pieces`, not by inspection alone.
         #
         # Reusing `Value.for_attribute` for the coercion step, rather
         # than re-deriving it, is the same "coercion is its own already-
@@ -341,6 +398,17 @@ module Hecks
         # real dispatch was itself malformed — `:unrecomputable`, not a
         # crash, the same discipline every other branch in this method
         # already follows for the generator's own deliberate malforming.
+        #
+        # @param source [Symbol, Object] the mutation's own declared source: an argument
+        #   name to resolve from `args`, or a literal value already
+        # @param args [Hash] the step's own raw args
+        # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+        #   namespace resolution
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity, nil] the construct that
+        #   declares `target`
+        # @param target [Symbol, nil] the mutation's own target field name
+        # @return [Object, Symbol] the recomputed, materialized value, or
+        #   `:unrecomputable` if resolving or coercing the source raises
         def recompute_set(source, args, aggregate, owner, target)
           raw = resolve_mutation_source(source, args)
           attribute = owner&.attribute(target)
@@ -393,6 +461,22 @@ module Hecks
         # through it via `Instance.defaults`), not the new glue
         # (`fill_declared_defaults` itself) this property exists to
         # catch a drift in.
+        #
+        # @param current [Object] the target field's before-value (an Array of elements)
+        # @param source_map [Hash{Symbol => Object}] the append mutation's own field map:
+        #   each appended field's name to its source (an argument name Symbol, or a literal)
+        # @param before_scope [Hash] the entity element's own before-state, the source a
+        #   caller-omitted field resolves against
+        # @param args [Hash] the step's own raw args
+        # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+        #   namespace resolution
+        # @param command [Bluebook::Command] the command that declared the mutation, for
+        #   coercing a caller-supplied arg
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity] the construct whose nested
+        #   entity `target` may declare; defaults to `aggregate`
+        # @param target [Symbol, nil] the append mutation's own target field name
+        # @return [Array] `current` (coerced to an Array) with the newly built,
+        #   symbol-keyed element appended
         def recompute_append(current, source_map, before_scope, args, aggregate, command, owner = aggregate, target = nil)
           fields = source_map.transform_values do |source|
             resolve_mutation_append_field(source, before_scope, args, aggregate, command)
@@ -415,6 +499,17 @@ module Hecks
         # (`Card` is `Board.entities`, never `Workspace.entities`), the
         # same distinction `EntityElement#appended_to_element`'s own fix
         # draws.
+        #
+        # @param aggregate [Bluebook::Aggregate] the root aggregate, forwarded to
+        #   `Instance.default_for`
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity, nil] the construct whose
+        #   nested entity `target` may declare
+        # @param target [Symbol, nil] the append mutation's own target field name
+        # @param fields [Hash{Symbol => Object}] the field map already resolved by
+        #   `recompute_append`
+        # @return [Hash{Symbol => Object}] `fields` unchanged if `target` is nil or does
+        #   not name a nested entity; otherwise `fields` with every declared attribute it
+        #   doesn't already hold filled in with its own default
         def fill_recompute_declared_defaults(aggregate, owner, target, fields)
           return fields unless target
 
@@ -430,6 +525,18 @@ module Hecks
           fields
         end
 
+        # Resolves one appended field's own value from its declared source.
+        #
+        # @param source [Symbol, Object] an append field's own source: an argument name,
+        #   or a literal value
+        # @param before_scope [Hash] the entity element's own before-state
+        # @param args [Hash] the step's own raw args
+        # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+        #   namespace resolution
+        # @param command [Bluebook::Command] the command that declared the mutation
+        # @return [Object] `before_scope[source]` if `source` names no caller-supplied
+        #   arg; `source` unchanged if it is not a Symbol; otherwise the coerced,
+        #   materialized arg value
         def resolve_mutation_append_field(source, before_scope, args, aggregate, command)
           return source unless source.is_a?(Symbol)
           return before_scope[source] unless args.key?(source)
@@ -455,6 +562,15 @@ module Hecks
         # throughout this whole property, so the eventual `symbolize_deep`
         # comparison is always materialized-against-materialized, never a
         # live `Value` against a Hash.
+        #
+        # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+        #   namespace resolution
+        # @param command [Bluebook::Command] the command whose own declared attribute
+        #   `source` may name
+        # @param source [Symbol] the argument name to coerce
+        # @param raw [Object] the raw arg value to coerce
+        # @return [Object] `raw`, coerced and materialized, if `source` names a declared
+        #   attribute of `command`; `raw` unchanged otherwise
         def coerce_recompute_append_arg(aggregate, command, source, raw)
           attribute = command.attribute(source)
           return raw unless attribute
@@ -463,6 +579,13 @@ module Hecks
         end
 
         # `MutationApplier#removed`'s own value-equality match, reproduced.
+        #
+        # @param current [Object] the target field's before-value (an Array of elements)
+        # @param source [Symbol, Object] the remove mutation's own source: an argument
+        #   name, or a literal value already
+        # @param args [Hash] the step's own raw args
+        # @return [Array] `current` (coerced to an Array) with every element matching the
+        #   resolved target value removed
         def recompute_remove(current, source, args)
           target = symbolize_deep(resolve_mutation_source(source, args))
           Array(current).reject { |element| symbolize_deep(element) == target }
@@ -475,6 +598,12 @@ module Hecks
         # `current ||= 0` — the same phantom-field fallback #multiply
         # itself already gives (unaffected by this session's #clamp fix,
         # since #multiply never needed one).
+        #
+        # @param current [Hash, Numeric, nil] the target field's before-value
+        # @param amount [Object] the resolved multiplier
+        # @return [Hash, Numeric, Symbol] the scaled field/value, or `:unrecomputable` if
+        #   `amount` is not Numeric or `current` is neither a Hash with a numeric field
+        #   nor a Numeric
         def recompute_multiply(current, amount)
           return :unrecomputable unless amount.is_a?(Numeric)
 
@@ -498,6 +627,12 @@ module Hecks
         # is always a literal `[min, max]`, never an argument reference
         # (MutationApplier's own comment on why `resolve_source` is
         # skipped for clamp) — so nothing here reads `args` for it at all.
+        #
+        # @param current [Hash, Numeric, nil] the target field's before-value
+        # @param bounds [Object] the mutation's own declared `[min, max]` literal
+        # @return [Hash, Numeric, Symbol] the clamped field/value, or `:unrecomputable`
+        #   if `bounds` is not a 2-element Array or `current` is neither a Hash with a
+        #   numeric field nor a Numeric
         def recompute_clamp(current, bounds)
           return :unrecomputable unless bounds.is_a?(Array) && bounds.size == 2
 
@@ -518,6 +653,11 @@ module Hecks
         # `CommandRules::Arithmetic#resolve_source`, reproduced: a
         # mutation's source is either the name of an argument or a
         # literal, told apart by type.
+        #
+        # @param source [Symbol, Object] an argument name to resolve from `args`, or a
+        #   literal value already
+        # @param args [Hash] the step's own raw args
+        # @return [Object] `args[source]` if `source` is a Symbol; `source` unchanged otherwise
         def resolve_mutation_source(source, args)
           source.is_a?(Symbol) ? args[source] : source
         end
@@ -531,6 +671,10 @@ module Hecks
         # both sides are normalized the same way first. Recursive, since
         # an appended/removed element can itself nest a value object
         # (RemoveTag's own `Tag` argument, `{"key"=>..., "value"=>...}`).
+        #
+        # @param value [Object] a Hash, Array, or scalar to normalize
+        # @return [Object] `value` with every Hash key symbolized, recursively through
+        #   nested Hashes and Arrays; any other value unchanged
         def symbolize_deep(value)
           case value
           when Hash  then value.to_h { |key, val| [key.to_sym, symbolize_deep(val)] }

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

@@ -54,6 +54,11 @@ module Hecks
         # branches shares logic with the others beyond that shared setup.
         # 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 tenant-scoped query answer, and every
+        #   refusal of one, agrees with `TenantScope.apply`'s own contract; otherwise a
+        #   message naming the offending query, its args, and what it should have done
         def authorize_scopes_or_refuses(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -116,6 +121,14 @@ module Hecks
         # those; the raised class does not.
         GUARD_REFUSAL_KINDS = %w[Hecks::Runtime::GivenNotMet Hecks::Runtime::EnsuresNotMet].freeze
 
+        # Checks that every given/ensures refusal a run actually raised names a rule
+        # the refusing command actually declares.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every guard refusal's quoted description matches
+        #   a `given`/`ensures` the refusing command (or its delegation target) declares;
+        #   otherwise a message naming the refusal and the declared descriptions it does
+        #   not match
         def guard_refusals_are_declared(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -190,6 +203,12 @@ module Hecks
         # false positive.
         # 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 stored record's `reference_to` attribute
+        #   points at a record sharing the same tenant value (or has no resolvable
+        #   target, or neither side declares a tenant field); otherwise a message naming
+        #   the referencing record, the reference, and the tenant mismatch
         def commands_respect_tenant_scope(history)
           bluebooks = history.fetch(:bluebooks)
           instances = history.fetch(:instances)
@@ -236,6 +255,10 @@ module Hecks
         # ..., tenant:` on any of its own queries — not every aggregate
         # is tenant-scoped, and one that isn't has nothing for this
         # property to check either side of.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to look up
+        # @return [Symbol, nil] the tenant field name, or nil if no query on the
+        #   aggregate declares `authorize ..., tenant:`
         def tenant_field_for(aggregate)
           authorization = aggregate.queries.filter_map(&:authorization).find(&:tenant)
           authorization&.tenant&.to_sym
@@ -267,6 +290,14 @@ module Hecks
         # own guards first, then every delegation target's; an offence is
         # only a description neither declares. Found live mining chess's
         # history: every refused move through a door read as undeclared.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @param verb [String] the dispatched verb, `"Domain::Aggregate.Command"` or
+        #   `"Domain::Aggregate.Entity.Command"`
+        # @param command [Bluebook::Command] the command `verb` resolves to
+        # @return [Array<String>] `command`'s own declared given/ensures descriptions,
+        #   plus every `delegate`d command's, in that order
         def effective_guard_descriptions(bluebooks, verb, command)
           own = command.guard_descriptions
           delegated = command.mutations.select { |m| m.op == :delegate }.flat_map do |delegation|
@@ -277,6 +308,14 @@ module Hecks
           own + delegated
         end
 
+        # Resolves a dispatched verb back to the declared command it names.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @param verb [String] the dispatched verb, `"Domain::Aggregate.Command"` or
+        #   `"Domain::Aggregate.Entity.Command"`
+        # @return [Bluebook::Command, nil] the declared command, or nil if `verb`'s
+        #   domain, aggregate, entity, or command is not found among `bluebooks`
         def command_for_verb(bluebooks, verb)
           domain, aggregate_name, command_path = Naming.split_verb(verb)
           return nil unless command_path
@@ -337,6 +376,11 @@ module Hecks
         # different named precondition `"customer is not closed"` instead
         # (a suspended customer must still be freezable), so it is not a
         # `"customer is active"` example, just the same mechanism.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every recomputed `enforce_givens`/
+        #   `enforce_lifecycle_guard` check agrees with what the real dispatch did;
+        #   otherwise a message naming the verb and the disagreement
         def lifecycle_guard_and_given_violations_are_refused(history)
           offenders = history.fetch(:guard_checks).filter_map do |check|
             next if check[:recomputed_refused] == check[:actual_refused]