Durable work#

Use a job for bounded background work and a workflow when coordination must survive process loss, long waits, retries, upgrades, or human decisions.

Keep decisions deterministic#

A workflow reads its event history and emits commands. It does not read the wall clock, network, filesystem, secrets, or random source directly. Those inputs arrive as recorded values through owned operations.

Replay validates that the current implementation emits a compatible command sequence for the retained history. It never redelivers external effects.

Put effects in activities#

Activities own deadlines, retry budgets, idempotency, deduplication, heartbeats, cancellation, fencing, and outcome reconciliation. The workflow sees an exact terminal or suspended result, including outcome unknown.

Retries are safe only within the activity's declared effect semantics. For an external action without idempotency or outcome lookup, a human or compensating path may be the only honest continuation.

Model every kind of wait#

Timers use an owned time contract. Signals deliver asynchronous intent. Queries observe workflow state without changing it. Updates request a validated state transition. Human tasks name assignment, delegation, expiry, escalation, and approval evidence.

Children retain ownership and cancellation relationships. Parent completion does not silently abandon durable child work.

Human tasks and approvals#

A human task is a durable typed wait, not a chat message. It names assignment and candidate groups, delegation, expiry, escalation, and the exact approval evidence it requires. The human decision arrives as a recorded event, so the workflow replays it deterministically instead of reading a live inbox.

Approvals bind the actual action, subject, scope, disclosure, provider, cost, expiry, and blast radius. Approving a summary never authorizes later different arguments: an edited amount, target, or parameter is a new proposal requiring a fresh grant. Rejection, expiry, and reassignment are first-class dispositions that complete or resume the same workflow instance.

Budget, capacity, and cancellation#

Workflows and activities carry explicit budgets: elapsed time, attempts, child tasks, effects, tokens, bytes, and monetary cost. Exhaustion is its own disposition rather than a generic failure, so a run can suspend for approval, hand off, or return bounded partial results with the exact consumed amounts.

Concurrency groups and singletons bound how many instances of the same key may coordinate at once. When a durable queue is full, the contract chooses backpressure, shedding, or spill; unbounded buffering is never a hidden default. Cancellation propagates through the instance, and each activity declares whether it can stop before dispatch, interrupt, drain, or only stop waiting. Dropping a future is not rollback after an effect may have crossed the boundary.

Evolve running workflows#

New code must remain replay-compatible with histories it can receive. Version markers, patch decisions, or explicit migration workflows establish the path. Planning identifies the deployed worker artifacts and the history ranges they can serve.

When a workflow revision cannot interpret a history, the system reports an exact incompatibility. It does not restart from current state or skip unknown events.

Inspecting a running workflow#

Queries observe instance state without changing it, while the durable history records decisions, activity attempts, timers, signals, human decisions, and external receipts. Inspect by exact instance or operation reference rather than by a screen or log line, and keep One's causal facts separate from linked external engine events.

Replay reproduces deterministic decisions within stated limits and never redelivers external effects; a missing observation window stays explicit. If a provider outcome is unknown, observe it before retrying, and resume the same operation instead of reconstructing authority from a transcript. See observability and history and recovery and continuity.

Choose the engine as a provider#

An embedded runtime, native durable engine, or external workflow service can realize the same bounded workflow contract. The provider profile states history durability, scheduling, timer, lease, replay, retention, encryption, multi-tenancy, recovery, and observation guarantees.

External engine events remain external references linked to One's causal facts; they do not become One facts or prove that downstream effects occurred.

Example#

Illustrative workflow code never retries an uncertain mutation blindly:

match create_shipment.await {
    Completed(shipment) => finish(shipment),
    OutcomeUnknown(effect) => reconcile(effect).await,
    Rejected(fault) => compensate(fault).await,
}

Executable evidence#

The checked-in support-triage project owns the durable coordination, deterministic decisions, exact activity outcomes, and idempotent resume used by the durable workflow recipe:

cargo test -p support-triage-agent --all-targets --offline
one check --workspace systems/system/idl/examples/support/triage/agent --offline

Measured budget and throughput claims belong to benchmark and performance evidence, not to this recipe.

See workflows and agents and observability and history, then follow the durable workflow recipe.