active_durable 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca565450baafb042b5ec363d2d7c101f24edd3281b180d43c173eaeff8dd8df8
-  data.tar.gz: 96ceecb07cf0d85b0d8aaf604dececee56301983d16055de408e533c53059da6
+  metadata.gz: 47ef8eb3bb5a133221ed52ce914ec952ff7f73f552b5352d4558b96e6738458c
+  data.tar.gz: af132b5a177125726a6aed8699e7cf4391c70e9e4fbac566531ab87c3204f998
 SHA512:
-  metadata.gz: a6dafa621dba36aac0429fc264922d876d378390aa7fccebf05a085bbcb1f2e001d7bf57d202075299e47cbbb20d29af86df62000adca22367bec76ab18dd16b
-  data.tar.gz: 7b4c90ddb5104811ab17be9532fe2c4ca029bae139eeeaafdef1bd04a222fa4c2896c34b2ce44376d3ff13222473e76276a991c125fcdbe057937d7e6a649896
+  metadata.gz: fe0584f97ce0594ee30c2186b8a10ac91e57505172b758cf8e667b290a6cb387e0da3566db685c8070798bdab84f32f225a7f2f1787aabc9b106bbe069ceb11e
+  data.tar.gz: 863396b2acc54f007f65c80379e3bcbac0512eb05888d3a91372cddfd88333e5b3536d25798949eaf2200a85fd021ae540a65ffd4d1d1078716e0221247a609b

