hecks 5.0.0 → 7.0.0

data/lib/hecks/adapters/driven/identity_registry.rb

@@ -16,7 +16,7 @@ module Hecks
       # @return [String, nil] the linked identity's id, or nil if nothing has linked this pair
       def resolve(registry, issuer:, subject:)
         # The verb comes from the declared identity provider (`provides "identity", resolve:`).
-        provider = registry.bluebooks.values.find { |chapter| chapter.provides?(::Hecks::Bluebook::Capabilities::IDENTITY) }
+        provider = registry.bluebooks.values.find { |declaration| declaration.provides?(::Hecks::Bluebook::Capabilities::IDENTITY) }
         verb = provider&.provided_verb(::Hecks::Bluebook::Capabilities::IDENTITY, :resolve) ||
                "Identity::ExternalIdentifier.ResolvedBy"
         rows = Runtime::Dispatcher.new(registry).query(

data/lib/hecks/adapters/driven/in_memory_ordering.rb

@@ -52,7 +52,7 @@ module Hecks
       # @param name [String] an attribute name
       # @return [Boolean] true when `name` is the lifecycle field
       def lifecycle_field?(aggregate, name)
-        aggregate.lifecycle&.field.to_s == name
+        aggregate.lifecycle_field.to_s == name
       end
 
       # Picks the member of a value object that orders it.
@@ -63,8 +63,9 @@ module Hecks
       # @param shape [Bluebook::ValueObject] the value object type
       # @return [String] the member name
       def orderable_member(shape)
+        sole = shape.sole_attribute
         shape.attributes.find { |a| %w[Integer Float].include?(a.type) }&.name ||
-          shape.sole_attribute&.name || "value"
+          sole&.name || "value"
       end
 
       # Resolves the dotted path `FieldPath.dig` should read to compare a value object field.

data/lib/hecks/adapters/driven/in_process_key_vault.rb

@@ -30,7 +30,7 @@ module Hecks
       # @param key_reference [String] the opaque reference {#issue} returned
       # @return [Boolean] true when a key was held and is now gone; false when this
       #   reference was already destroyed, or never issued
-      def destroy(key_reference:) = !(@keys ||= {}).delete(key_reference).nil? # rubocop:disable Naming/PredicateMethod
+      def destroy(key_reference:) = !(@keys ||= {}).delete(key_reference).nil?
 
       # Resets the vault to empty, forgetting every key this process ever issued.
       #

data/lib/hecks/adapters/driven/key_keeper.rb

@@ -0,0 +1,42 @@
+require_relative "../../runtime/registry"
+require_relative "../../ports/key_vault"
+
+module Hecks
+  module Adapters
+    # The `Keys` port's adapter for a `SubjectKey` (ADR 0142, ADR 0147): has the `key_vault` port
+    # issue a subject's key and destroy it, in the boot whose record asked. A vault that cannot
+    # raises, and the port records the refusal on the subject's key.
+    class KeyKeeper
+      # @param registry [Runtime::Registry] the registry the ask comes from, whose vault adapter
+      #   holds the keys
+      def initialize(registry:)
+        @registry = registry
+      end
+
+      # Issues a key for the subject a record names. The ask is handed that record's held state, in
+      # which the subject is still a one-field value object. The answer names the reference the
+      # vault gave, so the answer event carries it on to the policy that records it.
+      #
+      # @param subject_id [Hash, String] the subject, `{ value: }` as the record holds it
+      # @return [Hash{Symbol => String}] `key_reference:`, the vault's opaque reference
+      def issue(subject_id:, **)
+        { key_reference: Ports::KeyVault.issue(@registry, subject_id: plain(subject_id)) }
+      end
+
+      # Destroys the key a subject's record names. The answer names the key that was destroyed, as
+      # the state held it, so the answer event carries it on to the policy that records it.
+      #
+      # @param key_reference [Hash, String] the vault's opaque reference to the key, `{ value: }`
+      #   as the record holds it
+      # @return [Hash{Symbol => Object}] `key_reference:`, the key that was destroyed
+      def destroy(key_reference:, **)
+        Ports::KeyVault.destroy(@registry, key_reference: plain(key_reference))
+        { key_reference: key_reference }
+      end
+
+      private
+
+      def plain(reference) = reference.is_a?(Hash) ? reference[:value] : reference
+    end
+  end
+end

data/lib/hecks/adapters/driven/lambda/client.rb

@@ -4,7 +4,7 @@ module Hecks
   module Adapters
     class Lambda
       # The thin AWS client shared by this adapter's read methods and
-      # Runtime::RemoteDispatcher's writes: one Lambda invoke, one JSON round trip.
+      # Adapters::Lambda::RemoteDispatcher's writes: one Lambda invoke, one JSON round trip.
       #
       # The function name defaults to `"hecks-#{domain.downcase}"`, matching
       # `hecks deploy recipe.project`'s `stack_name` computation. A domain whose stack
@@ -60,7 +60,7 @@ module Hecks
 
         def invoke(payload)
           response = @client.invoke(function_name: @function_name, payload: JSON.generate(payload))
-          body = JSON.parse(response.payload.read)
+          body = parsed_body(response)
 
           if response.function_error
             raise Runtime::WiringError,
@@ -69,6 +69,12 @@ module Hecks
 
           body
         end
+
+        # The response payload is a stream of JSON text.
+        def parsed_body(response)
+          stream = response.payload
+          JSON.parse(stream.read)
+        end
       end
     end
   end

data/lib/hecks/adapters/driven/lambda/remote_dispatcher.rb

@@ -0,0 +1,185 @@
+require_relative "../../../runtime/dispatcher"
+require_relative "../../../runtime/declarations"
+require_relative "../../../runtime/instance"
+require_relative "../../../runtime/event"
+require_relative "../../../runtime/errors"
+require_relative "../../../naming"
+require_relative "client"
+require_relative "../../../ports/persistence/binding_policy"
+require_relative "../../../ports/persistence/remote_runtime"
+
+module Hecks
+  module Adapters
+    class Lambda
+      # The dispatcher for a domain whose `.world` declares `dispatched_by("Lambda")`.
+      # Same public shape as `Dispatcher`; writes go remote, reads stay local.
+      #
+      # Reads delegate to a local `Dispatcher` because the registry's repositories are
+      # already Lambda-backed. Writes cannot: givens and constraints must run in Rust,
+      # not be pre-checked here against incomplete local state.
+      class RemoteDispatcher
+        Result = Struct.new(:verb, :instance, :events, :refused_reactions, :blocking_reactions,
+                            :reaction_defects, keyword_init: true) do
+          # Lists the policy reactions this dispatch caused that the routed runtime refused.
+          #
+          # @return [Array<Hash{Symbol => Object}>] one `{ policy:, trigger:, reason: }` per refused
+          #   reaction, oldest first; empty when every reaction was delivered
+          def refused_reactions = self[:refused_reactions] || []
+
+          # Lists the refused reactions that block the run, as opposed to a benign non-match.
+          #
+          # @return [Array<Hash{Symbol => Object}>] the subset of `refused_reactions` that blocks
+          def blocking_reactions = self[:blocking_reactions] || []
+
+          # @return [Array<Hash{Symbol => Object}>] the reactions the host reported as crashed
+          def reaction_defects = self[:reaction_defects] || []
+
+          # The settled record's identity.
+          #
+          # @return [String]
+          def id    = instance.id
+
+          # The settled record's attributes.
+          #
+          # @return [Hash{Symbol => Object}] `:id` merged in last
+          def state = instance.to_h
+        end
+
+        include Runtime::Declarations
+
+        attr_reader :registry
+
+        # @param registry [Runtime::Registry] the booted registry this dispatcher fronts
+        # @param region [String] the AWS region the routed Lambda function lives in
+        # @param function [String, nil] the `dispatched_by("Lambda")` function name; nil
+        #   resolves it from `ENV["DOMAIN_NAME"]` or `registry.root`
+        def initialize(registry, region: "us-east-1", function: nil)
+          @registry = registry
+          # ENV["DOMAIN_NAME"] first: inside a deployed Lambda `root` is always
+          # `/var/task`, which would resolve the function name to "task".
+          @client = Adapters::Lambda::Client.new(domain: ENV["DOMAIN_NAME"] || File.basename(registry.root),
+                                                 region: region, function: function)
+          @local = Runtime::Dispatcher.new(registry)
+        end
+
+        # Dispatches a command by verb, locally or through the routed Lambda depending
+        # on the aggregate's bound adapter.
+        #
+        # @param verb [String] the fully qualified verb, `"Domain::Aggregate.Command"`
+        # @param saga_correlation [Hash, nil] correlation head => value stamped on emitted events
+        # @param args [Hash] the facts, plus optional `:to`/`:with` keys
+        # @return [RemoteDispatcher::Result] the verb, settled instance and emitted events
+        # @raise [Runtime::UnknownVerb] if the verb is not fully qualified or names an
+        #   undeclared domain or aggregate
+        # @raise [Runtime::RemoteRefusal] if the routed Lambda refuses the call
+        # @raise [Runtime::WiringError] if the adapter cannot be resolved, or the remote call
+        #   reports no mutation for the aggregate
+        def dispatch(verb, saga_correlation: nil, **args)
+          dispatch_flat(verb, args.merge(saga_correlation: saga_correlation))
+        end
+
+        # Same routing as `dispatch`, with the flat-facts wire form of `Dispatcher#dispatch_flat`.
+        #
+        # @param verb [String] the fully qualified verb
+        # @param args [Hash] the facts, plus optional Symbol keys `:to`, `:with` and
+        #   `:saga_correlation`
+        # @return [RemoteDispatcher::Result] the verb, settled instance and emitted events
+        def dispatch_flat(verb, args = {})
+          args = args.dup
+          saga_correlation = args.delete(:saga_correlation)
+          domain, aggregate = resolve_aggregate(verb)
+
+          unless remote_bound?(domain, aggregate)
+            return @local.dispatch_flat(verb, args.merge(saga_correlation: saga_correlation))
+          end
+
+          settle(verb, domain, aggregate, @client.dispatch(verb, args))
+        end
+
+        # Delegates to the local `Dispatcher`; see `Dispatcher#query`.
+        def query(verb, **args)           = @local.query(verb, **args)
+
+        # Delegates to the local `Dispatcher`; see `Dispatcher#reference_query`.
+        def reference_query(verb, **args) = @local.reference_query(verb, **args)
+
+        # Fetches the domain's whole event history from the routed Lambda on every call.
+        # Uncached: nothing calls it on a hot path.
+        #
+        # @return [Array<Runtime::Event>] every journaled event, oldest first, with
+        #   `occurred_at` always nil
+        def events
+          @client.read.fetch("events", []).map { |e| build_event(e) }
+        end
+
+        private
+
+        # The domain name and the aggregate a fully qualified verb names.
+        def resolve_aggregate(verb)
+          domain, aggregate_name, = Naming.split_verb(verb) || unknown_verb!("not_fully_qualified", verb: verb)
+          aggregate = @registry.bluebook(domain)&.aggregate(aggregate_name) ||
+                      unknown_verb!("no_aggregate", domain: domain, aggregate: aggregate_name)
+          [domain, aggregate]
+        end
+
+        def unknown_verb!(site, **facts)
+          raise Runtime::UnknownVerb, Runtime::RefusalWording.render_site("UnknownVerb", site, **facts)
+        end
+
+        # Not every aggregate in a routed domain is Lambda-bound (a persistence binding
+        # may name another adapter). Test the adapter's capability, not its name.
+        def remote_bound?(domain, aggregate)
+          adapter_name = Ports::Persistence::BindingPolicy.resolve(@registry, domain, aggregate).adapter
+          @registry.adapter_class(adapter_name) <= Ports::Persistence::RemoteRuntime
+        end
+
+        # The result of a remote dispatch: the record the host settled and what its step caused.
+        def settle(verb, domain, aggregate, response)
+          refuse_remote!(verb, response)
+          mutation = settled_mutation(verb, "#{domain}::#{aggregate.hecks_name}", response)
+          instance = Runtime::Instance.new(aggregate: aggregate, id: mutation["id"],
+                                           state: JSON.parse(JSON.generate(mutation["state"]), symbolize_names: true))
+
+          Result.new(verb: verb, instance: instance, events: step_events(response),
+                     refused_reactions: refused_reactions_of(response),
+                     blocking_reactions: Runtime::ReactionOutcome.blocking(step_reactions(response)),
+                     reaction_defects: Runtime::ReactionOutcome.defects(step_reactions(response)))
+        end
+
+        def refuse_remote!(verb, response)
+          refusal = response.fetch("refusals", []).find { |r| r["verb"] == verb }
+          raise Runtime::RemoteRefusal, "#{verb} refused: #{refusal["error"]}" if refusal
+        end
+
+        # `mutations` has one entry per replayed step, so `.last` is this step. Match by
+        # aggregate name: a reaction can mutate other aggregates in the same step.
+        def settled_mutation(verb, fqn, response)
+          response.fetch("mutations", []).last&.find { |m| m["aggregate"] == fqn } ||
+            raise(Runtime::WiringError,
+                  "#{verb} was accepted but rust/host reported no mutation for #{fqn} — response: #{response.inspect}")
+        end
+
+        # The newest step's reactions the remote runtime refused, from its `reactions_per_step`
+        # log (the whole-run `reactions` would also carry the replayed history's).
+        def refused_reactions_of(response)
+          step_reactions(response)
+            .select { |entry| entry["delivered"] == false }
+            .map { |entry| { policy: entry["policy"], trigger: entry["trigger"], reason: entry["reason"] } }
+        end
+
+        # Every reaction the newest step caused, delivered or not.
+        def step_reactions(response) = Array(response.fetch("reactions_per_step", []).last)
+
+        def step_events(response)
+          response.fetch("events", []).map { |e| build_event(e) }
+        end
+
+        # The kernel's event JSON carries no timestamp, so `occurred_at` stays nil
+        # rather than a synthesized `Time.now`.
+        def build_event(json)
+          Runtime::Event.new(name: json["name"], aggregate: json["aggregate"], id: json["id"],
+                             payload: JSON.parse(JSON.generate(json["payload"]), symbolize_names: true), occurred_at: nil)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/lambda.rb

@@ -1,4 +1,5 @@
 require_relative "lambda/client"
+require_relative "lambda/remote_dispatcher"
 require_relative "../../ports/query/in_memory"
 require_relative "../../ports/persistence/remote_runtime"
 require_relative "in_memory_ordering"
@@ -6,13 +7,23 @@ require_relative "../../runtime/instance"
 
 module Hecks
   module Adapters
-    # Read-side adapter for `persisted_by("Lambda")`; writes go through Runtime::RemoteDispatcher.
+    # Read-side adapter for `persisted_by("Lambda")`; writes go through `RemoteDispatcher`.
     # Read-only: `append`/`project` raise, since a local write would bypass remote validation.
     class Lambda
       include Ports::Persistence::RemoteRuntime
 
       attr_reader :aggregate
 
+      # Builds the dispatcher for a world's `dispatched_by("Lambda")`: writes go to the routed
+      # function, reads stay local.
+      #
+      # @param registry [Runtime::Registry] the booted registry
+      # @param settings [Hash{Symbol => Object}] the binding's `region` and `function`
+      # @return [RemoteDispatcher] the dispatcher the boot hands back
+      def self.dispatcher(registry, settings)
+        RemoteDispatcher.new(registry, region: settings.fetch(:region, "us-east-1"), function: settings[:function])
+      end
+
       # Resolves which Lambda function's Store to read from and builds the client that
       # reads it.
       #
@@ -80,7 +91,8 @@ module Hecks
       # Never memoized: the adapter outlives requests on a warm container, so a cached read
       # would hide every later write. Keyed by the bare id after "Domain::Aggregate#".
       def instances
-        @client.read.fetch("instances", {}).filter_map do |key, state|
+        stored = @client.read.fetch("instances", {})
+        stored.filter_map do |key, state|
           next unless key.start_with?(@prefix)
 
           [key.delete_prefix(@prefix), build_instance(key.delete_prefix(@prefix), state)]

data/lib/hecks/adapters/driven/memory/dispatch_claims.rb

@@ -0,0 +1,25 @@
+module Hecks
+  module Adapters
+    class Memory
+      # The in-process record of saga dispatches already applied, keyed by the dispatch's own key,
+      # held in the adapter's `@dispatch_claims`. See `Runtime::DispatchClaim`.
+      module DispatchClaims
+        # Whether the dispatch with this key has been applied.
+        #
+        # @param key [String] the dispatch key a saga leg stamped on the command
+        # @return [Boolean] true once `dispatch_claim` has accepted the key
+        def dispatch_applied?(key) = @dispatch_claims.key?(key)
+
+        # Records that the dispatch with this key is being applied, refusing a second claim.
+        #
+        # @param key [String] the dispatch key a saga leg stamped on the command
+        # @return [Boolean] true when the key was new and is now held; false when already held
+        def dispatch_claim(key)
+          return false if @dispatch_claims.key?(key)
+
+          @dispatch_claims[key] = true
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/memory/outbox_rows.rb

@@ -26,7 +26,7 @@ module Hecks
         # @param id [Integer] the row id `outbox_enqueue` assigned
         # @return [Boolean] true when the row was pending and is now claimed; false when it is
         #   unknown or not pending
-        def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
+        def outbox_claim(id)
           row = outbox_row(id)
           return false unless row&.pending?
 
@@ -42,7 +42,7 @@ module Hecks
         #   not validated here
         # @param error [String, nil] the failure description, or nil to clear it
         # @return [Boolean] true when the row exists and was updated; false when no row has `id`
-        def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
+        def outbox_settle(id, status:, error: nil)
           row = outbox_row(id) or return false
           row.status = status.to_s
           row.error  = error

data/lib/hecks/adapters/driven/memory.rb

@@ -4,6 +4,7 @@ require_relative "in_memory_ordering"
 require_relative "../../runtime/instance"
 require_relative "memory/shared_elements"
 require_relative "memory/outbox_rows"
+require_relative "memory/dispatch_claims"
 
 module Hecks
   module Adapters
@@ -11,6 +12,7 @@ module Hecks
     # per aggregate, plus an append-only `@entries`/`@events` log.
     class Memory
       include OutboxRows
+      include DispatchClaims
 
       # Reports that two tenant boots of this adapter never share state.
       #
@@ -22,8 +24,8 @@ module Hecks
 
       # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
       #
-      # @return [Array<Symbol>] `[:atomic_put]`
-      def persistence_capabilities = [:atomic_put]
+      # @return [Array<Symbol>] `[:atomic_put, :dispatch_claims]`
+      def persistence_capabilities = %i[atomic_put dispatch_claims]
 
       attr_reader :aggregate, :events
 
@@ -40,6 +42,7 @@ module Hecks
         @entries   = []
         @outbox    = []
         @outbox_deliveries = {}
+        @dispatch_claims = {}
       end
 
       # Looks up the current record for one aggregate identity.
@@ -169,6 +172,7 @@ module Hecks
         @entries = []
         @outbox  = []
         @outbox_deliveries = {}
+        @dispatch_claims = {}
         @elements.reset!
         self
       end
@@ -181,9 +185,16 @@ module Hecks
       # pending → claimed → delivered without a database (the same
       # reason Memory records `events`). See `Runtime::Outbox`.
       #
-      # @yield the writes to run together; an exception raised inside undoes nothing
+      # @yield the writes to run together; an exception raised inside undoes nothing but the
+      #   dispatch claims the block made, so a refused dispatch can be delivered again
       # @return [Object] the block's own result
-      def transaction = yield
+      def transaction
+        held = @dispatch_claims.keys
+        yield
+      rescue StandardError
+        (@dispatch_claims.keys - held).each { |key| @dispatch_claims.delete(key) }
+        raise
+      end
 
       private
 

data/lib/hecks/adapters/driven/postgres/codec.rb

@@ -67,7 +67,7 @@ module Hecks
         end
 
         def projected_only?(field)
-          @aggregate.lifecycle&.field&.to_sym != field[:name].to_sym &&
+          @aggregate.lifecycle_field&.to_sym != field[:name].to_sym &&
             @aggregate.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }
         end
 

