active_durable 0.5.0 → 0.7.0

data/app/views/active_durable/executions/show.html.erb

@@ -15,7 +15,7 @@
       Started <%= when_text(@execution.created_at) %>, last change <%= when_text(@execution.updated_at) %>.
       <% if @execution.wake_at %>Wakes <%= when_text(@execution.wake_at) %>.<% end %>
       <% if @execution.forked_from %>
-        Rerun of <%= link_to @execution.forked_from, execution_path(@execution.forked_from), class: "mono" %>.
+        Rerun of <%= execution_link(@execution.forked_from, class: "mono") %>.
       <% end %>
     </p>
   </div>
@@ -29,7 +29,7 @@
   </section>
 <% end %>
 
-<% if can_retry?(@execution) || can_compensate?(@execution, @forward_steps) || (can_rerun?(@execution) && @forward_steps.any?) %>
+<% if can_retry?(@execution) || can_compensate?(@execution, @forward_steps) || (can_rerun?(@execution) && @rerun_steps.any?) %>
   <section class="actions" aria-label="Actions">
     <% if can_retry?(@execution) %>
       <%= button_to retry_execution_path(@execution), class: "primary", form_class: "inline" do %>Retry<% end %>
@@ -40,10 +40,10 @@
         Undo everything
       <% end %>
     <% end %>
-    <% if can_rerun?(@execution) && @forward_steps.any? %>
+    <% if can_rerun?(@execution) && @rerun_steps.any? %>
       <%= form_with url: rerun_execution_path(@execution), method: :post, class: "inline", local: true do %>
         <label for="rerun-from">Run again from</label>
-        <%= select_tag :from, options_for_select(@forward_steps.map(&:name), rerun_default(@forward_steps)), id: "rerun-from" %>
+        <%= select_tag :from, options_for_select(@rerun_steps.map(&:name), rerun_default(@rerun_steps)), id: "rerun-from" %>
         <button type="submit">Rerun</button>
       <% end %>
       <p class="note">A rerun is a new execution. Steps before the one you choose are reused; that step and the ones
@@ -65,7 +65,7 @@
         <% items.each_with_index do |item, index| %>
           <% if index.positive? %>
             <% previous = items[index - 1] %>
-            <% if previous.kind == "pivot" && previous.state != "failed" %>
+            <% if previous.kind == "pivot" && !%w[failed blocked].include?(previous.state) %>
               <span class="gate" style="--i: <%= index %>"><span>point of no return</span></span>
             <% end %>
             <% wire = if item.state == "undone" || (backwards && previous.state == "undone") then "back"
@@ -158,6 +158,16 @@
                 <td class="error"><%= step.error&.dig("message").to_s.truncate(120) %></td>
               </tr>
             <% end %>
+            <% @hook_steps.each do |step| %>
+              <tr>
+                <td></td>
+                <td><strong>on :<%= step.name.delete_prefix("~") %></strong><span class="k">hook</span></td>
+                <td><%= status_pill(step.status) %></td>
+                <td><%= step.attempts %></td>
+                <td></td>
+                <td></td>
+              </tr>
+            <% end %>
           </tbody>
         </table>
       </div>
@@ -189,7 +199,7 @@
       <section class="panel">
         <h2>Reruns</h2>
         <% @reruns.each do |rerun| %>
-          <p><%= link_to rerun.id, execution_path(rerun), class: "mono" %> <%= status_pill(rerun.status) %></p>
+          <p><%= execution_link(rerun.id, class: "mono") %> <%= status_pill(rerun.status) %></p>
         <% end %>
       </section>
     <% end %>

data/app/views/layouts/active_durable/application.html.erb

@@ -33,7 +33,7 @@
     .tone-good, .st-completed { --c: var(--jade); --cb: var(--jade-bg); }
     .tone-wait, .st-retrying, .st-waiting, .st-sleeping { --c: var(--amber); --cb: var(--amber-bg); }
     .tone-busy, .st-running, .st-next { --c: var(--cobalt); --cb: var(--cobalt-bg); }
-    .tone-bad, .st-failed { --c: var(--ruby); --cb: var(--ruby-bg); }
+    .tone-bad, .st-failed, .st-blocked { --c: var(--ruby); --cb: var(--ruby-bg); }
     .tone-undo, .st-undone { --c: var(--violet); --cb: var(--violet-bg); }
     .tone-muted { --c: var(--slate); --cb: var(--slate-bg); }
 
