active_durable 0.6.0 → 0.8.0

data/lib/active_durable/operations.rb

@@ -14,22 +14,25 @@ module ActiveDurable
   module Operations
     module_function
 
-    # A blocked execution tries again from where it stopped: failed steps (or failed undos, if it was
-    # compensating) get a fresh set of attempts. Deploy the fix first when the cause was a bug.
+    # A blocked execution tries again from where it stopped: the step that blocked it (or the failed undos, if it
+    # was compensating) gets a fresh set of attempts. Failed steps the recipe already handled, such as a payment
+    # provider it replaced with another one, stay failed: running them again would pay twice. Deploy the fix
+    # first when the cause was a bug.
     def retry(execution_id)
       execution = with_idle_execution(execution_id, allowed: %w[blocked]) do |record|
-        failed = record.steps.where(status: "failed")
-        failed = record.compensating ? failed.where(kind: "undo") : failed.where.not(kind: "undo")
-        failed.update_all(status: "retrying", attempts: 0, wake_at: nil, updated_at: ActiveDurable.now)
+        blocking_steps(record).update_all(status: "retrying", attempts: 0, wake_at: nil,
+                                          updated_at: ActiveDurable.now)
         reopen!(record, error: nil)
       end
       ActiveDurable.instrument("retried", execution_id: execution.id)
       execution
     end
 
-    # Undoes every completed step, last one first. Not possible once the point of no return was passed.
+    # Undoes every completed step, last one first. Not possible once the point of no return was passed, nor while
+    # the execution is running: the lease is only renewed on notebook writes, so a worker may still be inside a
+    # slow step after its lease ran out (the sweeper resumes it if the worker died).
     def compensate(execution_id, reason: "compensated by an operator")
-      execution = with_idle_execution(execution_id, allowed: %w[blocked pending running sleeping waiting]) do |record|
+      execution = with_idle_execution(execution_id, allowed: %w[blocked pending sleeping waiting]) do |record|
         raise Error, "#{record.id} is already compensating; use ActiveDurable.retry to resume it" if record.compensating
         if record.steps.exists?(kind: "pivot", status: "completed")
           raise Error, "#{record.id} already passed its point of no return; it can only move forward"
@@ -52,12 +55,10 @@ module ActiveDurable
       Record.transaction do
         original = Execution.lock.find(execution_id)
         check_rerunnable!(original)
-        start = original.steps.where.not(kind: %w[undo hook]).find_by(name: from)
-        raise Error, "#{original.id} has no step :#{from} in its notebook" unless start
-
+        start = rerun_start(original, from)
         execution = Execution.create!(id: rerun_id(original), recipe: original.recipe,
                                       recipe_version: original.recipe_version, input: original.input,
-                                      status: "pending", forked_from: original.id)
+                                      context: original.context, status: "pending", forked_from: original.id)
         copy_steps(original, execution, before: start.position)
         original.update_columns(status: "superseded", updated_at: ActiveDurable.now) if original.status == "blocked"
       end
@@ -65,9 +66,19 @@ module ActiveDurable
       execution
     end
 
+    def rerun_start(original, from)
+      start = original.steps.where.not(kind: %w[undo hook]).find_by(name: from)
+      raise Error, "#{original.id} has no step :#{from} in its notebook" unless start
+      return start if start.position
+
+      parallel = from.split("/", 2).first
+      raise Error, ":#{from} is a branch of flow.parallel :#{parallel}; rerun from :#{parallel} instead"
+    end
+
     def with_idle_execution(execution_id, allowed:)
       execution = Record.transaction do
         record = Execution.lock.find(execution_id)
+        raise Error, "#{record.id} continued as #{record.continued_as}; use that one" if record.continued?
         unless allowed.include?(record.status)
           raise Error, "#{record.id} is #{record.status}; this works on #{allowed.join(", ")} executions"
         end
@@ -88,6 +99,7 @@ module ActiveDurable
     end
 
     def check_rerunnable!(original)
+      raise Error, "#{original.id} continued as #{original.continued_as}; rerun that one" if original.continued?
       return if original.status == "completed"
       return if original.status == "blocked" && !original.compensating
 
@@ -95,18 +107,44 @@ module ActiveDurable
                    "only completed executions, or blocked ones that are not compensating, can be rerun"
     end
 
