Runs and History
A workflow run is one execution of a version-pinned definition. The graph engine called this an instance. The durable runtime does not keep tokens or a live Dart future.
What a Run Stores
- workflow
code,version, and digest; - status:
running,blocked,completed,failed,cancelled, orcontinuedAsNew; - optimistic
revision; - input, terminal output or error;
- tenant, application, subject, starter, and idempotency key.
Progress is the immutable history plus the current command projection.
History
workflow_events is append-only and ordered by (run_id, sequence):
workflowStarted- activity scheduled / completed / failed
- user task created / completed / expired
- signal received
- timer fired
- cancellation, retry, redrive
- workflow completed / failed / continued as new
Replay reads this sequence. Events are never edited in place. Retention archives a complete history as a unit.
Commands
Commands are obligations, not facts:
| Type | Waits for |
|---|---|
| activity | a leased worker |
| user task | an assigned actor |
| signal | an external message |
| timer | durable time |
| workflow spawn | a child run |
Statuses are pending, claimed, completed, failed, or cancelled. Unique (run_id, operation_key, attempt) prevents duplicate emission during replay.
Continue as New
Long histories close the parent and create exactly one successor in the same transaction. Signals, cancel, redrive, and queries sent to an older run ID resolve the active generation. History reads stay generation-specific so audit evidence is never silently merged.
Queries
Workflow.query exposes a read-only snapshot from current bindings. A query cannot append history, schedule work, or consume runtime IDs.