hecks 5.0.0 → 6.0.0

data/lib/hecks/runtime/interpreting.rb

@@ -1,11 +1,15 @@
+require_relative "collecting"
 require_relative "value"
 require_relative "aggregate_lock"
 require_relative "needs"
+require_relative "dispatch_claim"
 
 module Hecks
   module Runtime
     # Shared by the stepwise interpreters: the traced step and coercion of declared arguments.
     module Interpreting
+      include DispatchClaim::Claiming
+
       # Gives each including interpreter its own `trace`, set by specs to observe dispatch order.
       # @param interpreter [Class] the class (`CommandInterpreter`, `EntityInterpreter`)
       #   including this module
@@ -60,13 +64,56 @@ module Hecks
       # Runs `order` by sending each `step_<name>` handler; `save` onward shares one transaction.
       # The outbox enqueue rides on `emit`; the vocabulary's step list is a pinned contract.
       def run_dispatch_order(order, ctx)
+        Collecting.active? ? run_collecting(order, ctx) : run_committing(order, ctx)
+      end
+
+      # The ordinary run: every step raises its first refusal, and `save` onward is one transaction.
+      def run_committing(order, ctx)
         split = order.index(:save)
         return order.each { |name| send(:"step_#{name}", ctx) } unless split && ctx.respond_to?(:repository) && ctx.repository
 
         order[0...split].each { |name| send(:"step_#{name}", ctx) }
-        ctx.repository.transaction do
-          order[split..].each { |name| send(:"step_#{name}", ctx) }
-          enqueue_outbox(ctx)
+        ctx.repository.transaction { run_transactional_steps(order[split..], ctx) }
+      end
+
+      # The validating run: every step, in order, with a refusal recorded and not raised. A stage
+      # that recorded one is finished and the run stops there, since a later stage reads what an
+      # earlier one settled. The role is checked first and alone, so a caller who may not run the
+      # command learns only that.
+      def run_collecting(order, ctx)
+        return if role_refused?(ctx)
+
+        split = order.index(:save)
+        before = split ? order[0...split] : order
+        stage = collect_steps(before, ctx, nil)
+        return if Collecting.refusals.any? || !split || !ctx.respond_to?(:repository) || !ctx.repository
+
+        ctx.repository.transaction { collect_steps(order[split..], ctx, stage) }
+      end
+
+      # Whether the role step refused the caller, which it records.
+      def role_refused?(ctx)
+        collect_step(:refuse_role_mismatch, ctx)
+        Collecting.refusals.any?
+      end
+
+      # Runs `names` as a validation does; returns the stage it stopped in, or the last it ran.
+      def collect_steps(names, ctx, stage)
+        names.each do |name|
+          next_stage = Collecting.stage_of(name)
+          break if Collecting.refusals.any? && next_stage != stage
+
+          stage = next_stage
+          collect_step(name, ctx)
+        end
+        stage
+      end
+
+      def collect_step(name, ctx)
+        Collecting.at_stage(Collecting.stage_of(name)) do
+          send(:"step_#{name}", ctx)
+        rescue Hecks::Refused => e
+          Collecting.refuse(e)
         end
       end
 
@@ -81,11 +128,12 @@ module Hecks
       # repository's write lock, and the rest get a striped in-process Mutex (ADR 0036).
       # A nil `lock_key_id` still locks correctly, just by aggregate type.
       def run_dispatch_order_with_isolation(order, ctx, lock_key_id:)
-        capabilities = ctx.repository.capabilities
+        repository = ctx.repository
+        capabilities = repository.capabilities
         if capabilities.include?(:optimistic_concurrency)
           run_dispatch_order(order, ctx)
         elsif capabilities.include?(:cross_process_lock)
-          ctx.repository.with_write_lock { run_dispatch_order(order, ctx) }
+          repository.with_write_lock { run_dispatch_order(order, ctx) }
         else
           AggregateLock.for(ctx.domain, ctx.aggregate, lock_key_id).synchronize { run_dispatch_order(order, ctx) }
         end