+    # Moving forward: the step named by the error, or the whole flow.parallel it belongs to, and every step that
+    # hit a bug. Compensating: every failed undo, since each of them stopped the compensation.
+    def blocking_steps(record)
+      steps = record.steps
+      return steps.where(kind: "undo", status: "failed") if record.compensating
+
+      name = record.error.is_a?(Hash) ? record.error["step"].to_s : ""
+      failed = steps.where(status: "failed").where.not(kind: %w[undo hook])
+      parallel = failed.where(kind: "parallel").pluck(:name)
+                       .find { |group| name == group || name.start_with?("#{group}/") }
+      named = if parallel
+                failed.where(name: parallel).or(failed.where("name LIKE ?", "#{Step.sanitize_sql_like(parallel)}/%"))
+              else
+                failed.where(name: name)
+              end
+      named.or(steps.where(status: "blocked"))
+    end
+
+    # A random suffix, never a count: a pruned rerun must not hand its id, and so its tickets, to a new one.
     def rerun_id(original)
-      root = original.id.sub(/~rerun-\d+\z/, "")
-      count = Execution.where("id LIKE ?", "#{Execution.sanitize_sql_like(root)}~rerun-%").count
-      "#{root}~rerun-#{count + 1}"
+      root = original.id.sub(/~rerun-\h+\z/, "")
+      "#{root}~rerun-#{SecureRandom.hex(4)}"
     end
 
+    # The steps before `from` that completed or failed (a failure the recipe handled must stay handled), and the
+    # branches of each flow.parallel among them, in the order they finished, so their undos still run.
     def copy_steps(original, execution, before:)
+      forward = original.steps.where.not(kind: %w[undo hook]).where(status: %w[completed failed])
+      kept = forward.where(position: ...before).order(:position).to_a
+      groups = kept.select { |step| step.kind == "parallel" }.map { |step| "#{step.name}/" }
+      branches = forward.where(position: nil).order(:updated_at, :id).select do |step|
+        groups.any? { |prefix| step.name.start_with?(prefix) }
+      end
       now = ActiveDurable.now
-      rows = original.steps.where.not(kind: %w[undo hook]).where(status: "completed").where(position: ...before)
-                     .map do |step|
+      rows = (kept + branches).map do |step|
         { execution_id: execution.id, name: step.name, kind: step.kind, position: step.position,
-          status: "completed", attempts: step.attempts, result: step.result, created_at: now, updated_at: now }
+          status: step.status, attempts: step.attempts, result: step.result, error: step.error,
+          created_at: now, updated_at: now }
       end
       Step.insert_all!(rows) if rows.any?
     end

data/lib/active_durable/pruner.rb

@@ -2,12 +2,11 @@
 
 module ActiveDurable
   # Deletes finished executions (completed, compensated, superseded) older than a cutoff, with their notebook and
-  # their signals. Active and blocked executions are never touched: they still need a worker or a person.
+  # their signals. Active and blocked executions are never touched: they still need a worker or a person. A
+  # continued execution goes together with the one that carried it on, never before: its id may still be in use.
   #
   # @api private
   module Pruner
-    FINISHED = %w[completed compensated superseded].freeze
-
     module_function
 
     # Returns how many executions were deleted. Each batch is deleted in its own transaction, steps and signals
@@ -18,9 +17,12 @@ module ActiveDurable
       cutoff = now - older_than.to_f
       deleted = 0
       loop do
-        ids = Execution.where(status: FINISHED).where("updated_at < ?", cutoff).limit(batch_size).pluck(:id)
+        ids = Execution.where(status: Execution::FINISHED - ["continued"]).where("updated_at < ?", cutoff)
+                       .limit(batch_size).pluck(:id)
         break if ids.empty?
 
+        ids += predecessors(ids)
+
         Record.transaction do
           Step.where(execution_id: ids).delete_all
           SignalRecord.where(execution_id: ids).delete_all
@@ -30,5 +32,18 @@ module ActiveDurable
       end
       deleted
     end
+
+    # The continued executions that led to these ones, all the way back.
+    def predecessors(ids)
+      return [] unless Execution.continuations?
+
+      found = []
+      layer = ids
+      until layer.empty?
+        layer = Execution.where(continued_as: layer).pluck(:id)
+        found.concat(layer)
+      end
+      found
+    end
   end
 end

data/lib/active_durable/record.rb

@@ -8,8 +8,16 @@ module ActiveDurable
   class Record < ActiveRecord::Base
     self.abstract_class = true
 