@@ -113,10 +113,12 @@
     tbody tr { transition: background-color .2s; }
     tbody tr:hover { background: var(--sunken); }
     tr.changed { animation: rowflash 1.8s ease; }
-    .exec-link { font: 700 .95rem/1.2 var(--f-code); white-space: nowrap; text-decoration: none; color: var(--ink); }
+    td.exec { min-width: 20ch; max-width: 30ch; }
+    .exec-link { font: 700 .95rem/1.2 var(--f-code); overflow-wrap: anywhere; text-decoration: none; color: var(--ink); }
     .exec-link:hover { text-decoration: underline; }
     .recipe { display: block; color: var(--soft); font-size: .82rem; margin-top: 2px; }
-    .problem { color: var(--ruby); max-width: 34ch; }
+    .problem { color: var(--ruby); min-width: 24ch; max-width: 40ch; }
+    .problem span { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden; }
     .when { white-space: nowrap; font-variant-numeric: tabular-nums; }
     .status { display: inline-flex; align-items: center; gap: 7px; padding: 4px 10px 4px 8px; border-radius: 999px;
               background: var(--cb); color: var(--c); font-weight: 700; font-size: .82rem; white-space: nowrap; }
@@ -138,7 +140,7 @@
                animation-delay: calc(var(--i, 0) * 45ms); }
     .mini .b.st-completed { background: var(--c); }
     .mini .b.k-pivot { transform: rotate(45deg) scale(.86); animation-name: pop-pivot; }
-    .mini .b.st-failed { animation: pop .35s both, shake .5s .5s ease 2; }
+    .mini .b.st-failed, .mini .b.st-blocked { animation: pop .35s both, shake .5s .5s ease 2; }
     .mini .b.st-undone { background: repeating-linear-gradient(135deg, var(--cb) 0 3px, var(--c) 3px 5px); }
     .mini .b.st-next { border-style: dashed; background: transparent; animation: pop .35s both, beat 1.2s ease-in-out infinite; }
     .mini .b.st-retrying, .mini .b.st-sleeping { animation: pop .35s both, beat 2.2s ease-in-out infinite; }
@@ -192,7 +194,7 @@
     .block.st-completed { --cb: color-mix(in srgb, var(--jade-bg) 85%, var(--surface)); }
     .block.k-pivot { border-width: 3px; }
     .block.k-pivot .kind { color: var(--amber); }
-    .block.st-failed { animation: drop .55s both, shake .5s .7s ease 2; box-shadow: 0 7px 0 var(--c2), 0 0 0 6px color-mix(in srgb, var(--ruby) 18%, transparent); }
+    .block.st-failed, .block.st-blocked { animation: drop .55s both, shake .5s .7s ease 2; box-shadow: 0 7px 0 var(--c2), 0 0 0 6px color-mix(in srgb, var(--ruby) 18%, transparent); }
     .block.st-undone { background: repeating-linear-gradient(135deg, var(--violet-bg) 0 10px, color-mix(in srgb, var(--violet) 22%, var(--violet-bg)) 10px 20px); }
     .block.st-undone h3 { text-decoration: line-through; text-decoration-thickness: 2px; }
     .block.st-next { background: transparent; border-style: dashed; box-shadow: none; animation: drop .55s both, beat 1.4s ease-in-out infinite; }

data/lib/active_durable/configuration.rb

@@ -25,6 +25,9 @@ module ActiveDurable
     # The sweeper ignores executions touched more recently than this, to leave room for their own job.
     attr_accessor :sweep_grace
 
+    # How long ActiveDurable.prune, PruneJob and rake active_durable:prune keep finished executions.
+    attr_accessor :keep_finished_for
+
     # Maximum threads used by flow.parallel. Your connection pool needs at least this many + 1 connections.
     attr_accessor :parallel_concurrency
 
@@ -36,6 +39,19 @@ 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
+
     attr_writer :logger
 
     def initialize
@@ -46,9 +62,11 @@ module ActiveDurable
       @undo_attempts = 10
       @backoff = ->(attempt) { [2**attempt, 3600].min }
       @sweep_grace = 60
+      @keep_finished_for = 30 * 24 * 3600
       @parallel_concurrency = 4
       @clock = -> { Time.current }
       @dashboard_authorize = nil
