Project Detected: Node.js TypeScript billing service using PostgreSQL, Prisma, a payment-provider SDK, and BullMQ --- Operation Reviewed: - Operation: Payment capture for an approved invoice - External side effect: Provider creates a card charge - Current retry path: HTTP timeout causes the API route to mark payment failed, while BullMQ retries with a new provider idempotency key --- Unknown Outcome Found: - The provider may accept the charge before the client times out - Ambiguity trigger: Response timeout after request transmission - Duplicate-side-effect risk: A retry with a new idempotency key can create a second charge --- Ambiguity Boundary: - Local operation identity: Stable payment_attempt UUID linked to invoice and amount - Provider reference: Merchant payment_attempt UUID stored in provider metadata - Idempotency support: Provider supports one idempotency key per logical capture - Authoritative lookup: Retrieve payment by merchant reference or idempotency result --- Reconciliation Contract: - Initial state: Timeout moves the payment attempt from in_flight to unknown - Reconciliation method: BullMQ retrieves the provider payment using the stored merchant reference - Retry decision: Retry only with the original idempotency key when the provider confirms no accepted payment - Maximum window: Twelve reconciliation attempts over 30 minutes - Manual-review condition: Provider lookup remains unavailable after the reconciliation window or returns conflicting payments --- Repair Applied: - Intent persistence: Payment attempt and idempotency key are committed before provider execution - Unknown-state handling: Timeout no longer marks the payment failed or releases the invoice for another charge - Reconciliation: Added a bounded reconciliation worker and verified webhook resolution - Duplicate protection: Invoice completion and receipt creation use unique payment-attempt keys --- Files Modified: - prisma/schema.prisma - src/payments/paymentAttemptService.ts - src/payments/providerClient.ts - src/payments/paymentReconciliationWorker.ts - src/payments/paymentWebhookHandler.ts - src/invoices/invoicePaymentService.ts - tests/paymentUnknownOutcome.test.ts --- Commands Executed: - npx prisma validate - npm run typecheck - npm test -- tests/paymentUnknownOutcome.test.ts - npm run build --- Timeout Simulation: - Failure point: Provider accepted the capture, but the client response was dropped - Local state after timeout: unknown - Blind retries performed: 0 --- Reconciliation Test: - Provider result: Existing successful charge found by merchant reference - Final local state: confirmed_succeeded - Provider operations created: 1 --- Duplicate-Side-Effect Test: - Confirmations delivered: API response retry, two reconciliation jobs, and duplicate webhook - Local completion effects: 1 invoice payment and 1 receipt - Duplicate external effects: 0 --- Validation Result: Schema validation, type checking, 27 timeout and reconciliation tests, and the production build completed successfully using an isolated database and mocked payment provider. No live charge was created. --- Remaining Risks: - The provider’s production idempotency-retention period and lookup-index delay require sandbox verification --- Important Notes: The repair preserves the same idempotency key across retries. Payment status remains pending rather than failed while the provider result is unknown.