hecks 1.3.0 → 1.5.0

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

@@ -1,11 +1,11 @@
 module Hecks
   module Fuzzing
     module Properties
-      # A DRY RUN LEAVES NO TRACE — `Dispatcher#dry_run?`'s whole contract
+      # **A dry run leaves no trace** — `Dispatcher#dry_run?`'s whole contract
       # ("the command evaluated hypothetically, nothing saved or emitted,
       # no reaction"), held to the store rather than trusted: `Replay`
       # snapshots every instance and the event count on either side of
-      # each `{"dry_run": …}` step, in a SEPARATE `dry_run_traces` array
+      # each `{"dry_run": …}` step, in a separate `dry_run_traces` array
       # (same order as `history[:dry_runs]`, never merged into it — that
       # array stays the exact `{verb:, ok:, error?:}` shape the compiled
       # Rust binary's own `dry_run` answers, so `spec/rust_conformance_
@@ -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]
@@ -37,7 +43,7 @@ module Hecks
       # Dispatch-binding and mutation-recomputation properties: a saga/
       # policy dispatch is bound to the value its own with_spec names, and a
       # command's append/remove/multiply/clamp mutations land on the same
-      # after-state an independent recomputation of the SAME rule produces.
+      # after-state an independent recomputation of the same rule produces.
 
       # Holds dispatch_binding_fidelity and mutations_match_recompute, plus
       # the independently-written re-derivations (#resolve_dispatch_binding,
@@ -49,17 +55,17 @@ module Hecks
         # are not claimable feature strings at all — see FEATURE_COVERAGE's
         # own comment on this entry). history[:saga_dispatches]/[:policy_dispatches]
         # (Registry#saga_dispatch_log/#policy_dispatch_log — additive,
-        # Ruby-only, NEVER touching saga_log/reaction_log, the byte-for-
+        # Ruby-only, never touching saga_log/reaction_log, the byte-for-
         # byte shape spec/rust_conformance_spec.rb holds Rust to) each
-        # carry the RAW inputs a dispatch's own args were resolved from,
+        # carry the raw inputs a dispatch's own args were resolved from,
         # captured live at the moment the resolution actually ran — a
         # saga's own memory keeps changing across a run, so re-deriving
-        # from history[:saga_instances]'s FINAL memory (the only other
+        # from history[:saga_instances]'s final memory (the only other
         # place it would be visible) would grade the wrong moment,
         # lifecycle_guard_and_given_violations_are_refused's own false
         # positive one item earlier, in a different shape.
         #
-        # #resolve_dispatch_binding/#resolve_trigger_binding are SEPARATE,
+        # #resolve_dispatch_binding/#resolve_trigger_binding are separate,
         # independently-written re-derivations of SagaInterpreter#
         # dispatch_args/PolicyInterpreter#trigger_args's own resolution —
         # never calling either method again, which would only ever agree
@@ -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)
@@ -99,9 +111,14 @@ module Hecks
 
         # SagaInterpreter#dispatch_args's own 4-branch resolution,
         # reproduced independently: a literal, the correlation key itself,
-        # the CURRENT triggering event's own payload, or — the fallback —
-        # the saga's own carried memory (seeded from the STARTING event's
+        # 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
@@ -116,7 +133,12 @@ module Hecks
         # PolicyInterpreter#trigger_args's own 2-branch resolution — a
         # 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.
+        # 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
@@ -137,33 +159,86 @@ module Hecks
         #
         # `history[:mutation_traces]` (Replay's own bounded, additive
         # extension — see #build_mutation_trace's own comment) carries a
-        # per-step before/after snapshot of the ENTITY ELEMENT an
+        # per-step before/after snapshot of the entity element an
         # entity-dispatched command's own mutations acted on, materialized
         # to plain data, plus the step's own raw args — the delta
         # `aggregation_matches_recompute` never had to ask for, because
-        # count/median are pure functions of FINAL state and a mutation
+        # count/median are pure functions of final state and a mutation
         # is not (the same "captured live, not re-derived from final
         # state" lesson item 8's own saga_dispatch_log already learned).
         #
         # #recompute_append/#recompute_remove/#recompute_multiply/
-        # #recompute_clamp are SEPARATE, independently-written
-        # reproductions of MutationApplier#appended/#removed and
+        # #recompute_clamp/#recompute_set are separate, independently-
+        # written reproductions of EntityElement#appended_to_element/
+        # #removed_from_element/#apply_to_element's own `:set` branch and
         # CommandRules::Arithmetic#multiply/#clamp — never calling either
