hecks 5.0.0 → 7.0.0

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

@@ -1,3 +1,4 @@
+require_relative "../collecting"
 require_relative "../errors"
 require_relative "../instance"
 require_relative "../entity_element"
@@ -13,12 +14,24 @@ module Hecks
       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)
+        Target = Struct.new(:entity, :command, :args, :element, :view) do
+          # @return [Array] the target command's ensures clauses
+          def ensures = command.ensures
+
+          # @return [Array] the target command's mutations, in declaration order
+          def mutations = command.mutations
+
+          # @return [String] the located element's identity
+          def element_id = view.id
+
+          # @return [Symbol, String, nil] the entity's state field, nil without a lifecycle
+          def lifecycle_field = entity.lifecycle_field
+        end
 
         private
 
         def step_delegate_to_entity(ctx)
-          delegation = ctx.command.mutations.find { |mutation| mutation.op == :delegate }
+          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
@@ -28,18 +41,35 @@ module Hecks
         end
 
         # Runs the target entity command's givens, transition, mutations and ensures against the
-        # element, answering the command and arguments `step_emit` will emit.
+        # element, answering the command and arguments `step_emit` will emit, or nil when a
+        # validation recorded a refusal in the target's givens or ensures.
         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
+          target = locate_delegate(ctx, delegation)
+          return unless delegate_stage_held?(:givens) { enforce_delegate_givens(ctx, target) }
+
+          transition  = @rules.admissible_transition(target.entity, target.command, target.view)
+          old_element = target.ensures.empty? ? nil : target.element.dup
           mutate_delegate(ctx, target, transition)
-          enforce_delegate_ensures(ctx, target, old_element)
+          return unless delegate_stage_held?(:ensures) { enforce_delegate_ensures(ctx, target, old_element) }
+
           [target.command, target.args]
         end
 
+        # Runs one of the target's own rule stages. A refusal it records while validating is placed
+        # in that stage, as the same rule's refusal is in a direct dispatch of the entity command,
+        # and finishes the delegation there, as a refused stage finishes any validating run.
+        #
+        # @param stage [Symbol] the `DispatchStage` the target's rules belong to
+        # @yield the stage's rules
+        # @return [Boolean] whether the stage recorded no refusal
+        def delegate_stage_held?(stage, &)
+          recorded = Collecting.refusals&.size
+          Collecting.at_stage(stage, &)
+          Collecting.refusals&.size == recorded
+        end
+
         def enforce_delegate_ensures(ctx, target, old_element)
-          settled = Instance.new(aggregate: target.entity, id: target.view.id, state: target.element)
+          settled = Instance.new(aggregate: target.entity, id: target.element_id, state: target.element)
           @rules.enforce_ensures(settled, target.command, target.args, old: old_element, domain: ctx.domain, parent: ctx.instance)
         end
 
@@ -51,19 +81,17 @@ module Hecks
           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)
+        def enforce_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|
+          target.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
+          target.element[target.lifecycle_field] = transition.target if transition
         end
 
         # The entity and command a `delegates_to` mutation names, resolved once so
@@ -72,16 +100,17 @@ module Hecks
           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 " \
+                           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 " \
+          aggregate = ctx.aggregate
+          aggregate.entities.find { |e| e.hecks_name == entity_name } ||
+            raise(WiringError, "#{ctx.command_hecks_name} delegates_to #{entity_name}." \
+                               "#{command_name}, but #{aggregate.hecks_name} has no " \
                                "entity named #{entity_name.inspect}")
         end
 

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

@@ -13,12 +13,12 @@ module Hecks
       module Hydration
         private
 
-        # Picks the hydration the command's dependency plan allows.
+        # Picks the hydration the command's dependency plan allows. A command that declares a
+        # `reference_to` acts on a record that must already exist, however complete its payload,
+        # as the Rust kernel's `Hydrate::Act` does; only a creating command may build one.
         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)
+          if ctx.command.creates? && ctx.plan.complete_state?
+            ctx.plan.state_independent? ? hydrate_complete_state(ctx) : hydrate_prior_or_initial(ctx)
           elsif legacy_implicit_creation?(ctx)
             hydrate_legacy_creation(ctx)
           else
