hecks 3.5.0 → 3.7.0

data/lib/hecks/runtime/outbox.rb

@@ -61,220 +61,9 @@ module Hecks
         else value
         end
       end
-
-      # Resolves each event's consumers once, at enqueue time, in the same
-      # order a direct dispatch would react to them (policies then sagas).
-      module Fanout
-        module_function
-
-        # One UID per event, kept off `Event#to_h` (parity/golden specs pin
-        # its shape) — policy and saga rows for the same event share it, which
-        # is what makes `delivery_id` mean "this fact, this consumer".
-        def rows_for(registry, events, domain)
-          uids = events.to_h { |event| [event, SecureRandom.uuid] }
-          events.flat_map do |event|
-            policies(registry, event, domain, uids[event]) + sagas(registry, event, domain, uids[event])
-          end
-        end
-
-        def policies(registry, event, domain, uid)
-          emitting = Naming.demodulise(event.aggregate)
-          Outbox.bluebooks_home_first(registry, domain).flat_map do |bluebook|
-            bluebook.policies.filter_map do |policy|
-              next unless policy.event_name == event.name
-              next unless policy.event_qualifier.nil? || policy.event_qualifier == emitting
-
-              consumer = "policy:#{bluebook.name}::#{policy.name}"
-              Row.new(delivery_id: "#{uid}/#{consumer}", event_uid: uid, domain: domain,
-                      kind: kind_for(registry, policy, bluebook.name), consumer: consumer,
-                      event: Outbox.serialize_event(event), status: "pending", attempts: 0)
-            end
-          end
-        end
-
-        # A saga only ever reacts within its own domain.
-        def sagas(registry, event, domain, uid)
-          bluebook = registry.bluebook(domain)
-          return [] unless bluebook
-
-          bluebook.process_managers.select { |process_manager| listens?(process_manager, event) }.map do |process_manager|
-            consumer = "saga:#{bluebook.name}::#{process_manager.name}"
-            Row.new(delivery_id: "#{uid}/#{consumer}", event_uid: uid, domain: domain, kind: "reaction",
-                    consumer: consumer, event: Outbox.serialize_event(event), status: "pending", attempts: 0)
-          end
-        end
-
-        def listens?(process_manager, event)
-          process_manager.starts_on == event.name || process_manager.ends_on == event.name ||
-            !process_manager.handler_for(event.name).nil?
-        end
-
-        # An "effect" is a reaction whose trigger resolves to an outbound port
-        # operation, claimed right before the adapter call and settled right
-        # after; everything else is a plain "reaction".
-        def kind_for(registry, policy, home_domain)
-          target = "#{policy.target_domain || home_domain}::#{policy.trigger_command}"
-          parsed = Naming.split_verb(target)
-          return "reaction" unless parsed
-
-          target_domain, aggregate_name, path = parsed
-          head, rest = path.to_s.split(".", 2)
-          return "reaction" unless rest
-
-          aggregate = registry.bluebook(target_domain)&.aggregate(aggregate_name)
-          port = aggregate&.port(head)
-          port&.operation(rest)&.outbound? ? "effect" : "reaction"
-        end
-      end
-
-      # One per Dispatcher: enqueues rows into a repository's outbox, drains
-      # them inline, and redrives whatever a crash left behind.
-      class Relay
-        attr_reader :registry, :log
-
-        # Additive and Ruby-only, unlike `saga_log`/`reaction_log`, which the
-        # Rust kernel ports byte-for-byte (spec/rust_conformance_spec.rb).
-        def initialize(registry)
-          @registry = registry
-          @log      = []
-        end
-
-        # Re-attaching (a second Dispatcher fronting the same registry) is
-        # safe: both dispatchers share this relay's log and every store.
-        def attach(policies:, sagas:)
-          @policies = policies
-          @sagas    = sagas
-          self
-        end
-
-        def attached? = !@policies.nil?
-
-        # Called inside the save transaction for command/entity paths, and
-        # outside one for port operations (which save nothing). Returns nil
-        # when the repository has no outbox — callers then react directly.
-        def enqueue(repository, events, domain)
-          return nil unless repository.outbox?
-          return [] if events.empty?
-
-          rows = Fanout.rows_for(@registry, events, domain)
-          rows.each { |row| row.aggregate = repository.aggregate.storage_name }
-          repository.outbox_enqueue(rows)
-        end
-
-        # `rows` nil means no outbox on this repository — react directly,
-        # the pre-outbox path.
-        def deliver(rows, events, domain, repository)
-          if rows.nil?
-            # Per event, in `emits` order — its policies, then its sagas
-            # (C10.2, docs/semantics/bluebook-semantics.md).
-            events.each do |event|
-              @policies.react(event, domain)
-              @sagas.advance(event, domain)
-            end
-            return
-          end
-
-          rows.each { |row| deliver_row(row, repository) }
-        end
-
-        # Claim, run the consumer, then settle. A failed claim means another
-        # relay already has this row.
-        def deliver_row(row, repository)
-          return false unless repository.outbox_claim(row.id)
-
-          row.status = "claimed"
-          begin
-            run_consumer(row)
-            repository.outbox_settle(row.id, status: "delivered")
-            row.status = "delivered"
-            true
-          rescue StandardError => e
-            # A DOMAIN_REFUSAL never reaches here (PolicyInterpreter and
-            # SagaInterpreter both rescue it as a recorded, undelivered
-            # reaction) — anything here is a defect in the relay's own path.
-            repository.outbox_settle(row.id, status: "failed", error: "#{e.class}: #{e.message}")
-            row.status = "failed"
-            row.error  = "#{e.class}: #{e.message}"
-            @log << { outbox: row.delivery_id, consumer: row.consumer, delivered: false, defect: true,
-                      reason: row.error }
-            false
-          end
-        end
-
-        # Every row across every bound store, newest last.
-        def rows(status: nil)
-          stores.flat_map { |repository| repository.outbox_rows(status: status) }
-        end
-
-        # `pending` rows are always safe to redrive (never claimed yet).
-        # `claimed` rows are only surfaced — redelivering a maybe-already-run
-        # consumer needs an explicit `claimed: true`.
-        def redrive!(claimed: false)
-          redriven = []
-          stores.each do |repository|
-            repository.outbox_rows(status: "pending").each do |row|
-              redriven << row if deliver_row(row, repository)
-            end
-            repository.outbox_rows(status: "claimed").each do |row|
-              if claimed
-                repository.outbox_settle(row.id, status: "pending")
-                row.status = "pending"
-                redriven << row if deliver_row(row, repository)
-              else
-                warn_stalled(row)
-              end
-            end
-          end
-          redriven
-        end
-
-        private
-
-        def run_consumer(row)
-          raise WiringError, "outbox relay has no dispatcher attached — nothing can run #{row.consumer}" unless attached?
-
-          event = Outbox.event_from(row.event)
-          kind, fqn = row.consumer.split(":", 2)
-          home, name = fqn.split("::", 2)
-          case kind
-          when "policy"
-            policy = @registry.bluebook(home)&.policies&.find { |candidate| candidate.name == name } ||
-                     raise(WiringError, "outbox row #{row.delivery_id} names policy #{fqn}, which no bluebook declares")
-            @policies.react(event, row.domain, only: [policy, home], event_uid: row.event_uid)
-          when "saga"
-            process_manager = @registry.bluebook(home)&.process_managers&.find { |candidate| candidate.name == name } ||
-                              raise(WiringError,
-                                    "outbox row #{row.delivery_id} names process_manager #{fqn}, which no bluebook declares")
-            @sagas.advance(event, row.domain, only: process_manager)
-          else
-            raise WiringError, "outbox row #{row.delivery_id} has an unknown consumer kind #{kind.inspect}"
-          end
-        end
-
-        def warn_stalled(row)
-          warn "[hecks] outbox row #{row.delivery_id} (#{row.consumer} on #{row.event[:name]} for " \
-               "#{row.event[:aggregate]}##{row.event[:id]}) was claimed before the last crash/restart and never " \
-               "settled — its #{row.kind} may or may not have actually run. hecks does not auto-redrive a claimed " \
-               "row (the outcome is unknown, and redelivering it could double the effect); inspect it and " \
-               "redrive by hand with `runtime.outbox.redrive!(claimed: true)` once you know it is safe."
-          @log << { outbox: row.delivery_id, consumer: row.consumer, kind: row.kind, stalled: true,
-                    event: row.event[:name], aggregate: row.event[:aggregate], id: row.event[:id] }
-        end
-
-        # Bluebooks, not hecksagons: a domain with no hecksagon is still
-        # bound to the default Memory adapter. An aggregate a hecksagon left
-        # unbound raises WiringError here and is skipped.
-        def stores
-          @registry.bluebooks.each_value.flat_map do |bluebook|
-            bluebook.aggregates.filter_map do |aggregate|
-              repository = @registry.repository(bluebook.name, aggregate)
-              repository if repository.outbox?
-            rescue WiringError
-              nil
-            end
-          end
-        end
-      end
     end
   end
 end
