active_durable 0.6.0 → 0.8.0

data/lib/active_durable/configuration.rb

@@ -39,6 +39,34 @@ module ActiveDurable
     # development and test only: closed in production, staging and any other environment.
     attr_accessor :dashboard_authorize
 
+    # Errors that mean the code is wrong, not the outside world. A step that raises one of them is neither retried
+    # nor undone: the execution is blocked until the code is fixed and someone calls ActiveDurable.retry. Classes
+    # or class names; a name also matches subclasses and needs no loaded gem. Add your own with
+    # `config.code_errors << "Payments::Misconfigured"`, or drop one with `config.code_errors -= ["ArgumentError"]`.
+    # Errors outside StandardError (LoadError, NotImplementedError, SystemStackError) always count as bugs.
+    attr_accessor :code_errors
+
+    # The default {#code_errors}. NameError covers NoMethodError, and IndexError covers KeyError.
+    DEFAULT_CODE_ERRORS = %w[
+      NameError ArgumentError TypeError IndexError FrozenError ZeroDivisionError RangeError
+      NoMatchingPatternError LocalJumpError RegexpError EncodingError
+    ].freeze
+
+    # Who the work is for (the tenant, the user, the request id), carried from where an execution starts to every
+    # run of it. An object with two methods:
+    #
+    #   module TenantContext
+    #     def self.capture = { "tenant_id" => Current.tenant_id }                        # when the execution starts
+    #     def self.wrap(context, &run) = Current.set(tenant_id: context["tenant_id"], &run) # around every run
+    #   end
+    #   config.context = TenantContext
+    #
+    # capture returns plain JSON (or nil), stored with the execution; ActiveDurable.start(..., context: {...})
+    # gives it explicitly instead. wrap runs around the recipe, the undos, the flow.on hooks and each
+    # flow.parallel branch thread, and must call the block exactly once. Executions started without a context
+    # get {}. Needs the context column (rails generate active_durable:upgrade).
+    attr_accessor :context
+
     attr_writer :logger
 
     def initialize
@@ -53,6 +81,8 @@ module ActiveDurable
       @parallel_concurrency = 4
       @clock = -> { Time.current }
       @dashboard_authorize = nil
+      @code_errors = DEFAULT_CODE_ERRORS.dup
+      @context = nil
       @logger = nil
     end
 

data/lib/active_durable/errors.rb

@@ -18,7 +18,10 @@ module ActiveDurable
   class RecipeChanged < Error; end
 
   # A step returned something that cannot be stored in the notebook as JSON.
-  class NotSerializable < Error; end
+  class NotSerializable < Error
+    # @api private
+    attr_accessor :step_name
+  end
 
   # Raise it inside a step to reject the work for a business reason: no retries, straight to compensation.
   class Abort < Error; end
@@ -37,8 +40,15 @@ module ActiveDurable
     end
   end
 
-  # An undo kept failing after all its attempts. The execution is blocked for a human to review.
-  class UndoFailed < Error; end
+  # An undo kept failing after all its attempts, or hit a bug. The execution is blocked for a human to review.
+  class UndoFailed < Error
+    attr_reader :step_name
+
+    def initialize(message = nil, step_name: nil)
+      @step_name = step_name
+      super(message)
+    end
+  end
 
   # A flow.on(:completed) or flow.on(:compensated) hook raised. The execution is blocked; ActiveDurable.retry runs
   # the hook again once it is fixed.
@@ -51,9 +61,10 @@ module ActiveDurable
     end
   end
 
-  # A step whose code cannot run as written: it raised NameError or NoMethodError (a typo, a missing class or
-  # method). Retrying cannot fix it and undoing the saga would punish customers for a bug, so the execution is
-  # blocked until the code is fixed and someone calls ActiveDurable.retry.
+  # A step whose code cannot run as written: it raised one of {Configuration#code_errors} (a typo, a missing
+  # key, a wrong argument). Retrying cannot fix it and undoing the saga would punish customers for a bug, so the
+  # execution is blocked until the code is fixed and someone calls ActiveDurable.retry. Rescuing it in the recipe
+  # does not help: the saga stops at the next step and blocks anyway.
   class CodeError < Error
     attr_reader :step_name
 