@@ -28,7 +28,7 @@ module Hecks
 
         # 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)
+          id = ctx.route ? ctx.routed_identity : acting_identity(ctx)
           (ctx.repository.find(id) || raise_record_missing(ctx.aggregate, id)).dup
         end
 
@@ -40,7 +40,7 @@ module Hecks
             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,
+                                                       command: ctx.command_hecks_name, aggregate: aggregate.hecks_name,
                                                        identity: identity_reading(aggregate)))
         end
 
@@ -63,37 +63,33 @@ module Hecks
 
         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)
+          # 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.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.
+        # A complete creating command that still reads prior state (lifecycle guards are the
+        # common case) — read once, so an occupied identity refuses before anything is built.
         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?
+          # dependent creating command (one with a `given` on its own prior state).
+          raise_already_exists(ctx.command, ctx.aggregate, id) if found
 
-          found ? found.dup : fresh_instance(ctx, id)
+          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)
+          ctx.routed_identity || derived || raise_creating_no_identity(ctx.command, ctx.aggregate)
         end
 
         def refuse_route_mismatch(command, route, derived)
@@ -115,10 +111,11 @@ module Hecks
         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)))
+          message = RefusalWording.render_site("NotFound", "record_missing",
+                                               aggregate: aggregate.hecks_name,
+                                               identity:  identity_reading(aggregate),
+                                               offered:   Rendering.describe(id))
+          raise(NotFound, RefusalWording.with_creator_hint(message, aggregate))
         end
 
         def raise_creating_no_identity(command, aggregate)

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

@@ -62,7 +62,8 @@ module Hecks
 
           coerce_entity_fields(aggregate, entity, fields)
           assign_entity_identity(aggregate, entity, current, fields)
-          fields[entity.lifecycle.field] ||= entity.lifecycle.default if entity.lifecycle
+          lifecycle = entity.lifecycle
+          fields[lifecycle.field] ||= lifecycle.default if 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)

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

@@ -16,10 +16,11 @@ module Hecks
         # both are validation, not persistence, and a real dispatch would
         # refuse on either before ever writing.
         def step_save(ctx)
-          step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state) }
+          step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.state) }
 
           if ctx.dry_run
             step(:save) { check_dry_run_creates_duplicate(ctx) }
+            DryRunPlan.write(ctx.aggregate, ctx.instance)
           else
             step(:save) { persist_and_check(ctx) }
           end
@@ -36,9 +37,9 @@ module Hecks
         # deliberately defers this exact check to here.
         def check_dry_run_creates_duplicate(ctx)
           return unless ctx.strategy == DependencyPlanning::ATOMIC_PUT && ctx.command.creates?
-          return unless ctx.repository.find(ctx.instance.id)
+          return unless ctx.repository.find(ctx.instance_id)
 
-          raise_already_exists(ctx.command, ctx.aggregate, ctx.instance.id)
+          raise_already_exists(ctx.command, ctx.aggregate, ctx.instance_id)
         end
 
         def persist_instance(ctx)
@@ -47,19 +48,26 @@ module Hecks
             # this interpreter reading the record first to check — a
             # `repository.find` before every atomic_put would be exactly the
             # read this strategy exists to skip.
-            ctx.repository.atomic_put(ctx.instance, insert_only: ctx.command.creates?)
+            ctx.repository.atomic_put(ctx.instance, insert_only: ctx.command.creates?, mints_era: mints_era?(ctx))
           else
             # `expected_version:` is nil for a brand-new record or a
             # non-CAS repository, either of which falls through to a
-            # plain, unconditional save inside `AppendOnly#save`.
-            ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
+            # plain, unconditional save inside `AppendOnly#save`. `mints_era:`
+            # reaches the journal entry only when this command declares it.
+            ctx.repository.save(ctx.instance, expected_version: ctx.instance_version, mints_era: mints_era?(ctx))
           end
         end
 
+        # The one-write allowance this command's record holds through an unminted boot: the
+        # binding names it (`mints_era` in the world), or the command still says `mints_era true`.
+        def mints_era?(ctx)
+          ctx.command.mints_era? || ctx.repository.mints_era_declared?(ctx.aggregate_hecks_name, ctx.command_hecks_name)
+        end
+
         def raise_for_persistence_outcome!(ctx)
