Runs and History
A workflow run is one execution of a version-pinned definition. The runtime does not keep a live Dart future or persisted stack.
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- operation scheduled / completed / failed
- work requested / responded / expired
- event 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 |
|---|---|
| operation | a leased worker |
| work | an assigned actor |
| event | an external sender |
| 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. Events, 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
Query exposes a read-only snapshot from current bindings. A query cannot append history, schedule work, or consume runtime IDs.