hecks 4.0.0 → 6.0.0

data/lib/hecks/runtime/command_interpreter.rb

@@ -14,6 +14,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 +45,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 +65,13 @@ 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
+      # @raise [StandardError] a domain refusal, a StaleWrite once retries run out, or a WiringError
       # rubocop:disable-next Metrics/ParameterLists -- the public dispatch signature every entry point calls
-      def call(domain, aggregate, command, invocation, correlation = nil, dry_run: false)
+      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

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"
@@ -121,7 +122,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 +161,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 +201,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/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

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

@@ -0,0 +1,44 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../value"
+require_relative "../../bluebook/one_of_union"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # Refuses a tagged reference (`reference_to one_of(A, B)`, ADR 0127) whose record does not
+      # exist in the aggregate its `type` names. `admits:` has already refused a type outside the
+      # union, so only the lookup is left here.
+      module OneOfReferences
+        # Checks every tagged reference `construct` holds in settled `state`.
+        #
+        # @param domain [String, Symbol] the domain whose repositories are read
+        # @param construct [Bluebook::Aggregate] the aggregate whose state was settled
+        # @param state [Hash{Symbol => Object}] the record's settled fields
+        # @return [void]
+        # @raise [Runtime::NotFound] if a tagged reference names a record that does not exist
+        def resolve_one_of_references(domain, construct, state)
+          Bluebook::OneOfUnion.attributes(construct).each do |attribute|
+            tagged = Value.materialize_unwrapped(state[attribute.name])
+            next unless tagged.is_a?(Hash)
+
+            validate_tagged_reference(domain, construct, tagged)
+          end
+        end
+
+        private
+
+        # Looks the tagged record up in the repository of the aggregate its `type` names.
+        def validate_tagged_reference(domain, construct, tagged)
+          target = construct.hecks_owner&.aggregate(tagged[:type].to_s)
+          key = tagged[:id].to_s
+          return if target.nil? || key.empty? || @registry.repository(domain, target).find(key)
+
+          raise NotFound,
+                RefusalWording.render_site("NotFound", "reference_target_missing",
+                                           target: target.name, heads: target.identity_heads.join(", "), key: key)
+        end
+      end
+    end
+  end
+end

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

@@ -1,7 +1,9 @@
 require_relative "../errors"
+require_relative "../collecting"
 require_relative "../refusal_wording"
 require_relative "../value"
 require_relative "../../rendering"
+require_relative "missing_reference"
 require_relative "tenant_boundary"
 
 module Hecks
@@ -24,7 +26,8 @@ module Hecks
         # Re-checks references, cardinality and tenant agreement against settled state.
         #
         # @raise [Runtime::TypeMismatch] if a required `has_one`/`belongs_to` holds nil
-        # @raise [Runtime::NotFound] if a reference names an identity that does not exist
+        # @raise [Runtime::NotFound] if a reference, or a tagged `one_of` reference, names an
+        #   identity that does not exist
         # @raise [Runtime::Unauthorized] if a referenced record belongs to another tenant
         def resolve_state_references(domain, construct, state)
           boundary = TenantBoundary.new(self, domain, construct, state, tenant_field_for(construct))
@@ -36,6 +39,7 @@ module Hecks
           end
 
           resolve_entity_references(domain, construct, state)
+          resolve_one_of_references(domain, construct, state)
         end
 
         # One reference-typed argument's value, refused unless its target identity exists.
@@ -43,7 +47,7 @@ module Hecks
           return if held.nil?
 
           target = referenced_aggregate(attribute)
-          validate_reference_values(domain, target, held, list: attribute.list?) if target
+          validate_reference_values(domain, target, held, list: attribute.list?, attribute: attribute.name) if target
         end
 
         # One reference-typed attribute of settled state: cardinality, target and tenant.
@@ -55,7 +59,7 @@ module Hecks
           target = referenced_aggregate(attribute)
           return unless target
 
-          validate_reference_values(domain, target, held, list: attribute.list?)
+          validate_reference_values(domain, target, held, list: attribute.list?, attribute: attribute.name)
           enforce_tenant_boundary(boundary, attribute, target, held)
         end
 
