hecks 3.5.0 → 3.6.0

data/lib/hecks/runtime/entity_element.rb

@@ -5,187 +5,23 @@ require_relative "refusal_wording"
 require_relative "errors"
 require_relative "identity"
 require_relative "instance"
+require_relative "entity_element/location"
+require_relative "entity_element/mutations"
 
 module Hecks
   module Runtime
     # Locates and mutates one entity element within an aggregate record — the shared
     # implementation behind EntityInterpreter and CommandInterpreter's own delegation.
     module EntityElement
+      extend Location
+      extend Mutations
+
       module_function
 
       # A sentinel that never equals a stored element field, since a real field can hold nil.
       UNMATCHABLE = Object.new.freeze
       private_constant :UNMATCHABLE
 
-      # Walks `chain` one hop at a time and returns the located element (or `instance`
-      # itself when `chain` is empty). `route`, when given, offers each hop's identity
-      # before falling back to `args`.
-      def locate_chain(root_aggregate, chain, instance, args, command_name, route = nil)
-        container = instance
-        owner     = root_aggregate
-        chain.each_with_index do |entity, index|
-          container = element_of(root_aggregate, owner, entity, command_name, container, args,
-                                 route&.entities&.fetch(index))
-          owner = entity
-        end
-        container
-      end
-
-      # Locates one element, matching every part of its declared identity, and copies
-      # the owning list and the element before any write so nothing aliases the caller's
-      # record. `routed_identity`, when given, matches directly by the element's own
-      # identity string instead of re-deriving `wants` from `args`.
-      # rubocop:disable-next Metrics/AbcSize
-      # rubocop:disable-next Metrics/CyclomaticComplexity
-      # rubocop:disable-next Metrics/PerceivedComplexity
-      # rubocop:disable-next Metrics/MethodLength
-      def element_of(root_aggregate, owner, entity, command_name, container, args, routed_identity = nil)
-        entity_name = entity.hecks_name
-        list_attr = owner.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
-                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_holds_no_list",
-                                                                  aggregate: owner.hecks_name, entity: entity_name))
-
-        wants = unless routed_identity
-                  entity.identity_paths.map do |path|
-                    head = path.to_s.split(".").first.to_sym
-                    raw  = args[head] ||
-                           raise(NotFound, RefusalWording.render_site("NotFound", "entity_element_no_identity",
-                                                                      command: command_name, entity: entity_name,
-                                                                      identity: Identity.reading(entity)))
-
-                    # A value that fails its own type's invariant can never match a stored
-                    # element (every stored one already satisfies it) — degrade to
-                    # `UNMATCHABLE` here rather than letting InvariantViolation propagate.
-                    want = begin
-                      Value.for_attribute(root_aggregate, entity.attribute(head), raw)
-                    rescue InvariantViolation
-                      UNMATCHABLE
-                    end
-
-                    [head, path, want, raw]
-                  end
-                end
-
-        original = Array(container[list_attr.name])
-        position = if routed_identity
-                     original.find_index { |element| element_identity(entity, element).to_s == routed_identity.to_s }
-                   else
-                     original.find_index do |el|
-                       wants.all? { |head, _path, want, _raw| want != UNMATCHABLE && el[head] == want }
-                     end
-                   end
-        unless position
-          raise NotFound, RefusalWording.render_site(
-            "NotFound", "entity_element_missing",
-            entity: entity_name, identity: Identity.reading(entity),
-            wants: wants&.map { |_h, path, _want, raw| Identity.scalar(path, raw) }&.join(", "),
-            aggregate: owner.hecks_name,
-            parent_id: container.respond_to?(:id) ? container.id.inspect : Rendering.describe(container)
-          )
-        end
-
-        # Copies the list and the found element before handing either back — the list
-        # attribute holds Hashes, and the caller mutates the returned element in place,
-        # so this keeps that mutation off the adapter's own record until it commits.
-        copied  = original.dup
-        element = copied[position].dup
-        copied[position] = element
-        container[list_attr.name] = copied
-        element
-      end
-
-      # An element's identity, joined from its declared identity paths (read off the
-      # stored Hash, not a dispatch payload).
-      def element_identity(entity, element)
-        parts = entity.identity_paths.map do |path|
-          head = path.to_s.split(".").first.to_sym
-          Identity.scalar(path, element[head])
-        end
-
-        Naming.identity(parts)
-      end
-
-      # Applies one declared mutation to an entity element, in place. `pre` is the
-      # element as it stood before this command: every read goes through it, every
-      # write lands on `element`.
-      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity
-      def apply_to_element(rules, aggregate, entity, element, mutation, args, pre = element)
-        case mutation.op
-        when :set
-          value = rules.resolve_source(mutation.source, args)
-          attribute = entity.attribute(mutation.target)
-          element[mutation.target] = attribute ? Value.for_attribute(aggregate, attribute, value) : value
-        when :append
-          element[mutation.target] = appended_to_element(aggregate, entity, pre, mutation, args)
-        when :remove
-          element[mutation.target] = removed_from_element(rules, aggregate, entity, pre, mutation, args)
-        when :increment, :decrement
-          attribute = entity.attribute(mutation.target)
-          amount    = rules.resolve_source(mutation.source, args)
-          current   = pre[mutation.target]
-          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))
-          element[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
-        when :multiply
-          attribute = entity.attribute(mutation.target)
-          amount    = rules.resolve_source(mutation.source, args)
-          current   = pre[mutation.target]
-          amount    = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
-          result    = rules.multiply(current, amount, mutation.target)
-          element[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
-        when :clamp
-          element[mutation.target] = rules.clamp(pre[mutation.target], mutation.source, mutation.target)
-        # `corrects`: a no-op here; the target event was already checked by
-        # EntityInterpreter#step_enforce_givens.
-        when :corrects
-          nil
-        else
-          # Backstop: an unhandled op must refuse, not silently apply nothing.
-          raise WiringError, "no entity mutation applier handles :#{mutation.op} — add one before declaring it"
-        end
-      end
-
-      # Rewraps a plain-Numeric arithmetic result into the attribute's own Value type.
-      # A no-op when `current` was already a Value, or the mutation targets no attribute.
-      def rewrap_arithmetic_result(aggregate, attribute, current, result)
-        return result if current.is_a?(Value) || attribute.nil? || result.is_a?(Value)
-
-        Value.for_attribute(aggregate, attribute, result)
-      end
-
-      # A caller-supplied arg wins; otherwise the field falls back to the element's own
-      # value. `args.key?` so an explicit nil still counts as supplied.
-      def resolve_element_append_source(source, element, args)
-        return source unless source.is_a?(Symbol)
-        return args[source] if args.key?(source)
-
-        element[source]
-      end
-
-      def appended_to_element(aggregate, entity, element, mutation, args)
-        fields       = mutation.source.transform_values { |source| resolve_element_append_source(source, element, args) }
-        element_type = entity.attribute(mutation.target)&.type
-        value_object = aggregate.value_object(element_type)
-        value_object&.attributes&.each do |attribute|
-          fields[attribute.name] = Value.scalar(fields[attribute.name]) if fields[attribute.name].is_a?(Value)
-        end
-        appended =
-          if value_object
-            Value.build(value_object, fields, aggregate)
-          else
-            # `entity.entities`, not `aggregate.entities` — a nested piece is a child of
-            # the owning entity, not of the root aggregate.
-            nested_entity = entity.entities.find { |piece| piece.hecks_name == element_type.to_s }
-            if nested_entity
-              check_entity_collision(entity, nested_entity, element[mutation.target], fields)
-              fill_declared_defaults(aggregate, nested_entity, fields)
-            else
-              fields
-            end
-          end
-        Freezer.deep(Array(element[mutation.target]) + [appended])
-      end
-
       # Fills every declared attribute `fields` does not already hold with its own
       # default (Instance.default_for), matching a freshly created aggregate's own
       # per-attribute defaults. Additive only: an existing key in `fields` is kept.
@@ -198,14 +34,6 @@ module Hecks
         fields
       end
 
-      # Removes the element matching by value, or by identity for entity-typed lists.
-      def removed_from_element(rules, aggregate, entity, element, mutation, args)
-        value     = rules.resolve_source(mutation.source, args)
-        attribute = entity.attribute(mutation.target)
-        value     = Value.for_attribute(aggregate, attribute, value) if attribute
-        Array(element[mutation.target]).reject { |candidate| list_element_match?(aggregate, attribute, candidate, value) }
-      end
-
       # The match rule `remove:` uses against one stored list element. Whole-value
       # equality for a non-entity-typed list; for an entity-typed one, matches by its
       # single identity head (a composite or absent identity never matches).

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

@@ -0,0 +1,51 @@
+require_relative "../instance"
+
+module Hecks
+  module Runtime
+    class EntityInterpreter
+      # The steps that hold an entity command to the domain's own rules: givens, the lifecycle
+      # transition, ensures and the parent aggregate's invariants. Mixed into
+      # {EntityInterpreter}.
+      module Enforcement
+        private
+
+        # Enforces this command's `given`s and correction-target admissibility.
+        # Checked against the parent aggregate, never the entity view — every
+        # emitted event is stamped with the root aggregate's name and the
+        # parent record's id, regardless of dispatch level.
+        def step_enforce_givens(ctx)
+          step(:enforce_givens) do
+            ctx.correction_bindings = @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command,
+                                                                       domain: ctx.domain)
+            @rules.enforce_givens(ctx.view, ctx.command, ctx.args, domain: ctx.domain, declaring: ctx.entity,
+                                  parent: ctx.instance, correction: ctx.correction_bindings)
+          end
+        end
+
+        def step_admissible_transition(ctx)
+          ctx.transition = step(:admissible_transition) { @rules.admissible_transition(ctx.entity, ctx.command, ctx.view) }
+        end
+
+        # An ensures reads the settled record, so it needs a view hydrated from
+        # `element` as it stands now, mutations included — unlike `view` above,
+        # built once and read pre-mutation by enforce_givens.
+        def step_enforce_ensures(ctx)
+          step(:enforce_ensures) do
+            settled = Instance.new(aggregate: ctx.entity, id: ctx.view.id, state: ctx.element)
+            # `correction:` reuses the `as:`-bound bindings `step_enforce_givens`
+            # already located; `|| {}` covers a command with no `corrects`
+            # mutation, where `ctx.correction_bindings` may be unset.
+            @rules.enforce_ensures(settled, ctx.command, ctx.args, old: ctx.old_element, domain: ctx.domain,
+                                   parent: ctx.instance, correction: ctx.correction_bindings || {})
+          end
+        end
+
+        # Enforces the parent aggregate's own invariants — there is no separate
+        # "entity invariant" concept (ADR 0025 scopes `invariant` to the aggregate).
+        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/entity_interpreter/locating.rb

@@ -0,0 +1,62 @@
+require_relative "../../rendering"
+require_relative "../entity_element"
+require_relative "../errors"
+require_relative "../identity"
+require_relative "../instance"
+require_relative "../refusal_wording"
+
+module Hecks
+  module Runtime
+    class EntityInterpreter
+      # Finds the parent aggregate record and the entity element a command addresses inside it.
+      # Mixed into {EntityInterpreter}.
+      module Locating
+        private
+
+        def step_hydrate_parent(ctx)
+          # `ctx.repository` is resolved once, in `#call`, before the
+          # isolation decision — not here.
+          ctx.instance = step(:hydrate_parent) { parent_record(ctx) }
+        end
+
+        def step_locate_element(ctx)
+          ctx.element = step(:locate_element) do
+            EntityElement.locate_chain(ctx.aggregate, ctx.chain, ctx.instance, ctx.args, ctx.command_name, ctx.route)
+          end
+          # `view` was hydrated once, here, into its own state hash
+          # (Value.hydrate builds a fresh Hash — never aliased with `element`)
+          # — exactly right for enforce_givens, which must read pre-mutation.
+          ctx.view = element_view(ctx)
+        end
+
+        def element_view(ctx)
+          Instance.new(aggregate: ctx.entity, id: EntityElement.element_identity(ctx.entity, ctx.element).to_s,
+                       state: ctx.element)
+        end
+
+        # Finds the parent aggregate: the declared identity first, then a bare
+        # `id:` for a record the caller derived itself.
+        def parent_record(ctx)
+          parent_id = parent_identity(ctx)
+          aggregate = ctx.aggregate
+          found = ctx.repository.find(parent_id) ||
+                  raise(NotFound, RefusalWording.render_site("NotFound", "record_missing",
+                                                             aggregate: aggregate.hecks_name,
+                                                             identity:  Identity.reading(aggregate),
+                                                             offered:   Rendering.describe(parent_id)))
+          found.dup
+        end
+
+        def parent_identity(ctx)
+          aggregate = ctx.aggregate
+          ctx.route&.aggregate ||
+            Identity.of(aggregate, ctx.args) ||
+            Identity.from(aggregate, ctx.args, :id) ||
+            raise(NotFound, RefusalWording.render_site("NotFound", "entity_parent_no_identity",
+                                                       command: ctx.command_name, aggregate: aggregate.hecks_name,
+                                                       entity: ctx.entity_name, identity: Identity.reading(aggregate)))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/entity_interpreter/resolution.rb

@@ -0,0 +1,42 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+
+module Hecks
+  module Runtime
+    class EntityInterpreter
+      # A dotted entity verb resolved against its aggregate: the entity
+      # chain it names and the command located at the end of it.
+      Resolution = Data.define(:entity_names, :chain, :command_name, :command) do
+        # Resolves a dotted entity verb into its entity chain and command,
+        # raising UnknownVerb if either segment doesn't exist.
+        def self.of(aggregate, dotted)
+          *entity_names, command_name = dotted.to_s.split(".")
+          if entity_names.empty?
+            raise UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
+                                                          aggregate: aggregate.hecks_name, entity: dotted.to_s)
+          end
+
+          chain = walk(aggregate, entity_names)
+          command = chain.last.command(command_name) ||
+                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_no_command",
+                                                                  entity: chain.last.hecks_name, command: command_name))
+          new(entity_names: entity_names, chain: chain, command_name: command_name, command: command)
+        end
+
+        # Walks one hop per dotted segment, resolving each entity name off
+        # the previous one — not limited to two levels.
+        def self.walk(aggregate, entity_names)
+          owner = aggregate
+          entity_names.map do |name|
+            found = owner.entities.find { |piece| piece.hecks_name == name } ||
+                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
+                                                                  aggregate: owner.hecks_name, entity: name))
+            owner = found
+            found
+          end
+        end
+        private_class_method :walk
+      end
+    end
+  end
+end

