hecks 3.5.0 → 3.6.0

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

@@ -1,90 +1,61 @@
+require "json"
+require_relative "aggregation_recompute"
+require_relative "group_by_recompute"
+require_relative "piece_invariants"
+
 module Hecks
   module Fuzzing
     module Properties
       # Stored-record, saga-rehydration, fan-out, and read-model-aggregation
       # properties, extended into Properties.
       module InvariantsAndAggregation
+        include AggregationRecompute
+        include GroupByRecompute
+        include PieceInvariants
+
         # Every stored record — and every entity nested inside it — still
         # satisfies its own declared invariants, re-checked independently of
         # whichever call site (Admissibility#enforce_invariants) was supposed
         # to have refused a violation live.
         def stored_records_satisfy_declared_invariants(history)
           bluebooks = history.fetch(:bluebooks)
-
-          offenders = history.fetch(:instances).filter_map do |key, state|
-            domain_name    = key.split("::").first
-            aggregate_name = key.split("::").last.split("#").first
-            bluebook       = bluebooks[domain_name]
-            aggregate      = bluebook&.aggregate(aggregate_name)
-            next unless aggregate
-
-            violated = aggregate.invariants.find do |invariant|
-              !Bluebook::Expression::Evaluator.call(invariant.canonical, state)
-            end
-            next "#{key} violates #{aggregate_name}'s own declared invariant #{violated.description.inspect}" if violated
-
-            check_piece_invariants(aggregate, state, key)
-          end
-
+          offenders = history.fetch(:instances).filter_map { |key, state| stored_record_offense(bluebooks, key, state) }
           offenders.empty? || offenders.join("; ")
         end
 
-        # A piece's own invariant, checked against every element its owner's
-        # `list_of` field holds — reapplies Admissibility#check_entity_invariants'
-        # own lookup against a plain Hash state rather than a live Instance.
-        def check_piece_invariants(owner_construct, owner_state, key)
-          owner_construct.entities.each do |entity|
-            next if entity.invariants.empty?
-
-            list_attr = owner_construct.attributes.find { |a| a.list? && a.type.to_s == entity.hecks_name }
-            next unless list_attr
-
-            Array(owner_state[list_attr.name]).each do |element|
-              violated = entity.invariants.find do |invariant|
-                !Bluebook::Expression::Evaluator.call(invariant.canonical, element)
-              end
-              if violated
-                return "#{key}'s own #{entity.hecks_name} violates its declared invariant " \
-                       "#{violated.description.inspect}"
-              end
-
-              nested = check_piece_invariants(entity, element, key)
-              return nested if nested
-            end
-          end
-          nil
-        end
-
         # A saga instance's own state is one the process manager declares, and
         # its memory survives the same JSON round-trip `SagaInterpreter#checkpoint`'s
         # own `deep_copy` performs (mirrored here, a private instance method
         # with no registry to hand it).
         def sagas_rehydrate_cleanly(history)
-          bluebook = history.fetch(:bluebook)
-          process_managers = bluebook.process_managers.to_h { |pm| [pm.name, pm] }
+          process_managers = history.fetch(:bluebook).process_managers.to_h { |pm| [pm.name, pm] }
 
           offenders = history.fetch(:saga_instances).flat_map do |pm_name, conversations|
-            pm = process_managers[pm_name]
-
             conversations.filter_map do |correlation, instance|
-              problems = []
+              saga_offense(pm_name, process_managers[pm_name], correlation, instance)
+            end
+          end
 
-              problems << "holds state #{instance[:state].inspect}, which #{pm_name} never declares" \
-                if pm && !pm.declares_state?(instance[:state])
+          offenders.empty? || offenders.join("; ")
+        end
 
-              rehydrated = JSON.parse(JSON.generate(instance[:memory]), symbolize_names: true)
-              if rehydrated != instance[:memory]
-                problems << "memory does not survive its own checkpoint round-trip " \
-                            "(checkpointed #{instance[:memory].inspect}, rehydrated #{rehydrated.inspect})"
-              end
+        # The message for one saga conversation that breaks, or nil.
+        def saga_offense(pm_name, manager, correlation, instance)
+          problems = saga_problems(pm_name, manager, instance)
+          "#{pm_name}##{correlation.inspect}: #{problems.join(" and ")}" unless problems.empty?
+        end
 