-          case ctx.persistence_outcome.status
+          case ctx.outcome_status
           when :conflicted
-            raise_already_exists(ctx.command, ctx.aggregate, ctx.instance.id)
+            raise_already_exists(ctx.command, ctx.aggregate, ctx.instance_id)
           when :stale
             # Not a declared vocabulary refusal, just a plain, informative
             # message — caught by `#call`'s retry loop, re-raised only once
@@ -69,8 +77,8 @@ module Hecks
         end
 
         def lost_race_wording(ctx)
-          "#{ctx.command.hecks_name} on #{ctx.aggregate.hecks_name} " \
-            "(#{identity_reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance.id)}) lost a race — " \
+          "#{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
 
@@ -81,13 +89,14 @@ module Hecks
         # real reason. Uses the same `RebuildSweep.remote_value` a sweep
         # computes, and runs only at save time, never as a live read mid-dispatch.
         def seed_projected_fields(ctx)
-          return if ctx.aggregate.projected_fields.empty?
+          aggregate = ctx.aggregate
+          return if aggregate.projected_fields.empty?
 
-          ctx.aggregate.projected_fields.each do |field|
-            value = RebuildSweep.remote_value(@registry, ctx.domain, ctx.aggregate, ctx.instance.state, field)
+          aggregate.projected_fields.each do |field|
+            value = RebuildSweep.remote_value(@registry, ctx.domain, aggregate, ctx.state, field)
             next if value.nil?
 
-            ctx.instance.state[field.name] = value
+            ctx.state[field.name] = value
           end
         end
       end

data/lib/hecks/runtime/command_interpreter.rb

@@ -4,6 +4,7 @@ require_relative "command_interpreter/mutation_applier"
 require_relative "command_interpreter/enforcement"
 require_relative "command_interpreter/hydration"
 require_relative "command_interpreter/persisting"
+require_relative "dry_run_plan"
 require_relative "command_interpreter/delegation"
 require_relative "../rendering"
 require_relative "errors"
@@ -14,6 +15,7 @@ require_relative "instance"
 require_relative "refusal_wording"
 require_relative "entity_element"
 require_relative "rebuild_sweep"
+require_relative "dispatch_context"
 
 module Hecks
   module Runtime
@@ -44,7 +46,9 @@ module Hecks
       # the step that sets them runs.
       Context = Struct.new(:domain, :aggregate, :command, :args, :repository, :instance, :transition, :old_state,
                            :result, :correlation, :route, :plan, :strategy, :persistence_outcome, :pending_delegation,
-                           :dry_run, :correction_bindings, :outbox_rows, :invocation)
+                           :dry_run, :correction_bindings, :outbox_rows, :invocation, :dispatch_key) do
+        include DispatchContext
+      end
 
       # @param registry [Runtime::Registry] the booted registry this interpreter reads
       # @param rules [Runtime::CommandRules] the shared rules engine (admissibility,
@@ -62,13 +66,12 @@ module Hecks
       # @param invocation [Runtime::Invocation] the invocation built for this call
       # @param correlation [Hash, nil] saga correlation stamped on emitted events, if any
       # @param dry_run [Boolean] validate every step without saving, emitting or enqueueing
+      # @param dispatch_key [String, nil] a saga dispatch's identity; an applied one runs no step
       # @return [Array] the settled instance, events, plan, persistence outcome, and outbox rows
-      # @raise [StandardError] a domain refusal (Runtime::DOMAIN_REFUSALS) when a rule refuses
-      # @raise [Runtime::StaleWrite, Runtime::WiringError] every retry loses, or resolve fails
-      # rubocop:disable-next Metrics/ParameterLists -- the public dispatch signature every entry point calls
-      def call(domain, aggregate, command, invocation, correlation = nil, dry_run: false)
+      # @raise [StandardError] a domain refusal, a StaleWrite once retries run out, or a WiringError
+      def call(domain, aggregate, command, invocation, correlation = nil, dry_run: false, dispatch_key: nil)
         args     = invocation.to_args