+    # JSON that reads back with its hash keys sorted, whatever order the database stored them in (see
+    # Serializer.canonical).
+    class CanonicalJson < ActiveRecord::Type::Json
+      def deserialize(value)
+        Serializer.canonical(super)
+      end
+    end
+
     # A JSON type object (not the :json symbol): resolving a symbol needs a database connection,
     # and these classes may load before the app has configured one.
-    JSON_TYPE = ActiveRecord::Type::Json.new
+    JSON_TYPE = CanonicalJson.new
   end
 end

data/lib/active_durable/runner.rb

@@ -8,7 +8,7 @@ module ActiveDurable
   class Runner
     SUSPEND = :active_durable_suspend
 
-    # Returns :completed, :compensated, :blocked, :sleeping, :waiting, :busy or :lease_lost.
+    # Returns :completed, :compensated, :continued, :blocked, :sleeping, :waiting, :busy or :lease_lost.
     def self.run(execution_id)
       lease = Lease.claim(execution_id)
       return :busy unless lease
@@ -25,8 +25,10 @@ module ActiveDurable
     end
 
     def run
-      ActiveDurable.instrument("execution", execution_id: execution.id, recipe: execution.recipe) do
-        catch(SUSPEND) { run_recipe }
+      ActiveDurable.with_context(execution.context) do
+        ActiveDurable.instrument("execution", execution_id: execution.id, recipe: execution.recipe) do
+          catch(SUSPEND) { run_recipe }
+        end
       end
     rescue LeaseLost => e
       ActiveDurable.config.logger.warn("[ActiveDurable] #{e.message}")
@@ -38,12 +40,35 @@ module ActiveDurable
       lease.release!(status: status, wake_at: wake_at)
       ActiveDurable.enqueue(execution.id, wait_until: wake_at) if wake_at
       # A signal may have been committed while we held the lease; its own job found us busy.
-      if status == "waiting" && SignalRecord.pending.exists?(execution_id: execution.id)
+      if status == "waiting" && SignalRecord.awaited.exists?(execution_id: execution.id)
         ActiveDurable.enqueue(execution.id)
       end
       throw SUSPEND, status.to_sym
     end
 
+    # flow.continue_as_new: in one transaction, closes this execution, creates the one that carries on and moves the
+    # pending signals to it. Closing it first takes its row lock, so ActiveDurable.signal (which locks the row too)
+    # either commits before, and its signal is moved, or waits and then follows continued_as.
+    def continue_as_new!(input)
+      unless Execution.continuations?
+        raise InvalidRecipe, "flow.continue_as_new needs the continued_as column. Run rails generate " \
+                             "active_durable:upgrade and rails db:migrate."
+      end
+
+      successor_id = ActiveDurable.next_in_chain(execution.id)
+      recipe = ActiveDurable.registry.latest(execution.recipe)
+      Record.transaction do
+        lease.release!(status: "continued", continued_as: successor_id, wake_at: nil)
+        ActiveDurable.crash_point(:continue_as_new, successor_id)
+        Execution.create!(id: successor_id, recipe: recipe.name, recipe_version: recipe.version, input: input,
+                          context: execution.context, status: "pending")
+        SignalRecord.pending.where(execution_id: execution.id).update_all(execution_id: successor_id)
+      end
+      ActiveDurable.instrument("continued", execution_id: execution.id, recipe: execution.recipe,
+                                            continued_as: successor_id)
+      throw SUSPEND, :continued
+    end
+
     private
 
     def run_recipe
@@ -58,12 +83,16 @@ module ActiveDurable
       block!(e)
     rescue StandardError => e
       fail!(e)
+    rescue ScriptError, SystemStackError => e # LoadError, NotImplementedError: bugs that StandardError misses
+      block!(@flow&.blocked_by || e)
     end
 
     # Only a step that failed for good (StepFailed) or a business rejection (Abort) undoes the saga. Anything else
     # the recipe raises is a bug: the execution is blocked, so fixing the code and calling ActiveDurable.retry
-    # carries it forward instead of refunding customers.
+    # carries it forward instead of refunding customers. A step that hit a bug blocks the run even if the recipe
+    # rescued its error.
     def fail!(error)
+      return block!(@flow.blocked_by) if @flow&.blocked_by
       return block!(error) if @flow.nil? || @flow.pivoted? || !compensates?(error)
 
       start_compensation!(error) unless @flow.compensating?