data/lib/hecks/runtime/entity_interpreter/saving.rb

@@ -0,0 +1,49 @@
+require_relative "../../rendering"
+require_relative "../errors"
+require_relative "../identity"
+
+module Hecks
+  module Runtime
+    class EntityInterpreter
+      # The save and emit steps: the parent record is written, and its events announced, with the
+      # root aggregate's name and the parent's identity. Mixed into {EntityInterpreter}.
+      module Saving
+        private
+
+        # `dry_run:` skips only the persist — the reference-existence check
+        # above stays unconditional either way.
+        def step_save(ctx)
+          step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state) }
+
+          return if ctx.dry_run
+
+          step(:save) { persist_parent(ctx) }
+        end
+
+        def persist_parent(ctx)
+          # `expected_version:` is nil for a non-CAS repository or an instance
+          # never read from storage — either falls through to a plain save.
+          ctx.persistence_outcome = ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
+          raise_lost_race(ctx) if ctx.persistence_outcome.status == :stale
+        end
+
+        # Intentionally not a `RefusalWording.render` call — see `Runtime::StaleWrite`'s own
+        # comment.
+        def raise_lost_race(ctx)
+          raise(StaleWrite,
+                "#{ctx.command.hecks_name} on #{ctx.aggregate.hecks_name} " \
+                "(#{Identity.reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance.id)}) lost a race — " \
+                "another write committed against this record after it was read")
+        end
+
+        # `dry_run:` skips this too — nothing was committed, so `ctx.result`
+        # stays nil and `Dispatcher#dry_run?` never reads it.
+        def step_emit(ctx)
+          return if ctx.dry_run
+
+          ctx.result = step(:emit) { @rules.emit(ctx.command, ctx.domain, ctx.aggregate, ctx.instance, ctx.args, ctx.repository) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/entity_interpreter.rb

@@ -11,6 +11,10 @@ require_relative "dependency_planning"
 require_relative "../ports/persistence/execution"
 require_relative "entity_element"
 require_relative "command_interpreter/argument_gate"
+require_relative "entity_interpreter/resolution"
+require_relative "entity_interpreter/locating"
+require_relative "entity_interpreter/enforcement"
+require_relative "entity_interpreter/saving"
 
 module Hecks
   module Runtime
@@ -22,6 +26,9 @@ module Hecks
       # Same argument gate aggregate commands and port operations run —
       # without it, entity commands skip unknown/absent-argument checks.
       include CommandInterpreter::ArgumentGate
+      include Locating
+      include Enforcement
+      include Saving
 
       attr_reader :registry
 
@@ -44,41 +51,7 @@ module Hecks
       Context = Struct.new(:domain, :aggregate, :entity, :entity_name, :command, :command_name,
                            :args, :repository, :instance, :chain, :element, :view, :transition,
                            :old_element, :result, :route, :plan, :persistence_outcome, :dry_run, :outbox_rows,
-                           :correction_bindings, :invocation)
-
-      # A dotted entity verb resolved against its aggregate: the entity
-      # chain it names and the command located at the end of it.
-      Resolution = Data.define(:entity_names, :chain, :command_name, :command) do
-        # Resolves a dotted entity verb into its entity chain and command,
-        # raising UnknownVerb if either segment doesn't exist.
-        def self.of(aggregate, dotted)
-          *entity_names, command_name = dotted.to_s.split(".")
-          if entity_names.empty?
-            raise UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
-                                                          aggregate: aggregate.hecks_name, entity: dotted.to_s)
-          end
-
-          chain = walk(aggregate, entity_names)
-          command = chain.last.command(command_name) ||
-                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_no_command",
-                                                                  entity: chain.last.hecks_name, command: command_name))
-          new(entity_names: entity_names, chain: chain, command_name: command_name, command: command)
-        end
-
-        # Walks one hop per dotted segment, resolving each entity name off
-        # the previous one — not limited to two levels.
-        def self.walk(aggregate, entity_names)
-          owner = aggregate
-          entity_names.map do |name|
-            found = owner.entities.find { |piece| piece.hecks_name == name } ||
-                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
-                                                                  aggregate: owner.hecks_name, entity: name))
-            owner = found
-            found
-          end
-        end
-        private_class_method :walk
-      end
+                           :correction_bindings, :invocation, keyword_init: true)
 
       # @param registry [Runtime::Registry] the booted registry this interpreter reads
       # @param rules [Runtime::CommandRules] the shared rules engine (admissibility,