+
+require_relative "outbox/fanout"
+require_relative "outbox/relay"

data/lib/hecks/runtime/policy_interpreter/arguments.rb

@@ -0,0 +1,67 @@
+require_relative "../reaction_invocation"
+
+module Hecks
+  module Runtime
+    class PolicyInterpreter
+      # What a policy's trigger is given: the event payload or its `with:` projection, the
+      # emitting record's identity, and the invocation the door re-enters with. Mixed into
+      # {PolicyInterpreter}.
+      module Arguments
+        private
+
+        # What the trigger is given: the whole event payload verbatim when no `with:` is
+        # declared, otherwise the projection (a Symbol names a payload field, anything else
+        # is a literal). `extra` is a fan-out's row key, merged into the source before the
+        # projection so a `with:` can name the row it acts on.
+        def trigger_args(policy, event, extra = {})
+          payload = event.payload.transform_keys(&:to_sym).merge(extra)
+          return payload unless ReactionInvocation.projection_declared?(policy)
+
+          projected_args(policy, event, emitter_identity(event).merge(payload))
+        end
+
+        def projected_args(policy, event, payload)
+          args = ReactionInvocation.resolve_mapping(
+            with_spec: policy.with_spec,
+            scopes:    [["event payload and fan-out row", payload]],
+            label:     "#{policy.name}'s trigger"
+          )
+
+          # Raw inputs kept for Properties.dispatch_binding_fidelity's re-derivation.
+          @registry.policy_dispatch_log << { policy: policy.name, on: event.name, payload: payload,
+                                              with_spec: policy.with_spec, args: args }
+          args
+        end
+
+        # The emitting record's identity, offered to an explicit `with:` projection under
+        # the emitting aggregate's identity heads (never over a payload value). Without it
+        # a cross-aggregate reaction cannot say which record to address. The build-time
+        # validator admits the same names (`BluebookBuilder.check_with_spec!`).
+        def emitter_identity(event)
+          return {} if event.id.nil? || event.id.to_s.empty?
+
+          construct = emitting_construct(event)
+          return {} unless construct
+
+          construct.identity_heads.to_h { |head| [head.to_sym, event.id] }
+        end
+
+        # The aggregate that emitted `event`, when its bluebook is loaded.
+        def emitting_construct(event)
+          domain, bare_name = event.aggregate.to_s.split("::", 2)
+          bare_name && @registry.bluebook(domain)&.aggregate(bare_name)
+        end
+
+        def reaction_invocation(target, args, policy, event)
+          ReactionInvocation.build(
+            registry:        @registry,
+            verb:            target,
+            projected:       args,
+            explicit:        ReactionInvocation.projection_declared?(policy),
+            source_receiver: { aggregate: event.aggregate, identity: event.id }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/policy_interpreter/fan_out.rb

@@ -0,0 +1,96 @@
+require_relative "../../naming"
+require_relative "../errors"
+require_relative "../query_interpreter"
+require_relative "../refusal_wording"
+
+module Hecks
+  module Runtime
+    class PolicyInterpreter
+      # A `for_each` policy: asks a query which rows the event concerns, and fires the trigger
+      # once per row. Mixed into {PolicyInterpreter}.
+      module FanOut
+        private
+
+        # Runs the `for_each` query against the event payload and fires the trigger once
+        # per row, addressing each row by `addressing_key_for`. A refusal is recorded per
+        # row and the fan-out continues; a crash resolving the query or an unaddressable
+        # target is one top-level defect for the policy.
+        def deliver_for_each(policy, event, domain, target, record)
+          return nil unless where_holds?(policy, event)
+
+          rows, reference_key = for_each_rows(policy, event, domain, target)
+          Array(rows).map do |row|
+            args = trigger_args(policy, event, reference_key => row[:id])
+            deliver_for_each_row(target, record.merge(for_row: row[:id]), args, policy, event)
+          end
+        rescue *DOMAIN_REFUSALS => e
+          record.merge(delivered: false, reason: e.message)
+        rescue StandardError => e
+          defect(policy, event, record, e, "resolving for_each #{policy.for_each}")
+        end
+
+        # The rows the `for_each` query answers, and the key by which the trigger addresses a row.
+        def for_each_rows(policy, event, domain, target)
+          query_domain, aggregate_name, query_name = policy.for_each_route(domain)
+          aggregate = resolve_query_aggregate(query_domain, aggregate_name, policy.for_each)
+          # The query reads the event, never the `with:` projection: it asks which rows.
+          query_args = for_each_query_args(aggregate.query(query_name), event)
+          rows = QueryInterpreter.new(@registry).call(query_domain, aggregate, query_name, query_args)
+          [rows, addressing_key_for(target, aggregate_name)]
+        end
+
+        # The event's own identity is not in its payload, so a query argument named
+        # after an identity head of the emitting aggregate is filled from `event.id`.
+        # Without it the query silently sees nothing. Never overrides a payload value.
+        def for_each_query_args(query, event)
+          args = event.payload.transform_keys(&:to_sym)
+          construct = query && emitting_construct(event)
+          return args unless construct
+
+          lent_attributes(query, construct, args).each { |attribute| args[attribute.name] = event.id }
+          args
+        end
+
+        # The query arguments named for an identity head the payload does not already carry.
+        def lent_attributes(query, construct, args)
+          heads = construct.identity_heads.map(&:to_s)
+          query.attributes.select { |attribute| heads.include?(attribute.name.to_s) && !args.key?(attribute.name) }
+        end
+
+        # Resolves `target` back to its declared command and asks it how a row of
+        # `aggregate_name` addresses it. Raises rather than guessing when the command is
+        # unresolvable or cannot be addressed: a domain-authoring mistake to surface.
+        def addressing_key_for(target, aggregate_name)
+          target_domain, target_aggregate_name, target_command_name = Naming.split_verb(target)
+          command = @registry.bluebook(target_domain)&.aggregate(target_aggregate_name)&.command(target_command_name)
+          raise UnknownVerb, "for_each's own trigger #{target.inspect} does not resolve to a declared command" unless command
+
+          key = command.addressing_key_for(aggregate_name)
+          return key if key
+
+          raise ArgumentError,
+                "#{target} cannot be addressed by a row of #{aggregate_name} — it declares no self-reference to " \
+                "#{aggregate_name} and no reference-typed attribute targeting it"
+        end
+
+        def deliver_for_each_row(target, row_record, args, policy, event)
+          return depth_refusal(row_record) if @door.reaction_depth_reached?
+
+          # The row key is already merged by `trigger_args`, so a projection can name it.
+          @door.reenter(target, **reaction_invocation(target, args, policy, event))
+          row_record.merge(delivered: true)
+        rescue *DOMAIN_REFUSALS => e
+          row_record.merge(delivered: false, reason: e.message)
+        end
+
+        def resolve_query_aggregate(domain, aggregate_name, verb)
+          bluebook = @registry.bluebook(domain) ||
+                     raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb))
+          bluebook.aggregate(aggregate_name) ||
+            raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_aggregate",
+                                                          domain: domain, aggregate: aggregate_name))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/policy_interpreter.rb

