active_durable 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 593d546eb6e8e46a70c03be3945934ed0c8a189937a5a27256478783cd345df0
-  data.tar.gz: 3226b77ada034c6bf49830dfdb30457904e14104b430b4cfb0a9def3d3de4124
+  metadata.gz: d6ce41040ab6f0cb0036bfe36b30b831a1f91a7da099b9f9e3914568716ef6e6
+  data.tar.gz: ac2223d523ec0edf3470b8b9b66b5a892d2521156ab0446e874feff3104c59ff
 SHA512:
-  metadata.gz: f0f0adcff14966f0b8cf7710218a6a6df9b27152593ea4d0d29c90f1968967817b467c33b9803dac0b7aaec6ff105c291a50ecf1335f15882b1969c4d7f7d2bd
-  data.tar.gz: 1ecba4e399e4f9a247ea9717e9727a50c86d7389aa41a4e53fe3aa9817a100e04a91ecfdc7a2dc51333b24ae9b94a666f1a3c2d5e1987132a48949970a210592
+  metadata.gz: c95a763c1808a55ceebf13c02aa1e53f29830601b2547f6175c6bb375f1b78b9a5c5cd02aa2da505afac8989259f2047f588448aef34ce3bdb98a61dc2037e85
+  data.tar.gz: f12d9dff80e6c7e77bdaa40cd3683356bfc443b04eb442d59a5ca2e8e3da5cd9ecf2f0f97df180014c41c723b49ffb6b80fcfc111833f02994856fef460f61c3

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--readme README.md
+--title "ActiveDurable"
+--no-private
+--hide-api private
+lib/**/*.rb
+-
+CHANGELOG.md

data/CHANGELOG.md

@@ -2,13 +2,49 @@
 
 All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
