Run Lifecycle
Stable run states, replay events, sources, and actor types.
Run lifecycle vocabulary appears in durable run records and append-only run events. Storage, operator tools, and dashboards can branch on these values.
RunStatus
| Enum | Value | Meaning |
|---|---|---|
RunStatus.CancellationRequested | cancellation_requested | Cancellation was requested for a leased running run; the owner may stop cooperatively, and maintenance can finalize after lease expiry. |
RunStatus.Cancelled | cancelled | Terminal cancellation outcome. |
RunStatus.Failed | failed | Terminal failure outcome after retry budget is exhausted, retry is not allowed, or a cancellation-requested attempt fails. |
RunStatus.Queued | queued | Waiting for worker acquisition or dispatch; runnable when runAt ?? updatedAt is due and queue capacity or an existing dispatch reservation allows it. |
RunStatus.Released | released | Business waiting; runnable again when runAt is due. |
RunStatus.Retrying | retrying | Failure-driven retry; runnable again when runAt is due. |
RunStatus.Running | running | A worker owns an active lease; the attempt is about to start or is executing. |
RunStatus.Scheduled | scheduled | Delivery has been requested for a future runAt. |
RunStatus.Succeeded | succeeded | Terminal success outcome. |
RunStatusClassification
| Enum | Value | Meaning |
|---|---|---|
RunStatusClassification.Active | active | The run can still move through lifecycle transitions. |
RunStatusClassification.Terminal | terminal | The run does not reactivate; rerun and manual retry create linked child runs. |
Use runStatusValues.isActive() and runStatusValues.isTerminal() instead of duplicating classification lists.
Status classification is broader than worker eligibility. cancellation_requested is active because it can still move to cancelled or failed, but it is not a runnable candidate. Terminal runs never accept more lifecycle events; rerun and manual retry create linked child runs instead.
Scan candidate status groups
Storage scans use narrower status groups than active/terminal classification. These groups are status-only gates; time and lease eligibility still come from getRunRunnableAvailableAt(), getRunDeliveryRecoveryAvailableAt(), and getRunCancellationFinalizationAvailableAt().
| Group | Values | Meaning |
|---|---|---|
runStatusValues.runnableCandidates | queued, released, retrying, running, scheduled | Statuses that listRunnableRuns() may return when the run is due or its lease has expired. |
runStatusValues.deliveryRecoveryCandidates | released, retrying, running, scheduled | Statuses that listRunsNeedingDelivery() may return when maintenance needs to append a fresh delivery request. |
runStatusValues.cancellationFinalizationCandidates | cancellation_requested | Statuses that listRunsNeedingCancellationFinalization() may return after the current lease expires. |
queued is excluded from delivery recovery candidates because it already has durable delivery intent and outbox state.
Use the matching predicates, such as runStatusValues.isDeliveryRecoveryCandidate(), instead of duplicating status switches in adapters.
Dispatch Reservation Predicate
Bounded queues reserve capacity before publishing a delivery wakeup. Use this helper anywhere storage code needs to reason about that reservation window.
| Helper | Condition | Meaning |
|---|---|---|
isRunDispatchReservation({ run, at, condition: RunDispatchReservationCondition.Active }) | active | The queued run still owns a dispatch slot at at. |
isRunDispatchReservation({ run, at, condition: RunDispatchReservationCondition.Expired }) | expired | The queued run had a dispatch slot, but it expired at or before at. |
RunCounters
RunRecord.counters is materialized from replayed events. It is durable run state, not a derived dashboard-only summary.
| Field | Incremented by | Meaning |
|---|---|---|
attempts | run.started | Count of started execution attempts. |
failures | run.failed, run.retry_scheduled | Failure pressure recorded for terminal failures and retry-scheduled failures. |
releases | run.released | Business waits that did not count as failure pressure. |
retries | run.retry_scheduled | Failed attempts that scheduled another try. |
run.succeeded and run.cancelled do not increment counters by themselves. They close an existing attempt or, for waiting-run cancellation, finish a run that may have no attempts.
RunAttemptStatus
RunAttemptStatus appears in runlane.runs.attempts(runId) summaries. It is derived from replayed run events; it is not stored as a separate durable run field.
| Enum | Value | Meaning |
|---|---|---|
RunAttemptStatus.Cancelled | cancelled | The attempt ended after cooperative cancellation. |
RunAttemptStatus.Failed | failed | The attempt failed without scheduling another try. |
RunAttemptStatus.Released | released | The attempt released the run to resume later. |
RunAttemptStatus.Retrying | retrying | The attempt failed and scheduled another try. |
RunAttemptStatus.Running | running | The attempt has started and has no terminal attempt event yet. |
RunAttemptStatus.Succeeded | succeeded | The attempt completed successfully. |
Only run.started creates an attempt summary. A later run.cancelled marks the latest still-running attempt as cancelled; cancelling queued, released, retrying, or scheduled work without a started attempt does not create an attempt row.
RunEventType
| Enum | Value | Meaning |
|---|---|---|
RunEventType.CancellationRequested | run.cancellation_requested | Operator or system requested cooperative cancellation of a leased running run. |
RunEventType.Cancelled | run.cancelled | Waiting work, a cancellation-requested run, or the latest running attempt completed with terminal cancellation. |
RunEventType.Created | run.created | First durable event for a run. |
RunEventType.DeliveryRequested | run.delivery_requested | Runtime recorded durable wakeup intent and storage creates the matching outbox row. |
RunEventType.Failed | run.failed | Current started attempt ended in terminal failure. |
RunEventType.LeaseClaimed | run.lease_claimed | Worker or inline execution claimed ownership for execution. |
RunEventType.LeaseHeartbeat | run.lease_heartbeat | Worker extended the current lease with the same worker id and token. |
RunEventType.Released | run.released | Attempt chose business waiting without counting a failure. |
RunEventType.RetryScheduled | run.retry_scheduled | Current started attempt failed and scheduled another try. |
RunEventType.Started | run.started | Execution attempt started. |
RunEventType.Succeeded | run.succeeded | Attempt completed successfully. |
RunSourceType
| Enum | Value | Meaning |
|---|---|---|
RunSourceType.ManualRetry | manual_retry | Operator-created child retry linked to a failed source run. |
RunSourceType.Rerun | rerun | Operator-created child rerun linked to a terminal source run. |
RunSourceType.Schedule | schedule | Schedule materialization created the run. |
RunSourceType.Trigger | trigger | Application trigger created the run. |
TriggerOutcomeType
TriggerOutcomeType appears in TriggerRunResult from runlane.trigger(). It describes the result of the trigger call, not the run lifecycle status.
| Enum | Value | Meaning |
|---|---|---|
TriggerOutcomeType.Created | created | The trigger call persisted a new run. |
TriggerOutcomeType.ReturnedExisting | returned_existing | Idempotency returned the active or retained run already owning the selected key. |
ActorType
| Enum | Value | Meaning |
|---|---|---|
ActorType.Operator | operator | Human or operator action. |
ActorType.Schedule | schedule | Schedule materializer action. |
ActorType.System | system | Framework/system action. |
ActorType.Worker | worker | Worker execution action. |
contractDefaults.actor.system and contractDefaults.actor.operator provide the canonical actor records for framework and operator actions that do not carry a more specific actor id.