@@ -4,6 +4,8 @@ require_relative "query_interpreter"
 require_relative "reaction_invocation"
 require_relative "refusal_wording"
 require_relative "value"
+require_relative "policy_interpreter/fan_out"
+require_relative "policy_interpreter/arguments"
 require_relative "../bluebook/expression/evaluator"
 
 module Hecks
@@ -11,6 +13,9 @@ module Hecks
     # Fires the declared `policy` reactions triggered by one just-emitted event,
     # recording every outcome on the reaction log.
     class PolicyInterpreter
+      include FanOut
+      include Arguments
+
       attr_reader :registry
 
       # @param registry [Runtime::Registry] the booted registry whose loaded
@@ -79,156 +84,36 @@ module Hecks
         record = { policy: policy.name, on: event.name, trigger: target }
 
         return deliver_for_each(policy, event, domain, target, record) unless policy.for_each.to_s.empty?
-        return nil unless where_holds?(policy, event)
 
-        if @door.reaction_depth_reached?
-          return record.merge(delivered: false,
-                              reason:    "reaction depth #{@door.max_reaction_depth} reached")
-        end
-
-        args = trigger_args(policy, event)
-        @door.reenter(target, **reaction_invocation(target, args, policy, event))
-        record.merge(delivered: true)
+        fire(policy, event, target, record)
       rescue *DOMAIN_REFUSALS => e
         record.merge(delivered: false, reason: e.message)
       rescue StandardError => e
