hecks 3.4.2 → 3.6.0

data/lib/hecks/runtime/command_interpreter/argument_gate.rb

@@ -16,9 +16,7 @@ module Hecks
         # `extra_identity_heads:` carries the identity heads of each entity hop an entity
         # dispatch walks; `[]` for a plain aggregate or port-operation dispatch.
         def refuse_unknown_arguments(domain, aggregate, command, args, extra_identity_heads: [])
-          addressing = [:id, *aggregate.identity_heads, *extra_identity_heads, reference_key(command)] +
-                       correlation_keys(domain)
-          known      = (command.attributes.map(&:name) + addressing).compact.map(&:to_sym)
+          known = known_argument_names(domain, aggregate, command, extra_identity_heads)
           # Sorted: refusal wording is pinned byte-for-byte, so it cannot follow payload order.
           unknown = (args.keys.map(&:to_sym) - known).sort
           return if unknown.empty?
@@ -29,6 +27,13 @@ module Hecks
                                            declared: declared_names(command))
         end
 
+        # Every name a payload may carry: the declared attributes plus the addressing keys.
+        def known_argument_names(domain, aggregate, command, extra_identity_heads)
+          addressing = [:id, *aggregate.identity_heads, *extra_identity_heads, reference_key(command)] +
+                       correlation_keys(domain)
+          (command.attributes.map(&:name) + addressing).compact.map(&:to_sym)
+        end
+
         # Refuses a declared, non-optional argument that is missing. Without it a missing
         # argument surfaces later as a misleading coercion error about a mistake the caller
         # did not make.
@@ -36,12 +41,8 @@ module Hecks
         # `aggregate:` is set only for a port operation, whose identity attribute is
         # promoted into routing by `to:` and so never appears in `args`; it is exempted.
         def refuse_absent_arguments(command, args, aggregate: nil)
-          given    = args.keys.map(&:to_sym)
-          exempt   = aggregate && command.respond_to?(:identity_attribute) &&
-                     command.identity_attribute(aggregate.hecks_name)&.name
-          required = command.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - [exempt]
           # Sorted, for the same reason as the unknown list.
-          absent = (required - given).sort
+          absent = (required_argument_names(command, aggregate) - args.keys.map(&:to_sym)).sort
           return if absent.empty?
 
           raise AbsentArgument,
@@ -50,6 +51,13 @@ module Hecks
                                            declared: declared_names(command))
         end
 
+        # The declared, non-optional argument names, less a port operation's promoted identity.
+        def required_argument_names(command, aggregate)
+          exempt = aggregate && command.respond_to?(:identity_attribute) &&
+                   command.identity_attribute(aggregate.hecks_name)&.name
+          command.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - [exempt]
+        end
+
         # An empty list must still read as a sentence; only the empty case is worded differently.
         def declared_names(command) = command.attributes.map(&:name)
 

data/lib/hecks/runtime/command_interpreter/delegation.rb