@@ -101,29 +74,11 @@ module Hecks
       # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class when a rule refuses
       # @raise [Runtime::StaleWrite, Runtime::WiringError] every retry loses, or resolve fails
       def call(domain, aggregate, resolution, invocation, dry_run: false)
-        chain        = resolution.chain
-        entity       = chain.last
-        command      = resolution.command
-        command_name = resolution.command_name
-        route        = invocation.target
-        args         = invocation.to_args
-        attempt = 0
+        settings = { invocation: invocation, route: invocation.target, dry_run: dry_run }
+        args     = invocation.to_args
+        attempt  = 0
         begin
-          ctx = Context.new(domain, aggregate, entity, resolution.entity_names.join("."), command, command_name, args)
-          ctx.invocation = invocation
-          ctx.chain = chain
-          ctx.route = route
-          ctx.dry_run = dry_run
-          # `root_aggregate:` is the true root aggregate (this method's first
-          # parameter), never `entity` — a `parent.X` read in this command's
-          # given/ensures means the root's field, not the entity's.
-          ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command, root_aggregate: aggregate)
-          # Resolved once, here — `step_hydrate_parent` reuses `ctx.repository`
-          # rather than re-fetching it.
-          ctx.repository = @registry.repository(domain, aggregate)
-          lock_id = Identity.best_effort(aggregate, args, route)
-          run_dispatch_order_with_isolation(DISPATCH_ORDER, ctx, lock_key_id: lock_id)
-          [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome, ctx.outbox_rows]
+          dispatch_once(new_context(domain, aggregate, resolution, args, settings))
         rescue StaleWrite
           attempt += 1
           retry if attempt < MAX_STALE_WRITE_RETRIES