-              next if problems.empty?
+        def saga_problems(pm_name, manager, instance)
+          problems = []
+          problems << "holds state #{instance[:state].inspect}, which #{pm_name} never declares" \
+            if manager && !manager.declares_state?(instance[:state])
 
-              "#{pm_name}##{correlation.inspect}: #{problems.join(' and ')}"
-            end
+          rehydrated = JSON.parse(JSON.generate(instance[:memory]), symbolize_names: true)
+          if rehydrated != instance[:memory]
+            problems << "memory does not survive its own checkpoint round-trip " \
+                        "(checkpointed #{instance[:memory].inspect}, rehydrated #{rehydrated.inspect})"
           end
-
-          offenders.empty? || offenders.join("; ")
+          problems
         end
 
         # A `for_each` policy dispatches exactly once per row its declared query
@@ -92,23 +63,25 @@ module Hecks
         # computation. `expected_row_ids` is `nil`, not `[]`, when `policy.where`
         # never held — no dispatch is the claim then, not "dispatched to zero rows."
         def fanout_dispatches_once_per_matching_row(history)
-          offenders = history.fetch(:fan_outs).filter_map do |finding|
-            expected = finding[:expected_row_ids]
-            actual   = finding[:actual_row_ids].sort
-
-            if expected.nil?
-              next if actual.empty?
+          offenders = history.fetch(:fan_outs).filter_map { |finding| fan_out_offense(finding) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-              next "#{finding[:policy]} on #{finding[:on]}: where did not hold, but dispatched to #{actual.inspect}"
-            end
+        # The message for one fan-out whose dispatches differ from the expectation, or nil.
+        def fan_out_offense(finding)
+          expected = finding[:expected_row_ids]
+          actual   = finding[:actual_row_ids].sort
+          return unexpected_dispatch_offense(finding, actual) if expected.nil?
+          return if actual == expected
 
-            next if actual == expected
+          "#{finding[:policy]} on #{finding[:on]}: for_each answered #{expected.inspect}, " \
+            "but the reaction log shows dispatches to #{actual.inspect}"
+        end
 
-            "#{finding[:policy]} on #{finding[:on]}: for_each answered #{expected.inspect}, " \
-              "but the reaction log shows dispatches to #{actual.inspect}"
-          end
+        def unexpected_dispatch_offense(finding, actual)
+          return if actual.empty?
 
-          offenders.empty? || offenders.join("; ")
+          "#{finding[:policy]} on #{finding[:on]}: where did not hold, but dispatched to #{actual.inspect}"
         end
 
         # A `count`/`median` report's reduced scalar matches the same reduction
@@ -116,72 +89,31 @@ module Hecks
         # and InMemory.comparable/.holds? — the same calls the interpreter
         # itself makes, so this oracle can't drift from what a field read or a
         # `where` clause means without the interpreter drifting identically.
-        # rubocop:disable-next Metrics/CyclomaticComplexity
-        # rubocop:disable-next Metrics/PerceivedComplexity
         def aggregation_matches_recompute(history)
           bluebook = history.fetch(:bluebook)
-
-          offenders = history.fetch(:queries).filter_map do |asked|
-            next if asked[:error]
-
-            domain, name = asked[:query].to_s.split(".", 2)
-            next unless name && domain == bluebook.name
-
-            model = bluebook.read_model(name)
-            next unless model&.reducing?
-
-            reduced_head = model.aggregate_heads.find { |head| head[:many] }
-            next unless reduced_head
-
-            rows = eligible_rows(bluebook, asked.fetch(:instances_at), domain, model, reduced_head, asked[:args] || {})
-            expected = recompute_reduction(model, rows)
-            actual = asked[:rows]&.first&.dig(reduced_head[:as])
-            next if actual == expected
-
-            "#{asked[:query]} #{asked[:args].inspect} answered #{actual.inspect} for #{reduced_head[:as]}, " \
-              "but recomputing independently from #{rows.length} eligible row(s) gives #{expected.inspect}"
-          end
-
+          offenders = history.fetch(:queries).filter_map { |asked| aggregation_offense(bluebook, asked) }
           offenders.empty? || offenders.join("; ")
         end
 
-        # ADR 0078's siblings of `count`/`median`, each an independent fold over the same
-        # eligible rows — never reusing ReadModelInterpreter#reduce's own arithmetic, only the
-        # shared field-reading primitives `recompute_median` already relied on.
-        def recompute_reduction(model, rows)
-          return rows.length if model.count?
-          return recompute_median(rows, model.median_field) if model.median_field
-          return recompute_values(rows, model.sum_field).sum if model.sum_field
-          return recompute_avg(rows, model.avg_field) if model.avg_field
-          return recompute_values(rows, model.min_field).min if model.min_field
-          return recompute_values(rows, model.max_field).max if model.max_field
-          return recompute_percentile(rows, model.percentile_field, model.percentile_at) if model.percentile_field
-          return recompute_values(rows, model.any_field).any? if model.any_field
+        # The message for one reducing ask whose answer disagrees with the recomputation, or nil.
+        def aggregation_offense(bluebook, asked)
+          return if asked[:error]
 
-          recompute_values(rows, model.all_field).all?
-        end
-
-        def recompute_values(rows, field)
-          rows.map { |state| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, field)) }.compact
-        end
+          model = asked_read_model(bluebook, asked)
+          return unless model&.reducing?
 