@@ -0,0 +1,116 @@
+require_relative "../errors"
+require_relative "../instance"
+require_relative "../entity_element"
+
+module Hecks
+  module Runtime
+    class CommandInterpreter
+      # The synchronous cousin of a policy's own `trigger` (see `CommandBuilder#delegates_to`).
+      # Runs between a command's own mutations and its ensures/invariants/save, so a refusal here
+      # leaves nothing committed on either side. Reimplements the entity pipeline (givens,
+      # transition, mutations, ensures) inline, to keep that exact ordering in one place rather
+      # than threading state through method boundaries as parameters.
+      module Delegation
+        # What a `delegates_to` mutation resolved to: the entity, its command, the command's own
+        # arguments, the located element, and a view of it for the givens.
+        Target = Struct.new(:entity, :command, :args, :element, :view)
+
+        private
+
+        def step_delegate_to_entity(ctx)
+          delegation = ctx.command.mutations.find { |mutation| mutation.op == :delegate }
+          return unless delegation
+
+          # Not emitted here — C7.2: a refused command records nothing, and the parent's own
+          # ensures/invariants/save steps still run after this one. Parked and emitted by
+          # `step_emit`, after the parent commits, alongside every other command's events.
+          step(:delegate_to_entity) { ctx.pending_delegation = run_delegation(ctx, delegation) }
+        end
+
+        # Runs the target entity command's givens, transition, mutations and ensures against the
+        # element, answering the command and arguments `step_emit` will emit.
+        def run_delegation(ctx, delegation)
+          target      = locate_delegate(ctx, delegation)
+          transition  = check_delegate_givens(ctx, target)
+          old_element = target.command.ensures.empty? ? nil : target.element.dup
+          mutate_delegate(ctx, target, transition)
+          enforce_delegate_ensures(ctx, target, old_element)
+          [target.command, target.args]
+        end
+
+        def enforce_delegate_ensures(ctx, target, old_element)
+          settled = Instance.new(aggregate: target.entity, id: target.view.id, state: target.element)
+          @rules.enforce_ensures(settled, target.command, target.args, old: old_element, domain: ctx.domain, parent: ctx.instance)
+        end
+
+        def locate_delegate(ctx, delegation)
+          entity, target_command, command_name = resolve_delegation_target(ctx, delegation)
+          target_args = mapped_and_gated_delegation_args(ctx, delegation, entity, target_command)
+          element = EntityElement.locate_chain(ctx.aggregate, [entity], ctx.instance, target_args, command_name)
+          view = Instance.new(aggregate: entity, id: EntityElement.element_identity(entity, element).to_s, state: element)
+          Target.new(entity, target_command, target_args, element, view)
+        end
+
+        # @return [Object, nil] the transition the target command is admissible under, if any
+        def check_delegate_givens(ctx, target)
+          @rules.enforce_givens(target.view, target.command, target.args,
+                                domain: ctx.domain, declaring: target.entity, parent: ctx.instance)
+          @rules.admissible_transition(target.entity, target.command, target.view)
+        end
+
+        def mutate_delegate(ctx, target, transition)
+          pre = target.element.dup # C4.2 — the update set reads the element as it was
+          target.command.mutations.each do |mutation|
+            EntityElement.apply_to_element(@rules, ctx.aggregate, target.entity, target.element, mutation, target.args, pre)
+          end
+          target.element[target.entity.lifecycle.field] = transition.target if transition
+        end
+
+        # The entity and command a `delegates_to` mutation names, resolved once so
+        # `step_delegate_to_entity` can read them as plain locals.
+        def resolve_delegation_target(ctx, delegation)
+          entity_name, _dot, command_name = delegation.target.to_s.rpartition(".")
+          entity = delegation_entity(ctx, entity_name, command_name)
+          target_command = entity.command(command_name) ||
+                           raise(WiringError, "#{ctx.command.hecks_name} delegates_to " \
+                                              "#{entity_name}.#{command_name}, which " \
+                                              "#{entity_name} declares no such command")
+          [entity, target_command, command_name]
+        end
+
+        def delegation_entity(ctx, entity_name, command_name)
+          ctx.aggregate.entities.find { |e| e.hecks_name == entity_name } ||
+            raise(WiringError, "#{ctx.command.hecks_name} delegates_to #{entity_name}." \
+                               "#{command_name}, but #{ctx.aggregate.hecks_name} has no " \
+                               "entity named #{entity_name.inspect}")
+        end
+
+        # Builds the target command's own args, then runs the same argument gate
+        # `EntityInterpreter` runs before a direct dispatch of that command — evaluated
+        # against the target command's own declared attributes and the already
+        # `with:`-mapped args, not the delegating command's. Without this, a `with:`
+        # mapping that omits one of the target's required attributes would silently
+        # mutate and persist state that was never validated at all.
+        # `extra_identity_heads:` exempts the entity's own identity field (e.g. `id`),
+        # which locates the element but is never a declared attribute.
+        def mapped_and_gated_delegation_args(ctx, delegation, entity, target_command)
+          # `with:` remaps, it does not enumerate — starting from a copy of this command's
+          # own resolved args and overlaying the explicit mapping means ambient context the
+          # caller never named (the aggregate's own identity) still flows through to the
+          # target, the same as a direct dispatch of the entity command would get.
+          target_args = ctx.args.merge(
+            delegation.source.to_h { |target_key, source_key| [target_key.to_sym, ctx.args[source_key]] }
+          )
+          # The target is dispatched as if called directly, so its needs and defaults are filled
+          # too.
+          target_args = enrich_arguments(target_command, target_args)
+
+          refuse_unknown_arguments(ctx.domain, ctx.aggregate, target_command, target_args,
+                                   extra_identity_heads: entity.identity_heads)
+          refuse_absent_arguments(target_command, target_args)
+          normalize_args(ctx.aggregate, target_command, target_args)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_interpreter/enforcement.rb