+      @code_errors = DEFAULT_CODE_ERRORS.dup
       @logger = nil
     end
 

data/lib/active_durable/engine.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveDurable
-  # The dashboard and the rake tasks. Mount it in config/routes.rb:
+  # The dashboard. Mount it in config/routes.rb:
   #
   #   mount ActiveDurable::Engine => "/durable"
   class Engine < ::Rails::Engine
@@ -17,8 +17,6 @@ module ActiveDurable
       end
     end
 
-    rake_tasks do
-      load File.expand_path("../tasks/active_durable.rake", __dir__)
-    end
+    # The rake tasks in lib/tasks are loaded by Rails::Engine itself: loading them here too would run them twice.
   end
 end

data/lib/active_durable/errors.rb

@@ -2,6 +2,7 @@
 
 # Error classes. Everything a recipe may want to rescue inherits from ActiveDurable::Error.
 module ActiveDurable
+  # The base class of every error ActiveDurable raises.
   class Error < StandardError; end
 
   # Raised when a recipe name (or version) has not been defined.
@@ -17,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
@@ -36,26 +40,97 @@ 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.
+  class HookFailed < Error
+    attr_reader :step_name
+
+    def initialize(event, error)
+      @step_name = "~#{event}"
+      super("flow.on(:#{event}) failed: #{error.class}: #{error.message}")
+    end
+  end
+
+  # 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
+
+    def initialize(step_name, error)
+      @step_name = step_name
+      super("step :#{step_name} cannot run: #{error.class}: #{error.message}")
+    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.
+  #
+  # @api private
   class ControlFlow < Exception; end # rubocop:disable Lint/InheritException
 
   # Another worker took over this execution (our lease expired). Stop without writing anything else.
+  #
+  # @api private
   class LeaseLost < ControlFlow; end
 
   # While compensating, replay reached a step that never completed: stop moving forward.
+  #
+  # @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

@@ -5,8 +5,15 @@ module ActiveDurable
   class Execution < Record
     self.table_name = "durable_executions"
 
+    # Statuses of an execution that will move on by itself: waiting for a worker, running, sleeping until a
+    # 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
+    # Statuses that never change again: signals are refused and ActiveDurable.prune may delete them.
+    FINISHED = %w[completed compensated superseded].freeze
+    # Every status.
     STATUSES = (ACTIVE + TERMINAL).freeze
 
     attribute :input, JSON_TYPE, default: -> { {} }
@@ -27,17 +34,24 @@ module ActiveDurable
     # the sweeper finds the pending row and enqueues it.
     after_create_commit { ActiveDurable.enqueue(id) }
 
+    # @return [Boolean] whether it will move on by itself
     def active?
       ACTIVE.include?(status)
     end
 
+    # @return [Boolean] whether it needs a person to move again, or finished
     def terminal?
       TERMINAL.include?(status)
     end
 
-    # The forward steps in recipe order (undo entries excluded).
+    # @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: "undo").reorder(:position).to_a
+      steps.where.not(kind: %w[undo hook]).reorder(:position).to_a
     end
   end
 end

data/lib/active_durable/flow.rb

@@ -1,21 +1,44 @@
 # frozen_string_literal: true
 
 module ActiveDurable
-  # The object a recipe receives. Every call that touches the outside world goes through it, so it can
-  # be checkpointed in the notebook and skipped on replay.
+  # The object a recipe receives. Every call that touches the outside world goes through it, so it can be
+  # checkpointed in the notebook and skipped when the recipe runs again after a crash.
   #
+  # Step names must be unique in a recipe: they are the steps' keys in the notebook. Every step takes the options
+  # `retry:` (an Integer of attempts, `false`, or `{ attempts:, backoff: }`) and, if it has an undo,
+  # `undo_on_failure: true`.
+  #
+  # @example
   #   Durable.define :checkout do |flow, order_id:|