-        settings = { invocation: invocation, route: invocation.target, correlation: correlation, dry_run: dry_run }
+        settings = { invocation:, route: invocation.target, correlation:, dry_run:, dispatch_key: }
         attempt  = 0
         begin
           dispatch_once(new_context(domain, aggregate, command, args, settings))
@@ -88,6 +91,7 @@ module Hecks
         ctx.correlation = settings[:correlation]
         ctx.route       = settings[:route]
         ctx.dry_run     = settings[:dry_run]
+        ctx.dispatch_key = settings[:dispatch_key]
         ctx.plan        = DependencyPlanning::Analyzer.call(aggregate: aggregate, command: command)
         # Resolved once here, before hydration: `Registry#repository` memoizes,
         # and the isolation decision needs its capabilities up front.
@@ -96,6 +100,8 @@ module Hecks
       end
 
       def dispatch_once(ctx)
+        return already_applied(ctx) if dispatch_applied?(ctx)
+
         lock_id = Identity.best_effort(ctx.aggregate, ctx.args, ctx.route, reference_key: reference_key(ctx.command))
         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]
@@ -131,7 +137,7 @@ module Hecks
       def step_hydrate(ctx)
         # `ctx.repository` is resolved once, in `#call`, before the
         # isolation decision (lock vs. CAS+retry) — not here.
-        ctx.strategy = ctx.plan.strategy_for(capabilities: ctx.repository.capabilities)
+        ctx.strategy = ctx.plan.strategy_for(capabilities: ctx.capabilities)
         ctx.instance = step(:hydrate) { hydrate_for(ctx) }
       end
 
@@ -146,7 +152,7 @@ module Hecks
         # ensures. A shallow dup suffices: mutations replace fields (set,
         # arithmetic via Value#with, append builds a new array), never
         # edit a held value in place.
-        ctx.old_state = ctx.instance.state.dup unless ctx.command.ensures.empty?
+        ctx.old_state = ctx.state.dup unless ctx.command_ensures.empty?
         step(:apply_mutations) { apply_all_mutations(ctx) }
       end
 
@@ -156,8 +162,8 @@ module Hecks
       # target is written to the candidate; declaration order carries
       # no meaning, and build refuses a field written twice.
       def apply_all_mutations(ctx)
-        pre = ctx.instance.state.dup
-        ctx.command.mutations.each do |mutation|
+        pre = ctx.state.dup
+        ctx.command_mutations.each do |mutation|
           apply(ctx.instance, ctx.aggregate, mutation, ctx.args, pre)
         end
       end
@@ -165,7 +171,8 @@ module Hecks
       def step_advance_lifecycle(ctx)
         return unless ctx.transition
 
-        step(:advance_lifecycle) { ctx.instance[ctx.aggregate.lifecycle.field] = ctx.transition.target }
+        aggregate = ctx.aggregate
+        step(:advance_lifecycle) { ctx.instance[aggregate.lifecycle_field] = ctx.transition_target }
       end
 
       # A delegating command emits nothing of its own; its result is the
@@ -174,7 +181,7 @@ module Hecks
       # `dry_run:` skips this too — nothing was committed, so `ctx.result`
       # stays nil.
       def step_emit(ctx)
-        return if ctx.dry_run
+        return DryRunPlan.emits(ctx.command) if ctx.dry_run
 
         ctx.result = step(:emit) { emit_events(ctx) }
       end

data/lib/hecks/runtime/command_rules/admissibility.rb

@@ -1,6 +1,7 @@
 require_relative "../../bluebook/expression/evaluator"
 require_relative "../../rendering"
 require_relative "../errors"
+require_relative "../collecting"
 require_relative "../refusal_wording"
 require_relative "../value"
 require_relative "../instance"
@@ -28,7 +29,6 @@ module Hecks
         # @return [void]
         # @raise [Runtime::GivenNotMet] a declared `given` does not hold
         # @raise [Runtime::LifecycleRefused] `declaring`'s `from:` guard refuses the state
-        # rubocop:disable-next Metrics/ParameterLists -- the dispatch context every interpreter passes by keyword
         def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
           # A rule reads only within its own aggregate boundary (ADR 0025);
           # `dereference` below resolves fresh reference arguments only,
