ajdc 0.0.1 → 0.1.0

data/skills/ajdc/examples/uniqueness.md

@@ -0,0 +1,87 @@
+# Uniqueness: one live run per identity
+
+`unique_by` names the `perform` parameters that identify a run and forbids a second live run
+for the same identity. The check runs at `perform_later`, inside the caller's transaction; the
+unique index on `[job_class, active_key]` settles concurrent enqueues. Terminal runs
+(`completed`, `discarded`, `cancelled`) free the identity.
+
+## `:skip` (default): the second start is a no-op
+
+For a sweep that starts runs, a button clicked twice, a webhook delivered twice.
+
+```ruby
+class License::LifecycleJob < ApplicationJob
+  include ActiveJob::Durable
+
+  unique_by :license
+
+  def perform(license) = # ...
+end
+
+# a daily starter for licenses expiring within 30 days; running it twice starts nothing new
+License.expiring_within(30.days).find_each { License::LifecycleJob.perform_later(it) }
+License::LifecycleJob.perform_later(license)   # => false while a run is live
+```
+
+## `:replace`: the new start cancels the live run
+
+For a reschedule or a renewal, when the date the run waits for has moved.
+
+```ruby
+class AppointmentReminderJob < ApplicationJob
+  include ActiveJob::Durable
+
+  unique_by :appointment, on_conflict: :replace
+
+  def perform(appointment)
+    step :remind, wait_until: appointment.start_at - 30.minutes do
+      AppointmentNotification.with(appointment:).deliver_later(appointment.patient)
+    end
+  end
+end
+
+# PatientAppointment: after_create_commit, and after_update_commit when start_at changed:
+#   AppointmentReminderJob.perform_later(self)      # the old run is cancelled, a new one parks
+```
+
+## `:reject`: the second start is an error
+
+For money and anything where a duplicate must be seen, not swallowed.
+
+```ruby
+class PayoutJob < ApplicationJob
+  include ActiveJob::Durable
+
+  unique_by :payout, on_conflict: :reject
+
+  def perform(payout, wallet_id, amount) = # ...
+end
+
+PayoutJob.perform_later(payout, wallet_id, amount)
+PayoutJob.perform_later(payout, wallet_id, amount)   # raises ActiveJob::Durable::RunAlreadyExists; error.run is the live one
+```
+
+`unique_by :payout` also lets a webhook find the run with the payout alone:
+`payout.job_run.wake_up(:payment, ...)`.
+
+## Identity inside an argument
+
+When the identity is not a `perform` parameter but a value inside one, name it with a block.
+A Stripe webhook payload:
+
+```ruby
+class Payment::ChargeImportJob < ApplicationJob
+  include ActiveJob::Durable
+
+  unique_by { |payload| payload.dig("data", "object", "id") }   # the charge id; :skip
+
+  def perform(payload)
+    step :import do
+      Payment::StripeChargeImport.call(payload.dig("data", "object"))
+    end
+  end
+end
+```
+
+Keep an idempotency guard inside the step when a duplicate may arrive after the run completed:
+uniqueness covers live and attention runs only.

data/skills/ajdc/references/api.md