@@ -96,10 +144,19 @@ module Hecks
         command.attributes.each_with_object(args.dup) do |attribute, normalized|
           next unless normalized.key?(attribute.name)
 
-          normalized[attribute.name] = coerce_argument(aggregate, command, attribute, normalized[attribute.name])
+          normalized[attribute.name] = coerce_collecting(aggregate, command, attribute, normalized[attribute.name])
         end
       end
 
+      # One argument through `coerce_argument`; when collecting, a refusal is recorded against the
+      # attribute and the value is left as it came, so the next attribute is still checked.
+      def coerce_collecting(aggregate, command, attribute, value)
+        coerce_argument(aggregate, command, attribute, value)
+      rescue Hecks::Refused => e
+        Collecting.refuse(e.within(attribute.name))
+        value
+      end
+
       # One declared argument through the reference gate, the list gate, then coercion.
       def coerce_argument(aggregate, command, attribute, value)
         Value.refuse_object_reference(command, attribute, value)

data/lib/hecks/runtime/invocation_builder.rb

@@ -11,7 +11,10 @@ module Hecks
       include InvocationFacts
 
       # What one `from_call` was asked for, handed to the builder for its receiver shape.
-      Call = Struct.new(:verb, :to, :with, :flat, :entity_depth, :aggregate, :declaring)
+      Call = Struct.new(:verb, :to, :with, :flat, :entity_depth, :aggregate, :declaring) do
+        # @return [Object] the command or operation the call declares, by calling `declaring`
+        def declaration = declaring.call
+      end
       private_constant :Call
 
       # Builds an Invocation for one of three call shapes (:aggregate,
@@ -43,19 +46,19 @@ module Hecks
       private
 
       def aggregate_call(call)
-        command = call.declaring.call
+        command = call.declaration
         facts   = facts_for(command, with: call.with, flat: call.flat)
         new(verb: call.verb, target: route(call.to), facts: facts)
       end
 
       def entity_call(call)
         target  = route(call.to, entity_depth: call.entity_depth)
-        command = call.declaring.call
+        command = call.declaration
         new(verb: call.verb, target: target, facts: facts_for(command, with: call.with, flat: call.flat))
       end
 
       def port_call(call)
-        operation = call.declaring.call
+        operation = call.declaration
         flat      = call.flat.dup
         target    = route(port_receiver(operation, call.aggregate, call.to, flat))
         raise TypeMismatch, "#{operation.hecks_name} requires its receiving aggregate in to:" unless target

data/lib/hecks/runtime/invocation_facts.rb

@@ -1,4 +1,5 @@
 require_relative "errors"
+require_relative "collecting"
 require_relative "refusal_wording"
 
 module Hecks
@@ -52,10 +53,12 @@ module Hecks
         unknown = (offered.keys - declared).sort
         return if unknown.empty?
 
-        raise UnknownArgument,
-              RefusalWording.render_site("UnknownArgument", "unknown_args",
-                                         command: declaring.hecks_name, unknown: unknown,
-                                         declared: declared)
+        Collecting.refuse_each(unknown) do |names|
+          UnknownArgument.new(RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                                         command: declaring.hecks_name, unknown: names,
+                                                         declared: declared),
+                              attribute: names.first)
+        end
       end
 
       # A fact the command `needs`, and an argument its attribute gives a default, are not absent:
@@ -64,10 +67,12 @@ module Hecks
         absent = required_fact_names(declaring) - offered.keys - filled_fact_names(declaring)
         return if absent.empty?
 
-        raise AbsentArgument,
-              RefusalWording.render_site("AbsentArgument", "absent_args",
-                                         command: declaring.hecks_name, absent: absent,
-                                         declared: declared)
+        Collecting.refuse_each(absent) do |names|
+          AbsentArgument.new(RefusalWording.render_site("AbsentArgument", "absent_args",
+                                                        command: declaring.hecks_name, absent: names,
+                                                        declared: declared),
+                             attribute: names.min)
+        end
       end
 
       def required_fact_names(declaring)

