--- id: STATE-COM-FUL-002 title: Enforcement 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: dispatched meaning: >- An enforce obligation has been authorized to carry this response to the application. - 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: resolved meaning: Staff retained closure and the result rather than executing further work. - name: restored meaning: >- The application has completed the restore instruction against the original enforcement. transitions: - from: pending to: dispatched trigger: The enforcement handler authorizes an acting instruction. guard: >- The frozen response must require application action, with an unconditional enforce gate. side_effects: - Enforce obligation authorized and queued in the existing transaction. - >- Raise a staff review when the selected response requests line cancellation. who: Enforcement handler provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#leaves the review enforcement pending with an enforcement_review exception and no obligation, and the cancel_line one dispatched with a review for the request - from: pending to: resolved trigger: Staff retain a closure result under the specific intervention authority. guard: >- The caller must hold enforcement-resolution authority and find an unresolved record. side_effects: - Close the enforcement review finding. - 'Record the staff action, responsible person and stated reason.' who: Administrator provenance: observed source: >- services-commerce:modules/operations/services/interventions/operations-interventions.ts - from: pending to: restored trigger: The application’s restore instruction completes. guard: A successful restore obligation must name this original enforcement. side_effects: - >- The original enforcement is marked restored once the restore outcome is applied. who: Enforcement handler provenance: observed source: >- services-commerce:modules/fulfillment/services/register/obligation-worker.ts:settleEnforcement - from: dispatched to: completed trigger: The owning workflow retains its required final successful result. guard: The enforce answer must identify the current authorization. side_effects: - Append successful enforcement to the order history. who: Register worker provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/persistence/enforcements.queries.integration.spec.js#moves an enforcement along its lifecycle (pending -> dispatched -> completed -> restored) and refuses a move it does not allow - from: dispatched to: failed trigger: >- A permanent refusal, exhausted retry budget or acknowledgement policy stops the work. guard: A failure must affect the current enforce authorization. side_effects: - >- Append enforcement failure to the history and raise its obligation finding. who: Register worker or sweep provenance: observed source: >- services-commerce:modules/fulfillment/services/register/register-sweeper.ts:sweepRegister - from: dispatched to: resolved trigger: Staff retain a closure result under the specific intervention authority. guard: The caller must hold enforcement-resolution authority. side_effects: [] who: Administrator provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/enforcements.ts:ENFORCEMENT_TRANSITIONS - from: failed to: dispatched trigger: The enforcement handler authorizes an acting instruction. guard: >- Persistence permits this edge, but staff re-authorization does not invoke it. side_effects: [] who: Administrator provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/enforcements.ts:ENFORCEMENT_TRANSITIONS - from: failed to: resolved trigger: Staff retain a closure result under the specific intervention authority. guard: The caller must hold enforcement-resolution authority. side_effects: [] who: Administrator provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/enforcements.ts:ENFORCEMENT_TRANSITIONS - from: completed to: restored trigger: The application’s restore instruction completes. guard: A successful restore obligation must identify the original enforcement. side_effects: - >- The original enforcement is marked restored once the restore outcome is applied. who: Enforcement handler provenance: observed source: >- services-commerce:modules/fulfillment/services/register/obligation-worker.ts:settleEnforcement - from: completed to: resolved trigger: Staff retain a closure result under the specific intervention authority. guard: The caller must hold enforcement-resolution authority. side_effects: [] who: Administrator provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/enforcements.ts:ENFORCEMENT_TRANSITIONS - from: resolved to: restored trigger: The application’s restore instruction completes. guard: The restore outcome must reference the enforcement being reversed. side_effects: - >- The original enforcement is marked restored once the restore outcome is applied. who: Enforcement handler provenance: observed source: >- services-commerce:modules/fulfillment/services/register/obligation-worker.ts:settleEnforcement invalid: - from: restored to: dispatched why: >- A completed restoration remains final; a later reversal has its own enforcement. - from: resolved to: pending why: Resolved work remains closed; another occurrence needs its own record. - from: completed to: dispatched why: >- Completion remains final for this action; use the owning replacement or correction process. concurrency: >- Enforcement creation, instruction dispatch and review can commit separately. Unique keys suppress a second creation without providing complete recovery of an unfinished first creation. invariants: - INV-DOM-COM-FUL-001-10 evidence: - >- services-commerce at c8b66a98: modules/fulfillment/db/enforcements.table.ts; services/persistence/enforcements.ts; services/enforcement/enforcement-handler.ts; docs/migrations/operations/README.md (D-P5-01, D-P5-02, Decisions E and F). --- # Enforcement Lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> pending: reversal on a delivered line pending --> dispatched: notify, suspend, cancel line pending --> resolved: staff review pending --> restored dispatched --> completed dispatched --> failed dispatched --> resolved failed --> dispatched: issue another authorizationd failed --> resolved completed --> restored: restore instruction completed completed --> resolved resolved --> restored restored --> [*] ``` ## Transitions Explained A reversal creates an enforcement beside the original delivery. Review leaves work with staff; an acting policy dispatches a separate enforce obligation. Restored funds create a restore instruction, and successful execution of that instruction marks the original enforcement restored. ## What Cannot Happen The persistence helper restricts transitions, but a permitted edge does not establish a caller. Staff re-authorization currently changes the failed obligation without moving its enforcement back to dispatched, leaving settlement unresolved. ## Concurrency and Timing Creation, dispatch and review are separate writes. Redelivery deduplicates existing enforcements, so a crash between those stages can strand work instead of finishing it.