data/lib/hecks/adapters/driven/postgres/journal.rb

@@ -94,8 +94,54 @@ module Hecks
           removed
         end
 
+        # Reads the chain heads the ledger sealed beside this journal, oldest first.
+        #
+        # @return [Array<Hash>] `through:` the highest sequence a seal covers, `head:` the chain
+        #   digest at that point and `previous:` the head the seal followed (genesis digest first)
+        # @raise [PG::Error] if a statement fails
+        def ledger_anchors
+          ensure_ledger_anchors!
+          pg_exec_params(
+            "SELECT through_sequence, head, previous FROM hecks_ledger_anchors " \
+            "WHERE aggregate_table = $1 ORDER BY through_sequence", [table]
+          ).map { |row| { through: row["through_sequence"].to_i, head: row["head"], previous: row["previous"] } }
+        end
+
+        # Seals a chain head beside this journal. Sealing the same point twice with the same head
+        # changes nothing; a different head for a sealed point is refused, never overwritten.
+        #
+        # @param through [Integer] the highest journal sequence the head covers
+        # @param head [String] the chain digest at `through`
+        # @param previous [String] the head of the seal before this one
+        # @return [void]
+        # @raise [Runtime::WiringError] if the point is already sealed with another head
+        # @raise [PG::Error] if a statement fails
+        def record_ledger_anchor(through:, head:, previous:)
+          ensure_ledger_anchors!
+          sealed = ledger_anchors.find { |anchor| anchor[:through] == through }
+          if sealed
+            return if sealed[:head] == head
+
+            raise Runtime::WiringError, "#{table} is already sealed through #{through} with another head: the journal changed"
+          end
+
+          pg_exec_params(
+            "INSERT INTO hecks_ledger_anchors (aggregate_table, through_sequence, head, previous) " \
+            "VALUES ($1, $2, $3, $4)", [table, through, head, previous]
+          )
+        end
+
         private
 
