# 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.

## 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:

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

See [workflows and agents](/one/model/workflows-and-agents) and
[observability and history](/one/platform/observability-history), then follow
the [durable workflow recipe](/one/examples/durable-workflow).