-        # again, which would only ever agree with itself. `:set`/
-        # `:increment`/`:decrement` are out of scope on purpose (the four
-        # "vendored, not yet upstream" ops this item exists for); a
-        # command mixing them with a recomputable op still gets the
-        # recomputable one checked.
+        # again, which would only ever agree with itself. Every one of
+        # these five reproduces the entity-scoped applier specifically
+        # (`EntityElement#apply_to_element`, entity_element.rb), never
+        # the aggregate-level `MutationApplier#apply` (mutation_applier.rb)
+        # — `build_mutation_trace` (replay.rb) only ever captures an
+        # entity-owned command's own mutation in the first place (that
+        # method's own `command_name&.include?(".")` guard), so there is
+        # no aggregate-level trace for this property to ever compare
+        # against `owner_for_verb`'s own comment draws the identical
+        # aggregate/owner distinction for `:append`. `:increment`/
+        # `:decrement` remain out of scope (CommandRules::Arithmetic#
+        # arithmetic's own VO-vs-scalar branching and INT64_RANGE overflow
+        # checks are a materially larger reproduction than the other five
+        # ops combined — scoped out of this pass, not forgotten; see
+        # docs/decisions/0056); a command mixing them with a recomputable
+        # op still gets the recomputable one checked.
+        #
+        # `:set` closes a real, separate gap from the other four — this is
+        # not "the fifth op of a symmetrical set." `self_consistency.rb`'s
+        # own rehydration/idempotency checks (lib/hecks/fuzzing/
+        # self_consistency.rb) can never catch a bug in `EntityElement#
+        # apply_to_element`'s `:set` branch (entity_element.rb) no matter
+        # how much they run: both the "live" state they snapshot and the
+        # "rehydrated" state they fold from `Ports::Persistence::
+        # AppendOnly`'s own journal trace back to the same single
+        # `step_apply_mutations` call (entity_interpreter.rb) — the
+        # journal holds the full POST-mutation state, not a delta (that
+        # file's own header), so a wrong `:set` result is already baked
+        # into both sides of that comparison before either one runs. A
+        # Ruby/Rust differential check is subject to the identical
+        # structural blind spot whenever Rust's own generated `:set`
+        # handling was derived from — and so shares — the same
+        # misunderstanding Ruby's implementation has. `#recompute_set`
+        # is a genuinely third computation, independent of both: it
+        # re-derives the expected value from the mutation's own declared
+        # `source` (an argument or a literal — matching `apply_to_
+        # element`'s own `resolve_source`, which unlike the aggregate-
+        # level `apply` never special-cases a `StateRef` source at all)
+        # and the step's own captured `args`, then compares against what
+        # the real dispatch actually stored — closing exactly the class
+        # of bug the self-consistency and (whenever Rust's codegen shares
+        # a ruby-derived misunderstanding) differential checks cannot see.
+        # `spec/fuzzing/mutation_set_self_correctness_spec.rb` proves this
+        # concretely: a defect planted directly in `EntityElement#apply_
+        # to_element`'s `:set` branch leaves `SelfConsistency.check`
+        # completely clean while `mutations_match_recompute` names it.
         #
         # `:unrecomputable` (never compared, never a finding) covers the
         # generator's own deliberate arg-malforming (`StepBuilder#malform`)
         # landing a non-Numeric amount/non-2-element bounds where
-        # multiply/clamp need one — the SAME shape `guard_check`'s own
+        # multiply/clamp need one — the same shape `guard_check`'s own
         # AbsentArgument false positive taught: a step whose raw material
         # doesn't fit the op's own contract is inconclusive, not a claimed
-        # mismatch.
-        RECOMPUTABLE_MUTATION_OPS = %i[append remove multiply clamp].freeze
-
+        # mismatch. `#recompute_set` returns it for the same reason,
+        # whenever `Value.for_attribute`'s own coercion door raises on the
+        # resolved raw source (malformed fuzzer input, never a real
+        # 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)
 
@@ -196,14 +271,20 @@ module Hecks
 
         # `command_for_verb`'s own root-aggregate half (Guards) —
         # re-derived independently rather than read off `entry[:domain]`/
-        # `entry[:aggregate]` (present on a REAL `build_mutation_trace`
+        # `entry[:aggregate]` (present on a real `build_mutation_trace`
         # entry, but not on every hand-built fixture this property is
         # tested against) so this works from `entry[:verb]` alone, the
         # one field every entry always carries. BUG#5's fix needs the