+        def ensure_ledger_anchors!
+          pg_exec_params(
+            "CREATE TABLE IF NOT EXISTS hecks_ledger_anchors (" \
+            "aggregate_table text NOT NULL, through_sequence bigint NOT NULL, head text NOT NULL, " \
+            "previous text NOT NULL, sealed_at timestamptz NOT NULL DEFAULT now(), " \
+            "PRIMARY KEY (aggregate_table, through_sequence))", []
+          )
+        end
+
         # Shared decode step for `entries`/`entries_since` — runs a query already selecting
         # `aggregate_id, operation, state, mirrors, sequence` and builds one Entry per row.
         def entries_matching(sql, binds = [])

data/lib/hecks/adapters/driven/postgres/name_guard.rb

@@ -0,0 +1,25 @@
+require_relative "../../../ports/persistence/stored_name_guard"
+
+module Hecks
+  module Adapters
+    class Postgres
+      # Reads how many rows a table holds before any table is created, for the stored-name guard.
+      module NameGuard
+        private
+
+        def refuse_orphaned_rows!
+          Ports::Persistence::StoredNameGuard.check!(@aggregate, row_count: method(:rows_under))
+        end
+
+        def rows_under(name)
+          [name, "#{name}_entries"].sum { |table| table_rows(table) }
+        end
+
+        def table_rows(table)
+          exists = pg_exec_params("SELECT to_regclass($1) AS found", [quote_ident(table)])[0]["found"]
+          exists ? pg_exec("SELECT COUNT(*) AS n FROM #{quote_ident(table)}")[0]["n"].to_i : 0
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres/outbox.rb