@@ -0,0 +1,157 @@
+# AJ/DC API reference (differences that matter)
+
+## 1. Setup
+
+```ruby
+gem "ajdc"
+bin/rails generate ajdc:install                     # migration for the two tables in the primary database
+bin/rails generate ajdc:install --database=durable  # or in a separate database, plus the initializer
+```
+
+Which database, and why it matters: `installation.md` §2.
+
+```yaml
+# config/recurring.yml (Solid Queue) or the app's scheduler
+durable_wake:
+  class: ActiveJob::Durable::WakeJob
+  schedule: every minute
+```
+
+`include ActiveJob::Durable` in the job. It includes `Continuable`; `step`, `start:`,
+`isolated:`, `step.cursor`, `step.set!`, `step.advance!`, `step.checkpoint!`, `attribute`,
+`retry_on`, `discard_on` are unchanged. The payload carries only the run id; progress and
+attributes live on the run row.
+
+## 2. Identity: `identified_by` versus `unique_by` versus `set(workflow_key:)`
+
+| Macro | Answers | Column | Effect on enqueue |
+|---|---|---|---|
+| none | "what is this run about?" | `key` = all arguments, positional in order then keywords `name=value` | none |
+| `identified_by :card` | same, narrowed to the named `perform` parameters | `key` from those parameters only | none |
+| `identified_by { \|card, **kw\| [card, kw.fetch(:format, "csv")] }` | same, computed | `key` from the block's return | none |
+| `unique_by :card` | "may two live runs exist for this?" | `active_key` while live or attention; `NULL` when terminal | `on_conflict` applies |
+| `unique_by { \|payload\| payload.dig("data", "object", "id") }` | same, computed; also sets `key` when `identified_by` is absent | `active_key` (and `key`) from the block's return | `on_conflict` applies |
+| `set(workflow_key: "x")` | one run's key, verbatim | `key` | none |
+
+- `identified_by` only names the run; use it so `workflow_runs.for(card)` finds the run
+  whatever the other arguments were.
+- `unique_by` takes the same forms as `identified_by`: names or a block. Alone, it also names
+  the run, so one declaration covers both columns. Declare both only when identity and
+  uniqueness must differ; then the two derive independently.
+- An unknown parameter name raises `ArgumentError` at declaration or first enqueue.
+- Identity inside a hash argument (a webhook payload): use the block form.
+
+`on_conflict`, checked at `perform_later` inside the caller's transaction, decided for
+concurrent enqueues by the unique index on `[job_class, active_key]`:
+
+| Value | Behaviour | Use for |
+|---|---|---|
+| `:skip` (default) | enqueues nothing, `perform_later` returns `false` | sweeps that start runs, double clicks, webhook retries |
+| `:reject` | raises `ActiveJob::Durable::RunAlreadyExists` (`error.run`) | payouts, anything with money |
+| `:replace` | `cancel!` the live run, start a new one, one transaction | reschedules, renewals, "the date moved" |
+
+## 3. Timers: `wait:` versus `wait_until:`
+
+```ruby
+step :remind, wait_until: license.expires_at - 2.weeks   # at a time
+step :revoke, wait: 2.weeks                              # after the previous step completed
+step :lazy,   wait_until: -> { expensive_query.date }    # callable: evaluated only when the step is reached
+```
+
+| | `wait:` | `wait_until:` |
+|---|---|---|
+| Takes | a Duration (or callable) | a Time (or callable) |
+| Anchored | once, at the previous step's completion (run start for a first step) | re-evaluated at every pass, including wake |
+| Target moves | does not move | re-arms by itself: `license.expires_at` changed, the run parks again |
+| Target in the past | runs at once | runs at once |
+
+A plain expression on the `step` line is evaluated on every pass, because `perform` re-runs on
+each resume and skips completed steps; use a callable only when the expression is expensive.
+
+Parked run: status `waiting`, `wake_at` set, nothing in the queue. `WakeJob` wakes due runs;
+precision is its interval. `run.wake_up` (no arguments) ends the wait now. `run.cancel!` stops
+the clock for that run.
+
+## 4. Signals: `await` and `wake_up`
+
+```ruby
+def perform(import)
+  await :confirmation, wait: 10.minutes        # deadline uses the timer keywords
+  return import.destroy! unless confirmed
+  step :apply
+end
+
+def confirmation(signal) = self.confirmed = signal.presence   # nil at the deadline
+
+# elsewhere
+import.job_run.wake_up(:confirmation, true)
+```
+
+- `await :name` is a step with an empty body; the method `name(value)` (or a block
+  `await(:name) { |value| ... }`) runs on wake with the value. `nil` means the deadline passed.
+- `wake_up(name, value)`: any JSON value. Sent before the `await` line is reached, it waits in
+  `pending_signals` and is consumed without parking. A second signal for the same name
+  overwrites. A run that is not live raises `ActiveJob::Durable::NotLive`.
+- The value is kept on the step row, so a crash in a later step replays the same argument.
+- `halt!` inside the handler leaves the await incomplete; `resume!` awaits again with a fresh
+  deadline.
+- `wake_up` with no name wakes whatever is parked: a timer ends now, an await receives `nil`.
+- Names must be unique per run; no `await` in a loop with a fixed name.
+
+## 5. Stopping: `halt_on`, `halt!`, `resume!`, `cancel!`
+
+| Call | From | Status after | Then |
+|---|---|---|---|
+| `retry_on E` | class | `enqueued` (retry wait) | automatic |
+| `discard_on E` | class | `discarded` | nothing; terminal |
+| `halt_on E` | class | `halted`, `error_class`, `error_message`, step row `halted` with cursor | `run.resume!` |
+| `halt!(reason)` | inside a step | `halted`, `halt_reason` | `run.resume!` |
+| uncaught error | | `failed`, error columns | `run.resume!` or a backend retry |
+| `run.cancel!` | outside | `cancelled`, `active_key` cleared | nothing; terminal |
+| `return` from `perform` | inside | `completed` | nothing |
+
+Declared handlers win over resume: an error with a `discard_on`/`retry_on`/`halt_on` goes to
+that handler; only undeclared errors are resumed by Continuation. No `resume_job` override.
+
+`resume!` re-enqueues at the halted or failed step, from its cursor, as a new attempt; earlier
+attempts keep their errors; manual resumes do not count toward `max_resumptions`. `cancel!` of a
+running job takes effect at its next checkpoint or step boundary.
+
+## 6. Statuses
+
+| Group | Statuses | Scope |
+|---|---|---|
+| live | `enqueued` (in the queue), `running` (in a worker), `waiting` (timer), `awaiting` (signal) | `live` |
+| attention | `failed`, `halted` | `attention`; resumable |
+| terminal | `completed`, `discarded`, `cancelled` | `terminal` |
+
+`enqueued` is written at every re-enqueue (isolated step, graceful stop, `retry_on`). An
+`enqueued` run with `started_at` null never ran. `stuck_for(1.hour)`: `running` with a stale
+heartbeat, or `enqueued`/`waiting`/`awaiting` with a stale transition.
+
+## 7. Reading runs
+
+```ruby
+MyJob.workflow_runs                                   # this class, newest first
+MyJob.workflow_runs.for(card)                         # the key perform_later(card) derives
+MyJob.workflow_runs.for(workflow_key: "cards/42")
+MyJob.workflow_runs.for(card).live.first              # or .sole under unique_by
+MyJob.workflow_runs.awaiting.at_step(:review)         # the review queue
+MyJob.workflow_runs.halted / .failed / .attention
+MyJob.workflow_runs.stuck_for(1.hour)
+run.status, run.current_step, run.completed_steps, run.state, run.wake_at, run.halt_reason
+run.steps                                             # one row per attempt: name, attempt, status, cursor, timings, error
+```
+
+Give the model a method for its run instead of a class-level helper:
+
+```ruby
+def job_run = ImportJob.workflow_runs.for(self).live.sole
+```
+
+## 8. Callbacks
+
+`before_step`, `after_step`, `around_step`: `ActiveSupport::Callbacks`, the `before_perform`
+shape. They run for steps that execute, not for skipped ones; `after_step` only on completion.
+`current_step` is the running `Step`. `throw :abort` in `before_step` skips the body and marks
+the step completed.