-        # A defect, not a refusal: recorded with `defect: true` and warned, never
-        # re-raised. The emitting command has already persisted, so propagating would
-        # only fail an unrelated caller. See DOMAIN_REFUSALS for why the two stay apart.
-        warn "[hecks] defect in reaction — policy #{policy.name} on #{event.name} " \
-             "firing #{target}: #{e.class}: #{e.message}"
-        record.merge(delivered: false, reason: e.message, defect: true, error_class: e.class.name)
+        defect(policy, event, record, e, "firing #{target}")
       end
 
-      # Runs the `for_each` query against the event payload and fires the trigger once
-      # per row, addressing each row by `addressing_key_for`. A refusal is recorded per
-      # row and the fan-out continues; a crash resolving the query or an unaddressable
-      # target is one top-level defect for the policy.
-      def deliver_for_each(policy, event, domain, target, record)
+      # Fires the trigger once, unless the `where` declines it or the cascade is as deep as it
+      # may go.
+      def fire(policy, event, target, record)
         return nil unless where_holds?(policy, event)
+        return depth_refusal(record) if @door.reaction_depth_reached?
 
-        query_domain, aggregate_name, query_name = policy.for_each_route(domain)
-        aggregate = resolve_query_aggregate(query_domain, aggregate_name, policy.for_each)
-        # The query reads the event, never the `with:` projection: it asks which rows.
-        query_args    = for_each_query_args(aggregate.query(query_name), event)
-        rows          = QueryInterpreter.new(@registry).call(query_domain, aggregate, query_name, query_args)
-        reference_key = addressing_key_for(target, aggregate_name)
-
-        Array(rows).map do |row|
-          deliver_for_each_row(target, record, trigger_args(policy, event, reference_key => row[:id]), row, policy, event)
-        end
-      rescue *DOMAIN_REFUSALS => e
-        record.merge(delivered: false, reason: e.message)
-      rescue StandardError => e
-        warn "[hecks] defect in reaction — policy #{policy.name} on #{event.name} " \
-             "resolving for_each #{policy.for_each}: #{e.class}: #{e.message}"
-        record.merge(delivered: false, reason: e.message, defect: true, error_class: e.class.name)
-      end
-
-      # The event's own identity is not in its payload, so a query argument named
-      # after an identity head of the emitting aggregate is filled from `event.id`.
-      # Without it the query silently sees nothing. Never overrides a payload value.
-      def for_each_query_args(query, event)
-        args = event.payload.transform_keys(&:to_sym)
-        return args unless query
-
-        domain, bare_name = event.aggregate.to_s.split("::", 2)
-        construct = bare_name && @registry.bluebook(domain)&.aggregate(bare_name)
-        return args unless construct
-
-        heads = construct.identity_heads.map(&:to_s)
-        query.attributes.each do |attribute|
-          next if args.key?(attribute.name)
-          next unless heads.include?(attribute.name.to_s)
-
-          args[attribute.name] = event.id
-        end
-        args
-      end
-
-      # What the trigger is given: the whole event payload verbatim when no `with:` is
-      # declared, otherwise the projection (a Symbol names a payload field, anything else
-      # is a literal). `extra` is a fan-out's row key, merged into the source before the
-      # projection so a `with:` can name the row it acts on.
-      def trigger_args(policy, event, extra = {})
-        payload = event.payload.transform_keys(&:to_sym).merge(extra)
-        return payload unless ReactionInvocation.projection_declared?(policy)
-
-        payload = emitter_identity(event).merge(payload)
-
-        args = ReactionInvocation.resolve_mapping(
-          with_spec: policy.with_spec,
-          scopes:    [["event payload and fan-out row", payload]],
-          label:     "#{policy.name}'s trigger"
-        )
-
-        # Raw inputs kept for Properties.dispatch_binding_fidelity's re-derivation.
-        @registry.policy_dispatch_log << { policy: policy.name, on: event.name, payload: payload,
-                                            with_spec: policy.with_spec, args: args }
-        args
-      end
-
-      # The emitting record's identity, offered to an explicit `with:` projection under
-      # the emitting aggregate's identity heads (never over a payload value). Without it
-      # a cross-aggregate reaction cannot say which record to address. The build-time
-      # validator admits the same names (`BluebookBuilder.check_with_spec!`).
-      def emitter_identity(event)
-        return {} if event.id.nil? || event.id.to_s.empty?
-
-        domain, bare_name = event.aggregate.to_s.split("::", 2)
-        construct = bare_name && @registry.bluebook(domain)&.aggregate(bare_name)
-        return {} unless construct
-
-        construct.identity_heads.to_h { |head| [head.to_sym, event.id] }
-      end
-
-      # Resolves `target` back to its declared command and asks it how a row of
-      # `aggregate_name` addresses it. Raises rather than guessing when the command is
-      # unresolvable or cannot be addressed: a domain-authoring mistake to surface.
-      def addressing_key_for(target, aggregate_name)
-        target_domain, target_aggregate_name, target_command_name = Naming.split_verb(target)
-        command = @registry.bluebook(target_domain)&.aggregate(target_aggregate_name)&.command(target_command_name)
-        raise UnknownVerb, "for_each's own trigger #{target.inspect} does not resolve to a declared command" unless command
-
-        key = command.addressing_key_for(aggregate_name)
-        return key if key
-
-        raise ArgumentError,
-              "#{target} cannot be addressed by a row of #{aggregate_name} — it declares no self-reference to " \
-              "#{aggregate_name} and no reference-typed attribute targeting it"
-      end
-
-      def deliver_for_each_row(target, record, args, row, policy, event)
-        row_record = record.merge(for_row: row[:id])
-
-        if @door.reaction_depth_reached?
-          return row_record.merge(delivered: false,
-                                  reason:    "reaction depth #{@door.max_reaction_depth} reached")
-        end
-
-        # The row key is already merged by `trigger_args`, so a projection can name it.
+        args = trigger_args(policy, event)
         @door.reenter(target, **reaction_invocation(target, args, policy, event))
