Proposed run states
The states below form the reference design used across the documentation. Your implementation may choose different names or additional states when its actual business requirements justify them. Do not copy a state without defining who can enter it and what evidence must exist.
| State | Meaning in this reference | Next transition |
|---|---|---|
queued |
Intent is durably accepted; processing has not begun. | running, failed, or canceled |
running |
One or more accepted items are being processed. | awaiting_review, succeeded, failed, or canceled |
awaiting_review |
An authorized decision is required before proceeding. | running, failed, or canceled |
succeeded |
The manifest's acceptance and delivery rules are satisfied. | Terminal; revised work creates a new run. |
failed |
The run cannot complete under its accepted policy. | Terminal; a repair can create a linked run. |
canceled |
Remaining work is stopped under the cancellation contract. | Terminal; preserve completed effects as history. |
Business state is not worker state
A package awaiting approval can be healthy even while no worker is active. A notification worker retry does not necessarily change the package's business state. Keep these concepts distinct so an operator can identify the actual owner of a delay.
The reference's awaiting_review state stores the exact input version and required decision rather than keeping a long-running worker asleep. If the input changes, the business policy must decide whether an earlier approval remains applicable. Never silently attach an old decision to a materially changed package.
Record transitions durably
Each transition should identify the run, previous state, new state, responsible actor or service, reason, and time. Use persistence and concurrency controls appropriate to the chosen architecture so competing workers cannot create contradictory accepted transitions.
A status endpoint should report accepted state, not whichever value a particular worker currently holds in memory. Keep detailed attempt history in related records while returning a bounded summary to ordinary status readers.
Make partial results explicit
A failed or canceled run may have produced useful artifacts. Preserve those item-level outcomes without claiming that the whole delivery succeeded. Whether a consumer may use them is a business acceptance decision, not a consequence of the files existing.
The example input manifest sets partial_delivery to false. Therefore, every required item must satisfy the acceptance rule before the run is declared succeeded. A different workflow can allow partial delivery, but it needs to state how incomplete items are communicated and repaired.
Cancellation cannot erase history
Define the point at which cancellation stops new work and what happens to requests already in flight. A downstream operation may have been accepted before the cancellation reached it. Reconcile that outcome rather than assuming the cancel request rolled back every effect.
Some business effects need a compensating process, such as a separate reversal request, rather than a technical retry or state edit. Keep that process visible and separately authorized. Do not make a cancel button promise behavior that the destination does not support.
Recovery preserves the accepted record
In this reference, terminal runs are not rewritten into a different historical outcome. A correction or operator-authorized repair creates a linked run with the corrected inputs or configuration. The original result remains available according to retention policy.
Temporary item retries can occur before the run becomes terminal, within its accepted attempt and deadline policy. See the webhook reliability playbook for repeated delivery and the batch manifest reference for item-level reconciliation.