data/lib/hecks/runtime/loader/boot_steps.rb

@@ -30,7 +30,8 @@ module Hecks
         # Each domain with a pending marking, with the attribute paths Privacy already marks for it.
         def already_marked_by_domain(dispatcher, registry, provider)
           verb = provider.provided_verb(Bluebook::Capabilities::PRIVACY, :markings_for)
-          registry.pending_privacy_markings.map { |marking| marking[:domain] }.uniq.to_h do |domain|
+          domains = registry.pending_privacy_markings.map { |marking| marking[:domain] }.uniq
+          domains.to_h do |domain|
             [domain, dispatcher.query(verb, domain: domain).map { |row| row[:attribute_path][:value] }]
           end
         end
@@ -54,7 +55,7 @@ module Hecks
         end
 
         # Resolves the Ruby implementation of every adapter a hecksagon binds, and of every
-        # `default_adapter` a world names (a chapter that binds nothing takes its world's).
+        # `default_adapter` a world names (a bluebook that binds nothing takes its world's).
         # An adapter's implementation can register its own persistence plugin as
         # a side effect of loading (e.g. `PostgresEra`) — resolving here, before
         # gates are collected, is what registers those plugins' gates without

data/lib/hecks/runtime/loader/described.rb

@@ -1,3 +1,5 @@
+require_relative "../declarations"
+
 module Hecks
   module Runtime
     class Loader
@@ -7,6 +9,8 @@ module Hecks
       # so a caller that can answer from `directory` alone (a launcher with its help already
       # remembered) never pays for the load. The directory is checked at once.
       class Described
+        include Declarations
+
         # @return [String] the domain directory that was described
         attr_reader :directory
 

data/lib/hecks/runtime/loader.rb

@@ -1,8 +1,7 @@
-require_relative "../adapters/driving/ruby"
 require_relative "../ports/loading"
 require_relative "../ports/persistence"
+require_relative "../ports/dispatch"
 require_relative "dispatcher"
-require_relative "remote_dispatcher"
 require_relative "boot_gates"
 require_relative "registry"
 require_relative "loader/boot_steps"
@@ -11,45 +10,40 @@ require_relative "loader/described"
 module Hecks
   module Runtime
     # Boots a domain: loads its bluebook directory into a fresh Registry, runs
-    # every boot gate, and hands back the bound Dispatcher (or RemoteDispatcher).
+    # every boot gate, and hands back the dispatcher the domain's world names.
+    #
+    # It reads no environment variable and installs no driving adapter: `Hecks::Assembly`
+    # chooses the overlay and plugs the Ruby facade in.
     class Loader
       extend BootSteps
 
-      # Default for a boot's `environment:` keyword: read `HECKS_ENVIRONMENT`. An explicit
-      # `nil` means no overlay, whatever the variable holds.
-      FROM_ENV = :from_env
-
       # Boots `path`: loads its bluebook directory into a fresh Registry, runs
-      # every registered boot gate, and returns the bound dispatcher. Pass
-      # `install_driving: false` to skip the `Widget::Item.Add(...)` global
-      # facade sugar (only a caller dispatching by FQN string needs to).
+      # every registered boot gate, and returns the dispatcher.
       #
       # @param path [String] a domain directory to boot
       # @param shared [String, nil] shared ports/adapters root; nil walks up from `path`
-      # @param environment [String, nil] environment overlay loaded after the domain; defaults
-      #   to `HECKS_ENVIRONMENT`, and an explicit nil loads none
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
+      # @param environment [String, nil] environment overlay loaded after the domain; nil loads none
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted dispatcher
       # @raise [Errno::ENOENT] if `path` names no domain directory
       # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
-      def self.boot(path, shared: nil, install_driving: true, environment: FROM_ENV)
-        described = describe(path, shared: shared, environment: environment)
-        boot_described(described, install_driving: install_driving)
+      def self.boot(path, shared: nil, environment: nil)
+        boot_described(describe(path, shared: shared, environment: environment))
       end
 