-        def recompute_avg(rows, field)
-          values = recompute_values(rows, field)
-          values.empty? ? nil : values.sum.to_f / values.length
+          reduced_head = many_head(model)
+          reduced_head && reduction_offense(bluebook, asked, model, reduced_head)
         end
 
-        # Same linear-interpolation formula as `ReadModelInterpreter#percentile`, written
-        # independently here rather than called, for the same reason `recompute_median`
-        # already is: an oracle that calls the interpreter's own fold agrees with a bug in it
-        # by construction (ADR 0061's `nest_rows` lesson).
-        def recompute_percentile(rows, field, at)
-          values = recompute_values(rows, field).sort
-          return nil if values.empty?
+        def reduction_offense(bluebook, asked, model, reduced_head)
+          rows = eligible_rows(bluebook, asked.fetch(:instances_at), model, reduced_head, asked[:args] || {})
+          expected = recompute_reduction(model, rows)
+          actual = asked[:rows]&.first&.dig(reduced_head[:as])
+          return if actual == expected
 
-          position = at * (values.length - 1)
-          lower = position.floor
-          fraction = position - lower
-          fraction.zero? ? values[lower] : values[lower] + (fraction * (values[lower + 1] - values[lower]))
+          "#{asked[:query]} #{asked[:args].inspect} answered #{actual.inspect} for #{reduced_head[:as]}, " \
+            "but recomputing independently from #{rows.length} eligible row(s) gives #{expected.inspect}"
         end
 
         # aggregation_matches_recompute's own shape, extended from reducing a
@@ -190,109 +122,16 @@ module Hecks
         # path not covering identity means the ask must have refused.
         def group_by_matches_recompute(history)
           bluebook = history.fetch(:bluebook)
-
-          offenders = history.fetch(:queries).filter_map do |asked|
-            domain, name = asked[:query].to_s.split(".", 2)
-            next unless name && domain == bluebook.name
-
-            model = bluebook.read_model(name)
-            next unless model&.group_by&.any?
-
-            grouped_head = model.aggregate_heads.find { |head| head[:many] }
-            next unless grouped_head
-
-            group_by_offense(bluebook, asked, model, grouped_head)
-          end
-
+          offenders = history.fetch(:queries).filter_map { |asked| group_by_ask_offense(bluebook, asked) }
           offenders.empty? || offenders.join("; ")
         end
 