@@ -133,6 +88,32 @@ module Hecks
 
       private
 
+      # A fresh context for one attempt, its plan and repository resolved up front.
+      def new_context(domain, aggregate, resolution, args, settings)
+        chain = resolution.chain
+        ctx = Context.new(domain: domain, aggregate: aggregate, entity: chain.last, chain: chain, args: args,
+                          entity_name: resolution.entity_names.join("."), command: resolution.command,
+                          command_name: resolution.command_name, **settings)
+        ctx.plan       = planned(ctx)
+        # Resolved once, here — `step_hydrate_parent` reuses `ctx.repository`
+        # rather than re-fetching it.
+        ctx.repository = @registry.repository(domain, aggregate)
+        ctx
+      end
+
+      # `root_aggregate:` is the true root aggregate (the dispatch's own aggregate),
+      # never `entity` — a `parent.X` read in this command's given/ensures means the root's
+      # field, not the entity's.
+      def planned(ctx)
+        DependencyPlanning::Analyzer.call(aggregate: ctx.entity, command: ctx.command, root_aggregate: ctx.aggregate)
+      end
+
+      def dispatch_once(ctx)
+        lock_id = Identity.best_effort(ctx.aggregate, ctx.args, ctx.route)
+        run_dispatch_order_with_isolation(DISPATCH_ORDER, ctx, lock_key_id: lock_id)
+        [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome, ctx.outbox_rows]
+      end
+
       # Answers the outside facts the entity command `needs`, as the aggregate interpreter does;
       # the arguments are otherwise already decoded.
       def step_decode_arguments(ctx)
