reliability-and-state-integrity

Add an existence check for the confirmed payment record inside a database transaction before processing. If the payment is already confirmed, return 200 without re-running charge logic, so duplicate webhook deliveries are safely ignored.

Use db.transaction with an async callback containing all critical inserts and updates, so any failure rolls back the entire write. Keep notifications, AI calls, and analytics outside the transaction body so side effects only run after commit.

The operation is not idempotent. Add a UNIQUE constraint on the natural key, such as userId plus poolId, and check for an existing record before inserting within the transaction so retries return the original result.

A guard left at isRunning true blocks future runs. Always release the guard in a finally block and add a timeout-based stale guard reset so crash recovery can clear it automatically.

Check expiry on every read using a server-side Date.now comparison against the expiry timestamp. A sweep is only cleanup; read-time enforcement prevents users from seeing expired state as valid when the sweep is delayed.

Side effects must run after the transaction commits, never inside it. Commit the critical write first, then send notifications or AI enrichment, and treat failed side effects as best-effort so they never roll back committed data.