@@ -63,6 +74,17 @@ module ActiveDurable
     end
   end
 
+  # A step ran, but the database refused to record its result. Running it again could repeat its effect and
+  # undoing the saga would skip it, so the execution is blocked at that step.
+  class CheckpointFailed < Error
+    attr_reader :step_name
+
+    def initialize(step_name, error)
+      @step_name = step_name
+      super("step :#{step_name} ran, but its result could not be recorded: #{error.class}: #{error.message}")
+    end
+  end
+
   # Control flow signals. They inherit from Exception on purpose: a `rescue => e` inside
   # user code must not swallow them, otherwise a lost lease could keep writing.
   #
@@ -79,13 +101,36 @@ module ActiveDurable
   # @api private
   class StopForward < ControlFlow; end
 
-  # Serializes an exception for the notebook and the dashboard.
+  # Serializes an exception for the notebook and the dashboard. The message is cleaned up first: it may quote the
+  # very bytes the database refused.
   def self.dump_error(error, step: nil)
     {
       "class" => error.class.name,
-      "message" => error.message.to_s[0, 2000],
+      "message" => storable_text(error.message)[0, 2000],
       "step" => step,
       "at" => now.utc.iso8601(6)
     }.compact
   end
+
+  # Whether an error means the code is wrong rather than the outside world: it is one of config.code_errors (or a
+  # subclass), or one of the errors Ruby raises outside StandardError, such as LoadError or SystemStackError.
+  #
+  # @api private
+  def self.code_error?(error)
+    return true unless error.is_a?(StandardError)
+
+    names = config.code_errors.map { |item| item.is_a?(Module) ? item.name : item.to_s }
+    error.class.ancestors.any? { |ancestor| names.include?(ancestor.name) }
+  end
+
+  # @api private
+  def self.storable_text(text)
+    text = text.to_s
+    text = if [Encoding::UTF_8, Encoding::BINARY, Encoding::US_ASCII].include?(text.encoding)
+             text.dup.force_encoding(Encoding::UTF_8).scrub("?")
+           else
+             text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")
+           end
+    text.delete("\u0000")
+  end
 end

data/lib/active_durable/execution.rb

@@ -9,12 +9,17 @@ module ActiveDurable
     # wake-up time (a sleep or a retry) or waiting for a signal.
     ACTIVE = %w[pending running sleeping waiting].freeze
     # Statuses where nothing happens without a person: done, undone, blocked (needs {ActiveDurable.retry},
-    # {ActiveDurable.compensate} or a fix), or replaced by a rerun.
-    TERMINAL = %w[completed compensated blocked superseded].freeze
+    # {ActiveDurable.compensate} or a fix), replaced by a rerun, or carried on by another execution
+    # (flow.continue_as_new, see {#continued_as}).
+    TERMINAL = %w[completed compensated blocked superseded continued].freeze
+    # Statuses that never change again. Signals are refused (a continued execution passes them on), and
+    # ActiveDurable.prune may delete them (a continued one only together with the execution that carried it on).
+    FINISHED = %w[completed compensated superseded continued].freeze
     # Every status.
     STATUSES = (ACTIVE + TERMINAL).freeze
 
     attribute :input, JSON_TYPE, default: -> { {} }
+    attribute :context, JSON_TYPE
     attribute :output, JSON_TYPE
     attribute :error, JSON_TYPE
 
@@ -32,6 +37,16 @@ module ActiveDurable
     # the sweeper finds the pending row and enqueues it.
     after_create_commit { ActiveDurable.enqueue(id) }
 