data/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to this project are documented here. The format follows
 [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`.
 
+## [0.8.0] - 2026-10-22
+
+For sagas that live long and talk to people, such as a WhatsApp agent that books appointments: a mailbox for
+messages, a fresh notebook for long conversations, and the tenant in every run.
+
+Upgrading from 0.7: `bin/rails generate active_durable:upgrade && bin/rails db:migrate`. It adds three nullable
+columns (`durable_executions.context`, `durable_executions.continued_as` with its index, `durable_steps.signal_name`);
+nothing is rewritten. Note the first change below: hash keys now come back sorted.
+
+### Added
+
+- `flow.continue_as_new(**input)` closes the execution and starts a new one of the same recipe (its latest version)
+  with that input, the same context and the signals nobody read yet, in one transaction. Ids follow the chain
+  `order-1`, `order-1~2`, `order-1~3`. The new `continued` status; `Durable.find(id, latest: true)`.
+  `Durable.signal` to any id of the chain reaches the newest execution, also during the hand-off.
+- `flow.wait_for(name, signal:, all:)`: several waits share one signal name, like a mailbox, and `all: true` takes
+  every pending signal at once, returning their payloads in order.
+- `config.context`: an object with `capture` (when an execution starts) and `wrap(context) { }` (around every run,
+  undo, hook and `flow.parallel` branch). `Durable.start(..., context: {...})` gives it explicitly. Reruns keep it.
+- `ActiveDurable::Testing.drain(id, expire_waits: false)` stops at a wait instead of fast-forwarding to its
+  timeout, to test a conversation turn by turn. `drain` follows `continue_as_new`.
+- The dashboard shows `continued` executions and links to the one that carries on.
+
+### Changed
+
+- Hash keys in step results, inputs, signal payloads and `flow.parallel` results are sorted, on the first run and
+  when read back. PostgreSQL's jsonb and MySQL's JSON store keys shorter-first, so a replay used to read a hash whose
+  keys were in another order than the first run returned. That broke anything that compares bytes, such as an AI
+  provider that checks the conversation it is sent again. Executions in flight during the upgrade see their keys in
+  a new order once.
+- `Durable.signal` locks the execution row while it writes the signal.
+- `Testing.drain` delivers each signal given in `signals:` once per call, instead of every time a step of that name
+  waits.
+- `Durable.start` takes `context:`, so `context` can no longer be an input key.
+- `ActiveDurable.retry`, `compensate` and `rerun` on a continued execution raise, naming the one that carries on.
+- `ActiveDurable.prune` deletes a continued execution only together with the one that carried it on.
+
 ## [0.7.0] - 2026-10-07
 
 Fixes from an architecture and security review. Most of them stop a saga from paying twice or undoing the wrong

data/README.md

@@ -213,6 +213,7 @@ ActiveDurable.configure do |config|
   config.sweep_grace = 1.minute         # the sweeper leaves executions this young alone
   config.keep_finished_for = 30.days    # then ActiveDurable::PruneJob deletes finished ones
   config.code_errors += ["Payments::Misconfigured"] # your own errors that mean a bug (see "A bug is not a failure")
+  config.context = TenantContext        # who the work is for, in every run (see "Context")
 
   # 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? }
@@ -413,7 +414,8 @@ Three rules follow from replaying the recipe:
 | `flow.pivot(name) { \|ticket\| ... }` | the step after which there is no going back | retried, then the saga is undone |
 | `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.wait_for(name, timeout:)` | waiting for `Durable.signal` (`signal:` and `all:` for a mailbox) | a timeout fails the saga |
+| `flow.continue_as_new(**input)` | a long-lived saga, such as a chat, that starts a fresh notebook | refused inside a step or with undos pending |
 | `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:`.
@@ -537,6 +539,18 @@ Durable.signal("loan-42", :kyc_done, verified: true)
 
 Pass `id:` to `Durable.start` to choose the execution id (the call becomes idempotent).
 
+**A mailbox.** By default the signal has the step's name. A conversation waits for the customer on every turn, so
+each turn gets its own step name and all of them share one signal name with `signal:`. A message that arrives while
+the saga is busy waits in the mailbox for the next turn. With `all: true` the wait takes every pending message at
+once and returns them in order, so five messages in a row are one turn, not five:
+
+```ruby
+messages = flow.wait_for("reply.#{turn}", signal: :message, all: true, timeout: 1.day)
+
+# in the WhatsApp webhook
+Durable.signal(conversation.execution_id, :message, text: params[:text])
+```
+
 </details>
 
 <details>
@@ -562,6 +576,57 @@ the finished branches are undone in the order they finished. Give your connectio
 
 </details>
 
+<details>
+<summary><b>Context: the tenant in every run</b></summary>
+
+<br>
+
+A saga runs in a worker, days after the request that started it, so `Current.tenant` and friends are gone.
+`config.context` carries them: `capture` runs when the execution starts and its JSON is stored with it; `wrap` runs
+around every run of it, including undos, hooks and each `flow.parallel` branch thread.
+
+```ruby
+module TenantContext
+  def self.capture = { "tenant_id" => Current.tenant_id }
+  def self.wrap(context, &run) = Current.set(tenant_id: context["tenant_id"], &run)
+end
+
+ActiveDurable.configure { |config| config.context = TenantContext }
+
+Durable.start(:checkout, order_id: order.id)                                  # captures the current tenant
+Durable.start(:welcome, tenant_id: t.id, context: { "tenant_id" => t.id })   # or gives it explicitly
+```
+
+`wrap` must call the block once. Executions started without a context get `{}`.
+
+</details>
+
+<details>
+<summary><b>Long conversations: continue as new</b></summary>
+
+<br>
+
+Every run replays the recipe from the top, reading the notebook. A chat that has gone on for 200 turns reads 1,000
+entries before it can answer. `flow.continue_as_new` closes the execution and starts a fresh one of the same recipe
+(its latest version) with the input you give it, usually a summary, plus the same context and the messages nobody
+read yet. All of it happens in one transaction:
+
+```ruby
+Durable.define(:chat) do |flow, conversation_id:, turn: 0, summary: nil|
+  # ... the turn ...
+  flow.continue_as_new(conversation_id: conversation_id, turn: turn + 1, summary: summary) if turn % 20 == 19
+end
+```
+
+The new execution's id is the old one plus `~2` (then `~3`), so its steps get new tickets. `Durable.signal` to any id
+of the chain reaches the newest execution, even one sent during the hand-off, and
+`Durable.find(id, latest: true)` returns it. Compute the input from step results, so a replay computes the same.
+`continue_as_new` is refused inside a step and while undos are pending (those steps could never be undone); after
+`flow.pivot` it is allowed. The old execution's hooks do not run, and it is pruned together with the one that
+carries on.
+
+</details>
+
 <details>
 <summary><b>Changing a recipe while sagas are in flight</b></summary>
 
@@ -581,6 +646,91 @@ New executions use the highest version; each execution keeps the one it started
 
 </details>
 
+## Example: a WhatsApp assistant that books appointments
+
+First in plain words, then the code.
+
+**What it does.** A customer writes to a bakery on WhatsApp: "Hi, can I come on Friday to order a cake?". An
+assistant (an AI that can see the calendar) answers, offers the free times and books the one the customer picks. The
+conversation can take two minutes or two days. The customer may send three messages in a row, or disappear and come
+back tomorrow. Meanwhile your servers restart, you deploy, a process dies.
+
+**The notebook.** Think of a cook who ticks every step of a recipe in a notebook. When someone interrupts, the cook
+does not trust their memory: they reread the notebook from the top, skip every step with a tick, and carry on from
+the first one without it. ActiveDurable does the same with your code. Each step's result is written in your database,
+and every time the saga wakes up (a message arrives, a timer rings) it rereads the recipe and skips what is done. That
+is why the assistant never books twice, even if the server dies right after booking: the booking has its tick. (A
+step that died halfway runs again with the same ticket, so the calendar and WhatsApp can recognize a repeat.)
+
+**Turns.** A turn is one exchange: the customer writes, the assistant answers. Each turn adds three ticks: the
+customer's messages, the AI's answer (which may book) and the WhatsApp message sent back. The AI's answer is written
+down too, so rereading never asks the AI again: no double cost, and the very same text.
+
+**The mailbox.** Every message goes to one mailbox, `:message`. If the customer writes while the assistant is
+thinking, the message waits there for the next turn. If they send five in a row, the assistant takes all five at
+once: one turn, not five.
+
+**A fresh page.** After 20 turns the notebook has 60 ticks to reread every time something happens. Instead of making
+the same page longer, `continue_as_new` starts a new page with a short summary ("Ana wants a cake on Friday, saw the
+times at 10 and 3"), keeping the messages nobody read yet.
+
+**Who it is for.** One app serves many bakeries. `config.context` writes down which one the conversation belongs to
+when it starts, and gives it back on every run, so each step sees the right calendar.
+
+```ruby
+# config/initializers/active_durable.rb
+module TenantContext
+  def self.capture = { "tenant_id" => Current.tenant_id }
+  def self.wrap(context, &run) = Current.set(tenant_id: context["tenant_id"], &run)
+end
+ActiveDurable.configure { |config| config.context = TenantContext }
+
+# app/sagas/booking_assistant_saga.rb
+BookingAssistantSaga = Durable.define(:booking_assistant) do |flow, conversation_id:, turn: 0, summary: nil|
+  conversation = Conversation.find(conversation_id)
+  history = summary ? [{ "role" => "user", "content" => "What happened so far: #{summary}" }] : []
+  booked = nil
+
+  20.times do |i|
+    n = turn + i
+    # 1. The customer's messages: every one that arrived since the last turn.
+    messages = flow.wait_for("customer.#{n}", signal: :message, all: true)
+    history << { "role" => "user", "content" => messages.map { |m| m["text"] }.join("\n") }
+
+    # 2. The AI's answer. When it decides to book, it calls Calendar.book(slot, key: ticket): booked once.
+    reply = flow.step("assistant.#{n}") { |ticket| BookingAssistant.answer(history, ticket: ticket) }
+    history << { "role" => "assistant", "content" => reply["text"] }
+
+    # 3. The answer. If the process dies right after sending it, this step runs again with the same ticket:
+    #    WhatsApp.send_text keeps the ticket with the message it sent and skips sending it twice.
+    flow.step("send.#{n}") { |ticket| WhatsApp.send_text(conversation.phone, reply["text"], key: ticket) }
+
+    if reply["booked"]
+      booked = reply
+      break
+    end
+  end
+  next booked if booked
+
+  # 20 turns without a booking: a fresh page with a summary.
+  summary = flow.step("summary.#{turn}") { BookingAssistant.summarize(history) }
+  flow.continue_as_new(conversation_id: conversation_id, turn: turn + 20, summary: summary["text"])
+end
+
+# app/controllers/whatsapp_webhooks_controller.rb
+def create
+  conversation = Conversation.open_for(params[:from]) # a new one once the last one ended; tenant: Current.tenant_id
+  id = "chat-#{conversation.id}"
+  Durable.start(:booking_assistant, id: id, conversation_id: conversation.id) # idempotent: starts it once
+  Durable.signal(id, :message, text: params[:text]) # reaches the newest page of the chain
+  head :ok
+end
+```
+
+To close conversations where the customer went quiet, give the wait a `timeout: 1.day` and rescue
+`ActiveDurable::StepFailed`. To test it turn by turn: `Testing.drain(id, expire_waits: false)`, then `Durable.signal`,
+then drain again.
+
 ## Dashboard
 
 ```ruby
@@ -654,7 +804,8 @@ point, kills it right there, and finishes it with a new worker. It is the fastes
 idempotent.
 
 `ActiveDurable::Testing.drain(id, signals: { name => payload })` runs an execution synchronously, fast-forwarding
-sleeps, retries and expired leases.
+sleeps, retries and expired leases, and follows `continue_as_new`. It fast-forwards wait timeouts too; to test a
+conversation turn by turn, pass `expire_waits: false`, send a signal and drain again.
 
 ## Observability
 
@@ -760,6 +911,9 @@ while sagas were halfway through. All of them settled, the refunds and hooks ran
   OpenTelemetry: keep secrets and personal data out of them.
 - Ids cannot be blank or contain `/`. Ids and step names compare exactly, also on MySQL.
 - `flow.transaction` is atomic only when the notebook lives in the same database as your data.
+- Step results, inputs and signals come back with their hash keys sorted, on the first run and on every replay, since
+  PostgreSQL and MySQL do not keep the order you wrote them in.
+- A replay reads the whole notebook. For sagas that grow without end, such as a chat, use `flow.continue_as_new`.
 
 ## Development
 

data/app/helpers/active_durable/dashboard_helper.rb

@@ -8,14 +8,14 @@ module ActiveDurable
 
     STATUS_TONES = {
       "completed" => "good", "compensated" => "undo", "blocked" => "bad", "superseded" => "muted",
-      "running" => "busy", "pending" => "busy", "sleeping" => "wait", "waiting" => "wait",
+      "continued" => "muted", "running" => "busy", "pending" => "busy", "sleeping" => "wait", "waiting" => "wait",
       "retrying" => "wait", "failed" => "bad", "undone" => "undo"
     }.freeze
 
     STATUS_WORDS = {
       "pending" => "Queued", "running" => "Running", "sleeping" => "Sleeping", "waiting" => "Waiting",
       "completed" => "Completed", "compensated" => "Undone", "blocked" => "Needs a person",
-      "superseded" => "Superseded"
+      "superseded" => "Superseded", "continued" => "Continued"
     }.freeze
 
     def status_pill(status)

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

@@ -17,6 +17,9 @@
       <% if @execution.forked_from %>
         Rerun of <%= execution_link(@execution.forked_from, class: "mono") %>.
       <% end %>
+      <% if @execution.continued? %>
+        Continued as <%= execution_link(@execution.continued_as, class: "mono") %>.
+      <% end %>
     </p>
   </div>
   <span class="badge"><%= ActiveDurable::DashboardHelper::STATUS_WORDS.fetch(@execution.status, @execution.status) %><%= ", undoing" if compensating_now?(@execution) %></span>

data/lib/active_durable/configuration.rb

@@ -52,6 +52,21 @@ module ActiveDurable
       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
@@ -67,6 +82,7 @@ module ActiveDurable
       @clock = -> { Time.current }
       @dashboard_authorize = nil
       @code_errors = DEFAULT_CODE_ERRORS.dup
+      @context = nil
       @logger = nil
     end
 

data/lib/active_durable/execution.rb

@@ -9,14 +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
-    # Statuses that never change again: signals are refused and ActiveDurable.prune may delete them.
-    FINISHED = %w[completed compensated 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
 
@@ -34,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)

data/lib/active_durable/flow.rb

@@ -199,36 +199,79 @@ 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?
 
-      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")
-      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
@@ -292,9 +335,11 @@ 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(records: name) { 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)
@@ -411,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

@@ -99,7 +99,8 @@ 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
@@ -155,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
@@ -175,10 +179,10 @@ module ActiveDurable
                                                   kind: branch.kind) do
           if branch.kind == "transaction"
             @notebook.transaction(records: branch.full_name) do
