Concepts
The mental model behind the engine. Replay is the durability mechanism, workflows orchestrate while steps do the work, a run can wait for months without holding a process, and every run belongs to a namespace that decides who drives it.
Four ideas carry the whole engine. Everything else in these docs follows from one of them.
Durability & replay
Checkpoint-and-replay makes a run survive crashes, and imposes one rule: the workflow body must be deterministic.
Workflows & steps
engine.register and BaseWorkflow, dispatched ctx.step vs in-process ctx.localStep, retries, fan-out and fatal errors.
Sleep & signals
ctx.sleep, ctx.waitForSignal and ctx.waitForEvent: durable waits that use no compute and survive restarts.
Tenancy
The two isolation axes, namespace on the engine and partition on the transport, and what each one partitions.
Durability is replay
A run survives a crash because the engine replays the workflow body from the top and gives steps that already completed their saved results instead of running them again. That one mechanism is what provides crash recovery, and it imposes one rule: the body must be deterministic. No Date.now(), Math.random(), or direct I/O outside a step. See Durability & replay.
Workflows orchestrate, steps do
A workflow decides what happens next. A step is the only place a side effect may happen. ctx.step dispatches a named handler over the configured transport, checkpoints it, retries it on its own policy, and returns the recorded result on the next replay. ctx.localStep runs a closure in-process when no worker boundary is needed. Fan-out, child workflows and entities all build on these. See Workflows & steps.
Waiting costs nothing
A run parked on ctx.sleep, ctx.waitForSignal or ctx.waitForEvent holds no process, thread or connection. Its state is a row and a wake time, and the engine resumes it when the timer comes due or the signal or event arrives. While parked, a month-long wait costs the same as a one-second wait. See Sleep & signals, and Events for name-based pub/sub.
Runs belong to someone
Every run is stamped with a namespace, and that stamp decides which pool drives it and which workers execute its steps. This is what lets one store and one broker host several worker pools without any of them taking another's work. See Tenancy, and Cluster for the deployment shapes built on it.
Comparison
How @adonis-agora/durable compares to plain @adonisjs/queue jobs, Temporal, Inngest, and BullMQ — what the suspend-model library approach buys you, and when a dedicated orchestration cluster or a managed platform is the better call.
Durability & replay
How checkpoint-and-replay makes a workflow survive crashes — and the one rule it imposes. The workflow body must be deterministic; all side effects live in steps.