-        # Judges one `group_by` ask against the rows it was eligible to see:
-        # refused exactly when two of them share a checked key path, and
-        # otherwise nested exactly as `nest_rows` nests them.
-        def group_by_offense(bluebook, asked, model, grouped_head)
-          rows = eligible_rows(bluebook, asked.fetch(:instances_at), bluebook.name, model, grouped_head, asked[:args] || {})
-          materialized = rows.map { |state| Runtime::Value.materialize_unwrapped(state) }
-          shared = shared_key_paths(materialized, model.group_by_fields)
-          checked = !model.groups_by_identity?(bluebook.aggregate(grouped_head[:aggregate]))
-          return collision_offense(asked, model.group_by_fields, shared.length, checked) if shared.any?
-          return nil if asked[:error]
-          return nil if asked[:rows]&.first&.dig(grouped_head[:as]) == nest_rows(materialized, model.group_by_fields)
-
-          "#{asked[:query]} #{asked[:args].inspect} answered a #{grouped_head[:as]} grouping that disagrees " \
-            "with independently nesting group_by #{model.group_by_fields.inspect} over #{rows.length} " \
-            "eligible row(s)"
-        end
-
-        # Judges an ask whose eligible rows share at least one full key path:
-        # a checked key path must have refused, and an identity-covering one
-        # cannot be shared by rows that hold their identity.
-        def collision_offense(asked, fields, shared, checked)
-          return nil if checked && asked[:error]
-
-          "#{asked[:query]} #{asked[:args].inspect} #{checked ? 'answered' : 'reached'}, but #{shared} key " \
-            "path(s) of group_by #{fields.inspect} are shared by more than one eligible row, " \
-            "#{checked ? 'so the ask must refuse' : 'though they cover the identity'}"
-        end
-
-        # Every full `group_by` key path more than one row reaches, found by
-        # tallying each row's tuple of grouped values, with no nesting at all.
-        def shared_key_paths(rows, fields)
-          rows.map { |row| fields.map { |field| row[field] } }.tally.select { |_, count| count > 1 }.keys
-        end
-
-        # One level of nesting per `group_by` field in declared order; the leaf
-        # is the row with every grouped field stripped. Called only when no key
-        # path is shared (`shared_key_paths` rules that out), so each leaf holds
-        # exactly one row; a second row raises rather than being picked over.
-        def nest_rows(rows, fields)
-          field, *rest = fields
-          rows.group_by { |row| row[field] }.transform_values do |group|
-            stripped = group.map { |row| row.reject { |key, _| key == field } }
-            next nest_rows(stripped, rest) unless rest.empty?
-            raise ArgumentError, "nest_rows reached a key path #{stripped.length} rows share" unless stripped.length == 1
-
-            stripped[0]
-          end
-        end
-
-        # The eligible rows a `count`/`median` head reduces: every instance of
-        # the reduced head's own aggregate, FK-matched against the report's root
-        # reference (if any), then narrowed by the report's own `where` clauses.
-        def eligible_rows(bluebook, instances, domain, model, reduced_head, args)
-          aggregate = bluebook.aggregate(reduced_head[:aggregate])
-          prefix = "#{domain}::#{reduced_head[:aggregate]}#"
-          # `id:` merged in, the same shape every live head row carries —
-          # count/median never read it, but group_by's own nesting does.
-          rows = instances.filter_map { |key, state| state.merge(id: key.split("#").last) if key.start_with?(prefix) }
-
-          if model.reference_target
-            reference_id = args[model.reference_name].to_s
-            fk_fields = aggregate.attributes.select do |attribute|
-              attribute.reference? && attribute.type.target_name == model.reference_target.to_s
-            end.map(&:name)
-
-            rows = rows.select { |state| fk_fields.any? { |field| state[field].to_s == reference_id } }
-          end
-
-          rows.select do |state|
-            model.wheres.all? do |clause|
-              held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, clause.field))
-              Ports::Query::InMemory.holds?(clause, held, args)
-            end
-          end
-        end
-
-        # ReadModelInterpreter#median's own definition, reproduced: the true
-        # middle for an odd count, the average of the two middles for an even
-        # count, `nil` for empty — never zero, so "nothing" isn't "zero."
-        def recompute_median(rows, field)
-          values = rows.map { |state| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, field)) }
-                       .compact.sort
-          return nil if values.empty?
+        def group_by_ask_offense(bluebook, asked)
+          model = asked_read_model(bluebook, asked)
+          return unless model&.group_by&.any?
 
-          middle = values.length / 2
-          values.length.odd? ? values[middle] : (values[middle - 1] + values[middle]) / 2.0
+          grouped_head = many_head(model)
+          grouped_head && group_by_offense(bluebook, asked, model, grouped_head)
         end
       end
     end

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