-              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
           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)

data/lib/active_durable/notebook.rb

@@ -53,8 +53,10 @@ module ActiveDurable
       write!(name, kind: kind, position: position, status: "blocked", attempts: attempts, error: error, wake_at: nil)
     end
 
-    def wait!(name, kind:, position:, wake_at:)
-      write!(name, kind: kind, position: position, status: "waiting", wake_at: wake_at)
+    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

data/lib/active_durable/operations.rb

@@ -58,7 +58,7 @@ module ActiveDurable
         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
@@ -78,6 +78,7 @@ module ActiveDurable
     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
@@ -98,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
 

data/lib/active_durable/pruner.rb

@@ -2,7 +2,8 @@
 
 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
@@ -16,9 +17,12 @@ module ActiveDurable
       cutoff = now - older_than.to_f
       deleted = 0
       loop do
-        ids = Execution.where(status: Execution::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
@@ -28,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}")
@@ -44,6 +46,29 @@ module ActiveDurable
       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

data/lib/active_durable/serializer.rb

@@ -2,8 +2,8 @@
 
 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, UTF-8 strings), so the first run
-  # and a replay behave the same. Anything that is not plain JSON, or that some database cannot store (a NUL
+  # 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
@@ -27,12 +27,25 @@ 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)
 
         key = utf8(key, "a key of #{path}")
