hecks 1.2.0 → 1.4.0

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

@@ -0,0 +1,100 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Angle-9 — `corrects` (retroactive correction) had exactly one
+      # declaration anywhere in the corpus (`examples/banking/bluebook/
+      # deposit_accounts.bluebook:353`, aggregate-level) and no property
+      # anywhere in this file ever checked it, and no `FEATURE_COVERAGE`
+      # claim either — confirmed absent before this file existed. `qa/
+      # stress_domains/corrections` gives it its first real coverage; see
+      # that domain's own NOTES.md for what it found (an entity-level
+      # `corrects` crashes Ruby at dispatch outright, and Rust's own
+      # generated code has no admissibility check for it at all — neither
+      # engine can be compared on the untested combination this property
+      # was written to watch, which is itself the headline finding).
+      module Corrections
+        # Every event named by a `corrects` mutation, on any command a
+        # booted history's own bluebooks declare — aggregate-level, or
+        # nested inside an entity at any depth (`each_command_including_
+        # entities`, below, is the same recursive walk `SequenceGenerator::
+        # Catalog#each_entity_chain` already uses, for the identical reason:
+        # `Aggregate#entities`/`Entity#entities` nest, ADR 0026, S17). For
+        # every such command, every event this history actually recorded
+        # under one of the command's own `emits` names must have an event
+        # named by the command's own `corrects` target — same aggregate-
+        # qualified name, same id — appearing strictly earlier in the same
+        # history.
+        #
+        # `history[:events]` is already in occurrence order (`Replay.call`'s
+        # own `runtime.events`, appended as each step dispatches) — "earlier"
+        # is therefore "earlier in this array," no timestamp comparison
+        # needed, and no per-step attribution back to which command produced
+        # which event is needed either: an event's own declared name already
+        # identifies the one command in its aggregate that can produce it
+        # (`AggregateBuilder::Sealing#seal_correction_targets`'s own
+        # `emitted_by` hash reads the identical fact, one level shallower).
+        #
+        # Why this cannot be `GUARANTEED_BY_CONSTRUCTION` the way the
+        # aggregate-level case almost is: `CommandRules::Admissibility#
+        # enforce_correction_target` (the dispatch-time check) and
+        # `AggregateBuilder::Sealing#seal_correction_targets` (the build-time
+        # check) both exist only for an aggregate-level `corrects` —
+        # `EntityInterpreter#step_enforce_givens` never calls the former at
+        # all, and the latter walks only `@commands` (the aggregate's own
+        # top-level list), never `@entities`. An entity-level `corrects`
+        # mutation is invisible to both doors today — this property is the
+        # only thing anywhere, on either engine, that would ever catch one
+        # going wrong.
+        def corrections_reference_an_emitted_event(history)
+          violations = []
+
+          (history[:bluebooks] || {}).each do |domain, bluebook|
+            bluebook.aggregates.each do |aggregate|
+              aggregate_key = "#{domain}::#{aggregate.hecks_name}"
+
+              each_command_including_entities(aggregate) do |command|
+                corrects_mutations = command.mutations.select { |mutation| mutation.op == :corrects }
+                next if corrects_mutations.empty?
+
+                corrects_mutations.each do |mutation|
+                  corrected_event = mutation.target.to_s
+
+                  command.emits.each do |produced_event_name|
+                    violations.concat(unmatched_corrections(history[:events], aggregate_key,
+                                                            produced_event_name.to_s, corrected_event,
+                                                            command.hecks_name))
+                  end
+                end
+              end
+            end
+          end
+
+          violations.empty? || violations.uniq.join("; ")
+        end
+
+        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
+          end
+
+          own_events.filter_map do |event, index|
+            preceding = events.first(index)
+            next if preceding.any? do |earlier|
+              earlier[:name] == corrected_event && earlier[:aggregate] == aggregate_key &&
+              earlier[:id].to_s == event[:id].to_s
+            end
+
+            "#{command_name} (#{aggregate_key}##{event[:id]}) emitted #{produced_event_name}, claiming to " \
+              "correct #{corrected_event}, but no #{corrected_event} for the same aggregate/id appears " \
+              "earlier in this history"
+          end
+        end
+
+        def each_command_including_entities(owner, &block)
+          owner.commands.each(&block)
+          owner.entities.each { |entity| each_command_including_entities(entity, &block) }
+        end
+      end
+    end
+  end
+end

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