@@ -25,6 +25,13 @@ module Hecks
         )
       SQL
 
+      CREATE_DISPATCH_CLAIMS_TABLE = <<~SQL.freeze
+        CREATE TABLE IF NOT EXISTS hecks_dispatch_claims (
+          claim_key   text PRIMARY KEY,
+          claimed_at  timestamptz NOT NULL DEFAULT now()
+        )
+      SQL
+
       # Runs the block inside one Postgres transaction, joining an already-open one.
       #
       # Re-entrant: PG refuses BEGIN inside BEGIN, so an inner call joins the open one.
@@ -62,13 +69,32 @@ module Hecks
         end
       end
 
+      # Whether the dispatch with this key has been applied.
+      #
+      # @param key [String] the dispatch key a saga leg stamped on the command
+      # @return [Boolean] true once `dispatch_claim` has accepted the key
+      def dispatch_applied?(key)
+        pg_exec_params("SELECT 1 FROM hecks_dispatch_claims WHERE claim_key = $1", [key]).ntuples.positive?
+      end
+
+      # Records that the dispatch with this key is being applied, refusing a second claim. Joins the
+      # save's transaction, so a rollback releases the claim with the write it guarded.
+      #
+      # @param key [String] the dispatch key a saga leg stamped on the command
+      # @return [Boolean] true when the key was new and is now held; false when already held
+      # @raise [PG::Error] if the insert fails
+      def dispatch_claim(key)
+        pg_exec_params("INSERT INTO hecks_dispatch_claims (claim_key) VALUES ($1) ON CONFLICT DO NOTHING " \
+                       "RETURNING claim_key", [key]).ntuples.positive?
+      end
+
       # Claims a pending outbox row with a compare-and-set update, counting the attempt.
       #
       # @param id [Integer] the row id `outbox_enqueue` assigned
       # @return [Boolean] true when the row was pending and is now claimed; false when it is
       #   unknown or another claimer got there first
       # @raise [PG::Error] if the update fails