-        out[key] = normalize(item, "#{path}[#{key.inspect}]")
+        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
 

data/lib/active_durable/signal_record.rb

@@ -17,17 +17,22 @@ module ActiveDurable
     # 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(steps[:name].eq(arel_table[:name]))
+                     .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

@@ -37,6 +37,16 @@ module ActiveDurable
       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/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)
+    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.7.0"
+  VERSION = "0.8.0"
 end

data/lib/active_durable.rb

@@ -124,10 +124,12 @@ module ActiveDurable
     # @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?
 
       id = check_id!(id)
@@ -143,6 +145,37 @@ module ActiveDurable
       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")
@@ -167,18 +200,33 @@ module ActiveDurable
     # @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.finished?
+      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

data/lib/generators/active_durable/install/templates/create_active_durable_tables.rb.tt

@@ -10,18 +10,21 @@ class CreateActiveDurableTables < ActiveRecord::Migration<%= migration_version %
       t.string :status, null: false
       t.boolean :compensating, null: false, default: false
       t.column :input, json_type
+      t.column :context, json_type
       t.column :output, json_type
       t.column :error, json_type
       t.datetime :wake_at, precision: 6
       t.datetime :locked_until, precision: 6
       t.string :lease_token
       t.string :forked_from, **exact
+      t.string :continued_as, **exact
       t.timestamps precision: 6
     end
     add_index :durable_executions, %i[status wake_at]
     add_index :durable_executions, %i[status updated_at]
     add_index :durable_executions, %i[recipe status]
     add_index :durable_executions, :forked_from