-        row_record.merge(delivered: true)
-      rescue *DOMAIN_REFUSALS => e
-        row_record.merge(delivered: false, reason: e.message)
+        record.merge(delivered: true)
       end
 
-      def reaction_invocation(target, args, policy, event)
-        ReactionInvocation.build(
-          registry:        @registry,
-          verb:            target,
-          projected:       args,
-          explicit:        ReactionInvocation.projection_declared?(policy),
-          source_receiver: { aggregate: event.aggregate, identity: event.id }
-        )
+      def depth_refusal(record)
+        record.merge(delivered: false, reason: "reaction depth #{@door.max_reaction_depth} reached")
       end
 
-      def resolve_query_aggregate(domain, aggregate_name, verb)
-        bluebook = @registry.bluebook(domain) ||
-                   raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb))
-        bluebook.aggregate(aggregate_name) ||
-          raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_aggregate",
-                                                        domain: domain, aggregate: aggregate_name))
+      # A defect, not a refusal: recorded with `defect: true` and warned, never
+      # re-raised. The emitting command has already persisted, so propagating would
+      # only fail an unrelated caller. See DOMAIN_REFUSALS for why the two stay apart.
+      def defect(policy, event, record, error, activity)
+        warn "[hecks] defect in reaction — policy #{policy.name} on #{event.name} " \
+             "#{activity}: #{error.class}: #{error.message}"
+        record.merge(delivered: false, reason: error.message, defect: true, error_class: error.class.name)
       end
     end
   end

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -84,13 +84,16 @@ module Hecks
       # needs data that lives on the record, and an event payload carries only arguments.
       # Arguments win over state.
       def ask(ctx)
