Workflow model

Workflows and runs

A workflow is a versioned definition of work. A run is one execution of that definition with a specific input. Every run records its workflow version so past results remain explainable after you deploy changes.

Steps

Steps are named units of work. A completed step can be resumed without repeating earlier work, so names should describe an outcome rather than an implementation detail.

const customer = await step('load-customer', () => crm.customers.get(input.id));

Inputs and outputs

Treat inputs and outputs as stable contracts. Validate at the workflow boundary and return serializable values. Large binary data should live in object storage and be passed by reference.

Failure and retry

Transient failures use bounded retries with backoff. Permanent failures stop the run and retain the completed timeline. Configure retry behavior on the smallest safe step.

Idempotency

For actions with external effects, pass an idempotency key based on the run and step identifiers. This prevents a retry from creating duplicate records or charges.