@@ -124,14 +153,14 @@ module ActiveDurable
 
       ActiveDurable.crash_point(:before_hook, name)
       ActiveDurable.instrument("hook", execution_id: execution.id, step: name, kind: "hook") do
-        notebook.transaction do
+        notebook.transaction(records: name) do
           hook.call
           ActiveDurable.crash_point(:after_hook_call, name)
           notebook.complete!(name, kind: "hook", position: nil, result: nil)
         end
       end
       ActiveDurable.crash_point(:after_hook_record, name)
-    rescue StandardError => e
+    rescue StandardError, ScriptError, SystemStackError => e
       raise if e.is_a?(HookFailed)
 
       raise HookFailed.new(event, e)
@@ -148,13 +177,13 @@ module ActiveDurable
       ActiveDurable.crash_point(:before_undo, entry.name)
       ActiveDurable.instrument("undo", execution_id: execution.id, step: entry.name) do
         if entry.kind == "transaction"
-          notebook.transaction { call_undo(entry, ticket, name) }
+          notebook.transaction(records: name) { call_undo(entry, ticket, name) }
         else
           call_undo(entry, ticket, name)
         end
       end
       ActiveDurable.crash_point(:after_undo_record, entry.name)
-    rescue StandardError => e
+    rescue StandardError, ScriptError, SystemStackError => e
       retry_undo!(entry, name, record, e)
     end
 
@@ -172,13 +201,19 @@ module ActiveDurable
       notebook.complete!(name, kind: "undo", position: nil, result: nil)
     end
 
+    # An undo is retried until config.undo_attempts, then the execution is blocked. A bug blocks it at once.
     def retry_undo!(entry, name, record, error)
       attempts = (record&.attempts || 0) + 1
       dumped = ActiveDurable.dump_error(error, step: name)
       max = ActiveDurable.config.undo_attempts
+      if ActiveDurable.code_error?(error)
+        notebook.fail!(name, kind: "undo", position: nil, attempts: attempts, error: dumped)
+        raise UndoFailed.new("undo of :#{entry.name} cannot run: #{error.class}: #{error.message}", step_name: name)
+      end
       if attempts >= max
         notebook.fail!(name, kind: "undo", position: nil, attempts: attempts, error: dumped)
-        raise UndoFailed, "undo of :#{entry.name} failed #{attempts} times (#{error.class}: #{error.message})"
+        raise UndoFailed.new("undo of :#{entry.name} failed #{attempts} times (#{error.class}: #{error.message})",
+                             step_name: name)
       end
 
       wake_at = ActiveDurable.now + RetryPolicy.new(attempts: max).delay(attempts)

data/lib/active_durable/serializer.rb

@@ -2,8 +2,9 @@
 
 module ActiveDurable
   # Step results, inputs and signal payloads live in the notebook as JSON. This module turns a value
-  # into exactly what a later replay will read back (string keys, no symbols), so the first run and a
-  # replay behave the same. Anything that is not plain JSON is rejected with a message that says where.
+  # into exactly what a later replay will read back (string keys, no symbols, UTF-8 strings, keys sorted), so the
+  # first run and a replay behave the same. Anything that is not plain JSON, or that some database cannot store (a NUL
+  # character, bytes that are not UTF-8), is rejected with a message that says where.
   #
   # @api private
   module Serializer
@@ -11,7 +12,8 @@ module ActiveDurable
 
     def normalize(value, path = "value")
       case value
-      when nil, true, false, String, Integer then value
+      when nil, true, false, Integer then value
+      when String then utf8(value, path)
       when Float then finite_float(value, path)
       when Symbol then value.to_s
       when Array then value.each_with_index.map { |item, index| normalize(item, "#{path}[#{index}]") }
@@ -25,12 +27,47 @@ module ActiveDurable
     end
 
     def normalize_hash(hash, path)
-      hash.each_with_object({}) do |(key, item), out|
+      out = hash.each_with_object({}) do |(key, item), normalized|
         key = key.to_s if key.is_a?(Symbol)
         raise NotSerializable, "#{path} has a #{key.class} key; use strings or symbols" unless key.is_a?(String)
 
-        out[key] = normalize(item, "#{path}[#{key.inspect}]")
+        key = utf8(key, "a key of #{path}")
+        normalized[key] = normalize(item, "#{path}[#{key.inspect}]")
       end