@@ -1,10 +1,43 @@
 module Hecks
   module Fuzzing
     module Properties
+      # **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
+      # (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_
+      # spec.rb`'s direct comparison against it never sees a key Rust
+      # doesn't have), and this is the comparison. Refused or accepted
+      # makes no difference — a hypothetical that was refused had even
+      # less business writing anything. Entries without the snapshots (a
+      # hand-built history, an older corpus) are skipped, not failed: no
+      # claim, no finding.
+      module DryRuns
+        def dry_runs_leave_no_trace(history)
+          offenders = Array(history[:dry_run_traces]).filter_map do |entry|
+            before = entry[:before]
+            after  = entry[:after]
+            next unless before && after
+
+            traces = []
+            traces << "events #{before[:events]} -> #{after[:events]}" unless before[:events] == after[:events]
+            traces << "instances changed" unless before[:instances] == after[:instances]
+            next if traces.empty?
+
+            "dry run of #{entry[:verb]} (ok: #{entry[:ok]}) left a trace: #{traces.join(', ')}"
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+      end
+
       # 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,
@@ -16,17 +49,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
@@ -66,8 +99,8 @@ 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).
         def resolve_dispatch_binding(entry)
           entry[:with_spec].to_h do |key, value|
@@ -83,7 +116,7 @@ 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.
         def resolve_trigger_binding(entry)
           entry[:with_spec].to_h do |key, value|
             resolved = value.is_a?(Symbol) ? entry[:payload][value] : value
@@ -104,32 +137,77 @@ 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
 
         def mutations_match_recompute(history)
           bluebooks = history.fetch(:bluebooks)
@@ -140,8 +218,14 @@ module Hecks
             command = command_for_verb(bluebooks, entry[:verb])
             next [] unless command
 
+            aggregate = aggregate_for_verb(bluebooks, entry[:verb])
+            next [] unless aggregate
+
+            owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
+
             command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }.filter_map do |mutation|
-              expected = recompute_mutation(mutation, entry[:before][mutation.target], entry[:args], entry[:before])
+              expected = recompute_mutation(mutation, entry[:before][mutation.target], entry[:args], entry[:before],
+                                            aggregate, command, owner)
               next if expected == :unrecomputable
 
               actual = entry[:after][mutation.target]
@@ -155,31 +239,227 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        def recompute_mutation(mutation, current, args, before_scope)
+        # `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, 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
+        # same reason `EntityElement#locate_chain` threads `root_aggregate`
+        # through every hop separately from each hop's own `owner`.
+        def aggregate_for_verb(bluebooks, verb)
+          domain_name, aggregate_name, = Naming.split_verb(verb)
+          return nil unless domain_name
+
+          bluebooks[domain_name]&.aggregate(aggregate_name)
+        end
+
+        # `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
+        # `Workspace`) — needed only by BUG#12's own recompute-side fix
+        # (`recompute_append`, below): `entity.attribute(mutation.target)`
+        # has to be asked of whichever construct actually declares it,
+        # never the root aggregate unconditionally, the same distinction
+        # `EntityElement#locate_chain` draws between `root_aggregate` and
+        # each hop's own `owner`. Re-derived independently from
+        # `entry[:verb]` alone, the same reasoning `aggregate_for_verb`'s
+        # own comment gives.
+        def owner_for_verb(bluebooks, verb)
+          domain_name, aggregate_name, command_path = Naming.split_verb(verb)
+          return nil unless command_path
+
+          aggregate = bluebooks[domain_name]&.aggregate(aggregate_name)
+          return nil unless aggregate
+          return aggregate unless command_path.include?(".")
+
+          entity_name, = command_path.split(".", 2)
+          aggregate.entities.find { |candidate| candidate.hecks_name == entity_name }
+        end
+
+        def recompute_mutation(mutation, current, args, before_scope, aggregate, command, owner = aggregate)
           case mutation.op