-  #     flow.transaction :reserve_stock, undo: -> { ... } do ... end
-  #     flow.step :charge, undo: ->(charge, ticket) { ... } do |ticket| ... end
-  #     flow.pivot(:ship) { |ticket| ... }
-  #     flow.step(:email) { ... }
+  #     order = Order.find(order_id)
+  #     flow.on(:compensated) { order.update!(status: "cancelled") }
+  #     flow.transaction :reserve_stock, undo: -> { order.release_stock! } do
+  #       order.reserve_stock!
+  #     end
+  #     flow.step :charge, undo: ->(charge, ticket) { Payments.refund(charge, ticket) } do |ticket|
+  #       Payments.charge(order, ticket)
+  #     end
+  #     flow.pivot(:ship) { |ticket| Carrier.ship(order, reference: ticket) }
+  #     flow.step(:email) { OrderMailer.shipped(order).deliver_now && true }
   #   end
   class Flow
+    # @api private
     UndoEntry = Struct.new(:name, :kind, :result, :undo)
+    # @api private
     STEP_OPTIONS = %i[retry undo_on_failure].freeze
+    # The events {#on} accepts.
+    HOOK_EVENTS = %i[completed compensated].freeze
 
+    # @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
       @notebook = runner.notebook
@@ -25,52 +48,135 @@ module ActiveDurable
       @position = 0
       @seen = {}
       @undo_stack = []
+      @hooks = {}
+      @blocked_by = nil
     end
 
+    # @return [String] the id of the execution this recipe is running for
     def execution_id
       @execution.id
     end
 
-    # The ticket (idempotency key) a step receives. It is the same every time the step runs.
+    # The ticket (idempotency key) a step receives: "<execution id>:<step name>". It is the same every time the
+    # step runs.
+    #
+    # @param name [Symbol, String]
+    # @return [String]
     def ticket_for(name)
       "#{execution_id}:#{name}"
     end
 
+    # @api private
     def compensating?
       @compensating
     end
 
+    # @api private
     def compensating!
       @compensating = true
     end
 
+    # @api private
     def pivoted?
       @pivoted
     end
 
-    # A step that talks to the outside world. It runs at most until it is recorded; pass the ticket to the
-    # service as its idempotency key so a repeat after a crash is recognised.
+    # A step that talks to the outside world. It runs until its result is recorded, so after a crash it may run
+    # again: pass the ticket to the service as its idempotency key, so the repeat is recognised.
+    #
+    # @param name [Symbol, String] unique in the recipe
+    # @param undo [#call, nil] how to undo it; receives (result, undo_ticket, step_ticket), as many as it declares
+    # @param options [Hash] `retry:` and `undo_on_failure:`
+    # @yieldparam ticket [String] the idempotency key of this step
+    # @yieldreturn [Object] the result, stored as JSON in the notebook
+    # @return [Object] the result, also when it was read from the notebook
+    # @raise [StepFailed] when it runs out of attempts or calls {#abort!}; rescue it to take another path
+    # @example
+    #   payment = flow.step :charge, undo: ->(charge, ticket) { Payments.refund(charge, ticket) } do |ticket|
+    #     Payments.charge(order, ticket)
+    #   end
     def step(name, undo: nil, **options, &block)
       run_step(name, "step", undo, options, block)
     end
 
-    # A step that only touches your own database. It runs in the same transaction that records it,
-    # so it happens exactly once.
+    # A step that only touches your own database. It runs in the same transaction that records it, so it happens
+    # exactly once. Its undo runs in a transaction too.
+    #
+    # @param (see #step)
+    # @yieldparam ticket [String]
+    # @yieldreturn [Object] the result, stored as JSON in the notebook
+    # @return [Object] the result
+    # @raise [StepFailed] when it runs out of attempts or calls {#abort!}
     def transaction(name, undo: nil, **options, &block)
       run_step(name, "transaction", undo, options, block)
     end
 
-    # The point of no return. Before it, failures are compensated; after it, steps are retried.
+    # The point of no return, such as shipping a parcel. Before it, a step that fails for good undoes the saga;
+    # after it, steps cannot declare an undo and are retried (config.after_pivot_attempts), then the execution is
+    # blocked for a person. If the pivot itself fails for good, the saga is undone: the point was never passed.
+    #
+    # @param name [Symbol, String]
+    # @param options [Hash] `retry:`
+    # @yieldparam ticket [String]
+    # @return [Object] the result
     def pivot(name, **options, &block)
       run_step(name, "pivot", nil, options, block)
     end
 