data/skills/ajdc/references/decision-guide.md

@@ -0,0 +1,130 @@
+# Decision guide: workflow, sweep, or hybrid
+
+## 1. The three ways to do "later"
+
+| | Cron sweep | Parked run per entity | Hybrid |
+|---|---|---|---|
+| Shape | a recurring job scans a table for due rows | one `Durable` run per entity, `wait_until:` | a recurring job starts runs for entities due within a window |
+| Where the schedule lives | cron YAML + a scope | the job's `perform`, top to bottom | both, the window in cron, the steps in the job |
+| Idempotency | by hand: claim columns, bucket arithmetic | by `unique_by` and completed steps | `unique_by ..., on_conflict: :skip` makes the sweep idempotent |
+| Reschedule | data-driven, free (the next scan re-derives) | `perform_later` again with `:replace`, or the moved `wait_until:` re-arms on wake | same as parked |
+| "Where is X?" | a query on the entity table | `workflow_runs.for(x)` | same |
+| Rows at rest | none | one run row per live entity | one per entity inside the window |
+| Precision | the cron interval | the `WakeJob` interval (one minute) | one minute |
+| Best when | the rule is a policy over a table, or rows number in the millions | the wait belongs to one entity and has steps before or after it | many entities, far-future dates |
+
+Rules:
+
+- **Park when the wait belongs to one entity and is part of a sequence.** A license lifecycle
+  (remind, expire, revoke), an appointment reminder, a 30-day grace period, a payout waiting for
+  a webhook.
+- **Sweep when the rule is a policy over a table.** "Delete chats older than 7 days", "post the
+  weekly digest", "rebuild the facts nightly". No entity has a position in it.
+- **Hybrid when both are true:** thousands of entities with dates years ahead. Start a run only
+  for entities due within N days; `unique_by :entity` with the default `:skip` makes the daily
+  starter idempotent. Cancel on the entity's terminal event.
+
+A parked run costs one row and nothing in the queue: the run is parked on the row, not in the
+adapter, and `WakeJob` wakes due runs. So "too many jobs waiting" is not the parked design's
+cost anymore; the cost is rows, and rows are cheap. What still argues for a sweep is the rule's
+nature, not volume.
+
+## 2. Replacing a sweep: the checklist
+
+Before you replace a working sweep, confirm each:
+
+1. Each row the sweep touches has an owner entity and a start event (created, cancelled,
+   confirmed) where `perform_later` can be called.
+2. There is a terminal event where the run should be cancelled (submitted, reactivated, paid).
+   Without one, runs accumulate as `waiting` and the sweep was right.
+3. The sweep's idempotency tricks (claim columns, `expires_at` buckets, `updated_at` compared
+   at wake) exist only because the parked job had no identity. `unique_by` removes them; if they
+   exist for another reason, keep them.
+4. The precision of one minute is enough. It is for e-mail, Slack, billing; it is not for
+   sub-minute SLAs.
+5. If the sweep also heals data (re-imports charges the webhook missed), keep the sweep as the
+   safety net and add the run for observability; both can coexist.
+
+If 1 or 2 fails, keep the sweep. If you keep a sweep and want observability, make the sweep
+itself a `Durable` job with a cursor; the run row shows progress and the last error.
+
+## 3. Signals: `await` versus a state column plus a controller
+
+Today's shape: a state column (`unconfirmed → scheduled → done`), a controller action that flips
+it and enqueues the second half, a vacuum for the ones nobody confirmed. Problems: the second
+half has no memory of the first, the deadline is enforced by a daily job, two entry points can
+race.
+
+`await` keeps one job with the wait in the middle. Use it when:
+
+- the flow has steps before and after the wait (parse then apply; withdraw then credit);
+- the wait has a deadline (`wait: 10.minutes`, `wait: 3.days`) or must be observable
+  (`workflow_runs.awaiting.at_step(:review)` is the review queue);
+- the signal carries a value the later steps need (a verdict, a payment amount).
+
+Keep the controller-flips-a-state shape when the "signal" is the only thing that ever happens
+(no second half), or when the decision must survive without any job (an audit record). Both can
+coexist: write the decision to the model and `wake_up` the run.
+
+### Repeated decisions
+
+`await` is a step, and step names are unique per run: an `await :decision` inside a loop is
+completed after the first pass and skipped on every later one. Three cases:
+
+| The decision | Shape |
+|---|---|
+| needs no value, only a go (the choice is already a row somewhere) | `halt!(:reason)` inside the loop; `resume!` from the outside. A halt is not a step; it can happen any number of times. |
+| carries a value, from a set known when `perform` runs | one `await` per name, e.g. per approver |
+| carries a value, an unknown number of times | write the value to a model, then `halt!`/`resume!`; the run reads the model when it continues |
+
+A known set, N approvers snapshotted at submission:
+
+```ruby
+def perform(time_off)
+  @time_off = time_off
+  step :notify_approvers
+  time_off.approvals.each do |approval|
+    await :"decision_#{approval.approver_id}", wait: 3.business_days
+  end
+  step :finalize
+end
+
+def method_missing(name, decision = nil)
+  return super unless name.start_with?("decision_")
+  halt!(:approver_silent) if decision.nil?                                # the deadline passed
+  @time_off.approvals.find_by!(approver_id: name.to_s.delete_prefix("decision_")).decide!(decision)
+end
+
+# controller: time_off.approval_run.wake_up(:"decision_#{current_member.id}", params[:decision])
+```
+
+The awaits run in order; a rejection can end the run early from its handler. Approvers are
+notified together in the first step, so waiting in order costs nothing visible.
+
+## 4. `halt!` versus `await` versus `retry_on`
+
+| Situation | Use |
+|---|---|
+| a transient error (network, lock) | `retry_on` |
+| an error nothing can fix (corrupt file) | `discard_on` |
+| an error a person fixes, then the run continues (out of storage, wrong config) | `halt_on Error`, then `run.resume!` |
+| a decision that needs no data, only a go (tool approval already recorded elsewhere) | `halt!(:reason)`, then `run.resume!` |
+| a decision that carries data (approve/reject, a webhook payload) | `await :name`, then `run.wake_up(:name, value)` |
+| a fixed wait | `step :x, wait: 2.weeks` |
+| a wait until a date on the record | `step :x, wait_until: record.date` |
+
+## 5. `isolated: true`
+
+Use `isolated: true` on steps that call slow external services (LLM, third-party API) so each
+step runs as its own job execution and no single run holds a worker for minutes. Not needed for
+steps that touch only the database. Isolation costs one re-enqueue per step.
+
+## 6. When not to use AJ/DC
+
+- Fan-out and fan-in (one step that spawns N jobs and waits for all). Use Solid Queue batches
+  (1.7+), GoodJob batches, or Sidekiq Pro; AJ/DC has no batch primitive yet. A `Durable` run may
+  start the batch and `await` the batch's `on_finish` job as a signal.
+- Replay-based determinism or exactly-once semantics. Steps are at-least-once; a completed step
+  is skipped on resume. Make step bodies idempotent (upserts, `find_or_create_by`, guards on a
+  fact column).
+- Sub-minute timers. The clock ticks with the scheduler.