-      # Finishes a boot from declarations `describe` already loaded: runs every boot gate and binds
+      # Finishes a boot from declarations `describe` already loaded: runs every boot gate and builds
       # the dispatcher, without reading the domain's files again.
       #
       # @param described [Described] what `describe` answered for the domain to boot
-      # @param install_driving [Boolean] install the `Widget::Item.Add(...)` global facade sugar
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted dispatcher
       # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
-      def self.boot_described(described, install_driving: true)
+      def self.boot_described(described)
         registry = described.registry
         run_boot_gates!(registry, described.directory)
         dispatcher = dispatcher_for(registry)
         redrive_outbox!(dispatcher)
+        redrive_sagas!(dispatcher)
         seed_privacy_markings!(dispatcher, registry)
-        install_driving ? bind_runtime(dispatcher) : dispatcher
+        dispatcher
       end
 
       # Loads `path`'s declarations into a fresh Registry and stops: no boot gate runs, no
@@ -63,12 +57,11 @@ module Hecks
       # @param environment [String, nil] environment overlay loaded after the domain
       # @return [Described] answers `registry` like a booted dispatcher does
       # @raise [Errno::ENOENT] if `path` names no domain directory
-      def self.describe(path, shared: nil, environment: FROM_ENV)
+      def self.describe(path, shared: nil, environment: nil)
         loading   = Ports::Loading.bootstrap
         directory = loading.bluebook_directory(path)
-        overlay   = selected_environment(environment)
 
-        Described.new(directory) { load_declarations(loading, directory, shared, overlay) }
+        Described.new(directory) { load_declarations(loading, directory, shared, environment) }
       end
 
       # Loads the directory's declarations into a fresh Registry, answering it.
@@ -84,19 +77,6 @@ module Hecks
         registry
       end
 
-      # The overlay a boot loads: the caller's own choice (nil meaning none), else the
-      # `HECKS_ENVIRONMENT` variable when the caller left the keyword at its default. A domain
-      # with no `environments/<name>.*` files ignores either.
-      #
-      # @param environment [String, nil, Symbol] the overlay a caller passed, or `FROM_ENV`
-      # @return [String, nil] the overlay name; nil for none
-      def self.selected_environment(environment)
-        return environment unless environment == FROM_ENV
-
-        named = ENV["HECKS_ENVIRONMENT"].to_s.strip
-        named.empty? ? nil : named
-      end
-
       # Redrives pending outbox rows after the dispatcher and saga
       # rehydration both exist (a redriven row may advance a saga, which
       # must already be in memory). Claimed rows are surfaced, never
@@ -107,6 +87,14 @@ module Hecks
         dispatcher.outbox.redrive!
       end
 
+      # Finishes the saga legs a crash cut short, once the dispatcher and the rehydrated instances
+      # both exist. A no-op for a remote dispatcher.
+      def self.redrive_sagas!(dispatcher)
+        return unless dispatcher.respond_to?(:redrive_sagas!)
+
+        dispatcher.redrive_sagas!
+      end
+
       # Boots the exact bluebook/hecksagon/world files in `paths`, in place —
       # unlike `boot`, no directory globbing and no copying into a temp dir
       # (a `persisted_by` path must resolve against the real project root,
@@ -114,22 +102,24 @@ module Hecks
       #
       # @param paths [Array<String>, String] the exact file paths to boot, in load order
       # @param shared [String, nil] shared ports/adapters root; nil walks up from the first path
-      # @param environment [String, nil] environment overlay loaded after the named files;
-      #   defaults to `HECKS_ENVIRONMENT`, and an explicit nil loads none
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
+      # @param environment [String, nil] environment overlay loaded after the named files; nil
+      #   loads none
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted dispatcher
       # @raise [Runtime::WiringError] if a boot gate finds a wiring problem