@@ -13,49 +13,60 @@ module Hecks
         # @return [true, String] true, or a message naming each offending instance
         def lifecycle_values_are_declared(history)
           bluebook = history.fetch(:bluebook)
-          declared = {}
-          bluebook.aggregates.each do |aggregate|
-            declared[aggregate.hecks_name] = Bluebook::ModelCheck.full_states(aggregate.lifecycle) if aggregate.lifecycle
+          declared = bluebook.aggregates.select(&:lifecycle).to_h do |aggregate|
+            [aggregate.hecks_name, Bluebook::ModelCheck.full_states(aggregate.lifecycle)]
           end
           return true if declared.empty?
 
           offenders = history.fetch(:instances).filter_map do |key, state|
-            aggregate_name = key.split("::").last.split("#").first
-            states = declared[aggregate_name]
-            next unless states
-
-            lifecycle = bluebook.aggregate(aggregate_name).lifecycle
-            value = state[lifecycle.field]
-            next if value.nil? || states.include?(value.to_s)
-
-            "#{key} holds #{lifecycle.field}=#{value.inspect}, which #{aggregate_name} never declares as a state"
+            undeclared_state_offense(bluebook, declared, key, state)
           end
 
           offenders.empty? || offenders.join("; ")
         end
 
+        # The message for one stored record holding an undeclared lifecycle state, or nil.
+        def undeclared_state_offense(bluebook, declared, key, state)
+          aggregate_name = key.split("::").last.split("#").first
+          states = declared[aggregate_name]
+          return unless states
+
+          lifecycle = bluebook.aggregate(aggregate_name).lifecycle
+          value = state[lifecycle.field]
+          return if value.nil? || states.include?(value.to_s)
+
+          "#{key} holds #{lifecycle.field}=#{value.inspect}, which #{aggregate_name} never declares as a state"
+        end
+
         # Every logged saga advance follows a `(from_state, to_state)` pair some handler declares.
         #
         # @param history [Hash] a replayed history as returned by `Replay.call`
         # @return [true, String] true, or a message naming the process manager and undeclared pair
         def saga_advances_follow_declared_handlers(history)
-          bluebook = history.fetch(:bluebook)
+          edges = saga_edges(history.fetch(:bluebook))
+          return true if edges.empty?
+
+          offenders = history.fetch(:sagas).filter_map { |entry| saga_advance_offense(edges, entry) }
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # The `(from_state, to_state)` pairs each process manager's handlers declare.
+        def saga_edges(bluebook)
           edges = Hash.new { |h, k| h[k] = [] }
           bluebook.process_managers.each do |pm|
             pm.handlers.each { |handler| edges[pm.name] << [handler.from_state, handler.to_state] }
           end
-          return true if edges.empty?
-
-          offenders = history.fetch(:sagas).filter_map do |entry|
-            next unless entry[:advanced]
+          edges
+        end
 
-            pair = [entry[:from], entry[:to]]
-            next if edges[entry[:process_manager]].include?(pair)
+        # The message for one logged saga advance no handler declares, or nil.
+        def saga_advance_offense(edges, entry)
+          return unless entry[:advanced]
 
-            "#{entry[:process_manager]} advanced #{pair.inspect}, which no declared handler names"
-          end
+          pair = [entry[:from], entry[:to]]
+          return if edges[entry[:process_manager]].include?(pair)
 
-          offenders.empty? || offenders.join("; ")
+          "#{entry[:process_manager]} advanced #{pair.inspect}, which no declared handler names"
         end
 
         # Replaying the same steps on a fresh boot yields identical events, refusals and instances.
@@ -70,22 +81,22 @@ module Hecks
         def replay_is_deterministic(domain_path, steps, adapter: :memory)
           first  = Replay.call(domain_path, steps, adapter: adapter)
           second = Replay.call(domain_path, steps, adapter: adapter)
+          return true if comparable_history(first) == comparable_history(second)
 