+    # @return [Boolean] whether flow.continue_as_new closed it; {#continued_as} is the id that carries on
+    def continued?
+      status == "continued"
+    end
+
+    # @api private
+    def self.continuations?
+      column_names.include?("continued_as")
+    end
+
     # @return [Boolean] whether it will move on by itself
     def active?
       ACTIVE.include?(status)
@@ -42,6 +57,11 @@ module ActiveDurable
       TERMINAL.include?(status)
     end
 
+    # @return [Boolean] whether it will never change again (blocked is not finished: it can be retried)
+    def finished?
+      FINISHED.include?(status)
+    end
+
     # The forward steps in recipe order (undo and hook entries excluded).
     def notebook
       steps.where.not(kind: %w[undo hook]).reorder(:position).to_a

data/lib/active_durable/flow.rb

@@ -32,6 +32,12 @@ module ActiveDurable
     # @api private
     attr_reader :undo_stack
 
+    # The bug (or unrecorded result) that stopped this run. Once set, no other step runs and the execution is
+    # blocked, even if the recipe rescued the error.
+    #
+    # @api private
+    attr_reader :blocked_by
+
     # @api private
     def initialize(runner, compensating:)
       @runner = runner
@@ -43,6 +49,7 @@ module ActiveDurable
       @seen = {}
       @undo_stack = []
       @hooks = {}
+      @blocked_by = nil
     end
 
     # @return [String] the id of the execution this recipe is running for
@@ -192,40 +199,84 @@ module ActiveDurable
     # Waits, without holding a worker, for {ActiveDurable.signal}(execution_id, name, payload). A signal sent
     # before the saga gets here is kept.
     #
-    # @param name [Symbol, String]
+    # By default the signal has the step's name. With `signal:`, several waits share one signal name, like a
+    # mailbox: a conversation can wait for :message on every turn, and a message that arrives while the saga is
+    # busy waits there for the next turn. With `all: true`, the wait takes every pending signal of that name at
+    # once and returns their payloads in the order they arrived, so a burst of five messages is one turn, not five.
+    #
+    # @param name [Symbol, String] the step's name
     # @param timeout [ActiveSupport::Duration, Numeric, nil] seconds; then the step fails and the saga is undone
-    # @return [Object] the signal's payload
+    # @param signal [Symbol, String, nil] the signal to wait for, when it is not the step's name
+    # @param all [Boolean] take every pending signal and return an Array of payloads
+    # @return [Object] the signal's payload, or an Array of payloads with `all: true`
     # @raise [StepFailed] when the timeout passes first
-    def wait_for(name, timeout: nil)
+    # @example A chat that waits for the customer on every turn
+    #   messages = flow.wait_for("reply.#{turn}", signal: :message, all: true, timeout: 1.day)
+    def wait_for(name, timeout: nil, signal: nil, all: false)
       name, position = visit!(name, "wait")
+      signal_name = signal.nil? ? name : signal.to_s
+      check_signal_name!(name, signal_name)
       entry = @notebook[name]
       return entry.result.deep_dup if entry&.completed?
       raise StepFailed.new(name, entry.error&.fetch("message", nil)) if entry&.failed?
       raise StopForward, name if compensating?
 
-      signal = SignalRecord.next_for(execution_id, name)
-      return consume_signal(signal, name, position).deep_dup if signal
+      signals = pending_signals(signal_name, all)
+      return consume_signals(signals, name, position, all).deep_dup if signals.any?
 
-      if entry.nil?
-        deadline = timeout && (now + timeout)
-        @notebook.wait!(name, kind: "wait", position: position, wake_at: deadline)
-        @runner.suspend!(deadline, "waiting")
-      end
+      keep_waiting(name, position, entry, timeout, signal_name)
+    end
 
