--- id: STATE-COM-ORD-009 title: Cancellation lifecycle object: DOM-COM-ORD-005 product_area: commerce module: orders revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b states: - name: requested meaning: The cancellation and lines are stored before immediate evaluation. - name: evaluating meaning: The system gathers seller advice and financial and approval facts. - name: prepared meaning: Evaluation produced a plan that needs confirmation or a successful fence. - name: awaiting_approval meaning: Execution needs an authorized person's decision. - name: approved meaning: 'The current plan is permitted to execute, automatically or by approval.' - name: executing meaning: The domain transaction committed and reversal and settlement continue. - name: completed meaning: All cancellation work and required financial settlement succeeded. - name: completed_with_exceptions meaning: Work ended with failures recorded for operational attention. - name: rejected meaning: The request was refused without executing the purchase change. - name: withdrawn meaning: The requester ended the request before execution. transitions: - from: requested to: evaluating trigger: The new request begins evaluation. guard: The caller has party authority over an accepted sale. side_effects: - obtain reversal advice from the affected sellers - obtain financial position for credit bounds who: 'Portal buyer, staff or administrator' provenance: observed source: 'services-commerce:modules/orders/services/cancellations/cancellation-workflow.ts:requestCancellation' - from: evaluating to: approved trigger: Evaluation permits the plan without a person. guard: No line or threshold requires approval. side_effects: - store evaluation with its thirty-minute recheck interval who: System provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#answers 200 with the document completed in the one request: allowed, executed, the money moved, the customer status cancelled - from: evaluating to: awaiting_approval trigger: Seller advice or the refund threshold requires a staff decision. guard: Evaluation records the approval need. side_effects: - keep affected lines occupied against another cancellation who: System provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#holds staff’s request for approval (participant_requires_approval) and refuses a second request on the line 409 line_already_cancelling (B38) - from: evaluating to: rejected trigger: Evaluation denies every affected line. guard: 'Denials can follow expired terms, shipping handoff or seller refusal.' side_effects: - record the customer-facing refusal outcome who: System provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#rejects the member’s request with after_cancellation_deadline, the customer status declined; nothing moved on the order - from: awaiting_approval to: approved trigger: An approver records permission to proceed and an explanation. guard: Console access and cancellation approval authority are required. side_effects: - 'persist intervention and history, then attempt external audit delivery' who: Approver provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#lets the approver approve it with a reason, and staff execute it; the intervention on the history - from: awaiting_approval to: rejected trigger: An approver records refusal and an explanation. guard: Console access and cancellation approval authority are required. side_effects: - persist local staff-intervention accountability who: Approver provenance: observed source: 'services-commerce:modules/orders/aws/api/post-purchase.routes.ts:rejectCancellation' - from: approved to: executing trigger: The caller requests immediate or later execution. guard: 'The plan remains current or unchanged after recheck, and all fences succeed.' side_effects: - stop pending delivery or fence completed work and create reversal obligations - apply cancelled units and return full-line offer uses and benefit availability - store settlement work and execute it when policy and domain conditions allow who: Requester or staff with the cancellation create permission provenance: observed source: 'services-commerce:modules/orders/services/cancellations/cancellation-workflow.ts:executeCancellation' - from: approved to: prepared trigger: Execution encounters an application or shipping fence conflict. guard: The attempted transaction rolled back. side_effects: - retain the execution blocker on the request who: System provenance: observed source: 'services-commerce:modules/orders/services/cancellations/cancellation-workflow.ts' - from: approved to: withdrawn trigger: The requester ends the approved plan before execution. guard: Execution has not begun. side_effects: - release document occupancy of affected lines who: Requester with the cancellation update permission provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#lets the member withdraw an approved, unexecuted request (a second request refused meanwhile), then request again - from: executing to: completed trigger: Settlement observes completed reversal and financial work. guard: The after-commit completion checks run for the eligible executing document. side_effects: - end the sale when every purchased item is cancelled - derive and persist the latest financial projection who: System (settlement) provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#is delivered by the worker to the participant’s cancel, which settles the document completed and runs the refund after the domain (ADR-13) - from: executing to: completed_with_exceptions trigger: Settlement observes a failed cancellation or financial step. guard: Remaining work has reached terminal outcomes. side_effects: - retain unresolved operational exceptions for staff who: System (settlement) provenance: observed source: 'services-commerce:modules/orders/services/cancellations/cancellation-settlement.ts:settleCancellation' invalid: - from: executing to: withdrawn why: Execution has already started reversal and settlement; completion must follow those outcomes. - from: rejected to: approved why: A refused request stays terminal and another request receives another document. - from: completed to: executing why: Completed requests cannot restart execution. concurrency: >- An aged plan is reevaluated after thirty minutes and a changed result requires confirmation. Domain reversal normally precedes money; policy can allow settlement after fencing. invariants: - INV-DOM-COM-ORD-005-01 - INV-DOM-COM-ORD-005-04 - INV-DOM-COM-ORD-005-09 evidence: - >- services-commerce at c8b66a98: modules/orders/services/persistence/cancellations.ts (CANCELLATION_TRANSITIONS); services/cancellations/cancellation-workflow.ts, cancellation-settlement.ts, cancellation-plan.ts; tests/e2e/cancellations.e2e.spec.js. --- # Cancellation lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> requested requested --> evaluating requested --> withdrawn evaluating --> approved: no approval needed evaluating --> awaiting_approval evaluating --> prepared evaluating --> rejected prepared --> approved prepared --> awaiting_approval prepared --> rejected prepared --> withdrawn awaiting_approval --> approved awaiting_approval --> rejected awaiting_approval --> withdrawn approved --> executing approved --> prepared: fence refused approved --> rejected approved --> withdrawn executing --> completed executing --> completed_with_exceptions ``` ## Transitions Explained Request evaluation assembles seller advice, credit bounds, charges and approval needs. An automatically permitted request can execute immediately when asked. Its transaction fences the purchase change and creates reversal and settlement work, then completion waits for those outcomes. ## What Cannot Happen Executing requests cannot be withdrawn or rejected. Terminal requests have no outgoing transitions, and live line occupancy prevents a second cancellation request. ## Concurrency and Timing An aged plan is reevaluated after thirty minutes and a changed result requires confirmation. Domain reversal normally precedes money; policy can allow settlement after fencing.