-        payload = held_state(ctx).merge(materialise(ctx.args))
-        answer  = adapter_for(ctx).public_send(Naming.snake(ctx.operation.hecks_name), **payload)
-        announce(ctx, ctx.operation.answers, ctx.args.merge(spread(answer)))
+        announce(ctx, ctx.operation.answers, ctx.args.merge(spread(adapter_answer(ctx))))
       rescue StandardError => e
         announce(ctx, ctx.operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
       end
 
+      def adapter_answer(ctx)
+        payload = held_state(ctx).merge(materialise(ctx.args))
+        adapter_for(ctx).public_send(Naming.snake(ctx.operation.hecks_name), **payload)
+      end
+
       # The answer is spread, not nested: a policy re-enters its target with the event
       # payload verbatim and cannot reach inside a key. The adapter's keys are therefore the
       # arguments of the reacting command, in the shape the runtime coerces
@@ -133,13 +136,7 @@ module Hecks
       def materialise(args) = Value.materialize(args)
 
       def announce(ctx, event_name, payload)
-        event = Event.new(
-          name:        event_name,
-          aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
-          id:          ctx.route.aggregate,
-          payload:     payload,
-          occurred_at: Time.now.utc.iso8601
-        )
+        event = event_for(ctx, event_name, payload)
         @registry.event_log << event
         [event]
       end
@@ -148,17 +145,21 @@ module Hecks
       # event is stamped with the coerced reference to the owning aggregate (already a plain id).
       def emit(ctx)
         ctx.operation.emits.map do |event_name|
-          event = Event.new(
-            name:        event_name,
-            aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
-            id:          ctx.route.aggregate,
-            payload:     ctx.args,
-            occurred_at: Time.now.utc.iso8601
-          )
+          event = event_for(ctx, event_name, ctx.args)
           @registry.event_log << event.emit!
           event
         end
       end
+
+      def event_for(ctx, event_name, payload)
+        Event.new(
+          name:        event_name,
+          aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
+          id:          ctx.route.aggregate,
+          payload:     payload,
+          occurred_at: Time.now.utc.iso8601
+        )
+      end
     end
   end
 end