-      if entry.wake_at && now >= entry.wake_at
-        error = WaitTimeout.new("no :#{name} signal arrived before #{entry.wake_at.utc.iso8601}")
-        @notebook.fail!(name, kind: "wait", position: position, attempts: 1,
-                              error: ActiveDurable.dump_error(error, step: name))
-        raise StepFailed.new(name, error)
+    # Closes this execution and starts a new one of the same recipe (its latest version) with `input`, the same
+    # context and the signals still waiting to be read. It keeps a long-lived saga, such as a conversation, from
+    # replaying an ever longer notebook: carry over a summary of what matters, not the whole history.
+    #
+    # The new execution's id is this one's plus "~2" (then "~3"...), so its steps get new tickets.
+    # {ActiveDurable.signal} sent to any id of the chain reaches the newest one; {ActiveDurable.find} with
+    # `latest: true` returns it. Call it in the recipe, not inside a step, and compute `input` from step results
+    # so a replay computes the same. Hooks of this execution do not run.
+    #
+    # @param input [Hash] the input of the new execution
+    # @raise [InvalidRecipe] inside a step or a parallel branch, or while undos are pending: those steps
+    #   could never be undone. Call it before them, or after flow.pivot.
+    # @example A conversation that starts a fresh notebook every 20 turns
+    #   flow.continue_as_new(summary: summary, turn: turn) if turn % 20 == 19
+    def continue_as_new(**input)
+      raise InvalidRecipe, "flow.continue_as_new must be called in the recipe, not inside a step" if inside_step?
+      raise blocked_by if blocked_by
+      raise StopForward, "continue_as_new" if compensating?
+
+      if @undo_stack.any? && !@pivoted
+        names = @undo_stack.map { |entry| ":#{entry.name}" }.join(", ")
+        raise InvalidRecipe, "flow.continue_as_new would leave #{names} without their undo. Continue before " \
+                             "steps with undo:, or after flow.pivot."
       end
 
-      @runner.suspend!(entry.wake_at, "waiting")
+      @runner.continue_as_new!(Serializer.normalize(input, "the input of continue_as_new"))
     end
 
+    # @api private
+    def inside_step?
+      Thread.current[INSIDE_STEP] == true
+    end
+
+    # @api private
+    def inside_step
+      previous = Thread.current[INSIDE_STEP]
+      Thread.current[INSIDE_STEP] = true
+      yield
+    ensure
+      Thread.current[INSIDE_STEP] = previous
+    end
+
+    # @api private
+    INSIDE_STEP = :active_durable_inside_step
+
     # Called when the recipe returns: every step the notebook knows about must have been reached.
     #
     # @api private
     def finish!
+      raise blocked_by if blocked_by
       return if compensating?
 
       missing = @notebook.forward_entries.reject { |entry| @seen.key?(entry.name) }
@@ -267,7 +318,11 @@ module ActiveDurable
         remember_failure(name, kind, undo, options)
         raise StepFailed.new(name, entry.error&.fetch("message", nil))
       end
-      raise StopForward, name if compensating?
+      if compensating?
+        # Stopped between attempts or on a bug: it may have acted, so undo_on_failure applies.
+        remember_failure(name, kind, undo, options) if entry&.unfinished?
+        raise StopForward, name
+      end
 
       @runner.suspend!(entry.wake_at, "sleeping") if entry&.retrying? && entry.wake_at && entry.wake_at > now
 
@@ -280,28 +335,53 @@ module ActiveDurable
       ActiveDurable.crash_point(:before_step, name)
       result = ActiveDurable.instrument("step", execution_id: execution_id, step: name, kind: kind) do
         if kind == "transaction"
-          @notebook.transaction { record_result(name, kind, position, block.call(ticket)) }
+          @notebook.transaction(records: name) do
+            record_result(name, kind, position, inside_step { block.call(ticket) })
+          end
         else
-          record_result(name, kind, position, block.call(ticket))
+          record_result(name, kind, position, inside_step { block.call(ticket) })
         end
       end
       ActiveDurable.crash_point(:after_record, name)
       result
