--- id: CAP-COM-FUL-009 title: Detect stalled and inconsistent order work feature: FEAT-COM-FUL-02 product_area: commerce module: fulfillment revision: 1 status: draft product_intent: proposed implementation_evidence: partially-observed supersedes: - CAP-COM-REG-025 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b intent_sources: [] purpose: >- Scheduled checks surface order work that stops progressing or disagrees with its records. outcomes: - Scheduled detection can identify problems before a customer reports them. - Checks delegate financial and delivery changes to the owning process. concepts: - CON-COM-FUL-003 actors: - ACT-COM-013 surfaces: - job preconditions: [] postconditions: [] permissions: [] rules: - id: BR-CAP-COM-FUL-009-01 proved_by: [ATS-COM-FUL-009-01, TST-COM-FUL-072, TST-COM-FUL-073] statement: >- The minute reconciler runs checks due every minute, every fifth minute, hourly at minute zero or daily at 02:00 UTC, and records a thrown check while continuing the others. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/operations/tests/integration/services/reconciler/reconciler.integration.spec.js#reads each cadence off the clock origin: >- D-P5-07 (build decision, not a product ruling): services-commerce:docs/migrations/operations/README.md#D-P5-07 - id: BR-CAP-COM-FUL-009-02 proved_by: [ATS-COM-FUL-008-11, ATS-COM-FUL-009-02, ATS-COM-FUL-009-07, TST-COM-FUL-069, TST-COM-FUL-071, TST-COM-FUL-072] statement: >- Unbilled placed orders older than ten minutes are counted, blocked candidates raise billing-blocked findings, and other candidates raise placed-without-invoice findings once sixty minutes old. kind: calculation enforced_at: - service must_prove: true provenance: observed source: >- services-commerce:modules/operations/services/reconciler/reconciler.ts:RECONCILER_CHECKS origin: none - id: BR-CAP-COM-FUL-009-03 proved_by: [ATS-COM-FUL-009-02, TST-COM-FUL-071, TST-COM-FUL-072] statement: >- Payment uncertainty lasting fifteen minutes, accepted lines missing invoice links after ten minutes, reservation holds ten minutes beyond expiry and migrated obligations blocked thirty days raise findings in their workspace; window-voided orders receive one informational finding. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/operations/tests/integration/services/reconciler/reconciler.integration.spec.js#raises tender_uncertain, the window’s tender_window_expired once, accepted_without_invoice_line, hold_stranded and migrated_unfulfilled, each in its tenant origin: none - id: BR-CAP-COM-FUL-009-04 proved_by: [ATS-COM-FUL-007-08, ATS-COM-FUL-009-03, ATS-COM-FUL-009-06, TST-COM-FUL-026, TST-COM-FUL-072] statement: >- Adjustments active for fifteen minutes are resumed, except processor-only refunds, which wait until their request is a day old. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/operations/tests/integration/services/reconciler/reconciler.integration.spec.js#raises refund_without_cancellation once for the reversal the handler never saw, and resumes the stale adjustment to completion origin: >- COMM-M1 R7-2 (repair report, not a product ruling): services-commerce:docs/milestones/COMM-M1-repairs-7-report.md#R7-2 - id: BR-CAP-COM-FUL-009-05 proved_by: [ATS-COM-FUL-009-03, TST-COM-FUL-026, TST-COM-FUL-072] statement: >- The reversal backstop raises one informational refund-without-cancellation exception for each order reached through recent reversal receipts, without inspecting cancellation documents. kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-commerce:modules/operations/services/reconciler/reconciler.ts:RECONCILER_CHECKS origin: none - id: BR-CAP-COM-FUL-009-06 proved_by: [] statement: >- The hourly dead-letter check publishes queue depth as a metric without creating an operational exception. kind: policy enforced_at: - service must_prove: false provenance: observed source: >- services-commerce:modules/operations/services/reconciler/reconciler.ts:RECONCILER_CHECKS origin: none - id: BR-CAP-COM-FUL-009-07 proved_by: [ATS-COM-FUL-009-04, TST-COM-FUL-072] statement: >- Daily checks raise one discount-drift finding per affected order from the previous two days and retain one recurring counter-drift finding per promotion or code whose use count disagrees with redemptions. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/operations/tests/integration/services/reconciler/reconciler.integration.spec.js#raises promotion_discount_drift for the order of the window whose discount its allocations do not add up to, with the figures origin: >- Decision I, Andrew 2026-10-18 (promotion drift checks): services-commerce:docs/migrations/promotions/README.md#B8; docs/migrations/operations/README.md#D-P5-17 - id: BR-CAP-COM-FUL-009-08 proved_by: [] statement: >- Reconciliation delegates actions to the owning keyed process instead of directly modifying money or application-delivered records. kind: invariant enforced_at: - service must_prove: false provenance: observed source: >- services-commerce:modules/operations/services/reconciler/reconciler.ts:runReconciler origin: none - id: BR-CAP-COM-FUL-009-09 proved_by: [ATS-COM-FUL-009-05, TST-COM-FUL-071] statement: >- Cross-workspace candidate reads require their sweep permissions and reject an existing transaction; resulting findings are written in each record's workspace. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/operations/tests/integration/services/persistence/reconciler-candidates.queries.integration.spec.js#refuses every read inside another transaction origin: none - id: BR-CAP-COM-FUL-009-10 proved_by: [] statement: >- Scheduled-amendment, overdue-return and inventory-balance checks remain skipped, while stale-obligation and acknowledgement handling remain delegated to the checkout sweep. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-commerce:modules/operations/tests/integration/services/reconciler/reconciler.integration.spec.js#measures the dead-letter queue through the port, records the sweeper’s two passes as its, and the waiting checks with their reason origin: none scenarios: - id: SC-CAP-COM-FUL-009-01 given: An unblocked order has waited an hour for billing. when: Run reconciliation alongside an eleven-minute-old unblocked fixture. then: >- The older order receives a missing-invoice exception and the younger order is only counted. provenance: test source: >- services-commerce:modules/operations/tests/integration/services/reconciler/reconciler.integration.spec.js#raises placed_without_invoice for the hour-old unbilled order and billing_blocked for the blocked one, and counts the eleven-minute one without raising edge_cases: - id: SC-CAP-COM-FUL-009-02 given: Staff resolved an order's discount-drift exception. when: Run the next daily drift check on the same order. then: The existing resolved finding prevents another exception for that order. provenance: test source: >- services-commerce:modules/operations/tests/integration/services/reconciler/reconciler.integration.spec.js#finds the order again and raises it nothing more: the resolved finding stands (D-P5-08) constraints: [] depends_on: [] related: - CAP-COM-FUL-007 - CAP-COM-FUL-008 journeys: - JNY-COM-FUL-002 open_questions: [] evidence: - repository: services-commerce paths: - >- modules/operations/tests/integration/services/reconciler/reconciler.integration.spec.js - modules/operations/services/reconciler/reconciler.ts - >- modules/operations/tests/integration/services/persistence/reconciler-candidates.queries.integration.spec.js 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-DAT-004, TC-LOG-004, TC-LOG-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-007, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-004, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-FUL-02-02, FAS-COM-FUL-02-05] suites: [TST-COM-FUL-026, TST-COM-FUL-069, TST-COM-FUL-071, TST-COM-FUL-072, TST-COM-FUL-073] --- # Detect stalled and inconsistent order work ## Purpose Scheduled checks surface order work that stops progressing or disagrees with its records. ## How It Works The reconciler selects checks according to the current clock. Each check reads candidates using its own budget and records what it finds. Problems become staff findings where that check implements a finding path. Actions needed for recovery are delegated to the process that owns the work. A failing check is recorded while other due checks continue. Some declared checks remain placeholders, and queue-depth monitoring creates a metric rather than a staff exception. The product should define ownership and response for each monitored failure before relying on the schedule operationally. ## Relationships - Complete the financial work requested by a post-sale document supplies or consumes related delivery records. - Review and resolve operations findings supplies or consumes related delivery records.