@@ -167,48 +148,15 @@ module Hecks
         step(:resolve_references) { @rules.resolve_references(ctx.domain, ctx.command, ctx.args) }
       end
 
-      def step_hydrate_parent(ctx)
-        # `ctx.repository` is resolved once, in `#call`, before the
-        # isolation decision — not here.
-        ctx.instance = step(:hydrate_parent) do
-          parent(ctx.repository, ctx.aggregate, ctx.entity_name, ctx.command_name, ctx.args, ctx.route)
-        end
-      end
-
-      def step_locate_element(ctx)
-        ctx.element = step(:locate_element) do
-          EntityElement.locate_chain(ctx.aggregate, ctx.chain, ctx.instance, ctx.args, ctx.command_name, ctx.route)
-        end
-        # `view` was hydrated once, here, into its own state hash
-        # (Value.hydrate builds a fresh Hash — never aliased with `element`)
-        # — exactly right for enforce_givens, which must read pre-mutation.
-        ctx.view = Instance.new(aggregate: ctx.entity, id: EntityElement.element_identity(ctx.entity, ctx.element).to_s,
-                                state: ctx.element)
-      end
-
-      # Enforces this command's `given`s and correction-target admissibility.
-      # Checked against the parent aggregate, never the entity view — every
-      # emitted event is stamped with the root aggregate's name and the
-      # parent record's id, regardless of dispatch level.
-      def step_enforce_givens(ctx)
-        step(:enforce_givens) do
-          ctx.correction_bindings = @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command, domain: ctx.domain)
-          @rules.enforce_givens(ctx.view, ctx.command, ctx.args, domain: ctx.domain, declaring: ctx.entity, parent: ctx.instance,
-                                correction: ctx.correction_bindings)
-        end
-      end
-
-      def step_admissible_transition(ctx)
-        ctx.transition = step(:admissible_transition) { @rules.admissible_transition(ctx.entity, ctx.command, ctx.view) }
-      end
-
       def step_apply_mutations(ctx)
         ctx.old_element = ctx.element.dup unless ctx.command.ensures.empty?