data/skills/ajdc/references/installation.md

@@ -0,0 +1,98 @@
+# Installing AJ/DC
+
+## 1. The gem
+
+```sh
+bundle add ajdc
+```
+
+Requirements: Ruby 3.3+, Rails 8.1+ (`attribute` on jobs needs Rails 8.2), SQLite, PostgreSQL or
+MySQL, and a queue adapter with a scheduler for the recurring wake job (Solid Queue recurring
+tasks, sidekiq-cron, GoodJob cron).
+
+## 2. The tables: one database or two
+
+AJ/DC writes two tables, `active_job_durable_runs` and `active_job_durable_steps`. Decide
+where they live before generating anything.
+
+| | Primary database (default) | Separate database |
+|---|---|---|
+| Command | `bin/rails generate ajdc:install` then `db:migrate` | `bin/rails generate ajdc:install --database=NAME` then `db:prepare` |
+| Files | one migration in `db/migrate` | one migration in `db/NAME_migrate`, plus `config/initializers/active_job_durable.rb` |
+| `perform_later` inside a transaction | the run row commits with the record that starts it; a rollback removes both | two databases, two transactions: a rollback of the record can leave an `enqueued` run |
+| `unique_by` conflicts | decided in the caller's transaction | decided in the durable database's transaction |
+| Choose it when | the default; any app where runs start from model callbacks or `with_lock` blocks | the app already keeps `solid_queue`, `solid_cache` in their own databases and wants run rows off the primary; or the primary is not writable from workers |
+
+Recommendation: the primary database unless there is a stated reason. The transaction property
+in `transactions.md` §1 depends on it.
+
+### Primary database
+
+```sh
+bin/rails generate ajdc:install
+bin/rails db:migrate
+```
+
+### Separate database
+
+1. Declare the database in `config/database.yml` with its own `migrations_paths`:
+
+   ```yaml
+   production:
+     primary:
+       <<: *default
+     durable:
+       <<: *default
+       database: storage/production_durable.sqlite3     # or the adapter's settings
+       migrations_paths: db/durable_migrate
+   ```
+
+   Repeat for `development` and `test`.
+
+2. Generate with the database name; the migration lands in that path and the initializer is
+   written:
+
+   ```sh
+   bin/rails generate ajdc:install --database=durable
+   bin/rails db:prepare
+   ```
+
+   ```ruby
+   # config/initializers/active_job_durable.rb (generated)
+   ActiveJob::Durable.connects_to = { database: { writing: :durable } }
+   ```
+
+3. In step bodies that start a run from inside a model transaction, guard the first step
+   against a record that was rolled back (`return unless record.persisted?`), since the run
+   row can exist without it.
+
+## 3. The clock
+
+Timers and signal deadlines are woken by one recurring job. Without it, nothing that waits ever
+wakes. Add it to the app's scheduler once:
+
+```yaml
+# config/recurring.yml (Solid Queue)
+durable_wake:
+  class: ActiveJob::Durable::WakeJob
+  schedule: every minute
+```
+
+sidekiq-cron, GoodJob cron and others: schedule `ActiveJob::Durable::WakeJob.perform_later`
+every minute. The interval is the precision of every `wait:`, `wait_until:` and `await`
+deadline.
+
+## 4. Verify
+
+```sh
+bin/rails runner 'puts ActiveJob::Durable::Run.count'        # 0, no error
+bin/rails runner 'puts ActiveJob::Durable.wake_up_due'       # 0, no error
+```
+
+Then convert one job: `include ActiveJob::Durable` in place of `ActiveJob::Continuable`, run
+its tests, enqueue it once, and read `MyJob.workflow_runs.last`.
+
+## 5. Mission Control
+
+If `mission_control-jobs` is mounted, the runs are plain Active Record rows next to the jobs;
+`ActiveJob::Durable::Run` has no UI of its own yet.