+    add_index :durable_executions, :continued_as
 
     # The notebook: one row per step (and per undo) of an execution.
     create_table :durable_steps do |t|
@@ -31,6 +34,7 @@ class CreateActiveDurableTables < ActiveRecord::Migration<%= migration_version %
       t.integer :position
       t.string :status, null: false
       t.integer :attempts, null: false, default: 0
+      t.string :signal_name, **exact
       t.column :result, json_type
       t.column :error, json_type
       t.datetime :wake_at, precision: 6

data/lib/generators/active_durable/upgrade/templates/add_active_durable_context.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# ActiveDurable 0.8: the context an execution started with (config.context), given back to it on every run.
+class AddActiveDurableContext < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :durable_executions, :context, json_type unless column_exists?(:durable_executions, :context)
+  end
+
+  def down
+    remove_column :durable_executions, :context if column_exists?(:durable_executions, :context)
+  end
+
+  private
+
+  # jsonb on PostgreSQL, json elsewhere, like the other JSON columns.
+  def json_type
+    connection.adapter_name.downcase.include?("postg") ? :jsonb : :json
+  end
+end

data/lib/generators/active_durable/upgrade/templates/add_active_durable_continued_as.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# ActiveDurable 0.8: flow.continue_as_new closes an execution and points it to the one that carries on.
+class AddActiveDurableContinuedAs < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :durable_executions, :continued_as, :string, **exact unless column_exists?(:durable_executions, :continued_as)
+    add_index :durable_executions, :continued_as unless index_exists?(:durable_executions, :continued_as)
+  end
+
+  def down
+    remove_index :durable_executions, :continued_as if index_exists?(:durable_executions, :continued_as)
+    remove_column :durable_executions, :continued_as if column_exists?(:durable_executions, :continued_as)
+  end
+
+  private
+
+  # MySQL compares strings ignoring case and accents by default; ids must match exactly.
+  def exact
+    connection.adapter_name.match?(/mysql|trilogy/i) ? { collation: "utf8mb4_bin" } : {}
+  end
+end