-        # ROOT aggregate specifically — `Value.for_attribute` resolves a
-        # value-object TYPE against the root's own namespace only, the
+        # root aggregate specifically — `Value.for_attribute` resolves a
+        # 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
@@ -211,7 +292,7 @@ module Hecks
           bluebooks[domain_name]&.aggregate(aggregate_name)
         end
 
-        # `mutation.target`'s own DECLARING construct — the root
+        # `mutation.target`'s own declaring construct — the root
         # aggregate for an aggregate-owned command (`AddSlot`'s own
         # `:slots`), or the entity a dot-shaped command belongs to
         # (`Board.AddCard`'s own `:cards`, declared on `Board`, not on
@@ -223,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
@@ -235,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
@@ -242,52 +347,136 @@ module Hecks
           when :remove   then recompute_remove(current, mutation.source, args)
           when :multiply then recompute_multiply(current, resolve_mutation_source(mutation.source, args))
           when :clamp    then recompute_clamp(current, mutation.source)
+          when :set      then recompute_set(mutation.source, args, aggregate, owner, mutation.target)
           end
         end
 
+        # `EntityElement#apply_to_element`'s own `:set` branch (entity_
+        # element.rb), reproduced independently — not `MutationApplier#
+        # apply`'s aggregate-level twin (mutation_applier.rb), a
+        # different method with a different shape: `build_mutation_trace`
+        # (replay.rb) only ever captures an entity-owned command's own
+        # mutation (`command_name&.include?(".")`, that method's own
+        # header), so `mutations_match_recompute` can only ever be
+        # checking `apply_to_element`'s branch, never `apply`'s — the
+        # same distinction `owner_for_verb`'s own comment already draws
+        # for `:append`. Confirmed by reading `apply_to_element` directly:
+        # its own `:set` branch resolves the source through `rules.
+        # resolve_source` unconditionally (no `StateRef` branch at all —
+        # unlike the aggregate-level `apply`, an entity-owned `sets` has
+        # no declared corpus site using `state(:x)` today, so this
+        # reproduces what ships, not a hypothetical), reads the
+        # attribute off `entity.attribute(mutation.target)` (the owning
+        # entity, `owner` here — `Board`, never `Workspace`), and coerces
+        # through `Value.for_attribute(aggregate, attribute, value)`
+        # (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`). 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-
+        # guaranteed door" reasoning `GUARANTEED_BY_CONSTRUCTION` states
+        # and `#coerce_recompute_append_arg` already leans on for BUG#5 —
+        # what this property exists to check is the source resolution and
+        # routing (did the right raw value, from the right source, land
+        # on the right target?), not whether `Value.for_attribute` itself
+        # coerces correctly (a separate, already-enforced concern).
+        # Rescued broadly: a `:set` mutation trace is only ever captured
+        # after a real, already-admitted dispatch (`Replay#build_
+        # mutation_trace`'s own header), so a raise here means this
+        # recomputation resolved the wrong raw material, not that the
+        # 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)
+          coerced = attribute ? Runtime::Value.for_attribute(aggregate, attribute, raw) : raw
+          Runtime::Value.materialize(coerced)
+        rescue StandardError
+          :unrecomputable
+        end
+
         # `EntityElement#appended_to_element`'s own field-mapping half,
-        # reproduced: the field map resolved the SAME two-tier way
+        # reproduced: the field map resolved the same two-tier way
         # (`MutationApplier#resolve_append_source` — a caller-supplied
         # arg, or the entity's own current field), then appended. (An
-        # entity-dispatched command's own mutations DO reach here —
+        # entity-dispatched command's own mutations do reach here —
         # `#build_mutation_trace`'s own comment describing them as never
         # reaching "the entity_element branch" means `MutationApplier#
-        # appended`'s own AGGREGATE-level entity_element fallback
+        # appended`'s own aggregate-level entity_element fallback
         # specifically, which really is unreached from here; entity-owned
         # append dispatches go through `EntityElement#appended_to_element`
-        # instead, and DO reach this method.)
+        # instead, and do reach this method.)
         #
         # BUG#5 — an entity-owned `:append` whose target field is itself
         # value-object-typed (`Board.AddCard`'s own `sets :cards, append:
         # { sequence: :sequence }`, `CardSequence`-typed). A caller-
-        # supplied arg reaches the REAL applier (`EntityElement#
+        # supplied arg reaches the real applier (`EntityElement#
         # appended_to_element`) already coerced: `Interpreting#
         # coerce_declared_arguments` runs `Value.for_attribute` over