data/skills/ajdc/references/testing.md

@@ -0,0 +1,152 @@
+# Testing durable workflows
+
+## 1. Setup
+
+```ruby
+class ImportJobTest < ActiveSupport::TestCase
+  include ActiveJob::TestHelper                      # perform_enqueued_jobs, assert_enqueued_jobs
+  include ActiveJob::Continuation::TestHelper        # interrupt_job_during_step / after_step (Rails 8.1)
+
+end
+```
+
+- Queue adapter `:test`. Use the block form, `perform_enqueued_jobs do ... end`: it performs
+  every job enqueued inside the block, including the re-enqueues at isolated steps, interrupts
+  and resumes, so a durable run executes until it parks, halts, fails or completes. Do not count
+  executions.
+- Freeze time with `travel_to`; timers compare `wake_at` with `Time.current`.
+- Each test starts from an empty runs table (`Run.delete_all` in setup if fixtures are not
+  transactional for the durable database).
+
+## 2. Drive a run to its next park
+
+```ruby
+perform_enqueued_jobs { ImportJob.perform_later(import) }   # runs through every step and re-enqueue
+
+run = ImportJob.workflow_runs.for(import).sole
+assert_equal "completed", run.status
+assert_equal %w[check process], run.completed_steps
+assert_equal "imported", import.reload.state                 # the logic, first of all
+```
+
+Assert the outcome on your models, then the run's `status` and `completed_steps`. Do not
+assert what happens between executions; that is the gem's business.
+
+## 3. Crash and resume (the SIGKILL test)
+
+Make a step fail once after progress, then assert the cursor and the resume:
+
+```ruby
+stub_import_to_fail_on("c")                    # your own stub, once
+perform_enqueued_jobs { ImportJob.perform_later(import, %w[a b c d e]) }
+
+run = ImportJob.workflow_runs.for(import).sole
+assert_equal "failed", run.status
+assert_equal %w[a b], import.reload.imported_items
+
+perform_enqueued_jobs { run.resume! }
+assert_equal %w[a b c d e], import.reload.imported_items     # c, d, e once; a, b not twice
+assert_equal "completed", run.reload.status
+```
+
+Graceful interrupt (deploy), Rails' own helper:
+
+```ruby
+perform_enqueued_jobs do
+  interrupt_job_during_step(ImportJob, :process, cursor: 2) { ImportJob.perform_later(import, items) }
+end
+assert_equal items, import.reload.imported_items             # nothing lost, nothing doubled
+```
+
+## 4. Halt and resume
+
+```ruby
+perform_enqueued_jobs { ImportJob.perform_later(import) }
+run = ImportJob.workflow_runs.for(import).sole
+assert_equal "halted", run.status
+assert_equal "InsufficientStorageError", run.error_class      # halt_on
+# or: assert_equal "tool_approval", run.halt_reason           # halt!
+
+fix_the_world
+perform_enqueued_jobs { run.resume! }
+assert_equal "completed", run.reload.status
+```
+
+## 5. Timers
+
+```ruby
+travel_to now do
+  perform_enqueued_jobs { License::LifecycleJob.perform_later(license) }   # reaches :remind, parks
+  run = License::LifecycleJob.workflow_runs.for(license).sole
+  assert_equal "waiting", run.status
+  assert_equal license.expires_at - 2.weeks, run.wake_at
+  assert_no_enqueued_emails
+end
+
+travel_to license.expires_at - 2.weeks do
+  perform_enqueued_jobs { ActiveJob::Durable.wake_up_due }                 # the clock, then :remind runs, parks at :expire
+  assert_enqueued_email_with LicenseMailer, :expiring_two_weeks, args: [license]
+end
+```
+
+Test what the step did, then where the run parked next. Test re-arming: move the date, tick
+the clock, assert the reminder did not go out. Test `wake_up` with no name: the step runs now.
+Wake with `ActiveJob::Durable.wake_up_due` inside `travel_to`; do not assert how many runs it
+woke or call the wake job directly.
+
+## 6. Signals
+
+```ruby
+perform_enqueued_jobs { BulkImportJob.perform_later(import) }   # parks at :confirmation
+run = import.job_run
+assert_equal "awaiting", run.status
+
+perform_enqueued_jobs { run.wake_up(:confirmation, true) }
+assert_equal "applied", import.reload.state
+```
+
+Also test the deadline: `travel_to` past it, `perform_enqueued_jobs { ActiveJob::Durable.wake_up_due }`,
+the import is destroyed. And the early signal: `wake_up` before the first execution, then the run
+completes without parking. Assert on the model; the run's `status` is the second assertion.
+
+## 7. Uniqueness
+
+```ruby
+assert ImportJob.perform_later(import)
+assert_equal false, ImportJob.perform_later(import)          # :skip
+assert_equal 1, Run.count
+```
+
+`:reject`: `assert_raises(ActiveJob::Durable::RunAlreadyExists)`. `:replace`: the first run is
+`cancelled`, the second is `enqueued`, `Run.count == 2`. After `cancel!` or completion, a new
+`perform_later` creates a new run.
+
+## 8. Transactions
+
+```ruby
+Account.transaction do
+  account.cancel                                   # creates the cancellation, perform_later inside with_lock
+  assert_enqueued_jobs 0                           # not yet: enqueue waits for commit
+  assert_equal 1, Run.count                        # the row is already there
+end
+assert_enqueued_jobs 1
+
+Account.transaction do
+  account.cancel
+  raise ActiveRecord::Rollback
+end
+assert_equal 0, Run.count
+assert_enqueued_jobs 0
+```
+
+## 9. Cancel
+
+Cancel a run, then perform: the model is untouched and the run is `cancelled`. Cooperative cancel
+of a running step is the gem's feature; do not test it in the app.
+
+## 10. What not to test
+
+Test logic, not the gem. Do not assert on `parked_job`, `pending_signals`, `resumptions`, step
+row attempts, cursors, the number of executions, or how many runs the clock woke. Assert on your
+models first, then on `status`, `current_step`, `completed_steps`, `state`, `wake_at`,
+`halt_reason` and `error_class` when the test is about them.