@@ -110,7 +110,6 @@ module Hecks
         # @param correction [Hash{Symbol => Object}] `corrects` event bindings, if any
         # @return [void]
         # @raise [Runtime::EnsuresNotMet] a declared `ensures` does not hold
-        # rubocop:disable-next Metrics/ParameterLists -- the dispatch context every interpreter passes by keyword
         def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
           # Same aggregate-boundary rule as enforce_givens (ADR 0025) —
@@ -121,7 +120,8 @@ module Hecks
           command.ensures.each do |rule|
             next if Bluebook::Expression::Evaluator.call_rule(rule, state, attrs)
 
-            raise EnsuresNotMet, "#{command.hecks_name} refused — #{rule.description}"
+            Collecting.refuse(EnsuresNotMet.new("#{command.hecks_name} refused — #{rule.description}",
+                                                rule: rule.description))
           end
         end
 
@@ -159,13 +159,17 @@ module Hecks
           command.givens.each do |given|
             next if Bluebook::Expression::Evaluator.call_rule(given, state, attrs)
 
-            raise GivenNotMet.new(
-              "#{command.hecks_name} refused — #{given.description}",
-              detail: Bluebook::Expression::Evaluator.comparison_detail(given.canonical, state, attrs)
-            )
+            Collecting.refuse(unmet_given(command, given, state, attrs))
           end
         end
 
+        # The refusal for one given that did not hold.
+        def unmet_given(command, given, state, attrs)
+          GivenNotMet.new("#{command.hecks_name} refused — #{given.description}",
+                          detail: Bluebook::Expression::Evaluator.comparison_detail(given.canonical, state, attrs),
+                          rule:   given.description)
+        end
+
         # The most recent emission of the event a `corrects` mutation names. Most recent match wins
         # if this record emitted the same event more than once; aggregate and id are already scoped
         # by correction_history, so only the event name is filtered here.
@@ -195,11 +199,12 @@ module Hecks
         # Routed through one "transition_blocked" template, so a lifecycle guard and a
         # transition raise identical wording.
         def raise_transition_blocked(command, lifecycle, current, allowed)
-          raise LifecycleRefused,
-                RefusalWording.render_site("LifecycleRefused", "transition_blocked",
-                                           command: command.hecks_name, field: lifecycle.field,
-                                           current: Rendering.describe(current),
-                                           allowed: allowed)
+          raise LifecycleRefused.new(
+            RefusalWording.render_site("LifecycleRefused", "transition_blocked",
+                                       command: command.hecks_name, field: lifecycle.field,
+                                       current: Rendering.describe(current), allowed: allowed),
+            attribute: lifecycle.field, stage: :state
+          )
         end
       end
     end

data/lib/hecks/runtime/command_rules/authorization.rb

@@ -24,22 +24,24 @@ module Hecks
         def refuse_role_mismatch(command, domain)
           caller = Caller.current
           return unless caller
-          return if command.role.to_s.empty?
 
-          return if role_held?(caller, command, domain)
+          roles = command.role_set
+          return if roles.empty?
+
+          return if roles.any? { |role| role_held?(caller, role, domain) }
 
           raise Unauthorized, RefusalWording.render_site("Unauthorized", "role_mismatch",
-                                                         command: command.hecks_name, role: command.role,
+                                                         command: command.hecks_name, role: roles.join(" or "),
                                                          caller_role: caller.role)
         end
 
         private
 
         # An identified caller holds the role by a live grant; an unidentified one by its string.
-        def role_held?(caller, command, domain)
-          return caller.role == command.role unless caller.actor_id && governance_attached?(domain)
+        def role_held?(caller, role, domain)
+          return caller.role == role unless caller.actor_id && governance_attached?(domain)
 