-        # EVERY arg the acting command itself declares, BEFORE dispatch
+        # every arg the acting command itself declares, before dispatch
         # ever reaches a mutation applier at all — independent of, and
         # earlier than, anything `appended_to_element`'s own value_object
-        # check does. `before_scope[source]` (the entity's OWN current
+        # check does. `before_scope[source]` (the entity's own current
         # field) needs no such re-coercion here: it's already the
-        # MATERIALIZED shape `build_mutation_trace` snapshotted it in
+        # materialized shape `build_mutation_trace` snapshotted it in
         # (`Value.materialize`, same as `entry[:after]`), not a raw value
         # sitting behind a live `Value`.
         #
-        # BUG#12 — `owner`/`target` (new here) let this ALSO reproduce
+        # BUG#12 — `owner`/`target` (new here) let this also reproduce
         # `EntityElement#fill_declared_defaults`'s own entity-nested-in-
         # entity fallback (`appended_to_element`'s `else` branch, when
         # the appended element is itself an entity — `Card`, nested
         # inside `Board` — not a value object): `owner.attribute(target)
         # &.type` names the appended element's own type; when that names
         # an entity of `aggregate` rather than a value object, every one
-        # of ITS OWN declared attributes `fields` doesn't already hold
+        # of its own declared attributes `fields` doesn't already hold
         # gets `Instance.default_for`'s own default — reused, not
         # reimplemented, for the identical "never agree with itself"
         # reason BUG#5's own coercion re-derivation above already gives:
         # `Instance.default_for` is pre-existing, independently-tested
         # machinery (an ordinary aggregate's own creation already runs
-        # through it via `Instance.defaults`), not the NEW glue
+        # 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)
@@ -305,11 +494,22 @@ module Hecks
         # isn't an entity nested directly under `owner` (a value object,
         # or nothing declared at all — `owner.attribute` answering `nil`
         # for a target the DSL itself would already have refused at
-        # build time). `owner.entities`, NOT `aggregate.entities` — a
-        # piece nested inside a piece is a child of the OWNING entity
+        # build time). `owner.entities`, not `aggregate.entities` — a
+        # piece nested inside a piece is a child of the owning entity
         # (`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
 
@@ -325,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)
@@ -335,8 +547,8 @@ module Hecks
         # `Interpreting#coerce_declared_arguments`'s own coercion,
         # reproduced independently (never calling it again, the same
         # "never agree with itself" rule this whole module's header
-        # comment gives) — a raw arg is coerced ONLY when its own name
-        # (`source`) is one of the ACTING COMMAND's own declared
+        # comment gives) — a raw arg is coerced only when its own name
+        # (`source`) is one of the acting command's own declared
         # attributes, exactly the condition that method checks before a
         # real dispatch ever coerces it either. `command.attribute(source)`
         # answering `nil` (a source that names no declared attribute —
@@ -350,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
@@ -358,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 }
@@ -367,9 +595,15 @@ module Hecks
         # reproduced on plain materialized data instead of a real Value:
         # a single-numeric-field Hash (the VO-typed case — ListCount, one
         # Integer field) scales that field ; a bare Numeric scales itself.
-        # `current ||= 0` — the SAME phantom-field fallback #multiply
+        # `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)
 
@@ -387,12 +621,18 @@ module Hecks
         end
 
         # `CommandRules::Arithmetic#clamp`'s own two branches, reproduced
-        # the same way #recompute_multiply is — including THIS SESSION'S
-        # OWN `current ||= 0` fix (command_rules/arithmetic.rb), the one
+        # the same way #recompute_multiply is — including this session's
+        # own `current ||= 0` fix (command_rules/arithmetic.rb), the one
         # arithmetic op that didn't have it until now. `mutation.source`
         # 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
 
@@ -411,21 +651,30 @@ module Hecks
         end
 
         # `CommandRules::Arithmetic#resolve_source`, reproduced: a
-        # mutation's source is either the NAME OF AN ARGUMENT or a
-        # LITERAL, told apart by type.
+        # 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
 
-        # A generated step's own `args` arrive with STRING keys on every
+        # A generated step's own `args` arrive with string keys on every
         # nested Hash (the wire/JSON shape `spec/corpus/*.json` already
         # uses) while `history[:mutation_traces]`' own materialized
-        # before/after state carries SYMBOL keys throughout (Runtime::
+        # before/after state carries symbol keys throughout (Runtime::
         # Value.materialize's own convention) — two hashes holding the
-        # identical fact compare UNEQUAL by Ruby's own `Hash#==` unless
+        # identical fact compare unequal by Ruby's own `Hash#==` unless
         # 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)] }