+      out.sort.to_h
+    end
+
+    # Databases do not keep the order of hash keys: PostgreSQL's jsonb and MySQL's JSON put shorter keys first.
+    # Sorting them, when writing and when reading back, gives a replay the very same hash as the first run, down
+    # to the order of its keys. That matters when a result is sent somewhere that compares bytes, such as an AI
+    # provider that checks the conversation it is sent again.
+    def canonical(value)
+      case value
+      when Hash then value.sort.to_h { |key, item| [key, canonical(item)] }
+      when Array then value.map { |item| canonical(item) }
+      else value
+      end
+    end
+
+    # Binary strings (Net::HTTP response bodies) are fine when their bytes are UTF-8; other encodings are converted.
+    def utf8(value, path)
+      string = value
+      if [Encoding::BINARY, Encoding::US_ASCII].include?(string.encoding)
+        string = string.dup.force_encoding(Encoding::UTF_8)
+      elsif string.encoding != Encoding::UTF_8
+        string = string.encode(Encoding::UTF_8)
+      end
+      unless string.valid_encoding?
+        raise NotSerializable, "#{path} has bytes that are not UTF-8. Decode it with the right encoding, or " \
+                               "Base64-encode binary data."
+      end
+      if string.include?("\u0000")
+        raise NotSerializable, "#{path} contains a NUL character (\\u0000), which PostgreSQL cannot store. " \
+                               "Strip it, or Base64-encode binary data."
+      end
+      string
+    rescue EncodingError => e
+      raise NotSerializable, "#{path} cannot be converted to UTF-8 (#{e.message})"
     end
 
     def finite_float(value, path)

data/lib/active_durable/signal_record.rb

@@ -13,10 +13,26 @@ module ActiveDurable
 
     scope :pending, -> { where(consumed_at: nil) }
 
+    # Pending signals that their execution is waiting for right now. Any other pending signal (a duplicate, or one
+    # for a later flow.wait_for) must not wake the execution up: it would only go back to waiting, forever.
+    scope :awaited, lambda {
+      steps = Step.arel_table
+      awaits = if Step.signal_names?
+                 Arel::Nodes::NamedFunction.new("COALESCE", [steps[:signal_name], steps[:name]])
+               else
+                 steps[:name]
+               end
+      waiting = steps.project(Arel.sql("1"))
+                     .where(steps[:execution_id].eq(arel_table[:execution_id])
+                     .and(awaits.eq(arel_table[:name]))
+                     .and(steps[:status].eq("waiting")))
+      pending.where(waiting.exists)
+    }
+
     after_create_commit { ActiveDurable.enqueue(execution_id) }
 
-    def self.next_for(execution_id, name)
-      pending.where(execution_id: execution_id, name: name.to_s).order(:id).first
+    def self.pending_for(execution_id, name)
+      pending.where(execution_id: execution_id, name: name.to_s).order(:id)
     end
   end
 end

data/lib/active_durable/step.rb

@@ -23,10 +23,30 @@ module ActiveDurable
       status == "retrying"
     end
 
+    # It hit a bug, or its result could not be recorded. It runs again when the execution is retried.
+    def blocked?
+      status == "blocked"
+    end
+
+    # It ran without recording a result: between attempts, or stopped by a bug. Its effect may have happened.
+    def unfinished?
+      retrying? || blocked?
+    end
+
     def waiting?
       status == "waiting"
     end
 
+    # The name of the signal a waiting step is waiting for.
+    def awaits
+      (self.class.signal_names? && signal_name) || name
+    end
+
+    # @api private
+    def self.signal_names?
+      column_names.include?("signal_name")
+    end
+
     def undo?
       kind == "undo"
     end

data/lib/active_durable/sweeper.rb

@@ -35,7 +35,7 @@ module ActiveDurable
                        .where("updated_at < ?", now - ActiveDurable.config.sweep_grace.to_f)
       ready = quiet.where(status: %w[pending running])
                    .or(quiet.where(wake_at: ..now))
-                   .or(quiet.where(status: "waiting", id: SignalRecord.pending.select(:execution_id)))
+                   .or(quiet.where(status: "waiting", id: SignalRecord.awaited.select(:execution_id)))
       ready.pluck(:id)
     end
   end

data/lib/active_durable/testing.rb

@@ -23,16 +23,21 @@ module ActiveDurable
     end
 
     # Runs an execution synchronously until it finishes, fast-forwarding sleeps, retries and expired