-      def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
+      def outbox_claim(id)
         pg_exec_params(
           "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = now() " \
           "WHERE id = $1 AND status = 'pending'",
@@ -85,7 +111,7 @@ module Hecks
       # @param error [String, nil] the failure description, or nil to store NULL
       # @return [Boolean] true when exactly one row was updated; false when no row has `id`
       # @raise [PG::Error] if the update fails
-      def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
+      def outbox_settle(id, status:, error: nil)
         pg_exec_params(
           "UPDATE hecks_outbox SET status = $2, error = $3, settled_at = now() WHERE id = $1",
           [id, status.to_s, error]
@@ -100,7 +126,7 @@ module Hecks
       #   keys; `[]` when none match
       # @raise [PG::Error] if the statement fails
       def outbox_rows(status: nil)
-        sql   = "SELECT * FROM hecks_outbox WHERE aggregate = $1"
+        sql   = "SELECT *, extract(epoch from (now() - claimed_at)) AS claimed_for FROM hecks_outbox WHERE aggregate = $1"
         binds = [table]
         if status
           sql << " AND status = $2"
@@ -120,17 +146,17 @@ module Hecks
       end
 
       def outbox_row_from(row)
+        text = %w[delivery_id event_uid aggregate domain kind consumer status error].to_h { |name| [name.to_sym, row[name]] }
         Runtime::Outbox::Row.new(
-          id: row["id"].to_i, delivery_id: row["delivery_id"], event_uid: row["event_uid"], aggregate: row["aggregate"],
-          domain: row["domain"], kind: row["kind"], consumer: row["consumer"],
-          event: JSON.parse(row["event"], symbolize_names: true), status: row["status"],
-          attempts: row["attempts"].to_i, error: row["error"]
+          **text, id: row["id"].to_i, event: JSON.parse(row["event"], symbolize_names: true),
+                  attempts: row["attempts"].to_i, claimed_for: row["claimed_for"]&.to_f
         )
       end
 
       def create_outbox_table!
         @db.exec(CREATE_OUTBOX_TABLE)
         @db.exec("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
+        @db.exec(CREATE_DISPATCH_CLAIMS_TABLE)
       end
     end
   end