--- id: STATE-COM-ORD-010 title: Amendment 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 amendment is recorded and proceeds to evaluation. - name: evaluating meaning: 'Seller advice and replacement pricing are being assembled, possibly waiting for missing input.' - name: prepared meaning: A calculated change still needs a condition resolved before execution. - name: awaiting_approval meaning: An authorized person must decide whether the change may proceed. - name: approved meaning: Execution is permitted for the evaluated plan. - name: scheduled meaning: The approved change has a later effective date or renewal point. - name: executing meaning: The replacement order exists and modification work is progressing. - name: awaiting_tender meaning: The replacement sale needs a payment before the amendment can continue. - name: completed meaning: 'Modification and settlement succeeded, superseding the original delivery.' - name: completed_with_exceptions meaning: Modification or settlement ended with operational failures. - name: rejected meaning: The change was refused and the original purchase remains standing. - name: withdrawn meaning: The requester abandoned the amendment before execution. - name: voided meaning: The replacement sale was voided and the original line restored. transitions: - from: evaluating to: approved trigger: Evaluation permits an amendment without approval. guard: The seller allows modification and replacement valuation is available. side_effects: - retain remaining-term valuation in the evaluated change who: System provenance: observed source: 'services-commerce:modules/orders/services/amendments/amendment-workflow.ts:requestAmendment' - from: evaluating to: rejected trigger: Evaluation denies the proposed change or later offer. guard: The refusal outcome ends the plan without execution. side_effects: - preserve the original purchase without financial execution who: System provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#rejects a change the participant refuses, with its problem, and leaves the line open - from: awaiting_approval to: approved trigger: An approver records permission and an explanation. guard: Console access and amendment approval authority are required. side_effects: - persist local staff-intervention accountability who: Approver provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#holds a change the participant wants approved; a second request on the line is 409; the approver approves, staff execute - from: approved to: scheduled trigger: The permitted change has a future or renewal effective point. guard: Effective mode is not immediate. side_effects: - retain scheduled intent without automatic effective-date execution who: System provenance: observed source: 'services-commerce:modules/orders/services/persistence/amendments.ts:AMENDMENT_TRANSITIONS' - from: approved to: executing trigger: The caller starts replacement execution. guard: 'Rechecked plan, original fence and new resource claims must succeed.' side_effects: - create the replacement purchase and bill outside its commit - record original-line amendment and successor linkage - create modification work linked to the original delivery - settle unused original value into replacement billing who: Requester or staff with the amendment create permission provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#placed the change order under the amendment: the original’s parties, one premium line at the remaining value, billed, placed - from: executing to: awaiting_tender trigger: Replacement credit leaves additional payment outstanding. guard: Terms or credit do not satisfy the replacement amount. side_effects: - use regular tender processing for replacement balance who: System provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#credited the unused value from the original payment and applied it to the change invoice; the document awaits the buyer’s tender - from: awaiting_tender to: executing trigger: Replacement acceptance invokes amendment follow-up. guard: This best-effort call only logs failure and has no automatic replay. side_effects: [] who: System (acceptance follow-up) provenance: observed source: 'services-commerce:modules/orders/services/amendments/amendment-settlement.ts:onChangeOrderAccepted' - from: awaiting_tender to: voided trigger: The replacement sale is voided at its elapsed deadline. guard: The linked void workflow supplies the outcome. side_effects: - reinstate the original purchased line who: System (void) provenance: observed source: 'services-commerce:modules/orders/services/amendments/amendment-settlement.ts:onChangeOrderVoided' - from: executing to: completed trigger: 'Settlement observes accepted replacement, completed modification and settled money.' guard: The amendment remains executing. side_effects: - supersede the original delivery and release its reservation records who: System (settlement) provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#completes once the buyer’s card accepts the change order and the worker delivers the modify: the original fulfilment superseded - from: approved to: withdrawn trigger: The requester ends the approved amendment. guard: Execution has not begun. side_effects: - leave original purchase availability unchanged who: Requester provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#lets the member withdraw an approved, unexecuted change; the line stays open invalid: - from: executing to: withdrawn why: Replacement execution requires settlement or replacement void to end. - from: scheduled to: executing why: 'The transition map requires scheduled work to return to approved, but no automatic caller does so.' - from: completed to: voided why: Completed amendments have no transition to voided. concurrency: >- Original-line occupancy and fencing protect execution. Acceptance resumes an awaiting amendment only through a best-effort follow-up, so failure can strand it after the replacement sale has been paid. invariants: - INV-DOM-COM-ORD-005-01 - INV-DOM-COM-ORD-005-04 evidence: - >- services-commerce at c8b66a98: modules/orders/services/persistence/amendments.ts (AMENDMENT_TRANSITIONS); services/amendments/amendment-workflow.ts, amendment-settlement.ts, amendment-plan.ts, proration.ts, promotion-amendment.ts; tests/e2e/amendments.e2e.spec.js. --- # Amendment lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> requested requested --> evaluating requested --> withdrawn evaluating --> approved 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 --> scheduled scheduled --> approved scheduled --> rejected scheduled --> withdrawn approved --> executing approved --> prepared approved --> rejected approved --> withdrawn executing --> awaiting_tender awaiting_tender --> executing: change order accepted awaiting_tender --> voided: change order voided executing --> voided executing --> completed executing --> completed_with_exceptions ``` ## Transitions Explained A regular amendment values the remaining original benefit and replacement, then creates a linked change order. Credit can cover a downgrade; an upgrade awaits payment. Completion also requires the application's modification and financial settlement. Later promotion application uses the same document kind without a replacement order. ## What Cannot Happen Execution cannot be withdrawn. A replacement order cannot itself be amended. Scheduled status records a future change without an automatic execution mechanism. ## Concurrency and Timing Original-line occupancy and fencing protect execution. Acceptance resumes an awaiting amendment only through a best-effort follow-up, so failure can strand it after the replacement sale has been paid.