--- id: STATE-COM-FUL-001 title: Obligation lifecycle object: DOM-COM-FUL-001 product_area: commerce module: fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b states: - name: pending meaning: >- The record is retained but still awaits the conditions or action needed to proceed. - name: blocked meaning: Delivery requires staff action before its waiting gate can open. - name: eligible meaning: >- The gate has met its conditions and proceeds to authorization in the same transaction. - name: authorized meaning: >- A current authorization and dispatch entry permit the application to begin delivery. - name: in_progress meaning: >- Work has begun or a partial result is retained while completion remains outstanding. - name: completed meaning: The owning process has retained the required completed outcome. - name: failed meaning: >- Work stopped after refusal, exhaustion or lost acknowledgement and needs recovery or closure. - name: cancelled meaning: >- The owning process withdrew the work under its permitted cancellation checks. - name: resolved meaning: Staff retained closure and the result rather than executing further work. - name: superseded meaning: A later delivery replaces the earlier completed obligation. transitions: - from: pending to: eligible trigger: Current facts satisfy the gate or staff explicitly override it. guard: The conditional opening must still find a waiting obligation. side_effects: - The opening transaction immediately retains authorization. who: Register evaluator or an administrator (override) provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:openGate - from: blocked to: eligible trigger: Current facts satisfy the gate or staff explicitly override it. guard: The block must be cleared or an authorized override must apply. side_effects: - The opening transaction immediately retains authorization. who: Register evaluator or an administrator (override) provenance: observed source: 'services-commerce:modules/fulfillment/services/register/gate-evaluation.ts' - from: eligible to: authorized trigger: The register issues the retained authorization. guard: The preceding gate opening supplies the authorization guard. side_effects: - >- Allocate the next authorization sequence and set its acknowledgement deadline. - Insert dispatch work for the newly issued authorization. - Append the gate-opening fact to order history. - Attempt the dispatch nudge after the authorization commit. who: Register evaluator provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:openGate - from: pending to: blocked trigger: Evaluation or staff action records a blocking condition. guard: >- The verdict requires staff attention, or hold placement finds a waiting record. side_effects: - >- Save the eligibility result, evaluated facts and explanation of any block. - Append the newly established blocking fact once. who: 'Register evaluator, or an administrator placing a hold' provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:recordGateEvaluation,placeStaffHold - from: pending to: cancelled trigger: The owning process withdraws work before departure or delivery permits it. guard: Delivery must still be waiting. side_effects: - Release eligible claims in the owning cancellation transaction. who: Orders (void or cancellation) provenance: documented source: 'services-commerce:docs/migrations/obligation-register/README.md#D-P4-03' - from: blocked to: cancelled trigger: The owning process withdraws work before departure or delivery permits it. guard: Cancellation must occur before delivery authorization. side_effects: [] who: Orders (cancellation) provenance: documented source: 'services-commerce:docs/migrations/obligation-register/README.md#D-P4-03' - from: eligible to: cancelled trigger: The owning process withdraws work before departure or delivery permits it. guard: >- This edge is permitted by persistence; opening ordinarily authorizes in the same transaction. side_effects: [] who: Orders provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:OBLIGATION_TRANSITIONS - from: authorized to: in_progress trigger: The application or financial worker records continuing work. guard: The application answer must identify the current authorization. side_effects: - Renew the retained acknowledgement expiry. - Update the retained total of completed units. - Append the immutable application attempt. who: Delivering application (worker answer or callback) provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:recordObligationOutcome - from: authorized to: completed trigger: The owning workflow retains its required final successful result. guard: >- The current authorization must report the whole owed quantity or staff must attest it. side_effects: - Store the references returned by the delivering application. - Append delivery completion to the order’s history. - Invoke same-order dependency continuation after outcome retention. who: Delivering application or an administrator (manual completion) provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:recordObligationOutcome,completeObligationManually - from: in_progress to: completed trigger: The owning workflow retains its required final successful result. guard: The current answer must bring completed units to the owed quantity. side_effects: - Close the current authorization with successful completion. - Invoke dependent settlement after the retained outcome. who: 'Delivering application, Shipping handoff or an administrator' provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#completes every unit’s obligation through the register (the allocation as the record), and emits one deferred cost relief fact per item - from: authorized to: failed trigger: >- A permanent refusal, exhausted retry budget or acknowledgement policy stops the work. guard: Failure must apply to the current in-flight authorization. side_effects: - >- Raise the diagnosis appropriate to failure, exhausted attempts or missing acknowledgement. - Append the delivery failure fact to order history. - Attempt to move the associated enforcement to failure. who: Register worker or register sweep provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/register/obligation-worker.integration.spec.js#fails the obligation with the participant’s code, raises obligation_failed, and acknowledges the item - from: in_progress to: failed trigger: >- A permanent refusal, exhausted retry budget or acknowledgement policy stops the work. guard: The failure or expiry must apply to the current authorization. side_effects: - Raise the attention finding required by this workflow. - Block same-order dependents after a permanent prerequisite outcome. who: Delivering application or register sweep provenance: observed source: >- services-commerce:modules/fulfillment/services/register/register-sweeper.ts:sweepRegister - from: failed to: authorized trigger: The register issues the retained authorization. guard: Staff re-authorization must find a failed obligation. side_effects: - >- Issue another authorization and retain its link to the preceding instruction. - Insert dispatch work for the newly issued authorization. - 'Record the staff action, responsible person and stated reason.' who: Administrator with re-authorize permission provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#re-authorizes the failed obligation at sequence two, which the participant fails again, then resolves it with its exceptions - from: failed to: resolved trigger: Staff retain a closure result under the specific intervention authority. guard: Staff closure must find a failed obligation. side_effects: - Close standing exceptions referring to this subject. - Invoke failed-prerequisite blocking after the retained outcome. - 'Record the staff action, responsible person and stated reason.' who: Administrator with resolve permission provenance: observed source: >- services-commerce:modules/fulfillment/services/register/obligation-interventions.ts:resolveObligationByStaff - from: completed to: superseded trigger: Replacement work supersedes a completed delivery. guard: Supersession must find an already completed obligation. side_effects: [] who: Orders (amendment settlement) provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:OBLIGATION_TRANSITIONS invalid: - from: blocked to: pending why: >- A waiting block remains until gate opening; releasing a hold does not restore pending. - from: completed to: failed why: >- Completion remains final for this action; use the owning replacement or correction process. - from: failed to: completed why: >- Failed work needs its permitted retry or staff closure before another outcome can apply. - from: authorized to: cancelled why: >- In-flight work cannot be cancelled directly; use the separate cancellation instruction. - from: cancelled to: authorized why: Cancelled work cannot be restarted through this lifecycle. concurrency: >- Obligation writes lock the record and apply conditional authorization or outcome checks. Database transition enforcement protects every writer; later workflow records can still fail independently. invariants: - INV-DOM-COM-FUL-001-02 - INV-DOM-COM-FUL-001-03 - INV-DOM-COM-FUL-001-05 - INV-DOM-COM-FUL-001-06 - INV-DOM-COM-FUL-001-09 evidence: - >- services-commerce at c8b66a98: modules/fulfillment/services/persistence/obligations.ts; services/register/*.ts; db/migrations/20261018004016_obligation_register.sql; docs/migrations/obligation-register/README.md; docs/migrations/operations/README.md (D-P5-11, D-P5-12). --- # Obligation Lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> pending: order placement pending --> blocked: staff action required pending --> eligible: conditions satisfied or overridden blocked --> eligible: condition cleared or overridden eligible --> authorized: same transaction pending --> cancelled blocked --> cancelled eligible --> cancelled authorized --> in_progress authorized --> completed authorized --> failed in_progress --> completed in_progress --> failed failed --> authorized: issue another authorization failed --> resolved: staff closure completed --> superseded cancelled --> [*] resolved --> [*] superseded --> [*] ``` ## Transitions Explained An obligation begins with frozen delivery conditions. A waiting gate can block or open; opening passes through eligibility and authorization in one transaction. Application outcomes retain partial progress or finish delivery, and staff recover a failure with a fresh authorization or a recorded resolution. ## What Cannot Happen Persistence and database guards prevent regression and preserve terminal cancellation, resolution and supersession. The eligible cancellation edge is permitted by the transition table, but normal gate opening does not expose an intervening request opportunity. ## Concurrency and Timing Financial events and staff actions can evaluate waiting gates. The sweep examines bounded pending and overdue pages, excludes blocked obligations and cannot promise a recovery deadline. Physical units retain the same acknowledgement expiry policy as other delivery work.