-    rescue NotSerializable, InvalidRecipe
-      raise
-    rescue NameError => e # NoMethodError too: a bug in the code, not a failure of the outside world
-      raise CodeError.new(name, e)
-    rescue StandardError => e
+    rescue Abort => e
+      handle_failure(name, kind, position, entry, undo, options, e)
+    rescue NotSerializable, InvalidRecipe, CheckpointFailed => e
+      block_step!(name, kind, position, entry, e)
+    rescue StandardError, ScriptError, SystemStackError => e
+      raise if blocked_by # a nested step already blocked the run
+
+      return block_step!(name, kind, position, entry, CodeError.new(name, e)) if ActiveDurable.code_error?(e)
+
       handle_failure(name, kind, position, entry, undo, options, e)
     end
 
+    # Outside a transaction the step has already acted when its result is recorded, so a write the database
+    # refuses is not a failure of the step: it blocks. Inside flow.transaction it rolled back with the step.
     def record_result(name, kind, position, value)
       result = Serializer.normalize(value, "the result of :#{name}")
       ActiveDurable.crash_point(:after_call, name)
-      @notebook.complete!(name, kind: kind, position: position, result: result)
+      begin
+        @notebook.complete!(name, kind: kind, position: position, result: result)
+      rescue StandardError => e
+        raise if kind == "transaction"
+
+        raise CheckpointFailed.new(name, e)
+      end
       result
     end
 
+    # Retrying cannot fix a bug and undoing the saga would punish customers for it: the step is written down as
+    # blocked, and nothing else runs until someone fixes the code and calls ActiveDurable.retry. It keeps its
+    # attempts, since a bug is not a failure of the outside world.
+    def block_step!(name, kind, position, entry, error)
+      error.step_name ||= name if error.respond_to?(:step_name=)
+      @blocked_by = error
+      @notebook.block!(name, kind: kind, position: position, attempts: entry&.attempts || 0,
+                             error: ActiveDurable.dump_error(error, step: name))
+      raise error
+    end
+
     def handle_failure(name, kind, position, entry, undo, options, error)
       attempts = (entry&.attempts || 0) + 1
       default = @pivoted ? config.after_pivot_attempts : config.step_attempts
@@ -348,6 +428,8 @@ module ActiveDurable
     end
 
     def visit!(name, kind)
+      raise blocked_by if blocked_by
+
       name = name.to_s
       raise InvalidRecipe, "step names cannot be blank" if name.empty?
       raise InvalidRecipe, "step names cannot end in ':undo' (#{name})" if name.end_with?(":undo")
@@ -374,15 +456,49 @@ module ActiveDurable
                            "recipe reached :#{name} (#{kind}). #{RECIPE_CHANGED_HINT}"
     end
 
-    def consume_signal(signal, name, position)
-      payload = signal.payload
+    def pending_signals(signal_name, all)
+      signals = SignalRecord.pending_for(execution_id, signal_name)
+      all ? signals.to_a : signals.limit(1).to_a
+    end
+
+    # Suspends the execution until a signal arrives, or fails the wait once its deadline has passed.
+    def keep_waiting(name, position, entry, timeout, signal_name)
+      unless entry&.waiting? # first time here, or retried after a timeout: wait again, with a new deadline
+        deadline = timeout && (now + timeout)
+        @notebook.wait!(name, kind: "wait", position: position, wake_at: deadline,
+                              signal_name: (signal_name unless signal_name == name))
+        @runner.suspend!(deadline, "waiting")
+      end
+
+      if entry.wake_at && now >= entry.wake_at
+        error = WaitTimeout.new("no :#{signal_name} signal arrived before #{entry.wake_at.utc.iso8601}")
+        @notebook.fail!(name, kind: "wait", position: position, attempts: 1,
+                              error: ActiveDurable.dump_error(error, step: name))
+        raise StepFailed.new(name, error)
+      end
+
+      @runner.suspend!(entry.wake_at, "waiting")
+    end
+
+    # Takes the signals and completes the wait in one transaction: either both happen or neither does.
+    def consume_signals(signals, name, position, all)
+      result = all ? signals.map(&:payload) : signals.first.payload
+      ids = signals.map(&:id)
       @notebook.transaction do