@@ -84,28 +88,23 @@ module Hecks
           raise TypeMismatch,
                 "#{construct.hecks_name}.#{attribute.name} is a required " \
                 "#{attribute.relationship} relationship — expected one " \
-                "#{attribute.type.target_name} identity, got nil"
+                "#{attribute.target_name} identity, got nil"
         end
 
-        # Resolves the attribute's target through the chapter IR.
+        # Resolves the attribute's target through the bluebook IR.
         #
         # @raise [Bluebook::DSL::Malformed] if the reference does not know its declaring aggregate
-        def referenced_aggregate(attribute)
-          attribute.type.resolve
-        end
+        def referenced_aggregate(attribute) = attribute.target_aggregate
 
         # Refuses a reference-typed value whose target identity does not exist.
-        def validate_reference_values(domain, target, held, list:)
+        def validate_reference_values(domain, target, held, list:, attribute:)
           values = list ? Array(held) : [held]
           values.each do |value|
             key = reference_key(value)
             next if key.empty?
             next if @registry.repository(domain, target).find(key)
 
-            raise NotFound,
-                  RefusalWording.render_site("NotFound", "reference_target_missing",
-                                             target: target.name, heads: target.identity_heads.join(", "),
-                                             key: key)
+            Collecting.refuse(MissingReference.refusal(target, key, attribute))
           end
         end
 
@@ -156,7 +155,8 @@ module Hecks
         end
 
         def dereferenced_name(attribute)
-          attribute.name.to_s.delete_suffix("_id").to_sym
+          name = attribute.name.to_s
+          name.delete_suffix("_id").to_sym
         end
 
         # The target aggregate and stored record a reference argument names, or nil when it names

data/lib/hecks/runtime/command_rules.rb

@@ -1,5 +1,6 @@
 require_relative "command_rules/admissibility"
 require_relative "command_rules/references"
+require_relative "command_rules/one_of_references"
 require_relative "command_rules/arithmetic"
 require_relative "command_rules/emission"
 require_relative "command_rules/authorization"
@@ -14,6 +15,7 @@ module Hecks
     class CommandRules
       include Admissibility
       include References
+      include OneOfReferences
       include Arithmetic
       include Emission
       include Authorization

data/lib/hecks/runtime/declarations.rb

@@ -0,0 +1,66 @@
+module Hecks
+  module Runtime
+    # **A domain's declarations**, asked of the dispatcher or described domain that holds them.
+    #
+    # A caller holding a dispatcher (or a described domain) asks it for a bluebook, a repository
+    # or the translations, rather than reaching through its registry. The includer answers
+    # `registry`.
+    module Declarations
+      # Every loaded bluebook, by name.
+      #
+      # @return [Hash{String => Bluebook::Declaration}] the loaded bluebooks, keyed by name
+      def bluebooks = registry.bluebooks
+
+      # Exposes one loaded domain's bluebook.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @return [Bluebook::Bluebook, nil] the bluebook, or nil when no such domain is loaded
+      def bluebook(domain) = registry.bluebook(domain)
+
+      # The first bluebook loaded: a one-domain boot's own bluebook.
+      #
+      # @return [Bluebook::Declaration, nil] the first loaded bluebook, or nil when none loaded
+      def first_bluebook = registry.first_bluebook
+
+      # Answers whether a domain was loaded as a bounded bluebook.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @return [Boolean] whether the domain is a bounded bluebook
+      def bounded?(domain) = registry.bounded?(domain)
+
+      # The repository that stores `aggregate`.
+      #
+      # @param domain [String, Symbol] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate
+      # @return [Persistence::AppendOnly] the aggregate's authoritative repository
+      def repository(domain, aggregate) = registry.repository(domain, aggregate)
+
+      # A domain's wiring.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @return [Bluebook::Hecksagon, nil] the wiring, or nil when none is registered
+      def hecksagon(domain) = registry.hecksagon(domain)
+
+      # A domain's world settings.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @return [Bluebook::World, nil] the world, or nil when none is registered
+      def world(domain) = registry.world(domain)
+
+      # Every declared translation between eras.
+      #
+      # @return [Array<Bluebook::Translation>] the loaded translations
+      def translations = registry.translations
+
+      # The privacy markings declared before their aggregate was loaded.
+      #
+      # @return [Array<Hash>] each marking's domain, attribute path, category and readers
+      def pending_privacy_markings = registry.pending_privacy_markings
+
+      # Every saga instance this boot has started.
+      #
+      # @return [Hash] the saga instances, by process manager and then correlation
+      def saga_instances = registry.saga_instances
+    end
+  end
+end