-      def self.boot_files(paths, shared: nil, install_driving: true, environment: FROM_ENV)
+      def self.boot_files(paths, shared: nil, environment: nil)
         loading   = Ports::Loading.bootstrap
         files     = Array(paths).map { |path| File.expand_path(path) }
         directory = File.dirname(files.first)
-        registry  = load_files(loading, files, shared, selected_environment(environment))
+        registry  = load_files(loading, files, shared, environment)
 
         run_boot_gates!(registry, directory)
-        dispatcher = dispatcher_for(registry)
-        install_driving ? bind_runtime(dispatcher) : dispatcher
+        dispatcher_for(registry)
       end
 
-      # Loads exactly `files` into a fresh Registry rooted beside their directory, answering it.
+      # Loads exactly `files` into a fresh Registry rooted beside their directory, answering it. An
+      # `.adapter` among them stands in for the shared root's adapters, which are then left
+      # unloaded, so a
+      # test can answer a port with its own adapter and never construct the domain's real one.
       def self.load_files(loading, files, shared, overlay)
         directory = File.dirname(files.first)
         root      = loading.shared_root(shared, directory)
@@ -137,32 +127,32 @@ module Hecks
 
         Hecks.with_registry(registry) do
           loading.load_library
-          loading.load_project(root)
+          loading.load_project(root, adapters: files.none? { |file| file.end_with?(".adapter") })
           loading.load_selected(files, environment: overlay)
         end
         registry
       end
 
-      # `RemoteDispatcher` for a domain declaring `dispatched_by("Lambda")`,
-      # `Dispatcher` otherwise. That's an explicit opt-in, never inferred from
-      # `deployed_to("AwsLambda")` alone — that verb only means a deploy
-      # target exists, and treating it as "dispatch via Lambda" would reroute
-      # every local boot of a domain that merely declares one.
+      # The local `Dispatcher`, unless the domain's world binds the dispatch port: then the bound
+      # adapter builds the dispatcher (`dispatched_by("Lambda")` routes writes to a Lambda). That
+      # is an explicit opt-in, never inferred from `deployed_to("AwsLambda")` alone, which only
+      # means a deploy target exists.
+      #
+      # @param registry [Runtime::Registry] the booted registry
+      # @return [Runtime::Dispatcher, Object] the dispatcher the boot hands back
+      # @raise [Runtime::WiringError] if the bound adapter cannot build a dispatcher
       def self.dispatcher_for(registry)
-        domain = registry.bluebooks.keys.first
-        settings = registry.world(domain)&.for_verb("dispatched_by") || {}
-        return Dispatcher.new(registry) unless settings[:adapter] == "Lambda"
+        settings = registry.world(registry.bluebooks.keys.first)&.for_verb(Ports::Dispatch::VERB) || {}
+        return Dispatcher.new(registry) unless settings[:adapter]
 
-        RemoteDispatcher.new(registry, region: settings.fetch(:region, "us-east-1"), function: settings[:function])
+        Ports::Dispatch.dispatcher(registry, settings)
       end
 
-      # Installs the facade sugar (`Widget::Item.Add(...)`) closed over
-      # `dispatcher`. The binding lives in the facade's own modules, not a
-      # class-level global, so two boots in one process don't share one name.
-      def self.bind_runtime(dispatcher)
-        Adapters::Driving::Ruby.install(dispatcher)
-        dispatcher
-      end
+      # Installs the Ruby facade over a dispatcher built by hand. See `Hecks.bind_runtime`.
+      #
+      # @param dispatcher [Runtime::Dispatcher] a dispatcher over a verified registry
+      # @return [Runtime::Dispatcher] the same dispatcher
+      def self.bind_runtime(dispatcher) = Hecks.bind_runtime(dispatcher)
     end
   end
 end

data/lib/hecks/runtime/outbox/redrive.rb

