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.
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.
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,
}
See workflows and agents and observability and history, then follow the durable workflow recipe.