data/lib/hecks/runtime/dependency_planning/analyzer.rb

@@ -61,7 +61,8 @@ module Hecks
         # as a read; the interpreter reseeds it on save.
         def owner_field_names(construct)
           fields = construct.attributes.to_set(&:name)
-          fields << construct.lifecycle.field.to_sym if construct.lifecycle
+          lifecycle = construct.lifecycle
+          fields << lifecycle.field.to_sym if lifecycle
           construct.projected_fields.each { |field| fields << field.name } if construct.respond_to?(:projected_fields)
           fields
         end

data/lib/hecks/runtime/dependency_planning/expression_reads.rb

@@ -64,8 +64,9 @@ module Hecks
 
         # The path a lookup reads, unless its root is a name an enclosing block bound.
         def collect_lookup(node, bound_names)
-          root = node.path.to_s.split(".", 2).first
-          bound_names.include?(root) ? [] : [node.path.to_s]
+          path = node.path.to_s
+          root = path.split(".", 2).first
+          bound_names.include?(root) ? [] : [path]
         end
       end
     end

data/lib/hecks/runtime/dependency_planning/mutation_analysis.rb

@@ -16,7 +16,8 @@ module Hecks
               known_writes << attribute.name if deterministic_initial_value?(attribute)
             end
 
-            known_writes << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+            state_field = aggregate.lifecycle_field
+            known_writes << state_field.to_sym if state_field
           end
 
           def deterministic_initial_value?(attribute)

data/lib/hecks/runtime/dispatch_claim.rb