-          Ports::Authorization.holds_role?(registry, actor_id: caller.actor_id, role: command.role,
+          Ports::Authorization.holds_role?(registry, actor_id: caller.actor_id, role: role,
                                                      as_of: caller.as_of, scope: caller.scope)
         end
 

data/lib/hecks/runtime/command_rules/emission.rb

@@ -15,7 +15,6 @@ module Hecks
         # @param repository [Ports::Persistence::AppendOnly] asked to `record_event` if it can
         # @param correlation [Hash, nil] saga correlation, set before the event freezes
         # @return [Array<Runtime::Event>] the emitted events in `emits` order
-        # rubocop:disable-next Metrics/ParameterLists -- the positional signature both interpreters call
         def emit(command, domain, aggregate, instance, args, repository, correlation = nil)
           stamp = { aggregate: "#{domain}::#{aggregate.hecks_name}", id: instance.id,
                     payload: args, correlation: correlation }

data/lib/hecks/runtime/command_rules/guard_state.rb

@@ -10,11 +10,11 @@ module Hecks
         class GuardState
           def initialize(instance)
             @instance = instance
-            @declared = instance.respond_to?(:aggregate) ? instance.aggregate.attributes.to_h { |a| [a.name, a] } : {}
+            @owner = instance.aggregate if instance.respond_to?(:aggregate)
+            @declared = instance.respond_to?(:aggregate) ? @owner.attributes.to_h { |a| [a.name, a] } : {}
             # Separate index: a projected field's absence raises its own
             # refusal, not AttributeAbsent's (ADR 0025).
-            owner = instance.aggregate if instance.respond_to?(:aggregate)
-            @projected = owner.respond_to?(:projected_fields) ? owner.projected_fields.to_h { |f| [f.name, f] } : {}
+            @projected = @owner.respond_to?(:projected_fields) ? @owner.projected_fields.to_h { |f| [f.name, f] } : {}
           end
 
           def key?(name) = @declared.key?(name.to_sym) || @projected.key?(name.to_sym) || @instance.key?(name)
@@ -29,18 +29,18 @@ module Hecks
             attribute = @declared[name.to_sym]
             return nil if attribute.nil? || attribute.optional?
 
-            raise AttributeAbsent,
-                  RefusalWording.render_site("AttributeAbsent", "absent_read",
-                                             aggregate: @instance.aggregate.hecks_name, field: name)
+            raise AttributeAbsent.new(RefusalWording.render_site("AttributeAbsent", "absent_read",
+                                                                 aggregate: @owner.hecks_name, field: name),
+                                      attribute: name)
           end
 
           private
 
           def raise_projection_absent(projected)
-            raise ProjectionAbsent,
-                  RefusalWording.render_site("ProjectionAbsent", "absent_read",
-                                             aggregate: @instance.aggregate.hecks_name, field: projected.name,
-                                             reference: projected.reference, remote_field: projected.remote_field)
+            message = RefusalWording.render_site("ProjectionAbsent", "absent_read",
+                                                 aggregate: @owner.hecks_name, field: projected.name,
+                                                 reference: projected.reference, remote_field: projected.remote_field)
+            raise ProjectionAbsent.new(message, attribute: projected.name)
           end
         end
       end

data/lib/hecks/runtime/command_rules/invariants.rb

@@ -1,3 +1,4 @@
+require_relative "../collecting"
 require_relative "../../bluebook/expression/evaluator"
 require_relative "../errors"
 require_relative "../instance"
@@ -64,7 +65,8 @@ module Hecks
             construct.invariants.each do |invariant|
               next if Bluebook::Expression::Evaluator.call_rule(invariant, state, attrs)
 
-              raise InvariantViolation, "#{construct.hecks_name} refused — #{invariant.description}"
+              Collecting.refuse(InvariantViolation.new("#{construct.hecks_name} refused — #{invariant.description}",
+                                                       rule: invariant.description))
             end
           end
 

data/lib/hecks/runtime/command_rules/missing_reference.rb

@@ -0,0 +1,25 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # The refusal for a reference whose target identity does not exist.
+      module MissingReference
+        module_function
+
+        # @param target [Bluebook::Aggregate] the aggregate the reference points at
+        # @param key [String] the identity that was not found
+        # @param attribute [Symbol] the reference attribute that named it
+        # @return [Runtime::NotFound] the refusal, in the `references` stage
+        def refusal(target, key, attribute)
+          NotFound.new(
+            RefusalWording.render_site("NotFound", "reference_target_missing",
+                                       target: target.name, heads: target.identity_heads.join(", "), key: key),
+            attribute: attribute, stage: :references
+          )
+        end
+      end
+    end
+  end
+end