data/lib/generators/active_durable/upgrade/templates/add_active_durable_signal_name.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# ActiveDurable 0.8: flow.wait_for(name, signal: ...) writes down which signal a step waits for, when it is not the
+# step's own name.
+class AddActiveDurableSignalName < ActiveRecord::Migration<%= migration_version %>
+  def up
+    return if column_exists?(:durable_steps, :signal_name)
+
+    add_column :durable_steps, :signal_name, :string, **exact
+  end
+
+  def down
+    remove_column :durable_steps, :signal_name if column_exists?(:durable_steps, :signal_name)
+  end
+
+  private
+
+  # MySQL compares strings ignoring case and accents by default; signal names must match exactly.
+  def exact
+    connection.adapter_name.match?(/mysql|trilogy/i) ? { collation: "utf8mb4_bin" } : {}
+  end
+end

data/lib/generators/active_durable/upgrade/upgrade_generator.rb

@@ -16,7 +16,10 @@ module ActiveDurable
       desc "Adds the migrations that newer ActiveDurable versions need. Run it after updating the gem."
 
       # In the order they were released. Never edit one that shipped: add a new one.
-      MIGRATIONS = %w[add_active_durable_prune_index make_active_durable_ids_case_sensitive].freeze
+      MIGRATIONS = %w[
+        add_active_durable_prune_index make_active_durable_ids_case_sensitive add_active_durable_context
+        add_active_durable_signal_name add_active_durable_continued_as
+      ].freeze
 
       # @api private
       def create_migration_files

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_durable
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - William Romero
@@ -120,7 +120,10 @@ files:
 - lib/active_durable/version.rb
 - lib/generators/active_durable/install/install_generator.rb
 - lib/generators/active_durable/install/templates/create_active_durable_tables.rb.tt
+- lib/generators/active_durable/upgrade/templates/add_active_durable_context.rb.tt
+- lib/generators/active_durable/upgrade/templates/add_active_durable_continued_as.rb.tt
 - lib/generators/active_durable/upgrade/templates/add_active_durable_prune_index.rb.tt
+- lib/generators/active_durable/upgrade/templates/add_active_durable_signal_name.rb.tt
 - lib/generators/active_durable/upgrade/templates/make_active_durable_ids_case_sensitive.rb.tt
 - lib/generators/active_durable/upgrade/upgrade_generator.rb
 - lib/tasks/active_durable.rake