-[Semantic Versioning](https://semver.org/). Before 1.0 the database schema may change between minor versions:
-regenerate the migration when upgrading.
+[Semantic Versioning](https://semver.org/). Schema changes ship as new migrations: after updating the gem, run
+`bin/rails generate active_durable:upgrade` and `bin/rails db:migrate`.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-06
+
+Usable in a real app: found by a first-time user's walkthrough, plus hooks, cleanup, upgrades and an API reference.
+
+Upgrading from 0.5: `bin/rails generate active_durable:upgrade && bin/rails db:migrate`. Note the behavior change
+below: a plain exception raised by a recipe now blocks the saga instead of undoing it; use `flow.abort!` for business
+rejections.
+
+### Added
+
+- `flow.on(:completed) { ... }` and `flow.on(:compensated) { ... }`: hooks to update your own records when a saga
+  ends. Declared before the first step, so a saga undone early still knows them. Each runs once, in a transaction
+  with the notebook entry that records it (exactly once for database changes, covered by the crash tester); a failing
+  hook blocks the execution and `ActiveDurable.retry` runs only the hook. The dashboard lists them in the notebook,
+  and OpenTelemetry traces them.
+- Cleanup: `ActiveDurable.prune(older_than:)`, `ActiveDurable::PruneJob` and `bin/rails active_durable:prune` delete
+  finished executions (completed, compensated, superseded) older than `config.keep_finished_for` (30 days by
+  default), with their notebook and signals, in batches. Active and blocked executions are never deleted.
+- An API reference: the public API has YARD docs (parameters, returns, errors, examples) and the internals are
+  marked `@api private`, so rubydoc.info shows only what an app calls. `.yardopts` configures it.
+- `bin/rails generate active_durable:upgrade` adds the migrations a newer version needs, skipping the ones the app
+  already has. The first one is an index on `durable_executions (status, updated_at)` for the cleanup and the
+  sweeper; new installs get it from `active_durable:install`.
+
 ### Changed
 
+- **A bug no longer undoes a saga.** Only a step that fails for good, or `flow.abort!`, undoes the finished steps.
+  Any other error raised by the recipe, and a `NameError` or `NoMethodError` inside a step (now
+  `ActiveDurable::CodeError`, not retried), blocks the execution instead: a typo in a deploy used to refund every
+  saga that woke up with it. Fix the code and call `ActiveDurable.retry`. A business rejection raised as a plain
+  exception in the recipe body now blocks too: use `flow.abort!` (or raise `ActiveDurable::Abort`).
+- The repository moved to [webresstudio/active_durable](https://github.com/webresstudio/active_durable). Links to the
+  old address redirect.
+- A website, in English and Spanish, with an interactive simulator of a checkout: pick what goes wrong (a crash, a
+  refused parcel, a declined card…) and watch the steps, the notebook and the outside world. Source in `site/`, built
+  by `bin/site` and published to GitHub Pages by `.github/workflows/pages.yml`. The gem's homepage and both READMEs
+  link to it. Its simulator also shows a bug in a deploy (the saga is blocked, nothing is undone, a retry carries it
+  on) and the order's own status, set by `flow.on(:compensated)`.
 - README: the quick start recipe reads top to bottom, with one-line undos and the Stripe calls in a `Payments`
   module where charging and refunding sit side by side. A new section, "In a Rails app", sets up a Rails app step by
   step: install, job backend, sweeper, the initializer with every setting, routes, where each piece of code goes
@@ -16,6 +52,20 @@ regenerate the migration when upgrading.
   before going to production. The settings moved there from "Observability".
 - Specs cover undos without arguments (`-> { ... }`), a `Method` as an undo, and `flow.abort!` inside a step, which
   skips the step's remaining retries.
+- gemspec: Active Job, Active Record and Active Support are required `>= 6.1, < 9`, the versions CI tests, instead
+  of any version from 6.1 on. The duplicate homepage link is gone, so `gem build` no longer warns.
+
+### Fixed
+
+- The rake tasks were loaded twice (Rails already loads an engine's `lib/tasks`), so each one ran twice.
+- `bin/rails active_durable:sweep` with the `:async` adapter (the Rails default in development) enqueued jobs that died
+  with the rake process. It now runs the due executions itself.
+- Dashboard: the execution id no longer widens its column (long ids wrap), and long problems take two lines, with the
+  full message on hover.
+- README: `Payments` turns Stripe's errors into its own, so the recipe does not depend on Stripe; development with
+  `:async` is explained (sagas started from the console are lost until the sweeper runs); a Minitest example. The
+  order page shows the order's own status, written by the saga (`mark_shipped`, `flow.on(:compensated)`), instead of
+  the saga's status, which said "Processing…" for days after the parcel left.
 
 ## [0.5.0] - 2026-10-06
 

data/README.md

@@ -5,22 +5,25 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/williamromero/active_durable/actions/workflows/main.yml"><img src="https://github.com/williamromero/active_durable/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/webresstudio/active_durable/actions/workflows/main.yml"><img src="https://github.com/webresstudio/active_durable/actions/workflows/main.yml/badge.svg" alt="CI"></a>
   <img src="https://img.shields.io/badge/ruby-3.1%2B-CC342D?logo=ruby&logoColor=white" alt="Ruby 3.1 and newer">
   <img src="https://img.shields.io/badge/rails-6.1%2B-D30001?logo=rubyonrails&logoColor=white" alt="Rails 6.1 and newer">
   <img src="https://img.shields.io/badge/PostgreSQL%20%C2%B7%20MySQL%20%C2%B7%20SQLite-tested-3DD6A0" alt="PostgreSQL, MySQL and SQLite">
   <img src="https://img.shields.io/badge/no%20Redis-no%20extra%20servers-7EA6FF" alt="No Redis, no extra servers">
   <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-B08CFF" alt="MIT license"></a>
+  <a href="https://webresstudio.github.io/active_durable/"><img src="https://img.shields.io/badge/website-try%20the%20simulator-F2B641" alt="Website: try the interactive simulator"></a>
 </p>
 
 <p align="center">
+  <a href="https://webresstudio.github.io/active_durable/"><b>Website</b></a> ·
   <a href="#quick-start">Quick start</a> ·
   <a href="#in-a-rails-app">In a Rails app</a> ·
   <a href="#how-it-works">How it works</a> ·
   <a href="#the-building-blocks">Building blocks</a> ·
   <a href="#dashboard">Dashboard</a> ·
   <a href="#testing-the-crash-tester">Crash tester</a> ·
-  <a href="#compatibility">Compatibility</a>
+  <a href="#compatibility">Compatibility</a> ·
+  <a href="https://rubydoc.info/gems/active_durable">API reference</a>
 </p>
 
 ---
@@ -61,6 +64,7 @@ Write the recipe once, in `app/sagas/`:
 # app/sagas/checkout_saga.rb
 CheckoutSaga = Durable.define(:checkout) do |flow, order_id:|
   order = Order.find(order_id)
+  flow.on(:compensated) { order.update!(status: "cancelled") } # once every finished step was undone
 
   # Touches only your database: committed together with its checkpoint, so it runs exactly once.
   flow.transaction :reserve_stock, undo: -> { order.release_stock! } do
@@ -71,7 +75,7 @@ CheckoutSaga = Durable.define(:checkout) do |flow, order_id:|
   # Talks to the outside world: the ticket is an idempotency key that never changes for this step.
   payment = flow.step :charge, undo: ->(charge, ticket) { Payments.refund(charge, ticket) } do |ticket|
     Payments.charge(order, ticket)
-  rescue Stripe::CardError => e
+  rescue Payments::CardDeclined => e
     flow.abort!(e.message) # a declined card is not retried: the stock is released right away
   end
 
@@ -79,6 +83,7 @@ CheckoutSaga = Durable.define(:checkout) do |flow, order_id:|
   flow.pivot :dispatch do |ticket|
     { "tracking" => Carrier.ship(order.id, reference: ticket).tracking_number, "payment" => payment["id"] }
   end
+  flow.transaction(:mark_shipped) { order.update!(status: "shipped") } # your own status, for your pages
 
   flow.step(:confirmation_email) { OrderMailer.shipped(order.id).deliver_now && true }
   flow.sleep(:wait_for_delivery, 3.days) # no worker is held while it sleeps
@@ -91,12 +96,16 @@ The calls to Stripe live in a plain module, doing and undoing side by side. The
 ```ruby
 # app/services/payments.rb
 module Payments
+  class CardDeclined < StandardError; end
+
   def self.charge(order, ticket)
     intent = Stripe::PaymentIntent.create(
       { amount: order.total_cents, currency: "usd", customer: order.user.stripe_id, confirm: true },
       { idempotency_key: ticket }
     )
     { "id" => intent.id } # written in the notebook, so it must fit in JSON
+  rescue Stripe::CardError => e
+    raise CardDeclined, e.message # the recipe speaks your language, not Stripe's
   end
 
   def self.refund(charge, ticket)
@@ -131,6 +140,9 @@ Run the three commands from the [quick start](#quick-start). The migration creat
 exactly once only because the notebook and your data commit together. A queue in its own database, like Solid
 Queue's in Rails 8, is fine.
 
+When you update the gem, run `bin/rails generate active_durable:upgrade` and then `bin/rails db:migrate`: it adds only
+the migrations your app is missing, and running it twice changes nothing.
+
 ### 2. A job backend
 
 ActiveDurable runs on Active Job, so it uses the backend you already have. New Rails 8 apps come with Solid Queue;
@@ -145,8 +157,11 @@ config.solid_queue.connects_to = { database: { writing: :queue } }
 
 - **Workers must listen to the saga queue.** It is `:default` unless you change `config.queue_name`; if you do, add
   it to your workers (Solid Queue's `config/queue.yml`, Sidekiq's `-q`).
-- **In development** Rails' default `:async` adapter runs jobs inside the server, sleeps and retries included. With
-  Solid Queue, run `bin/jobs` next to the server.
+- **In development** Rails' default `:async` adapter keeps each job in the memory of the process that enqueued it.
+  The server runs its own, sleeps and retries included, but a saga started from the console, `bin/rails runner`, a
+  rake task or `db/seeds.rb` is lost when that process exits, and scheduled wake-ups are lost when the server
+  restarts. A minute later, `bin/rails active_durable:sweep` picks them up: with `:async` it runs them right there.
+  Or run Solid Queue in development too, with `bin/jobs` next to the server.
 
 ### 3. The sweeper
 
@@ -159,11 +174,18 @@ production:
   active_durable_sweep:
     class: ActiveDurable::SweepJob
     schedule: every minute
+  active_durable_prune:
+    class: ActiveDurable::PruneJob
+    schedule: every day at 4am
 ```
 
 With another backend, schedule `ActiveDurable::SweepJob` in its own scheduler (GoodJob cron, sidekiq-cron), or run
 `bin/rails active_durable:sweep` from cron.
 
+The second entry is the cleanup: finished executions (completed, undone or superseded) are kept for
+`config.keep_finished_for`, 30 days by default, and then `ActiveDurable::PruneJob` deletes them with their notebook.
+Active and blocked executions are never deleted. Without it, every saga stays in the database forever.
+
 ### 4. The initializer
 
 The settings, with their defaults:
@@ -179,6 +201,7 @@ ActiveDurable.configure do |config|
   config.backoff = ->(attempt) { [2**attempt, 3600].min } # or [5, 30, 300], or a number
   config.parallel_concurrency = 4       # threads per flow.parallel
   config.sweep_grace = 1.minute         # the sweeper leaves executions this young alone
+  config.keep_finished_for = 30.days    # then ActiveDurable::PruneJob deletes finished ones
 
   # Who may open the dashboard outside development and test. With Devise (HTTP basic auth: see Dashboard):
   config.dashboard_authorize = ->(controller) { controller.request.env["warden"]&.user&.admin? }
@@ -237,7 +260,7 @@ class OrdersController < ApplicationController
   end
 end
 
-# app/models/order.rb
+# app/models/order.rb: orders has a status column ("placed" by default) that the saga updates
 class Order < ApplicationRecord
   def checkout
     Durable.find("checkout-#{id}")
@@ -245,15 +268,16 @@ class Order < ApplicationRecord
 end
 ```
 
-The `id:` ties the saga to its order, so the order page can show where the saga is:
+The `id:` ties the saga to its order: `order.checkout` is for your team and the dashboard. The page shows the order's
+own status, which the saga writes as it goes (`mark_shipped`, `flow.on(:compensated)`), not the saga's: a shipped
+order still has a saga sleeping three days before it asks for a review.
 
 ```erb
 <%# app/views/orders/show.html.erb %>
-<% case @order.checkout.status %>
-<% when "completed" %>   Your order is confirmed.
-<% when "compensated" %> We could not complete it and refunded you.
-<% when "blocked" %>     We are looking into it.
-<% else %>               Processing…
+<% case @order.status %>
+<% when "shipped" %>   Your order is on its way.
+<% when "cancelled" %> We could not complete it and refunded you.
+<% else %>             Processing…
 <% end %>
 ```
 
@@ -275,6 +299,7 @@ the notebook, not to the job: if your backend retries the job too, the copy find
 | stop retrying a business failure | `flow.abort!`, like the declined card above |
 | see what is running | the [dashboard](#dashboard), or `ActiveDurable::RunJob` in your backend's UI |
 | hear about a stuck saga | the `blocked.active_durable` [event](#observability) |
+| delete finished sagas | schedule `ActiveDurable::PruneJob` once a day (step 3) |
 | run a saga inline in tests | `ActiveDurable::Testing.drain(id)` |
 | start or wake sagas from your own jobs | call `Durable.start` or `Durable.signal` there |
 
@@ -301,6 +326,26 @@ it "charges once and confirms the order" do
 end
 ```
 
+With Minitest, the Rails default:
+
+```ruby
+# test/test_helper.rb
+require "active_durable/testing"
+
+class ActiveSupport::TestCase
+  setup { ActiveDurable::Testing.reset! }
+end
+
+# test/services/place_order_test.rb
+class PlaceOrderTest < ActiveSupport::TestCase
+  test "charges once and confirms the order" do
+    order = PlaceOrder.call(email: "ana@example.com", total_cents: 4200)
+
+    assert_equal "completed", ActiveDurable::Testing.drain(order.checkout.id).status
+  end
+end
+```
+
 `drain` runs the saga right there, without a worker. Stub Stripe as you already do, then let the
 [crash tester](#testing-the-crash-tester) kill the saga at every point.
 
@@ -308,6 +353,7 @@ end
 
 - [ ] Workers are running and listen to `config.queue_name`.
 - [ ] The sweeper runs every minute.
+- [ ] The cleanup runs every day, or you keep every execution on purpose.
 - [ ] `dashboard_authorize` is set; without it the dashboard answers 403.
 - [ ] `lease_duration` is longer than your slowest step.
 - [ ] Every step that calls an outside service passes the ticket as its idempotency key.
@@ -334,8 +380,8 @@ stateDiagram-v2
   sleeping --> running: wake-up time
   waiting --> running: Durable.signal
   running --> completed: every step done
-  running --> compensated: failure before the pivot, undos ran
-  running --> blocked: needs a person
+  running --> compensated: a step failed for good, or flow.abort!, before the pivot
+  running --> blocked: a bug, a failure after the pivot or a failing hook
   blocked --> pending: ActiveDurable.retry
 ```
 
@@ -357,6 +403,7 @@ Three rules follow from replaying the recipe:
 | `flow.parallel(name) { \|branches\| ... }` | several steps at the same time | each branch like a step |
 | `flow.sleep(name, 3.days)` | waiting without holding a worker | — |
 | `flow.wait_for(name, timeout:)` | waiting for `Durable.signal` | a timeout fails the saga |
+| `flow.on(:completed) { ... }` | updating your own records when the saga ends (also `:compensated`) | blocks; a retry runs the hook again |
 
 Steps take `undo:`, `retry:` (`3`, `false` or `{ attempts:, backoff: }`) and `undo_on_failure:`.
 
@@ -377,11 +424,15 @@ idempotency key, Stripe answers with the first result instead of charging twice.
 
 <br>
 
-When a step runs out of attempts, raises `ActiveDurable::Abort`, or the recipe raises, every finished step is undone,
-last one first. Each undo is written in the notebook too, so a crash in the middle of undoing resumes where it
+When a step runs out of attempts or calls `flow.abort!`, every finished step is undone, last one first. Each undo is written in the notebook too, so a crash in the middle of undoing resumes where it
 stopped. An undo receives `(result, undo_ticket, step_ticket)` and takes as many as it declares: `-> { ... }` takes
 none. Any object that responds to `call` works too, such as `Payments.method(:refund)`.
 
+**A bug is not a failure.** Anything else the recipe raises, and a `NameError` or `NoMethodError` inside a step,
+blocks the execution instead of undoing it: a typo in a deploy must never refund your customers. Fix the code and
+call `ActiveDurable.retry(id)`, or press Retry in the dashboard, and the saga carries on from where it stopped. To
+reject the work for a business reason outside a step, call `flow.abort!(reason)`.
+
 A step that failed is not undone, because it did not happen. The exception is a step whose failure may hide a
 success, like a charge whose answer timed out: declare `undo_on_failure: true` and its undo runs with `nil` as the
 result, so it can look the outcome up with the step's ticket.
@@ -409,6 +460,32 @@ everything. After it, steps cannot declare `undo:` and are retried with backoff
 
 </details>
 
+<details>
+<summary><b>When a saga ends: hooks</b></summary>
+
+<br>
+
+`flow.on(:completed)` and `flow.on(:compensated)` run once the saga ends that way, to update your own records:
+
+```ruby
+CheckoutSaga = Durable.define(:checkout) do |flow, order_id:|
+  order = Order.find(order_id)
+  flow.on(:completed) { order.update!(status: "delivered") }
+  flow.on(:compensated) { order.update!(status: "cancelled") }
+
+  flow.transaction(:reserve_stock, undo: -> { order.release_stock! }) { ... }
+end
+```
+
+Declare them before the first step: a saga undone at its first step never reaches the lines after it. `completed`
+runs after the last step and `compensated` after the last undo, each in a transaction together with the notebook
+entry that records it, so a hook that only touches your database runs exactly once, even if the process dies. If a
+hook raises, the execution is blocked, and `ActiveDurable.retry` runs the hook again, not the steps.
+
+For progress before the end (paid, shipped), write a step: `flow.transaction(:mark_shipped) { ... }`.
+
+</details>
+
 <details>
 <summary><b>Sleeping and waiting for signals</b></summary>
 
@@ -511,6 +588,7 @@ end
 ActiveDurable.retry("checkout-7")                                   # blocked: try again where it stopped
 ActiveDurable.compensate("checkout-7", reason: "customer cancelled") # undo everything (only before the pivot)
 ActiveDurable.rerun("checkout-7", from: :ship)                      # a new execution reusing steps before :ship
+ActiveDurable.prune(older_than: 30.days)                            # delete finished executions and their notebook
 ```
 
 All three refuse an execution a worker is running right now. A rerun runs the chosen step and the following ones
@@ -554,7 +632,7 @@ end
 
 | Event | Payload |
 | --- | --- |
-| `execution` / `step` / `compensation` / `undo` | `execution_id` (and `recipe`, `step`, `kind`) |
+| `execution` / `step` / `compensation` / `undo` / `hook` | `execution_id` (and `recipe`, `step`, `kind`) |
 | `completed` / `compensated` | `execution_id`, `recipe` |
 | `blocked` | `execution_id`, `recipe`, `error` |
 | `retried` / `compensation_requested` / `rerun` | operator actions |
@@ -606,6 +684,8 @@ Every feature works on every version. Things your app may need on older Rails, u
 - A step runs **at least once**; with an idempotency key it has its effect once. `flow.transaction` runs exactly
   once, because its change and its checkpoint commit together.
 - One worker at a time per execution: taking an execution and every write are fenced by a lease token.
+- A hook (`flow.on`) runs once; exactly once if it only touches your database.
+- A bug never undoes a saga: an error in the code blocks it until you fix it and call `ActiveDurable.retry`.
 - Sagas do not isolate each other: two sagas can see each other's intermediate states.
 - `flow.transaction` is atomic only when the notebook lives in the same database as your data.
 

data/app/controllers/active_durable/executions_controller.rb

@@ -23,8 +23,9 @@ module ActiveDurable
       @execution = Execution.find(params[:id])
       steps = @execution.steps.to_a
       @steps = steps
-      @forward_steps = steps.reject(&:undo?).sort_by { |step| step.position.to_i }
+      @forward_steps = steps.select(&:forward?).sort_by { |step| step.position.to_i }
       @undo_steps = steps.select(&:undo?)
+      @hook_steps = steps.select(&:hook?)
       @signals = @execution.signals.to_a
       @reruns = Execution.where(forked_from: @execution.id).order(:created_at).to_a
     end

data/app/helpers/active_durable/dashboard_helper.rb

@@ -87,7 +87,7 @@ module ActiveDurable
     # their parallel step, undone steps are marked, and an active execution gets a "next" ghost block.
     def track_items(execution, steps)
       undone = steps.select { |step| step.undo? && step.completed? }.to_set { |step| step.name.delete_suffix(":undo") }
-      branches, main = steps.reject(&:undo?).partition { |step| step.position.nil? }
+      branches, main = steps.select(&:forward?).partition { |step| step.position.nil? }
 
       items = main.sort_by(&:position).map do |step|
         build_item(step, undone, branches.select { |branch| branch.name.start_with?("#{step.name}/") })

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

@@ -42,7 +42,7 @@
         <% @executions.each do |execution| %>
           <% items = track_items(execution, @steps_by_execution.fetch(execution.id, [])) %>
           <tr data-id="<%= execution.id %>" data-status="<%= execution.status %>">
-            <td>
+            <td class="exec">
               <%= link_to execution.id, execution_path(execution), class: "exec-link" %>
               <span class="recipe"><%= execution.recipe %>, version <%= execution.recipe_version %></span>
             </td>
@@ -69,7 +69,8 @@
               <% if compensating_now?(execution) %><%= status_pill("compensating") %><% end %>
             </td>
             <td class="when"><%= execution.wake_at ? when_text(execution.wake_at) : tag.span("—", class: "muted") %></td>
-            <td class="problem"><%= execution.error&.dig("message").to_s.truncate(110) %></td>
+            <% problem = execution.error&.dig("message").to_s %>
+            <td class="problem"><span title="<%= problem %>"><%= problem.truncate(110) %></span></td>
             <td class="when"><%= when_text(execution.updated_at) %></td>
           </tr>
         <% end %>

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

@@ -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>

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

@@ -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; }

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
 
@@ -46,6 +49,7 @@ 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

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.
@@ -39,14 +40,43 @@ module ActiveDurable
   # An undo kept failing after all its attempts. The execution is blocked for a human to review.
   class UndoFailed < Error; 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 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.
+  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
+
   # 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.

data/lib/active_durable/execution.rb

@@ -5,8 +5,13 @@ 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
+    # Every status.
     STATUSES = (ACTIVE + TERMINAL).freeze
 
     attribute :input, JSON_TYPE, default: -> { {} }
@@ -27,17 +32,19 @@ 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).
+    # 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