@@ -0,0 +1,105 @@
+module Hecks
+  module Runtime
+    module Outbox
+      # What the relay does with the rows a crash left behind: a pending row is always safe to
+      # deliver again, a claimed one (claimed, then never settled) is only surfaced until the
+      # caller says its effect did not run. Mixed into `Relay`, which supplies `stores`,
+      # `deliver_row` and `log`.
+      module Redrive
+        # `pending` rows are always safe to redrive (never claimed yet).
+        # `claimed` rows are only surfaced — redelivering a maybe-already-run
+        # consumer needs an explicit `claimed: true`.
+        def redrive!(claimed: false)
+          stores.flat_map { |repository| redrive_store(repository, claimed) }
+        end
+
+        # Redrives the one claimed row named by its delivery id, on the caller's word that its
+        # effect did not run. Every other claimed row stays as it is, and a pending row is not
+        # touched.
+        #
+        # @param delivery_id [String] the row's `delivery_id`, as the stalled-row warning names it
+        # @return [Array<Row>] the row when it redrove, `[]` when its consumer failed again
+        # @raise [Hecks::Runtime::NotFound] when no claimed row has that delivery id, or the row
+        #   was claimed too recently to be stalled
+        def redrive_row!(delivery_id)
+          repository, row = stalled_row(delivery_id)
+          redrive_claimed?(row, repository, true) ? [row] : []
+        end
+
+        # Settles the one claimed row named by its delivery id as failed, without running its
+        # consumer: for a row whose effect is known to have landed, or that nobody wants run, so
+        # the stalled-row warning stops naming it. The error says it was abandoned by hand.
+        #
+        # @param delivery_id [String] the row's `delivery_id`, as the stalled-row warning names it
+        # @return [Array<Row>] the row that was settled
+        # @raise [Hecks::Runtime::NotFound] when no claimed row has that delivery id, or the row
+        #   was claimed too recently to be stalled
+        def abandon_row!(delivery_id)
+          repository, row = stalled_row(delivery_id)
+          [abandon(row, repository)]
+        end
+
+        private
+
+        # The store and the claimed row that carry `delivery_id`, once the row has stood claimed
+        # past `STALLED_AFTER`: a younger claim is a reaction running in another process.
+        def stalled_row(delivery_id)
+          stores.each do |repository|
+            row = repository.outbox_rows(status: "claimed").find { |candidate| candidate.delivery_id == delivery_id }
+            next unless row
+            raise Hecks::Runtime::NotFound, in_flight_wording(row) unless row.stalled?
+
+            return [repository, row]
+          end
+          raise Hecks::Runtime::NotFound, "no claimed outbox row #{delivery_id.inspect}"
+        end
+
+        def in_flight_wording(row)
+          "outbox row #{row.delivery_id} is in flight, claimed #{row.claimed_seconds_ago}s ago; only a row " \
+            "claimed over #{STALLED_AFTER}s ago is stalled"
+        end
+
+        def abandon(row, repository)
+          repository.outbox_settle(row.id, status: "failed", error: "abandoned by an operator, not redelivered")
+          row.status = "failed"
+          row
+        end
+
+        # The rows of one store that redrove: its pending rows first, then its claimed ones.
+        def redrive_store(repository, claimed)
+          redriven = repository.outbox_rows(status: "pending").select { |row| redrive_pending?(row, repository) }
+          stalled = repository.outbox_rows(status: "claimed").select(&:stalled?)
+          redriven + stalled.select { |row| redrive_claimed?(row, repository, claimed) }
+        end
+
+        def redrive_pending?(row, repository) = !withheld?(row) && deliver_row(row, repository)
+
+        def redrive_claimed?(row, repository, claimed)
+          unless claimed
+            warn_stalled(row)
+            return false
+          end
+          return false if withheld?(row)
+
+          repository.outbox_settle(row.id, status: "pending")
+          row.status = "pending"
+          deliver_row(row, repository)
+        end
+
+        def warn_stalled(row)
+          warn stalled_wording(row)
+          @log << { outbox: row.delivery_id, consumer: row.consumer, kind: row.kind, stalled: true,
+                    event: row.event[:name], aggregate: row.event[:aggregate], id: row.event[:id] }
+        end
+
+        def stalled_wording(row)
+          "[hecks] outbox row #{row.delivery_id} (#{row.consumer} on #{row.event[:name]} for " \
+            "#{row.event[:aggregate]}##{row.event[:id]}) was claimed before the last crash/restart and never " \
+            "settled — its #{row.kind} may or may not have actually run. hecks does not auto-redrive a claimed " \
+            "row (the outcome is unknown, and redelivering it could double the effect); inspect it and " \
+            "redrive by hand with `runtime.outbox.redrive!(claimed: true)` once you know it is safe."
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/outbox/relay.rb