@@ -0,0 +1,38 @@
+module Hecks
+  module Runtime
+    class CommandInterpreter
+      # The steps that hold a command to the domain's own rules: givens, the lifecycle transition,
+      # ensures and invariants. Each runs through the shared rules engine.
+      module Enforcement
+        private
+
+        def step_enforce_givens(ctx)
+          step(:enforce_givens) do
+            # Structural check before the declared givens (same ordering as
+            # NotFound/AlreadyExists at hydration). Also locates the correction
+            # target, if `as:` named one, so `step_enforce_ensures` can reuse it.
+            ctx.correction_bindings = @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command,
+                                                                       domain: ctx.domain)
+            @rules.enforce_givens(ctx.instance, ctx.command, ctx.args, domain: ctx.domain,
+                                  declaring: ctx.aggregate, parent: ctx.instance, correction: ctx.correction_bindings)
+          end
+        end
+
+        def step_admissible_transition(ctx)
+          ctx.transition = step(:admissible_transition) { @rules.admissible_transition(ctx.aggregate, ctx.command, ctx.instance) }
+        end
+
+        def step_enforce_ensures(ctx)
+          step(:enforce_ensures) do
+            @rules.enforce_ensures(ctx.instance, ctx.command, ctx.args, old: ctx.old_state,
+                                   domain: ctx.domain, parent: ctx.instance, correction: ctx.correction_bindings || {})
+          end
+        end
+
+        def step_enforce_invariants(ctx)
+          step(:enforce_invariants) { @rules.enforce_invariants(ctx.instance, ctx.aggregate, domain: ctx.domain) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_interpreter/hydration.rb

@@ -0,0 +1,139 @@
+require_relative "../errors"
+require_relative "../identity"
+require_relative "../instance"
+require_relative "../refusal_wording"
+require_relative "../dependency_planning"
+require_relative "../../rendering"
+
+module Hecks
+  module Runtime
+    class CommandInterpreter
+      # Finds or builds the record a command acts on, and refuses when the identity it names is
+      # missing, occupied or contradicts its route.
+      module Hydration
+        private
+
+        # Picks the hydration the command's dependency plan allows.
+        def hydrate_for(ctx)
+          if ctx.plan.complete_state? && ctx.plan.state_independent?
+            hydrate_complete_state(ctx)
+          elsif ctx.plan.complete_state?
+            hydrate_prior_or_initial(ctx)
+          elsif legacy_implicit_creation?(ctx)
+            hydrate_legacy_creation(ctx)
+          else
+            hydrate_existing(ctx)
+          end
+        end
+
+        # The record an acting command names, by route or by the identity its arguments carry.
+        def hydrate_existing(ctx)
+          id = ctx.route ? ctx.route.aggregate : acting_identity(ctx)
+          (ctx.repository.find(id) || raise_record_missing(ctx.aggregate, id)).dup
+        end
+
+        # The identity an acting command's arguments carry, by its own facts, `id`, or its
+        # reference key.
+        def acting_identity(ctx)
+          aggregate = ctx.aggregate
+          identity_of(aggregate, ctx.args) ||
+            identity_from(aggregate, ctx.args, :id) ||
+            identity_from(aggregate, ctx.args, reference_key(ctx.command)) ||
+            raise(NotFound, RefusalWording.render_site("NotFound", "acting_no_identity",
+                                                       command: ctx.command.hecks_name, aggregate: aggregate.hecks_name,
+                                                       identity: identity_reading(aggregate)))
+        end
+
+        # Transitional compatibility for a command that has not yet acquired
+        # explicit effects — isolated from the normal routing/planning path so
+        # `reference_to` does not choose how a migrated command hydrates. An
+        # un-migrated command routes here on `creates?` alone, regardless of
+        # whether it has any mutations; requiring an empty write_set here would
+        # wrongly exclude one that sets fields.
+        def legacy_implicit_creation?(ctx)
+          ctx.route.nil? && ctx.command.creates?
+        end
+
+        def hydrate_legacy_creation(ctx)
+          id = identity_of(ctx.aggregate, ctx.args) || raise_creating_no_identity(ctx.command, ctx.aggregate)
+          raise_already_exists(ctx.command, ctx.aggregate, id) if ctx.repository.find(id)
+
+          fresh_instance(ctx, id)
+        end
+
+        def hydrate_complete_state(ctx)
+          id = creation_identity(ctx)
+          # `creates?` on an occupied identity refuses (`AlreadyExists`), except
+          # under ATOMIC_PUT: that adapter enforces the same refusal itself,
+          # atomically, via `insert_only:` in `step_save` — reading here too
+          # would race the write for nothing.
+          if ctx.command.creates? && ctx.strategy != DependencyPlanning::ATOMIC_PUT && ctx.repository.find(id)
+            raise_already_exists(ctx.command, ctx.aggregate, id)
+          end
+
+          fresh_instance(ctx, id)
+        end
+
+        # A complete command may still depend on prior state (lifecycle guards
+        # are the common case) — read once, so an existing record is checked
+        # against its real state rather than assumed defaults.
+        def hydrate_prior_or_initial(ctx)
+          id    = creation_identity(ctx)
+          found = ctx.repository.find(id)
+          # Same refusal as `hydrate_complete_state`, for a complete-but-state-
+          # dependent command (one with a `given` on its own prior state).
+          # Gated on `creates?`: a non-creating command's complete payload just
+          # means "act on whatever this identity already holds".
+          raise_already_exists(ctx.command, ctx.aggregate, id) if found && ctx.command.creates?
+
+          found ? found.dup : fresh_instance(ctx, id)
+        end
+
+        # The identity a complete command's facts derive, checked against its route.
+        def creation_identity(ctx)
+          derived = identity_of(ctx.aggregate, ctx.args)
+          refuse_route_mismatch(ctx.command, ctx.route, derived) if ctx.route && derived
+          ctx.route&.aggregate || derived || raise_creating_no_identity(ctx.command, ctx.aggregate)
+        end
+
+        def refuse_route_mismatch(command, route, derived)
+          return if route.aggregate.to_s == derived.to_s
+
+          raise TypeMismatch,
+                "#{command.hecks_name} routes to #{route.aggregate.inspect}, but its identity facts name #{derived.inspect}"
+        end
+
+        def fresh_instance(ctx, id)
+          Instance.new(aggregate: ctx.aggregate, id: id, args: ctx.args)
+        end
+
+        def raise_already_exists(command, aggregate, id)
+          raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
+                                                          command: command.hecks_name, aggregate: aggregate.hecks_name,
+                                                          identity: identity_reading(aggregate),
+                                                          offered: Rendering.describe(id)))
+        end
+
+        def raise_record_missing(aggregate, id)
+          raise(NotFound, RefusalWording.render_site("NotFound", "record_missing",
+                                                     aggregate: aggregate.hecks_name,
+                                                     identity:  identity_reading(aggregate),
+                                                     offered:   Rendering.describe(id)))
+        end
+
+        def raise_creating_no_identity(command, aggregate)
+          raise(NotFound, RefusalWording.render_site("NotFound", "creating_no_identity",
+                                                     command:   command.hecks_name,
+                                                     aggregate: aggregate.hecks_name,
+                                                     identity:  identity_reading(aggregate)))
+        end
+
+        # Shared with `EntityInterpreter`, in `Runtime::Identity`, rather than
+        # kept as two copies that could only ever drift.
+        def identity_of(aggregate, args)   = Identity.of(aggregate, args)
+        def identity_from(aggregate, args, key) = Identity.from(aggregate, args, key)
+        def identity_reading(construct)    = Identity.reading(construct)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_interpreter/list_mutations.rb