-        taken = SignalRecord.where(id: signal.id, consumed_at: nil).update_all(consumed_at: now)
-        raise LeaseLost, "signal #{signal.id} for #{execution_id} was already consumed" if taken.zero?
+        taken = SignalRecord.where(id: ids, consumed_at: nil).update_all(consumed_at: now)
+        raise LeaseLost, "a signal for #{execution_id} was already consumed" if taken != ids.size
 
-        @notebook.complete!(name, kind: "wait", position: position, result: payload)
+        @notebook.complete!(name, kind: "wait", position: position, result: result)
       end
-      payload
+      result
+    end
+
+    def check_signal_name!(name, signal_name)
+      raise InvalidRecipe, "flow.wait_for :#{name} needs a signal name that is not blank" if signal_name.empty?
+      return if signal_name == name || Step.signal_names?
+
+      raise InvalidRecipe, "flow.wait_for :#{name}, signal: :#{signal_name} needs the signal_name column. Run " \
+                           "rails generate active_durable:upgrade and rails db:migrate."
     end
   end
 end

data/lib/active_durable/flow_parallel.rb

@@ -36,7 +36,11 @@ module ActiveDurable
         prepare_branches!(name, branches)
         entry = @notebook[name]
         return finish_recorded_parallel(name, entry, branches) if entry&.completed? || entry&.failed?
-        raise StopForward, name if compensating?
+
+        if compensating? # stopped halfway: undo the branches that finished
+          remember_branches(name, branches, include_failed: true)
+          raise StopForward, name
+        end
 
         run_parallel(name, position, branches)
       end
@@ -77,6 +81,12 @@ module ActiveDurable
 
       def run_parallel(name, position, branches)
         outcomes = branch_outcomes(branches)
+        blocked = outcomes.find { |_, (state, _)| state == :blocked }
+        if blocked
+          @blocked_by = blocked.last.last
+          raise @blocked_by
+        end
+
         failed = outcomes.select { |_, (state, _)| state == :failed }
         if failed.any?
           full_name, (_, error) = failed.first
@@ -89,13 +99,14 @@ module ActiveDurable
         wakes = outcomes.values.filter_map { |state, value| value if state == :retry }
         @runner.suspend!(wakes.min, "sleeping") if wakes.any?
 
-        results = branches.to_h { |branch| [branch.name, outcomes.fetch(branch.full_name).last] }
+        # By branch name in sorted order, which is also how a replay reads it back from the notebook.
+        results = Serializer.canonical(branches.to_h { |branch| [branch.name, outcomes.fetch(branch.full_name).last] })
         @notebook.complete!(name, kind: "parallel", position: position, result: results)
         remember_branches(name, branches)
         results.deep_dup
       end
 
-      # { full_name => [:completed, result] | [:retry, wake_at] | [:failed, error] }
+      # { full_name => [:completed, result] | [:retry, wake_at] | [:failed, error] | [:blocked, error] }
       def branch_outcomes(branches)
         outcomes = {}
         runnable = []
@@ -145,9 +156,12 @@ module ActiveDurable
       end
 
       def in_branch_context(wrappers, &block)
+        context = @runner.execution.context
         run = lambda do
           Record.connection_pool.with_connection do
-            wrappers.reverse.inject(block) { |inner, (wrapper, captured)| -> { wrapper.wrap(captured, &inner) } }.call
+            ActiveDurable.with_context(context) do
+              wrappers.reverse.inject(block) { |inner, (wrapper, captured)| -> { wrapper.wrap(captured, &inner) } }.call
+            end
           end
         end
         if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
@@ -164,19 +178,31 @@ module ActiveDurable
         result = ActiveDurable.instrument("step", execution_id: execution_id, step: branch.full_name,
                                                   kind: branch.kind) do
           if branch.kind == "transaction"