-          # What is stripped is declared in `Nondeterministic::FIELDS`. Outbox rows are stripped
-          # per row, not dropped, so status, consumer and event payload stay checked.
-          strip_outbox_nondeterminism = lambda do |history|
-            traces = Array(history[:outbox_traces]).map do |trace|
-              trace.merge(rows: trace[:rows].map do |row|
-                Nondeterministic.strip(row, :outbox_row).merge(event: Nondeterministic.strip(row[:event], :event))
-              end)
-            end
-            history.merge(outbox_traces: traces)
-          end
+          "two replays of the same #{steps.length} steps produced different histories"
+        end
 
-          comparable = ->(history) { Nondeterministic.strip(strip_outbox_nondeterminism.call(history), :history) }
-          return true if comparable.call(first) == comparable.call(second)
+        # What is stripped is declared in `Nondeterministic::FIELDS`. Outbox rows are stripped
+        # per row, not dropped, so status, consumer and event payload stay checked.
+        def comparable_history(history)
+          traces = Array(history[:outbox_traces]).map do |trace|
+            trace.merge(rows: trace[:rows].map { |row| stripped_outbox_row(row) })
+          end
+          Nondeterministic.strip(history.merge(outbox_traces: traces), :history)
+        end
 
-          "two replays of the same #{steps.length} steps produced different histories"
+        def stripped_outbox_row(row)
+          Nondeterministic.strip(row, :outbox_row).merge(event: Nondeterministic.strip(row[:event], :event))
         end
       end
     end

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