-        step(:apply_mutations) do
-          pre = ctx.element.dup # the update set reads the element as it stood before mutation
-          ctx.command.mutations.each do |mutation|
-            EntityElement.apply_to_element(@rules, ctx.aggregate, ctx.entity, ctx.element, mutation, ctx.args, pre)
-          end
+        step(:apply_mutations) { mutate_element(ctx) }
+      end
+
+      def mutate_element(ctx)
+        pre = ctx.element.dup # the update set reads the element as it stood before mutation
+        ctx.command.mutations.each do |mutation|
+          EntityElement.apply_to_element(@rules, ctx.aggregate, ctx.entity, ctx.element, mutation, ctx.args, pre)
         end
       end
 
@@ -218,73 +166,6 @@ module Hecks
         step(:advance_lifecycle) { ctx.element[ctx.entity.lifecycle.field] = ctx.transition.target }
       end
 
-      # An ensures reads the settled record, so it needs a view hydrated from
-      # `element` as it stands now, mutations included — unlike `view` above,
-      # built once and read pre-mutation by enforce_givens.
-      def step_enforce_ensures(ctx)
-        step(:enforce_ensures) do
-          settled = Instance.new(aggregate: ctx.entity, id: ctx.view.id, state: ctx.element)
-          # `correction:` reuses the `as:`-bound bindings `step_enforce_givens`
-          # already located; `|| {}` covers a command with no `corrects`
-          # mutation, where `ctx.correction_bindings` may be unset.
-          @rules.enforce_ensures(settled, ctx.command, ctx.args, old: ctx.old_element, domain: ctx.domain, parent: ctx.instance,
-                                 correction: ctx.correction_bindings || {})
-        end
-      end
-
-      # Enforces the parent aggregate's own invariants — there is no separate
-      # "entity invariant" concept (ADR 0025 scopes `invariant` to the aggregate).
-      def step_enforce_invariants(ctx)
-        step(:enforce_invariants) { @rules.enforce_invariants(ctx.instance, ctx.aggregate, domain: ctx.domain) }
-      end
-
-      # `dry_run:` skips only the persist — the reference-existence check
-      # above stays unconditional either way.
-      def step_save(ctx)
-        step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state) }
-
-        return if ctx.dry_run
-
-        step(:save) do
-          # `expected_version:` is nil for a non-CAS repository or an instance
-          # never read from storage — either falls through to a plain save.
-          ctx.persistence_outcome = ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
-          if ctx.persistence_outcome.status == :stale
-            # Intentionally not a `RefusalWording.render` call — see
-            # `Runtime::StaleWrite`'s own comment.
-            raise(StaleWrite,
-                  "#{ctx.command.hecks_name} on #{ctx.aggregate.hecks_name} " \
-                  "(#{Identity.reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance.id)}) lost a race — " \
-                  "another write committed against this record after it was read")
-          end
-        end
-      end
-
-      # `dry_run:` skips this too — nothing was committed, so `ctx.result`
-      # stays nil and `Dispatcher#dry_run?` never reads it.
-      def step_emit(ctx)
-        return if ctx.dry_run
-
-        ctx.result = step(:emit) { @rules.emit(ctx.command, ctx.domain, ctx.aggregate, ctx.instance, ctx.args, ctx.repository) }
-      end
-
-      # Finds the parent aggregate: the declared identity first, then a bare
-      # `id:` for a record the caller derived itself.
-      def parent(repository, aggregate, entity_name, command_name, args, route = nil)
-        parent_id = route&.aggregate ||
-                    Identity.of(aggregate, args) ||
-                    Identity.from(aggregate, args, :id) ||
-                    raise(NotFound, RefusalWording.render_site("NotFound", "entity_parent_no_identity",
-                                                               command: command_name, aggregate: aggregate.hecks_name,
-                                                               entity: entity_name, identity: Identity.reading(aggregate)))
-        found = repository.find(parent_id) ||
-                raise(NotFound, RefusalWording.render_site("NotFound", "record_missing",
-                                                           aggregate: aggregate.hecks_name,
-                                                           identity:  Identity.reading(aggregate),
-                                                           offered:   Rendering.describe(parent_id)))
-        found.dup
-      end
-
       # Entity element helpers (`locate_chain`, `element_of`, `element_identity`,
       # `apply_to_element`) live in `Runtime::EntityElement`, shared with
       # `CommandInterpreter#delegate_to_entity`.