Developer docs · Private synthetic preview
Correct before release.
A held order is reviewed as a controlled local workflow. Each change is tied to the revision it was based on, so stale work cannot silently replace newer truth.
Availability. This describes a private, authenticated synthetic workflow. It does not book a shipment, create a label, contact a carrier, write back to a storefront, or notify a customer.
State model
| Stage | Entry condition | Evidence to retain | Safe transition |
|---|---|---|---|
| Intake | A typed synthetic or approved redacted record is accepted. | Stable source identity and immutable creation input. | Create one canonical held record. |
| Held | The workflow cannot safely continue. | Named reason, current revision, and responsible role. | Open a correction against the current revision. |
| In correction | An authorised operator starts bounded review. | Before-and-after field values and actor context. | Run deterministic validation. |
| Ready to release | Current validation passes and required local approvals are present. | Validation attempt, policy context, and approval evidence. | Record the local release operation. |
| Released locally | The local operation, audit event, and outbox intent are recorded. | Operation identity, request identity, and exact evidence binding. | Future provider work remains a separate boundary. |
Revision and concurrency rules
- Read the current revision before presenting editable fields.
- Bind a proposed correction and validation attempt to that revision.
- Reject a write when the canonical revision has changed.
- Reload and present the new difference instead of merging silently.
- Never force an overwrite to make a queue appear clear.
Failure handling
| Failure | Meaning | Response |
|---|---|---|
| Validation failed | The proposed record does not satisfy deterministic checks. | Keep the order held and show actionable check evidence. |
| Revision conflict | Another accepted change superseded the reviewed input. | Reload, compare, and require re-review. |
| Approval missing | The local release gate is incomplete. | Keep the state ready but unreleased. |
| Outcome unknown | A future external action cannot be proven successful or failed. | Stop automatic retry and reconcile by operation identity. |
Related guidance
Read validation and evidence for revision-bound checks, rules and approvals for authority separation, and reliability for replay and unknown-outcome handling.