-            @notebook.transaction { record_result(branch.full_name, branch.kind, nil, branch.block.call(ticket)) }
+            @notebook.transaction(records: branch.full_name) do
+              record_result(branch.full_name, branch.kind, nil, inside_step { branch.block.call(ticket) })
+            end
           else
-            record_result(branch.full_name, branch.kind, nil, branch.block.call(ticket))
+            record_result(branch.full_name, branch.kind, nil, inside_step { branch.block.call(ticket) })
           end
         end
         ActiveDurable.crash_point(:after_record, branch.full_name)
         [:completed, result]
-      rescue NotSerializable, InvalidRecipe
-        raise
-      rescue NameError => e
-        raise CodeError.new(branch.full_name, e)
-      rescue StandardError => e
+      rescue Abort => e
         branch_failure(branch, entry, e)
+      rescue NotSerializable, InvalidRecipe, CheckpointFailed => e
+        block_branch(branch, entry, e)
+      rescue StandardError, ScriptError, SystemStackError => e
+        return block_branch(branch, entry, CodeError.new(branch.full_name, e)) if ActiveDurable.code_error?(e)
+
+        branch_failure(branch, entry, e)
+      end
+
+      # Like block_step!, from inside a branch thread: the run blocks once every branch has finished.
+      def block_branch(branch, entry, error)
+        error.step_name ||= branch.full_name if error.respond_to?(:step_name=)
+        @notebook.block!(branch.full_name, kind: branch.kind, position: nil, attempts: entry&.attempts || 0,
+                                           error: ActiveDurable.dump_error(error, step: branch.full_name))
+        [:blocked, error]
       end
 
       def branch_failure(branch, entry, error)
@@ -205,7 +231,7 @@ module ActiveDurable
 
           if entry.completed?
             @undo_stack << UndoEntry.new(entry.name, branch.kind, entry.result, branch.undo)
-          elsif include_failed && branch.options[:undo_on_failure] && (entry.failed? || entry.retrying?)
+          elsif include_failed && branch.options[:undo_on_failure] && (entry.failed? || entry.unfinished?)
             @undo_stack << UndoEntry.new(entry.name, branch.kind, nil, branch.undo)
           end
         end

data/lib/active_durable/notebook.rb

@@ -48,17 +48,30 @@ module ActiveDurable
                    wake_at: nil)
     end
 
-    def wait!(name, kind:, position:, wake_at:)
-      write!(name, kind: kind, position: position, status: "waiting", wake_at: wake_at)
+    # The step hit a bug or its result could not be recorded: it runs again after ActiveDurable.retry.
+    def block!(name, kind:, position:, attempts:, error:)
+      write!(name, kind: kind, position: position, status: "blocked", attempts: attempts, error: error, wake_at: nil)
+    end
+
+    def wait!(name, kind:, position:, wake_at:, signal_name: nil)
+      attributes = { kind: kind, position: position, status: "waiting", wake_at: wake_at }
+      attributes[:signal_name] = signal_name if Step.signal_names?
+      write!(name, **attributes)
     end
 
     # Runs the block in a database transaction and remembers the notebook writes made inside it only once it
-    # commits. flow.transaction steps and their undos use it: a step that rolled back must not look completed.
-    def transaction(&)
+    # commits. flow.transaction steps, their undos and hooks use it: a step that rolled back must not look
+    # completed. With `records:`, the block must have recorded that entry: Active Record swallows
+    # ActiveRecord::Rollback, so a block that raised it would otherwise look done.
+    def transaction(records: nil, &)
       pending = []
       Thread.current[pending_key] = pending
       result = Record.transaction(&)
       pending.each { |name, entry| remember(name, entry) }
+      if records && !self[records]&.completed?
+        raise Error, ":#{records} rolled back (ActiveRecord::Rollback), so nothing was recorded. Raise an error " \
+                     "or call flow.abort! to make it fail."
+      end
       result
     ensure
       Thread.current[pending_key] = nil