-    # leases. Signals given as { name => payload } are delivered when the saga waits for them.
-    # Returns the execution; it stays "waiting" if it waits for a signal you did not provide.
-    def drain(execution_id, signals: {}, max_runs: 500)
+    # leases, and following flow.continue_as_new to the execution that carries on. Signals given as
+    # { name => payload } are delivered, once each, when the saga waits for them. Returns the (last) execution; it
+    # stays "waiting" if it waits for a signal you did not provide.
+    #
+    # A wait with a timeout is fast-forwarded to it too, so the saga goes on as if no signal came. Pass
+    # `expire_waits: false` to stop at the wait instead, send signals yourself and drain again: that is how to
+    # test a conversation turn by turn.
+    def drain(execution_id, signals: {}, max_runs: 500, expire_waits: true)
       signals = signals.transform_keys(&:to_s)
       max_runs.times do
-        execution = Execution.find(execution_id)
+        execution = ActiveDurable.find(execution_id, latest: true)
         return execution if execution.terminal?
-        return execution unless ready_for_next_run?(execution, signals)
+        return execution unless ready_for_next_run?(execution, signals, expire_waits: expire_waits)
 
-        Runner.run(execution_id)
+        Runner.run(execution.id)
       end
       raise Error, "execution #{execution_id} did not settle after #{max_runs} runs"
     end
@@ -96,12 +101,12 @@ module ActiveDurable
     # Decides what has to happen before the next run. Returns false when nothing can move the execution.
     #
     # @api private
-    def ready_for_next_run?(execution, signals)
+    def ready_for_next_run?(execution, signals, expire_waits: true)
       now = ActiveDurable.now
       if execution.locked_until && execution.locked_until > now
         travel(execution.locked_until - now + 0.001) # a crashed worker still holds the lease
       elsif execution.status == "waiting"
-        return waiting_can_move?(execution, signals, now)
+        return waiting_can_move?(execution, signals, now, expire_waits: expire_waits)
       elsif execution.wake_at && execution.wake_at > now
         travel(execution.wake_at - now + 0.001)
       end
@@ -109,13 +114,13 @@ module ActiveDurable
     end
 
     # @api private
-    def waiting_can_move?(execution, signals, now)
-      return true if SignalRecord.pending.exists?(execution_id: execution.id)
+    def waiting_can_move?(execution, signals, now, expire_waits: true)
+      return true if SignalRecord.awaited.exists?(execution_id: execution.id)
 
       waiting = execution.steps.find_by(status: "waiting")
-      if waiting && signals.key?(waiting.name)
-        ActiveDurable.signal(execution.id, waiting.name, signals[waiting.name])
-      elsif execution.wake_at
+      if waiting && signals.key?(waiting.awaits)
+        ActiveDurable.signal(execution.id, waiting.awaits, signals.delete(waiting.awaits))
+      elsif execution.wake_at && expire_waits
         travel(execution.wake_at - now + 0.001) if execution.wake_at > now
       else
         return false

data/lib/active_durable/version.rb

@@ -2,5 +2,5 @@
 
 module ActiveDurable
   # The gem's version.
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/active_durable.rb

@@ -119,46 +119,114 @@ module ActiveDurable
     # @param input [Hash] keyword arguments for the recipe; stored as JSON
     # @return [Execution]
     # @raise [UnknownRecipe] if no recipe has that name
-    # @raise [ArgumentError] if the id already belongs to an execution of another recipe
+    # @raise [ArgumentError] if the id already belongs to an execution of another recipe, or is blank, has a "/",
+    #   a NUL character or bytes that are not UTF-8
     # @raise [NotSerializable] if the input cannot be stored as JSON
     # @example
     #   Durable.start(:checkout, id: "checkout-#{order.id}", order_id: order.id)
-    def start(name, id: nil, **input)
+    def start(name, id: nil, context: nil, **input)
       recipe = registry.latest(name)
       attributes = { recipe: recipe.name, recipe_version: recipe.version, status: "pending",
                      input: Serializer.normalize(input, "input") }
+      captured = capture_context(context)
+      attributes[:context] = captured unless captured.nil?
       return Execution.create!(attributes.merge(id: "#{recipe.name}-#{SecureRandom.uuid}")) if id.nil?
 