@@ -0,0 +1,98 @@
+require_relative "../value"
+require_relative "../entity_element"
+
+module Hecks
+  module Runtime
+    class CommandInterpreter
+      # The list-valued mutations: `append` builds one element, `remove` drops the matching ones.
+      # Mixed into {MutationApplier}.
+      module ListMutations
+        private
+
+        # A caller-supplied arg wins; otherwise the field falls back to the instance's own
+        # value. `args.key?` so an explicit nil still counts as supplied.
+        def resolve_append_source(source, instance, args)
+          # `state(:field)` reads the record's own value, never an argument.
+          return instance[source.name] if source.is_a?(StateRef)
+          return source unless source.is_a?(Symbol)
+          return args[source] if args.key?(source)
+
+          instance[source]
+        end
+
+        def appended(instance, aggregate, mutation, args)
+          fields       = mutation.source.transform_values { |source| resolve_append_source(source, instance, args) }
+          element_type = aggregate.attribute(mutation.target)&.type
+          element      = appended_element(aggregate, element_type, instance[mutation.target], fields)
+
+          # Frozen so a caller cannot push into the aggregate's state after dispatch.
+          Freezer.deep(Array(instance[mutation.target]) + [element])
+        end
+
+        # The one element an append adds: a value object, or an entity with its own identity.
+        def appended_element(aggregate, element_type, current, fields)
+          value_object = aggregate.value_object(element_type)
+          unwrap_single_fields(value_object, fields)
+          return Value.build(value_object, fields, aggregate) if value_object
+
+          entity_element(aggregate, element_type, current, fields)
+        end
+
+        # A single-field value unwraps to its scalar; a multi-field one passes through whole.
+        def unwrap_single_fields(value_object, fields)
+          value_object&.attributes&.each do |attribute|
+            held = fields[attribute.name]
+            fields[attribute.name] = Value.scalar(held) if held.is_a?(Value) && held.to_h.size == 1
+          end
+        end
+
+        # Removes the element matching by value, or by identity for entity-typed lists.
+        def removed(instance, aggregate, mutation, args)
+          value     = @rules.resolve_source(mutation.source, args)
+          attribute = aggregate.attribute(mutation.target)
+          value     = Value.for_attribute(aggregate, attribute, value) if attribute
+          Array(instance[mutation.target]).reject do |element|
+            EntityElement.list_element_match?(aggregate, attribute, element, value)
+          end
+        end
+
+        def entity_element(aggregate, element_type, current, fields)
+          entity = aggregate.entities.find { |piece| piece.hecks_name == element_type.to_s }
+          return fields unless entity
+
+          coerce_entity_fields(aggregate, entity, fields)
+          assign_entity_identity(aggregate, entity, current, fields)
+          fields[entity.lifecycle.field] ||= entity.lifecycle.default if entity.lifecycle
+          # Fill declared defaults for attributes the append mapping did not touch, shared with
+          # EntityElement so both entity-creation paths agree on what "the default" means.
+          EntityElement.fill_declared_defaults(aggregate, entity, fields)
+        end
+
+        def coerce_entity_fields(aggregate, entity, fields)
+          entity.attributes.each do |attribute|
+            next unless fields.key?(attribute.name)
+
+            fields[attribute.name] = Value.for_attribute(aggregate, attribute, fields[attribute.name])
+          end
+        end
+
+        # Mints the entity's identity when the append left it out; otherwise the entity-collision
+        # guard (shared with EntityElement#appended_to_element) checks the one given.
+        def assign_entity_identity(aggregate, entity, current, fields)
+          if entity.identified_by && !fields.key?(entity.identified_by)
+            attribute = entity.attribute(entity.identified_by)
+            fields[entity.identified_by] = Value.from_identifier(aggregate, attribute, next_identity(current, entity))
+          else
+            EntityElement.check_entity_collision(aggregate, entity, current, fields)
+          end
+        end
+
+        # One past the highest identity held, not `size + 1`, which repeats one after a shrink.
+        def next_identity(current, entity)
+          held = Array(current).map { |element| Value.scalar(element[entity.identified_by]).to_i }
+          held.max.to_i + 1
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_interpreter/mutation_applier.rb