@@ -0,0 +1,72 @@
+module Hecks
+  module Runtime
+    # The identity of one saga dispatch, and the capability a repository needs to dedupe by it.
+    #
+    # A saga leg stamps each command it dispatches with a key naming the saga instance, the event
+    # that moved it, the leg's trigger and the dispatch's position. A repository that declares
+    # `:dispatch_claims` records the key in the same transaction as the write it guards
+    # (`dispatch_claim`) and answers whether a key was applied (`dispatch_applied?`), so delivering
+    # the same dispatch again changes nothing, whatever the command does.
+    module DispatchClaim
+      CAPABILITY = :dispatch_claims
+
+      module_function
+
+      # @param process_manager [String] the saga's declared name
+      # @param correlation [String] the saga instance's correlation value
+      # @param trigger [String] the event name, or `REFUSED`, that selected the leg
+      # @param event [Runtime::Event] the event that moved the leg
+      # @param index [Integer] the dispatch's position within the leg
+      # @return [String] the key, stable across a crash because it is built from the leg's own event
+      def key(process_manager:, correlation:, trigger:, event:, index:)
+        [process_manager, correlation, trigger, event.name, event.id, event.occurred_at, index].join("/")
+      end
+
+      # @param repository [#capabilities] the repository a command saves through
+      # @return [Boolean] whether it dedupes dispatches by key
+      def supported?(repository) = repository.capabilities.include?(CAPABILITY)
+
+      # What an interpreter does with a dispatch key: read it before any step, claim it inside the
+      # save's transaction. Mixed into {Interpreting}; the context carries `dispatch_key`.
+      module Claiming
+        private
+
+        # The steps from `save` onward, run only if this delivery wins the dispatch's claim; a
+        # delivery that lost it applies nothing and answers with no events.
+        def run_transactional_steps(steps, ctx)
+          unless dispatch_claimed?(ctx)
+            ctx.result = []
+            return
+          end
+
+          steps.each { |name| send(:"step_#{name}", ctx) }
+          enqueue_outbox(ctx)
+        end
+
+        # Whether the dispatch may go on: it carries no key, its repository dedupes none, or the
+        # key was new and is now claimed in this transaction. False means another delivery of the
+        # same dispatch got there first, so nothing is applied.
+        def dispatch_claimed?(ctx)
+          return true unless keyed_dispatch?(ctx)
+
+          ctx.repository.dispatch_claim(ctx.dispatch_key)
+        end
+
+        # Whether a saga dispatch with this key was already applied, read before any step runs so a
+        # guard the first delivery changed cannot refuse the second.
+        def dispatch_applied?(ctx)
+          keyed_dispatch?(ctx) && ctx.repository.dispatch_applied?(ctx.dispatch_key)
+        end
+
+        # What a command answers when its dispatch was already applied: no record, no events, and
+        # nothing for the reaction layer to do.
+        def already_applied(ctx) = [nil, [], ctx.plan, nil, []]
+
+        def keyed_dispatch?(ctx)
+          ctx.respond_to?(:dispatch_key) && ctx.dispatch_key && !ctx.dry_run && ctx.repository &&
+            DispatchClaim.supported?(ctx.repository)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dispatch_context.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Runtime
+    # What a dispatch step asks its context for, answered from the record, command and
+    # aggregate the context holds. Mixed into each interpreter's `Context` struct, which
+    # supplies the readers (`instance`, `command`, `aggregate`, `route`, ...) these read.
+    module DispatchContext
+      # @return [Hash{Symbol => Object}] the record's held state
+      def state = instance.state
+
+      # @return [Object] the record's identity
+      def instance_id = instance.id
+
+      # @return [Integer, nil] the version the record was read at, nil when never stored
+      def instance_version = instance.version
+
+      # @return [Symbol] what the repository answered the save with (`:stale`, `:conflicted`, ...)
+      def outcome_status = persistence_outcome.status
+
+      # @return [String] the aggregate's declared name
+      def aggregate_hecks_name = aggregate.hecks_name
+
+      # @return [String] the command's declared name
+      def command_hecks_name = command.hecks_name
+
+      # @return [Array] the command's ensures clauses
+      def command_ensures = command.ensures
+
+      # @return [Array] the command's mutations, in declaration order
+      def command_mutations = command.mutations
+
+      # @return [Object] the state the admitted transition moves to
+      def transition_target = transition.target
+
+      # @return [Object] what the repository can do (CAS, locking, atomic put)
+      def capabilities = repository.capabilities
+
+      # @return [Object, nil] the aggregate identity the route names, nil without a route
+      def routed_identity = route&.aggregate
+    end
+  end
+end

data/lib/hecks/runtime/dispatcher/queries.rb

@@ -29,6 +29,23 @@ module Hecks
           @queries.call(domain, aggregate, query_name, args)
         end
 
+        # Answers one page of a cursor query: its rows, and the `after` that asks for the next page.
+        #
+        # @param verb [String] `"Domain::Aggregate.Query"` of a query that declares `cursor`
+        # @param after [String, nil] the position the previous page answered; nil asks page one
+        # @param page_size [Integer, nil] a page smaller than the query's own `limit`; never larger
+        # @param args [Hash{Symbol => Object}] the query's declared arguments
+        # @return [Hash{Symbol => Object}] `rows`, one Hash per record, and `after`, the next
+        #   position or nil when no row follows
+        # @raise [ArgumentError] if the query has no cursor, or `after` is not one it handed out
+        # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
+        def query_page(verb, after: nil, page_size: nil, **args)
+          domain, aggregate_name, query_name = parse(verb)
+          aggregate = resolve_aggregate(domain, aggregate_name, verb)
+
+          @queries.page(domain, aggregate, query_name, after ? args.merge(after: after) : args, page_size: page_size)
+        end
+
         # Answers an aggregate or entity query through the reference interpreter alone.
         #
         # Never answered by the bound adapter's native hook; the fuzzer's query oracle diffs it