@@ -1,4 +1,6 @@
 require_relative "consumer_runner"
+require_relative "redrive"
+require_relative "runnable"
 
 module Hecks
   module Runtime
@@ -7,6 +9,8 @@ module Hecks
       # them inline, and redrives whatever a crash left behind.
       class Relay
         include ConsumerRunner
+        include Redrive
+        include Runnable
 
         attr_reader :registry, :log
 
@@ -27,6 +31,11 @@ module Hecks
 
         def attached? = !@policies.nil?
 
+        # Forgets every delivery the relay recorded, as a fresh boot starts with none.
+        #
+        # @return [void]
+        def clear_log = @log.clear
+
         # Called inside the save transaction for command/entity paths, and
         # outside one for port operations (which save nothing). Returns nil
         # when the repository has no outbox — callers then react directly.
@@ -35,7 +44,8 @@ module Hecks
           return [] if events.empty?
 
           rows = Fanout.rows_for(@registry, events, domain)
-          rows.each { |row| row.aggregate = repository.aggregate.storage_name }
+          aggregate = repository.aggregate
+          rows.each { |row| row.aggregate = aggregate.storage_name }
           repository.outbox_enqueue(rows)
         end
 
@@ -69,13 +79,6 @@ module Hecks
           stores.flat_map { |repository| repository.outbox_rows(status: status) }
         end
 
-        # `pending` rows are always safe to redrive (never claimed yet).
-        # `claimed` rows are only surfaced — redelivering a maybe-already-run
-        # consumer needs an explicit `claimed: true`.
-        def redrive!(claimed: false)
-          stores.flat_map { |repository| redrive_store(repository, claimed) }
-        end
-
         private
 
         def settle_delivery(row, repository)
@@ -99,37 +102,6 @@ module Hecks
                     reason: row.error }
         end
 
-        # The rows of one store that redrove: its pending rows first, then its claimed ones.
-        def redrive_store(repository, claimed)
-          redriven = repository.outbox_rows(status: "pending").select { |row| deliver_row(row, repository) }
-          redriven + repository.outbox_rows(status: "claimed").select { |row| redrive_claimed?(row, repository, claimed) }
-        end
-
-        def redrive_claimed?(row, repository, claimed)
-          unless claimed
-            warn_stalled(row)
-            return false
-          end
-
-          repository.outbox_settle(row.id, status: "pending")
-          row.status = "pending"
-          deliver_row(row, repository)
-        end
-
-        def warn_stalled(row)
-          warn stalled_wording(row)
-          @log << { outbox: row.delivery_id, consumer: row.consumer, kind: row.kind, stalled: true,
-                    event: row.event[:name], aggregate: row.event[:aggregate], id: row.event[:id] }
-        end
-
-        def stalled_wording(row)
-          "[hecks] outbox row #{row.delivery_id} (#{row.consumer} on #{row.event[:name]} for " \
-            "#{row.event[:aggregate]}##{row.event[:id]}) was claimed before the last crash/restart and never " \
-            "settled — its #{row.kind} may or may not have actually run. hecks does not auto-redrive a claimed " \
-            "row (the outcome is unknown, and redelivering it could double the effect); inspect it and " \
-            "redrive by hand with `runtime.outbox.redrive!(claimed: true)` once you know it is safe."
-        end
-
         # Bluebooks, not hecksagons: a domain with no hecksagon is still
         # bound to the default Memory adapter. An aggregate a hecksagon left
         # unbound raises WiringError here and is skipped.