--- id: WF-COM-FUL-002 title: Open delivery when an order's facts change trigger: An Accounting receivable change event reaches Commerce. 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-002 - CAP-COM-FUL-003 - CAP-COM-FUL-007 moves: - STATE-COM-FUL-001 crosses: - SVC-COM-FUL-fulfillment idempotency: >- Event identity selects an existing receipt before work and stores success last. Conditional gate opening permits one retained authorization even when event processing overlaps. concurrency: >- Overlapping event delivery can repeat history before receipt deduplication. Each gate’s conditional opening and record lock prevent a second authorization. hops: - 'n': 1 actor_or_service: >- Financial facts receiver (Accounting's change-events dispatcher invokes it) action: >- Enter the event workspace, skip a retained receipt, resolve affected lines and append the order’s financial-history fact. anchor: >- services-commerce:modules/fulfillment/services/facts/financial-facts-handler.ts:applyChangeEvent seam: event on_failure: >- Return that event failed for redelivery; unknown workspace or unmatched business records return success without delivery work. left_inconsistent: History or mirror changes can already stand before a success receipt. observer: Per-event response and Commerce logs. provenance: observed source: 'services-commerce:modules/fulfillment/contracts/financial-facts.ts' - 'n': 2 actor_or_service: Financial facts receiver action: Resume active financial adjustments on affected orders. anchor: >- services-commerce:modules/fulfillment/services/facts/financial-facts-handler.ts seam: sync on_failure: Fail the event so its later delivery can try again. left_inconsistent: The adjustment retains its last completed financial steps. observer: Retained adjustment step history. provenance: documented source: 'services-commerce:docs/milestones/COMM-M1-repairs-6-report.md#R6-2' - 'n': 3 actor_or_service: Register evaluator action: >- Read current billing, financial position, terms, approval, readiness, parent and hold facts, then retain a waiting gate verdict. anchor: >- services-commerce:modules/fulfillment/services/policies/evaluate-gate.ts:evaluateGate seam: sync on_failure: >- Return event failure; bounded recovery covers pending records and excludes blocked records. left_inconsistent: Earlier obligations can already have been evaluated. observer: 'Gate verdict, facts and blocked-history records.' provenance: test source: >- services-commerce:modules/fulfillment/tests/unit/policies/evaluate-gate.spec.js - 'n': 4 actor_or_service: Register evaluator action: >- Commit gate opening, authorization, acknowledgement deadline, dispatch entry and opening history together. anchor: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:openGate seam: sync on_failure: Rollback keeps the obligation waiting for another evaluation. left_inconsistent: The failed opening retains neither authorization nor dispatch. observer: Authorization history. provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/obligations.ts:openGate - 'n': 5 actor_or_service: Financial facts receiver action: >- Apply reversal or restore handling to affected delivery records before storing the financial receipt. anchor: >- services-commerce:modules/fulfillment/services/enforcement/enforcement-handler.ts:enforceReversal seam: sync on_failure: Fail the event for redelivery under enforcement deduplication. left_inconsistent: Earlier enforcement creation may remain without completed dispatch. observer: Enforcement and staff-review records. provenance: observed source: >- services-commerce:modules/fulfillment/services/facts/financial-facts-handler.ts - 'n': 6 actor_or_service: Financial facts receiver action: Retain the event receipt after processing and nudge queued dispatch work. anchor: >- services-commerce:modules/fulfillment/services/persistence/financial-fact-receipts.ts seam: sync on_failure: >- Failed receipt writing permits redelivery; a failed nudge relies on later scheduled dispatch. left_inconsistent: Earlier evaluations and enforcements can remain committed. observer: Receipt and dispatcher logs. provenance: documented source: 'services-commerce:docs/migrations/obligation-register/README.md#D-P4-13' branches: - >- The minute sweep (a pass of Orders' checkout sweeper) evaluates each pending obligation of an accepted order not evaluated for ten minutes, a bounded page per run; blocked obligations are not swept. - >- Interventions (approval, released hold) and a prerequisite report evaluate the one obligation at once. waits: - 'Accounting''s next change event, or a subsequent sweep.' evidence: - >- services-commerce at c8b66a98: modules/fulfillment/services/facts/*.ts; services/register/gate-evaluation.ts, register-sweeper.ts; services/policies/evaluate-gate.ts; services/persistence/obligations.ts; contracts/financial-facts.ts; aws/cdk/commerce.function-environment.ts (the position view provider deployed); docs/migrations/obligation-register/README.md (D-P4-02, D-P4-04, D-P4-13). 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-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, 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-PRV-001, TC-PRV-002] --- # Open Delivery When an Order's Facts Change ## What It Does A financial event identifies affected lines, then Commerce reads current positions rather than trusting an old event amount. Active money adjustments resume, waiting gates evaluate and reversal responses run before the event receipt is retained. ## The Flow ```mermaid sequenceDiagram participant A as Accounting dispatcher participant F as Facts receiver participant V as Position view participant E as Evaluator participant D as Dispatch table A->>F: batch of change events F->>F: receipt exists? skip F->>V: staff closure lines, read positions F->>E: evaluate waiting obligations E->>D: open gate: authorization + dispatch entry F->>F: reversal: enforcement handler F->>F: write receipt last F-->>A: succeeded or failed per event ``` ## When Something Fails A failed event requests redelivery without a success receipt. Earlier history, mirror changes, evaluations or enforcements can already have committed. Gate opening itself retains authorization and dispatch atomically; receipt ordering does not make the whole event atomic.