-    # Rejects the saga for a business reason: no retries, straight to compensation.
+    # Runs a block once the saga ends that way, to update your own records (the order is paid, the order is
+    # cancelled). Declare hooks before the first step, so a saga undone at its first step still knows them. The
+    # block runs in a transaction together with the notebook entry that records it: a hook that only touches your
+    # database runs exactly once, even across crashes. If it raises, the execution is blocked and
+    # {ActiveDurable.retry} runs it again.
+    #
+    # @param event [Symbol] :completed (after the last step) or :compensated (after the last undo)
+    # @return [nil]
+    # @raise [InvalidRecipe] after the first step, for another event, or twice for the same event
+    # @example
+    #   flow.on(:completed) { order.update!(status: "delivered") }
+    #   flow.on(:compensated) { order.update!(status: "cancelled") }
+    def on(event, &block)
+      raise InvalidRecipe, "flow.on needs a block" unless block
+      unless HOOK_EVENTS.include?(event)
+        raise InvalidRecipe, "flow.on(:#{event}): the events are :completed and :compensated"
+      end
+      if @position.positive?
+        raise InvalidRecipe, "flow.on(:#{event}) must come before the first step: when a saga is undone early, " \
+                             "the steps after the failure are never reached"
+      end
+      raise InvalidRecipe, "flow.on(:#{event}) is declared twice" if @hooks.key?(event)
+
+      @hooks[event] = block
+      nil
+    end
+
+    # @api private
+    def hook(event)
+      @hooks[event]
+    end
+
+    # Rejects the saga for a business reason, such as a declined card: no retries, straight to undoing what was
+    # done. Call it inside a step or in the recipe itself.
+    #
+    # @param message [String] recorded as the error
+    # @raise [Abort] always
+    # @example
+    #   flow.step :charge do |ticket|
+    #     Payments.charge(order, ticket)
+    #   rescue Payments::CardDeclined => e
+    #     flow.abort!(e.message)
+    #   end
     def abort!(message)
       raise Abort, message
     end
 
-    # Waits without holding a worker: the wake-up time is written down and the execution is released.
+    # Waits without holding a worker: the wake-up time is written down and the execution is released until then.
+    #
+    # @param name [Symbol, String]
+    # @param duration [ActiveSupport::Duration, Numeric] seconds
+    # @return [nil]
+    # @example
+    #   flow.sleep(:wait_for_delivery, 3.days)
     def sleep(name, duration)
       name, position = visit!(name, "sleep")
       entry = @notebook[name]
@@ -90,7 +196,13 @@ module ActiveDurable
       @runner.suspend!(wake_at, "sleeping")
     end
 
-    # Waits for Durable.signal(execution_id, name, payload) and returns the payload.
+    # 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]
+    # @param timeout [ActiveSupport::Duration, Numeric, nil] seconds; then the step fails and the saga is undone
+    # @return [Object] the signal's payload
+    # @raise [StepFailed] when the timeout passes first
     def wait_for(name, timeout: nil)
       name, position = visit!(name, "wait")
       entry = @notebook[name]
@@ -101,7 +213,7 @@ module ActiveDurable
       signal = SignalRecord.next_for(execution_id, name)
       return consume_signal(signal, name, position).deep_dup if signal
 
-      if entry.nil?
+      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)
         @runner.suspend!(deadline, "waiting")
@@ -118,7 +230,10 @@ module ActiveDurable
     end
 
     # 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) }
@@ -129,6 +244,7 @@ module ActiveDurable
                            "#{missing.size == 1 ? "it" : "them"}. #{RECIPE_CHANGED_HINT}"
     end
 
+    # @api private
     RECIPE_CHANGED_HINT = "Either the recipe changed while this execution was in flight, or code outside a " \
                           "step read data that changed between runs. Keep reads that decide the path inside " \
                           "steps, or define a new recipe version."
@@ -159,7 +275,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
 
@@ -172,26 +292,51 @@ 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) { record_result(name, kind, position, block.call(ticket)) }
         else
           record_result(name, kind, position, block.call(ticket))
         end
       end
       ActiveDurable.crash_point(:after_record, name)
       result
-    rescue NotSerializable, InvalidRecipe
-      raise
-    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
@@ -238,9 +383,12 @@ 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")
+      raise InvalidRecipe, "step names cannot start with '~' (#{name}): it marks hooks" if name.start_with?("~")
       if @seen.key?(name)
         raise DuplicateStepName, "the recipe uses the step name :#{name} twice. Each step needs its own name: " \
                                  "it is the step's key in the notebook."