---
id: WF-COM-ORD-006
title: Run the every-minute sweeps
trigger: The minute schedule invokes the shared checkout sweeper with concurrency one.
product_area: commerce
module: orders
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
implements:
  - CAP-COM-ORD-001
  - CAP-COM-ORD-005
  - CAP-COM-ORD-006
  - CAP-COM-ORD-007
  - CAP-COM-ORD-008
  - CAP-COM-ORD-009
  - CAP-COM-ORD-010
  - CAP-COM-ORD-011
  - CAP-COM-ORD-013
moves:
  - STATE-COM-ORD-001
  - STATE-COM-ORD-002
  - STATE-COM-ORD-003
  - STATE-COM-ORD-004
  - STATE-COM-ORD-005
  - STATE-COM-ORD-006
  - STATE-COM-ORD-008
crosses:
  - SVC-COM-ORD-checkout
  - SVC-COM-ORD-orders
  - SVC-COM-ORD-entitlements
  - SVC-COM-ORD-participants
  - SVC-ACC-TRX-transactions
idempotency: >-
  Passes reread current candidates and condition changes on their expected states. Financial recovery retains
  stable remote keys, making repeated processing safe for completed work.
concurrency: >-
  Reserved concurrency permits one scheduled invocation at a time. Candidate discovery crosses workspaces
  under a transaction-local sweep flag, and each bounded write enters the selected workspace.
hops:
  - 'n': 1
    actor_or_service: Checkout expiry pass
    action: Abandon expired open carts in expiry order and release their holds under system attribution.
    anchor: 'services-commerce:modules/checkout/services/checkout/checkout-sweeper.ts:sweepExpiredCheckouts'
    seam: schedule
    on_failure: A changed cart is skipped; other failures abort the invocation.
    left_inconsistent: 'Later passes do not run, and the failing oldest candidate may recur.'
    observer: Observed through the function log and error alarm expose failure.
    provenance: observed
    source: 'services-commerce:modules/checkout/aws/lambda/SWEEPER.ts:handler'
  - 'n': 2
    actor_or_service: Hold pass
    action: 'Expire unplaced holds and stale their items, then confirm pending placed leases.'
    anchor: 'services-commerce:modules/orders/services/reservations/reservation-sweeper.ts:sweepReservations'
    seam: schedule
    on_failure: Unanswered leases wait for the next pass; thrown failures abort the invocation.
    left_inconsistent: Subsequent passes lose this invocation's processing opportunity.
    observer: Observed through function failure alert; hold-stranded exception from the reconciler after ten minutes.
    provenance: observed
    source: 'services-commerce:modules/orders/services/reservations/reservation-sweeper.ts:sweepReservations'
  - 'n': 3
    actor_or_service: Tender-window pass
    action: Void eligible pay-now and deposit sales whose deadlines elapsed.
    anchor: 'services-commerce:modules/orders/services/orders/tender-window-sweeper.ts:sweepTenderWindows'
    seam: schedule
    on_failure: Changed sale status is skipped; other failures abort the invocation.
    left_inconsistent: Expired sales keep resources and the remaining passes are delayed.
    observer: Observed through function failure alert; window-expired informational exceptions.
    provenance: observed
    source: 'services-commerce:modules/orders/services/orders/tender-window-sweeper.ts:sweepTenderWindows'
  - 'n': 4
    actor_or_service: Register pass (fulfilment module)
    action: Delegate stale obligation evaluation and overdue authorization handling to fulfilment's register pass.
    anchor: 'services-commerce:modules/fulfillment/services/register/register-sweeper.ts:sweepRegister'
    seam: schedule
    on_failure: A propagated register error terminates the shared invocation.
    left_inconsistent: Financial and later passes have not run.
    observer: Observed through failure activates the function error alarm.
    provenance: observed
    source: 'services-commerce:modules/checkout/aws/lambda/SWEEPER.ts:handler'
  - 'n': 5
    actor_or_service: Financial passes
    action: >-
      Run billing recovery, uncertain-payment recovery and stale mirror refresh, synchronizing installment
      schedules where needed.
    anchor: 'services-commerce:modules/orders/services/orders/financial-sweeps.ts:sweepFinancials'
    seam: schedule
    on_failure: Each order failure is logged without stopping the pass; unconfigured Accounting skips financial work.
    left_inconsistent: The failed order waits for another invocation.
    observer: Observed through observed through operational exceptions; sweep results in the log.
    provenance: observed
    source: 'services-commerce:modules/orders/services/orders/financial-sweeps.ts:sweepFinancials'
  - 'n': 6
    actor_or_service: Entitlement expiry pass
    action: Record expiry for active grants beyond their validity end.
    anchor: 'services-commerce:modules/entitlements/services/register/entitlement-sweeper.ts:sweepEntitlements'
    seam: schedule
    on_failure: Changed grants are skipped; unexpected failures stop the invocation.
    left_inconsistent: 'Stored state can remain active, although consumption checks the expired window.'
    observer: Observed through failure activates the function error alarm.
    provenance: observed
    source: 'services-commerce:modules/entitlements/services/register/entitlement-sweeper.ts:sweepEntitlements'
  - 'n': 7
    actor_or_service: Idempotency purge
    action: 'During the daily early-morning window, purge old completed request keys and expired ledger claims.'
    anchor: 'services-commerce:aws/commerce.idempotency.ts:isIdempotencyPurgeDue'
    seam: schedule
    on_failure: 'If the window is missed, the next eligible daily invocation must perform cleanup.'
    left_inconsistent: Expired ledger data remains stored longer.
    observer: Observed through the function log records the outcome.
    provenance: observed
    source: 'services-commerce:modules/checkout/aws/lambda/SWEEPER.ts:handler'
branches:
  - >-
    A separate operations reconciler runs each minute, records exceptions and resumes stale adjustments
    without taking over these checkout passes.
waits: []
evidence:
  - >-
    services-commerce at c8b66a98: modules/checkout/aws/lambda/SWEEPER.ts, aws/checkout.module.ts,
    aws/logic/checkout-sweeper.lambda.ts; services/checkout/checkout-sweeper.ts;
    modules/orders/services/reservations/reservation-sweeper.ts, services/orders/tender-window-sweeper.ts,
    financial-sweeps.ts; modules/entitlements/services/register/entitlement-sweeper.ts;
    aws/commerce.idempotency.ts; modules/operations/services/reconciler/reconciler.ts.
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-TEN-004, TC-CRY-001, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, 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]
---

# Run the every-minute sweeps

## What It Does

One scheduled invocation coordinates the module's timed processing. It handles cart and reservation expiry, payment deadlines, register work, financial recovery, grant expiry and daily request-ledger cleanup.

## The Flow

```mermaid
sequenceDiagram
  participant R as Schedule (every minute)
  participant S as Sweeper
  participant DB as Commerce database
  participant X as Accounting
  R->>S: invoke (one at a time)
  S->>DB: carts past expiry: abandon
  S->>DB: holds past expiry: expire; leases: confirm
  S->>DB: orders past window: void
  S->>DB: register: stale obligations
  S->>X: billing retry, uncertain payments, mirrors
  S->>DB: grants past window: expire
  S->>DB: idempotency purge (03:00 UTC)
```

## When Something Fails

The invocation runs passes sequentially. Financial passes isolate individual order failures, while propagated earlier errors can prevent all later passes. An oldest failing record can recur and starve unrelated recovery. Unconfigured Accounting skips financial work.

## Open Design Questions

The product should require isolation between records and passes and a visible signal for persistent failures before relying on the schedule for recovery.