-      execution = Execution.create_or_find_by!(id: id.to_s) { |record| record.assign_attributes(attributes) }
+      id = check_id!(id)
+      execution = begin
+        Execution.create_or_find_by!(id: id) { |record| record.assign_attributes(attributes) }
+      rescue ActiveRecord::RecordNotFound
+        # Rails < 7.1 on MySQL: inside the app's transaction, the plain read after the duplicate insert uses an
+        # older snapshot and misses the row another start just committed. A locking read sees it.
+        Execution.lock.find(id)
+      end
       return execution if execution.recipe == recipe.name
 
       raise ArgumentError, "execution #{id} already exists for recipe :#{execution.recipe}"
     end
 
+    # The context to store with a new execution: the one given to start, or config.context.capture.
+    #
+    # @api private
+    def capture_context(explicit)
+      value = explicit.nil? ? config.context&.capture : explicit
+      return nil if value.nil?
+
+      unless Execution.column_names.include?("context")
+        raise Error, "the durable_executions table has no context column. Run rails generate " \
+                     "active_durable:upgrade and rails db:migrate."
+      end
+      Serializer.normalize(value, "the context")
+    end
+
+    # Runs the block inside config.context.wrap, with the context the execution started with.
+    #
+    # @api private
+    def with_context(context, &block)
+      wrapper = config.context
+      return yield if wrapper.nil?
+
+      ran = false
+      result = wrapper.wrap(context || {}) do
+        ran = true
+        block.call
+      end
+      raise Error, "config.context.wrap must call its block" unless ran
+
+      result
+    end
+
+    # @api private
+    def check_id!(id)
+      id = Serializer.normalize(id.to_s, "the execution id")
+      raise ArgumentError, "execution ids cannot be blank" if id.strip.empty?
+      return id unless id.include?("/")
+
+      raise ArgumentError, "execution ids cannot contain \"/\" (#{id}): the dashboard could not route them. " \
+                           "Use - or : instead."
+    rescue NotSerializable => e
+      raise ArgumentError, e.message
+    end
+
     # Delivers a signal to a saga waiting, now or later, in flow.wait_for(name). A signal that arrives before the
-    # saga waits is kept until it does.
+    # saga waits is kept until it does, also while the saga is blocked.
     #
     # @param execution_id [String]
     # @param name [Symbol, String] the name given to {Flow#wait_for}
     # @param payload [Object] what wait_for returns; stored as JSON
     # @return [void]
     # @raise [ActiveRecord::RecordNotFound] if there is no such execution
-    # @raise [Error] if the execution already finished
+    # @raise [Error] if the execution already finished: completed, compensated or superseded
     # @example In a webhook controller
     #   Durable.signal("loan-42", :kyc_done, verified: true)
     def signal(execution_id, name, payload = nil)
-      execution = Execution.find(execution_id)
-      raise Error, "execution #{execution_id} already finished (#{execution.status})" if execution.terminal?
+      payload = Serializer.normalize(payload, "signal payload")
+      Record.transaction do
+        # Locked, so a flow.continue_as_new committing right now cannot strand the signal on the closed execution.
+        execution = Execution.lock.find(execution_id)
+        execution = Execution.lock.find(execution.continued_as) while execution.continued?
+        raise Error, "execution #{execution_id} already finished (#{execution.status})" if execution.finished?
 
-      SignalRecord.create!(execution_id: execution.id, name: name.to_s,
-                           payload: Serializer.normalize(payload, "signal payload"))
+        SignalRecord.create!(execution_id: execution.id, name: name.to_s, payload: payload)
+      end
     end
 
     # @param execution_id [String]
+    # @param latest [Boolean] follow flow.continue_as_new to the execution that carries on now
     # @return [Execution]
     # @raise [ActiveRecord::RecordNotFound]
-    def find(execution_id)
-      Execution.find(execution_id)
+    def find(execution_id, latest: false)
+      execution = Execution.find(execution_id)
+      execution = Execution.find(execution.continued_as) while latest && execution.continued?
+      execution
+    end
+
+    # "order-1" continues as "order-1~2", then "order-1~3".
+    #
+    # @api private
+    def next_in_chain(execution_id)
+      base, number = execution_id.match(/\A(.+)~(\d+)\z/)&.captures
+      base ? "#{base}~#{number.to_i + 1}" : "#{execution_id}~2"
     end
 
     # Resumes a blocked execution where it stopped: failed steps (or failed undos, if it was undoing) get a fresh