--- id: WF-COM-FUL-006 title: Execute a post-sale financial adjustment step by step trigger: >- A post-sale document, financial event, scheduled recovery or staff action invokes adjustment execution. product_area: commerce module: fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b implements: - CAP-COM-FUL-007 moves: - STATE-COM-FUL-003 crosses: - SVC-COM-FUL-fulfillment - SVC-COM-FUL-operations idempotency: >- One originating document identifies an adjustment. Fixed document-derived step keys permit replay without another Accounting document, and already finished steps are skipped. 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. hops: - 'n': 1 actor_or_service: Originating document (Orders) action: >- Retain one document adjustment with its fixed memo, fee, application and refund or credit steps when document timing permits. anchor: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:requestFinancialAdjustment seam: sync on_failure: Rollback the requesting document transaction. left_inconsistent: The refused request retains no new adjustment. observer: Adjustment-request history. provenance: observed source: >- services-commerce:modules/fulfillment/services/adjustments/adjustment-worker.ts:planAdjustmentSteps - 'n': 2 actor_or_service: Adjustment worker action: >- Mark the next financial step submitted before sending its stable-key Accounting command. anchor: >- services-commerce:modules/fulfillment/services/adjustments/adjustment-worker.ts:executeAdjustment seam: sync on_failure: Keep a lost-answer step submitted for another same-key command. left_inconsistent: Accounting may already hold a result Commerce has not retained. observer: Submitted step and stale-work reconciliation. provenance: documented source: 'services-commerce:docs/migrations/operations/README.md#D-P5-06' - 'n': 3 actor_or_service: Adjustment worker action: >- Retain successful Accounting references, wait on retryable refusal or fail permanent refusal, then advance only completed steps. anchor: >- services-commerce:modules/fulfillment/services/adjustments/adjustment-commands-port.ts seam: sync on_failure: Exhausted retryable attempts create the Finance failure finding. left_inconsistent: Earlier financial documents remain issued. observer: Finance findings and order history. provenance: observed source: >- services-commerce:modules/fulfillment/services/adjustments/adjustment-worker.ts - 'n': 4 actor_or_service: Adjustment worker action: >- Wait for processor-pending refund settlement without spending attempts and use its event to finish or fail the work. anchor: >- services-commerce:modules/fulfillment/services/facts/financial-facts-handler.ts seam: event on_failure: >- Reconciliation delays resuming processor-only pending work until it is a day old. left_inconsistent: The originating document can remain awaiting money settlement. observer: Retained processor-pending step. provenance: documented source: 'services-commerce:docs/milestones/COMM-M1-repairs-7-report.md#R7-2' - 'n': 5 actor_or_service: Adjustment worker action: >- Complete the retained adjustment and permit its originating document to settle. anchor: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts:settleFinancialAdjustment seam: sync on_failure: Retain unfinished settlement for another execution. left_inconsistent: Money can have moved while document completion is still pending. observer: Adjustment-completion history. provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/financial-adjustments.ts - 'n': 6 actor_or_service: Staff action: >- Resume failed work under retained step keys or record staff-confirmed external settlement. anchor: >- services-commerce:modules/operations/services/interventions/operations-interventions.ts:retryAdjustmentByStaff seam: sync on_failure: Refuse retry or resolution outside the permitted lifecycle. left_inconsistent: Earlier financial effects are retained rather than reversed. observer: Staff intervention ledger. provenance: observed source: >- services-commerce:modules/operations/services/interventions/operations-interventions.ts:resolveAdjustmentByStaff branches: - An unpaid line needs only the memo; a zero fee creates no fee invoice. - >- An amendment applies freed money to its new invoice before crediting any remainder. waits: - Accounting's answer; a processor's refund settlement. evidence: - >- services-commerce at c8b66a98: modules/fulfillment/services/adjustments/*.ts; services/persistence/financial-adjustments.ts; db/financial-adjustments.table.ts; modules/operations/services/reconciler/reconciler.ts; docs/migrations/operations/README.md (D-P5-05, D-P5-06, D-P5-15); docs/milestones/COMM-M1-repairs-6-report.md, COMM-M1-repairs-7-report.md. controls: [TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Execute a Post-Sale Financial Adjustment Step by Step ## What It Does A post-sale document requests its money work when its own timing permits. The worker sends a retained sequence of Accounting commands, each under a stable step key, and stores the result before progressing. Staff can retry unfinished work or record external settlement. ## The Flow ```mermaid sequenceDiagram participant D as Originating document participant W as Adjustment worker participant A as Accounting participant R as Reconciler participant S as Staff D->>W: request (steps planned), run after commit loop each step W->>W: mark submitted W->>A: command under step key A-->>W: reference or refusal end R->>W: resume after 15 minutes S->>W: retry from failed step ``` ## When Something Fails Recovery continues forward and retains completed financial documents. Lost answers resend the same key; permanent refusal or exhausted retryable attempts raises a Finance finding. Processor-pending refunds wait for their settlement event.