@@ -0,0 +1,162 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Independent recomputations of what each mutation op leaves behind, for
+      # `DispatchAndMutations#mutations_match_recompute` to compare against the real dispatch.
+      module MutationRecompute
+        # What a recomputation needs of the step it re-derives.
+        #
+        # `before` is the entity's state before the dispatch; `owner` is the construct declaring
+        # the mutated attribute, the root aggregate unless a dot-shaped command names an entity.
+        Context = Struct.new(:aggregate, :command, :owner, :before, :args)
+
+        # Dispatches to the recompute rule for `mutation.op`.
+        #
+        # @param mutation [Object] the mutation the command declares
+        # @param current [Object] the mutated attribute's value before the dispatch
+        # @param context [Context] the step being re-derived
+        # @return [Object, Symbol] the recomputed after-value, or `:unrecomputable`
+        def recompute_mutation(mutation, current, context)
+          case mutation.op
+          when :append   then recompute_append(current, mutation.source, context, mutation.target)
+          when :remove   then recompute_remove(current, mutation.source, context.args)
+          when :multiply then recompute_multiply(current, resolve_mutation_source(mutation.source, context.args))
+          when :clamp    then recompute_clamp(current, mutation.source)
+          when :set      then recompute_set(mutation.source, context, mutation.target)
+          end
+        end
+
+        # Re-derives the `:set` branch of `EntityElement#apply_to_element`. The
+        # attribute comes from `owner`, not the root aggregate, which would leave a
+        # nested entity's value uncoerced and disagree with the real after-state.
+        # Any raise means the raw material was wrong, so the result is `:unrecomputable`.
+        def recompute_set(source, context, target)
+          raw = resolve_mutation_source(source, context.args)
+          attribute = context.owner&.attribute(target)
+          coerced = attribute ? Runtime::Value.for_attribute(context.aggregate, attribute, raw) : raw
+          Runtime::Value.materialize(coerced)
+        rescue StandardError
+          :unrecomputable
+        end
+
+        # Re-derives `EntityElement#appended_to_element`: each field resolves from a
+        # caller arg (coerced as `Interpreting#coerce_declared_arguments` does) or from
+        # the entity's current field (already materialized), then the element is appended.
+        # A nested-entity element also gets its declared defaults.
+        def recompute_append(current, source_map, context, target = nil)
+          fields = source_map.transform_values { |source| resolve_mutation_append_field(source, context) }
+          fill_recompute_declared_defaults(context, target, fields)
+          Array(current) + [symbolize_deep(fields)]
+        end
+
+        # Fills defaults for a nested-entity element via `Instance.default_for`, which is
+        # independently tested. No-op unless `target` names an entity under `owner`
+        # (`owner.entities`, not `aggregate.entities`).
+        #
+        # A value-object element type (the more common shape: `list_of` a plain composite,
+        # not a nested entity) defaults the other way real dispatch does — through
+        # `Runtime::Value.apply_defaults`, the exact primitive `EntityElement#appended_to_
+        # element`'s own `Value.build` call uses. Without this branch, a caller-omitted,
+        # VO-declared `default:` field is left out of the recomputed element entirely,
+        # disagreeing with real dispatch's fully-defaulted one.
+        def fill_recompute_declared_defaults(context, target, fields)
+          element_type = target && context.owner&.attribute(target)&.type
+          return fields unless element_type
+
+          entity = context.owner.entities.find { |piece| piece.hecks_name == element_type.to_s }
+          return fill_entity_defaults(context.aggregate, entity, fields) if entity
+
+          fill_value_object_defaults(context.aggregate, element_type, fields)
+        end
+
+        def fill_entity_defaults(aggregate, entity, fields)
+          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 fill_value_object_defaults(aggregate, element_type, fields)
+          value_object = aggregate.value_object(element_type)
+          value_object ? Runtime::Value.apply_defaults(value_object, fields) : fields
+        end
+
+        # Resolves one appended field's value from its declared source.
+        def resolve_mutation_append_field(source, context)
+          return source unless source.is_a?(Symbol)
+          return context.before[source] unless context.args.key?(source)
+
+          coerce_recompute_append_arg(context, source, context.args[source])
+        end
+
+        # Coerces a raw arg only when `source` is a declared attribute of the command,
+        # as a real dispatch does. Materialized so the comparison is plain data on both sides.
+        def coerce_recompute_append_arg(context, source, raw)
+          attribute = context.command.attribute(source)
+          return raw unless attribute
+
+          Runtime::Value.materialize(Runtime::Value.for_attribute(context.aggregate, attribute, raw, argument: true))
+        end
+
+        # Re-derives `MutationApplier#removed`: removes every value-equal element.
+        # `Value.materialize` first: once `args` arrives normalized (replay.rb's
+        # `build_mutation_trace`), a composite `remove:` source is already a built
+        # `Runtime::Value` with its own declared defaults filled — comparing it
+        # unmaterialized against `current`'s plain Hashes would never match, wrongly
+        # keeping an element real dispatch correctly removed.
+        def recompute_remove(current, source, args)
+          target = symbolize_deep(Runtime::Value.materialize(resolve_mutation_source(source, args)))
+          Array(current).reject { |element| symbolize_deep(element) == target }
+        end
+
+        # Re-derives `CommandRules::Arithmetic#multiply` on plain data: a Hash with one
+        # numeric field scales that field, a bare Numeric scales itself. A nil
+        # `current` is treated as 0.
+        def recompute_multiply(current, amount)
+          return :unrecomputable unless amount.is_a?(Numeric)
+
+          apply_to_number(current) { |number| number * amount }
+        end
+
+        # Re-derives `CommandRules::Arithmetic#clamp` like #recompute_multiply. The
+        # source is always a literal `[min, max]`, never an argument reference.
+        def recompute_clamp(current, bounds)
+          return :unrecomputable unless bounds.is_a?(Array) && bounds.size == 2
+
+          min, max = bounds
+          apply_to_number(current) { |number| number.clamp(min, max) }
+        end
+
+        # Yields a bare Numeric, or the first numeric field of a Hash, and puts the result back.
+        # Anything else, or a Hash with no numeric field, is `:unrecomputable`; nil counts as 0.
+        def apply_to_number(current)
+          current ||= 0
+          return yield(current) if current.is_a?(Numeric)
+          return :unrecomputable unless current.is_a?(Hash)
+
+          field = current.keys.find { |f| current[f].is_a?(Numeric) }
+          return :unrecomputable unless field
+
+          current.merge(field => yield(current[field]))
+        end
+
+        # A mutation source is an argument name (Symbol) or a literal.
+        def resolve_mutation_source(source, args)
+          source.is_a?(Symbol) ? args[source] : source
+        end
+
+        # Symbolizes hash keys recursively. Generated args carry string keys while
+        # materialized trace state carries symbols, and `Hash#==` would otherwise differ.
+        def symbolize_deep(value)
+          case value
+          when Hash  then value.to_h { |key, val| [key.to_sym, symbolize_deep(val)] }
+          when Array then value.map { |val| symbolize_deep(val) }
+          else value
+          end
+        end
+      end
+    end
+  end
+end