--- id: STATE-COM-FUL-003 title: Financial adjustment lifecycle object: DOM-COM-FUL-003 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: 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: resolved meaning: Staff retained closure and the result rather than executing further work. transitions: - from: pending to: in_progress trigger: The application or financial worker records continuing work. guard: The adjustment must not already be completed or resolved. side_effects: - Mark a step submitted before issuing its Accounting command. - Append adjustment-step progress to the order history. who: Adjustment worker provenance: observed source: >- services-commerce:modules/fulfillment/services/adjustments/adjustment-worker.ts:executeAdjustment - from: pending to: completed trigger: The owning workflow retains its required final successful result. guard: Every financial step must be done or skipped. side_effects: - Record successful adjustment completion in history. who: Adjustment worker provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:ADJUSTMENT_TRANSITIONS - from: in_progress to: completed trigger: The owning workflow retains its required final successful result. guard: >- Every required step must succeed or be skipped, including processor refund settlement. side_effects: - >- Settle the originating document after its required financial work completes. who: Adjustment worker or financial facts receiver provenance: documented source: 'services-commerce:docs/milestones/COMM-M1-repairs-6-report.md#R6-2' - from: in_progress to: failed trigger: >- A permanent refusal, exhausted retry budget or acknowledgement policy stops the work. guard: The failure must be permanent or reach the permitted attempt limit. side_effects: - Adjustment failed exception created for Finance. who: Adjustment worker provenance: observed source: >- services-commerce:modules/fulfillment/services/adjustments/adjustment-worker.ts - from: pending to: failed trigger: >- A permanent refusal, exhausted retry budget or acknowledgement policy stops the work. guard: Persistence permits failing pending work for an unrecoverable refusal. side_effects: - Adjustment failed exception created. who: Adjustment worker provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:ADJUSTMENT_TRANSITIONS - from: failed to: pending trigger: A person retries including a reason. guard: The caller needs sensitive retry authority and a failed adjustment. side_effects: - Clear the retained failure and return the failed step to planned work. - Intervention stored; worker resumes from the failed step. who: Administrator provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:retryFinancialAdjustment - from: failed to: resolved trigger: Staff retain a closure result under the specific intervention authority. guard: The caller needs the specific sensitive resolution authority. side_effects: - Close the associated exception. - '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: resolved trigger: Staff retain a closure result under the specific intervention authority. guard: The caller needs adjustment-resolution authority and a nonterminal record. side_effects: [] who: Administrator provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:ADJUSTMENT_TRANSITIONS - from: in_progress to: resolved trigger: Staff retain a closure result under the specific intervention authority. guard: The caller needs adjustment-resolution authority and a nonterminal record. side_effects: [] who: Administrator provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:ADJUSTMENT_TRANSITIONS invalid: - from: completed to: pending why: >- Completion remains final for this action; use the owning replacement or correction process. - from: resolved to: pending why: Resolved work remains closed; another occurrence needs its own record. - from: failed to: completed why: >- Failed work needs its permitted retry or staff closure before another outcome can apply. concurrency: >- Requesters and background or staff callers can overlap. Step retention locks the adjustment, and external commands rely on their stable keys rather than a single long transaction. invariants: - INV-DOM-COM-FUL-003-05 - INV-DOM-COM-FUL-003-06 - INV-DOM-COM-FUL-003-07 - INV-DOM-COM-FUL-003-08 evidence: - >- services-commerce at c8b66a98: modules/fulfillment/db/financial-adjustments.table.ts; services/persistence/financial-adjustments.ts; services/adjustments/adjustment-worker.ts, adjustment-commands-port.ts; docs/migrations/operations/README.md (D-P5-05, D-P5-06, D-P5-15). --- # Financial Adjustment Lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> pending: document requests pending --> in_progress: worker runs pending --> completed pending --> failed pending --> resolved in_progress --> completed in_progress --> failed in_progress --> resolved failed --> pending: staff retry failed --> resolved: staff resolve completed --> [*] resolved --> [*] ``` ## Transitions Explained The originating document requests a fixed sequence of financial steps. Execution records each command before sending and retains its result before continuing. Retryable refusal waits for another run; permanent refusal or exhausted attempts creates a Finance finding. ## What Cannot Happen Completed and resolved adjustments are terminal. Staff retry starts from retained unfinished work rather than undoing financial documents that already exist. ## Concurrency and Timing Requesters, financial events, reconciliation and staff can invoke the worker. Stable step keys support repeated commands. Processor-pending refunds wait for settlement events without spending the failure-attempt budget.