--- id: WF-COM-FUL-005 title: Respond to reversed and restored money on delivered lines trigger: A reversal or restoration event selects delivered order work. product_area: commerce module: fulfillment revision: 1 status: draft design_intent: confirmed origin: >- Decisions E and F, Andrew 2026-10-18 (review by a person by default; staff finish the money side of a line cancellation): services-commerce:docs/migrations/operations/README.md#2026-10-18 — Progress checkpoint (section 5 of the 14-section walk: the register, enforcement, adjustments and the operations area) implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b implements: - CAP-COM-FUL-006 moves: - STATE-COM-FUL-002 - STATE-COM-FUL-001 crosses: - SVC-COM-FUL-fulfillment - SVC-COM-FUL-operations idempotency: >- Obligation and cause identity deduplicate enforcement creation. Existing enforcement records are skipped on replay, which can strand dispatch or review after a crash. concurrency: >- Enforcement creation, instruction dispatch and review can commit separately. Unique keys suppress a second creation without providing complete recovery of an unfinished first creation. hops: - 'n': 1 actor_or_service: Financial facts receiver action: >- Classify supported reversal causes and select completed or progressing obligations, leaving waiting delivery alone. anchor: >- services-commerce:modules/fulfillment/services/enforcement/enforcement-handler.ts:ENFORCEABLE_STATES seam: event on_failure: Fail financial-event processing for redelivery. left_inconsistent: Earlier event work can already have committed. observer: Event response and logs. provenance: documented source: 'services-commerce:docs/migrations/operations/README.md#D-P5-04' - 'n': 2 actor_or_service: Enforcement handler action: >- Apply the frozen response: no action for none, or a pending enforcement and review finding for review. anchor: >- services-commerce:modules/fulfillment/services/enforcement/enforcement-handler.ts:enforceReversal seam: sync on_failure: Return event failure; existing enforcement creation is skipped on retry. left_inconsistent: An enforcement can remain without its review finding. observer: Staff enforcement reviews. provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#leaves the review enforcement pending with an enforcement_review exception and no obligation, and the cancel_line one dispatched with a review for the request - 'n': 3 actor_or_service: Enforcement handler action: >- For acting responses, create an unconditional enforce obligation, authorize dispatch and retain staff review for cancel-line money work. anchor: >- services-commerce:modules/fulfillment/services/persistence/enforcements.ts:createEnforcement seam: state_machine on_failure: Return failure for event redelivery. left_inconsistent: A created enforcement may lack its dispatch continuation. observer: Enforcement and obligation records. provenance: documented source: 'services-commerce:docs/migrations/operations/README.md#D-P5-02' - 'n': 4 actor_or_service: Obligation worker action: >- Deliver the enforce instruction through the register worker and move its enforcement from the application’s final result. anchor: >- services-commerce:modules/fulfillment/services/register/obligation-worker.ts seam: queue on_failure: >- Use known worker retries; follow-up settlement can fail after the obligation completes. left_inconsistent: The enforcement can lag its terminal obligation outcome. observer: Enforcement state and delivery findings. provenance: observed source: >- services-commerce:modules/fulfillment/services/register/obligation-worker.ts - 'n': 5 actor_or_service: Enforcement handler action: >- Retain the informational reversal finding independently of automatic cancellation-document creation. anchor: >- services-commerce:modules/fulfillment/services/enforcement/enforcement-handler.ts seam: sync on_failure: Fail the event when finding creation throws. left_inconsistent: Existing reversal effects are not rolled back. observer: Informational Operations finding. provenance: observed source: >- services-commerce:modules/fulfillment/services/enforcement/enforcement-handler.ts - 'n': 6 actor_or_service: Enforcement handler (funds restored) action: >- Create a separate restore instruction for eligible acting enforcements, dispatch where supported and otherwise retain staff review. anchor: >- services-commerce:modules/fulfillment/services/persistence/enforcements.ts:markEnforcementRestored seam: state_machine on_failure: >- Fail the event; an existing restore record can be skipped rather than completed on retry. left_inconsistent: Application access can still await restoration or staff action. observer: Restore review findings. provenance: observed source: >- services-commerce:modules/fulfillment/services/enforcement/enforcement-handler.ts - 'n': 7 actor_or_service: Staff action: >- Record staff resolution and close the associated enforcement review with its reason and result. anchor: >- services-commerce:modules/operations/services/interventions/operations-interventions.ts:resolveEnforcementByStaff seam: sync on_failure: 'Refuse unauthorized, terminal or otherwise invalid resolution.' left_inconsistent: No financial document is created by resolution itself. observer: Intervention and order history. provenance: observed source: >- services-commerce:modules/operations/services/interventions/operations-interventions.ts branches: - >- The reconciler's backstop, each five minutes, raises the existing informational finding for orders reached through recent reversal receipts, without inspecting cancellation documents. waits: - A person's review; the money coming back. evidence: - >- services-commerce at c8b66a98: modules/fulfillment/services/enforcement/enforcement-handler.ts; services/persistence/enforcements.ts; services/facts/financial-facts-handler.ts; modules/operations/services/reconciler/reconciler.ts; docs/migrations/operations/README.md (D-P5-01 to D-P5-04, Decisions E and F). 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] --- # Respond to Reversed and Restored Money on Delivered Lines ## What It Does Reversal handling selects delivered or progressing obligations and follows each frozen response. Review creates staff attention; an acting response sends an enforce instruction. Restoration creates a separate instruction when the application supports it, otherwise it leaves review work. ## The Flow ```mermaid sequenceDiagram participant A as Accounting participant F as Facts receiver participant H as Enforcement handler participant R as Register participant P as Delivering application participant S as Staff A->>F: reversal event F->>H: delivered obligations of the lines alt review (default) H->>S: enforcement review finding else notify, suspend, cancel line H->>R: enforce obligation, authorized R->>P: enforce P-->>R: completed or failed end A->>F: restore instruction completed F->>H: restore each enforcement that acted ``` ## When Something Fails Creating an enforcement does not atomically dispatch it or create its review. Redelivery skips existing records, which can strand a partially created enforcement. Instructions do not automatically create cancellation documents or reverse earlier financial work.