-          when :append   then recompute_append(current, mutation.source, before_scope, args)
+          when :append
+            recompute_append(current, mutation.source, before_scope, args, aggregate, command, owner, mutation.target)
           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
 
-        # `MutationApplier#appended`'s own value-object branch (never the
-        # entity_element branch — see #build_mutation_trace's own comment
-        # on why an entity-dispatched command's own mutations never reach
-        # it), reproduced: the field map resolved the SAME two-tier way
+        # `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`). 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.
+        #
+        # 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.
+        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
         # (`MutationApplier#resolve_append_source` — a caller-supplied
-        # arg, or the entity's own current field), then appended.
-        def recompute_append(current, source_map, before_scope, args)
-          fields = source_map.transform_values { |source| resolve_mutation_append_field(source, before_scope, args) }
+        # arg, or the entity's own current field), then appended. (An
+        # 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
+        # specifically, which really is unreached from here; entity-owned
+        # append dispatches go through `EntityElement#appended_to_element`
+        # 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#
+        # appended_to_element`) already coerced: `Interpreting#
+        # coerce_declared_arguments` runs `Value.for_attribute` over
+        # 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
+        # field) needs no such re-coercion here: it's already the
+        # 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
+        # `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
+        # 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
+        # (`fill_declared_defaults` itself) this property exists to
+        # catch a drift in.
+        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)
+          end
+          fill_recompute_declared_defaults(aggregate, owner, target, fields)
           Array(current) + [symbolize_deep(fields)]
         end
 
-        def resolve_mutation_append_field(source, before_scope, args)
+        # BUG#12's own recompute-side half — see `#recompute_append`'s
+        # own comment above for why this exists and why it reuses
+        # `Instance.default_for` rather than calling `EntityElement#
+        # fill_declared_defaults` again. A no-op whenever `target` names
+        # no attribute at all (every RECOMPUTABLE_MUTATION_OPS caller but
+        # `:append` passes no `target`) or `target`'s own declared type
+        # 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
+        # (`Card` is `Board.entities`, never `Workspace.entities`), the
+        # same distinction `EntityElement#appended_to_element`'s own fix
+        # draws.
+        def fill_recompute_declared_defaults(aggregate, owner, target, fields)
+          return fields unless target
+
+          element_type = owner&.attribute(target)&.type
+          entity = element_type && owner.entities.find { |piece| piece.hecks_name == element_type.to_s }
+          return fields unless entity
+
+          entity.attributes.each do |attribute|
+            next if fields.key?(attribute.name)
+
+            fields[attribute.name] = attribute.list? ? [] : Runtime::Instance.default_for(aggregate, attribute)
+          end
+          fields
+        end
+
+        def resolve_mutation_append_field(source, before_scope, args, aggregate, command)
           return source unless source.is_a?(Symbol)
-          return args[source] if args.key?(source)
+          return before_scope[source] unless args.key?(source)
+
+          coerce_recompute_append_arg(aggregate, command, source, args[source])
+        end
+
+        # `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
+        # 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 —
+        # never possible for `coerce_declared_arguments` to have touched
+        # it in the real dispatch either) leaves `raw` exactly as it
+        # arrived, the same as every bare-scalar append this already
+        # handled correctly before BUG#5's fix.
+        #
+        # `Value.materialize`d immediately after coercing — matching the
+        # plain-data shape `entry[:before]`/`entry[:after]` already carry
+        # throughout this whole property, so the eventual `symbolize_deep`
+        # comparison is always materialized-against-materialized, never a
+        # live `Value` against a Hash.
+        def coerce_recompute_append_arg(aggregate, command, source, raw)
+          attribute = command.attribute(source)
+          return raw unless attribute
 
-          before_scope[source]
+          Runtime::Value.materialize(Runtime::Value.for_attribute(aggregate, attribute, raw, argument: true))
         end
 
         # `MutationApplier#removed`'s own value-equality match, reproduced.
@@ -192,7 +472,7 @@ 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).
         def recompute_multiply(current, amount)
@@ -212,8 +492,8 @@ 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
@@ -236,18 +516,18 @@ 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.
         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"=>...}`).