@@ -1,11 +1,30 @@
 require_relative "../value"
 require_relative "../entity_element"
+require_relative "list_mutations"
 
 module Hecks
   module Runtime
     class CommandInterpreter
       # Applies a command's declared mutations (set, append, remove, arithmetic) to an instance.
       module MutationApplier
+        include ListMutations
+
+        # The handler each mutation op dispatches to. `delegate` and `corrects` both apply nothing
+        # here, for unrelated reasons: `delegates_to` is applied by
+        # CommandInterpreter#step_delegate_to_entity, and `corrects` has its target event checked
+        # up front by CommandRules::Admissibility#enforce_correction_target.
+        OP_HANDLERS = {
+          set:       :apply_set,
+          append:    :apply_append,
+          increment: :apply_arithmetic,
+          decrement: :apply_arithmetic,
+          remove:    :apply_remove,
+          multiply:  :apply_multiply,
+          clamp:     :apply_clamp,
+          delegate:  :apply_nothing,
+          corrects:  :apply_nothing
+        }.freeze
+
         private
 
         def assign_creation_attributes(instance, aggregate, command, args)
@@ -18,104 +37,67 @@ module Hecks
         end
 
         # Applies one mutation: sources read `pre` (pre-dispatch state), targets write `instance`.
-        # rubocop:disable Lint/DuplicateBranch -- :delegate and :corrects
-        # both no-op here, for unrelated reasons; merging would blur that.
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         def apply(instance, aggregate, mutation, args, pre = instance)
-          case mutation.op
-          when :set
-            value = if mutation.source.is_a?(StateRef)
-                      pre[mutation.source.name]
-                    else
-                      @rules.resolve_source(mutation.source,
-                                            args)
-                    end
-            # A plain `sets` of a list takes the whole list; only `append:` and `remove:` take
-            # one element.
-            list_attribute = aggregate.attribute(mutation.target)
-            Value.refuse_scalar_list(aggregate, list_attribute, value) if list_attribute && !mutation.source.is_a?(StateRef)
-            instance[mutation.target] = Value.for(aggregate, mutation.target, value)
-          when :append
-            instance[mutation.target] = appended(pre, aggregate, mutation, args)
-          when :increment, :decrement
-            amount = @rules.resolve_source(mutation.source, args)
-            attribute = aggregate.attribute(mutation.target)
-            current   = pre[mutation.target]
-            # Wrap `amount` only when `current` is already a Value (see #rewrap_arithmetic_result).
-            amount = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
-            result = @rules.arithmetic(current, amount, mutation.target, @rules.sign_of(mutation.op))
-            instance[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
-          # Removes a list element by value, the counterpart to append.
-          when :remove
-            instance[mutation.target] = removed(pre, aggregate, mutation, args)
-          # Scales the current value; the counterpart to clamp below.
-          when :multiply
-            amount = @rules.resolve_source(mutation.source, args)
-            attribute = aggregate.attribute(mutation.target)
-            current   = pre[mutation.target]
-            amount = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
-            result = @rules.multiply(current, amount, mutation.target)
-            instance[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
-          # Bounds the current value into [min, max]; the source is a literal pair, read as is.
-          when :clamp
-            instance[mutation.target] = @rules.clamp(pre[mutation.target], mutation.source, mutation.target)
-          # `delegates_to`: a no-op here; CommandInterpreter#step_delegate_to_entity applies it.
-          when :delegate
-            nil
-          # `corrects`: a no-op here; its target event is checked up front by
-          # CommandRules::Admissibility#enforce_correction_target.
-          when :corrects
-            nil
-          else
+          handler = OP_HANDLERS.fetch(mutation.op) do
             # Backstop: an unhandled op must refuse, not silently apply nothing.
             raise Runtime::WiringError, "no mutation applier handles :#{mutation.op} — add one before declaring it"
           end
+          send(handler, instance, aggregate, mutation, args, pre)
+        end
+
+        def apply_set(instance, aggregate, mutation, args, pre)
+          from_state = mutation.source.is_a?(StateRef)
+          value = from_state ? pre[mutation.source.name] : @rules.resolve_source(mutation.source, args)
+          # A plain `sets` of a list takes the whole list; only `append:` and `remove:` take
+          # one element.
+          list_attribute = aggregate.attribute(mutation.target)
+          Value.refuse_scalar_list(aggregate, list_attribute, value) if list_attribute && !from_state
+          instance[mutation.target] = Value.for(aggregate, mutation.target, value)
         end
-        # rubocop:enable Lint/DuplicateBranch
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
-
-        # A caller-supplied arg wins; otherwise the field falls back to the instance's own
-        # value. `args.key?` so an explicit nil still counts as supplied.
-        def resolve_append_source(source, instance, args)
-          # `state(:field)` reads the record's own value, never an argument.
-          return instance[source.name] if source.is_a?(StateRef)
-          return source unless source.is_a?(Symbol)
-          return args[source] if args.key?(source)
-
-          instance[source]
+
+        def apply_append(instance, aggregate, mutation, args, pre)
+          instance[mutation.target] = appended(pre, aggregate, mutation, args)
+        end
+
+        # Removes a list element by value, the counterpart to append.
+        def apply_remove(instance, aggregate, mutation, args, pre)
+          instance[mutation.target] = removed(pre, aggregate, mutation, args)
         end
 
-        def appended(instance, aggregate, mutation, args)
-          fields       = mutation.source.transform_values { |source| resolve_append_source(source, instance, args) }
-          element_type = aggregate.attribute(mutation.target)&.type
-          value_object = aggregate.value_object(element_type)
-          value_object&.attributes&.each do |attribute|
-            held = fields[attribute.name]
-            # A single-field value unwraps to its scalar; a multi-field one passes through whole.
-            fields[attribute.name] = Value.scalar(held) if held.is_a?(Value) && held.to_h.size == 1
+        def apply_arithmetic(instance, aggregate, mutation, args, pre)
+          apply_numeric(instance, aggregate, mutation, args, pre) do |current, amount|
+            @rules.arithmetic(current, amount, mutation.target, @rules.sign_of(mutation.op))
           end
-          element = if value_object
-                      Value.build(value_object, fields,
-                                  aggregate)
-                    else
-                      entity_element(aggregate, element_type, instance[mutation.target],
-                                     fields)
-                    end
-
-          # Frozen so a caller cannot push into the aggregate's state after dispatch.
-          Freezer.deep(Array(instance[mutation.target]) + [element])
         end
 
-        # Removes the element matching by value, or by identity for entity-typed lists.
-        def removed(instance, aggregate, mutation, args)
-          value     = @rules.resolve_source(mutation.source, args)
-          attribute = aggregate.attribute(mutation.target)
-          value     = Value.for_attribute(aggregate, attribute, value) if attribute
-          Array(instance[mutation.target]).reject do |element|
-            EntityElement.list_element_match?(aggregate, attribute, element, value)
+        # Scales the current value; the counterpart to clamp below.
+        def apply_multiply(instance, aggregate, mutation, args, pre)
+          apply_numeric(instance, aggregate, mutation, args, pre) do |current, amount|
+            @rules.multiply(current, amount, mutation.target)
           end
         end
 
+        # Bounds the current value into [min, max]; the source is a literal pair, read as is.
+        def apply_clamp(instance, _aggregate, mutation, _args, pre)
+          instance[mutation.target] = @rules.clamp(pre[mutation.target], mutation.source, mutation.target)
+        end
+
+        def apply_nothing(_instance, _aggregate, _mutation, _args, _pre)
+          nil
+        end
+
+        # Resolves the amount, lets the block combine it with the current value, and stores the
+        # result back as the attribute's own type.
+        def apply_numeric(instance, aggregate, mutation, args, pre)
+          amount    = @rules.resolve_source(mutation.source, args)
+          attribute = aggregate.attribute(mutation.target)
+          current   = pre[mutation.target]
+          # Wrap `amount` only when `current` is already a Value (see #rewrap_arithmetic_result).
+          amount = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
+          result = yield(current, amount)
+          instance[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
+        end
+
         # Wraps a plain-Numeric arithmetic result back into the attribute's Value type.
         # Skipped when `current` was already a Value, since the Value path returns one.
         def rewrap_arithmetic_result(aggregate, attribute, current, result)
@@ -123,35 +105,6 @@ module Hecks
 
           Value.for_attribute(aggregate, attribute, result)
         end
-
-        def entity_element(aggregate, element_type, current, fields)
-          entity = aggregate.entities.find { |piece| piece.hecks_name == element_type.to_s }
-          return fields unless entity
-
-          entity.attributes.each do |attribute|
-            next unless fields.key?(attribute.name)
-
-            fields[attribute.name] = Value.for_attribute(aggregate, attribute, fields[attribute.name])
-          end
-          if entity.identified_by && !fields.key?(entity.identified_by)
-            attribute = entity.attribute(entity.identified_by)
-            fields[entity.identified_by] = Value.from_identifier(aggregate, attribute, next_identity(current, entity))
-          else
-            EntityElement.check_entity_collision(aggregate, entity, current, fields)
-          end
-          fields[entity.lifecycle.field] ||= entity.lifecycle.default if entity.lifecycle
-          # Fill declared defaults for attributes the append mapping did not touch, shared with
-          # EntityElement so both entity-creation paths agree on what "the default" means.
-          EntityElement.fill_declared_defaults(aggregate, entity, fields)
-        end
-
-        # One past the highest identity held, not `size + 1`, which repeats one after a shrink.
-        def next_identity(current, entity)
-          held = Array(current).map { |element| Value.scalar(element[entity.identified_by]).to_i }
-          held.max.to_i + 1
-        end
-
-        # The entity-collision guard is shared with EntityElement#appended_to_element.
       end
     end
   end