cabloy 5.1.124 → 5.1.126

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/bean/meta.index.ts

@@ -12,7 +12,9 @@ import { $tableColumns } from 'vona-module-a-ormutils';
     ...$tableColumns('payPaymentSession', 'providerOrderId'),
     ...$tableColumns('payPaymentSession', 'providerCaptureId'),
     ...$tableColumns('payProviderOperation', 'paymentSessionId+kind'),
+    ...$tableColumns('payProviderOperation', 'refundOperationId'),
     ...$tableColumns('payProviderOperation', 'state+nextAttemptAt'),
+    ...$tableColumns('payProviderOperation', 'state+claimExpiresAt'),
     ...$tableColumns('payProviderOperation', 'idempotencyKey'),
     ...$tableColumns('payRefundOperation', 'paymentSessionId'),
     ...$tableColumns('payRefundOperation', 'state'),
@@ -21,6 +23,7 @@ import { $tableColumns } from 'vona-module-a-ormutils';
     ...$tableColumns('payWebhookInbox', 'paymentSessionId'),
     ...$tableColumns('payWebhookInbox', 'state'),
     ...$tableColumns('payPaymentAudit', 'paymentSessionId'),
+    ...$tableColumns('payOutboxEvent', 'refundOperationId'),
     ...$tableColumns('payOutboxEvent', 'state+nextAttemptAt'),
     ...$tableColumns('payOutboxEvent', 'state+claimExpiresAt'),
   },

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/bean/meta.redlock.ts

@@ -1,7 +1,9 @@
 import { Meta } from 'vona-module-a-meta';
 import { BeanRedlockBase } from 'vona-module-a-redlock';
 
-export type TypeRedlockLockResource = `pay.webhook.${string}`;
+export type TypeRedlockLockResource =
+  | `pay.providerOperation.start.${string}`
+  | `pay.webhook.${string}`;
 export type TypeRedlockLockIsolateResource = never;
 
 @Meta()

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/bean/meta.version.ts

@@ -33,6 +33,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
     await this.bean.model.createTable(providerOperation.$table, table => {
       table.basicFields();
       table.tableIdentity(providerOperation.paymentSessionId);
+      table.tableIdentity(providerOperation.refundOperationId);
       table.string(providerOperation.kind, 32);
       table.string(providerOperation.state, 32);
       table.string(providerOperation.idempotencyKey, 100);
@@ -41,6 +42,9 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
       table.string(providerOperation.providerResourceId, 255);
       table.integer(providerOperation.attemptCount);
       table.dateTime(providerOperation.claimedAt);
+      table.string(providerOperation.claimToken, 100);
+      table.dateTime(providerOperation.claimExpiresAt);
+      table.dateTime(providerOperation.submittedAt);
       table.dateTime(providerOperation.nextAttemptAt);
       table.string(providerOperation.errorCode, 100);
       table.string(providerOperation.errorSummary, 255);
@@ -71,9 +75,11 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
       table.tableIdentity(webhookInbox.paymentSessionId);
       table.tableIdentity(webhookInbox.refundOperationId);
       table.string(webhookInbox.paymentState, 32);
+      table.string(webhookInbox.refundState, 32);
       table.integer(webhookInbox.amountMinor);
       table.string(webhookInbox.currency, 3);
       table.string(webhookInbox.providerCaptureId, 255);
+      table.string(webhookInbox.providerRefundId, 255);
       table.string(webhookInbox.payloadHash, 64);
       table.string(webhookInbox.state, 32);
       table.integer(webhookInbox.retryCount);
@@ -99,6 +105,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate {
       table.basicFields();
       table.string(outboxEvent.eventType, 100);
       table.tableIdentity(outboxEvent.paymentSessionId);
+      table.tableIdentity(outboxEvent.refundOperationId);
       table.json(outboxEvent.payload);
       table.string(outboxEvent.state, 32);
       table.integer(outboxEvent.attemptCount);

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/bean/queue.outboxDispatch.ts

@@ -3,6 +3,8 @@ import type { IQueueExecute, IQueuePushOptions } from 'vona-module-a-queue';
 
 import { BeanQueueBase, Queue } from 'vona-module-a-queue';
 
+import type { IPaymentOutcomeEvent, IRefundOutcomeEvent } from '../types/payment.ts';
+
 export interface IOutboxDispatchJobData {
   outboxEventId: TableIdentity;
 }
@@ -16,13 +18,16 @@ export class QueueOutboxDispatch
     const event = await this.scope.service.outbox.claim(data.outboxEventId);
     if (!event) return;
     try {
-      if (event.eventType !== 'payment.outcome.v1') {
-        this.app.throw(409, `unsupported payment outbox event: ${event.eventType}`);
-      }
       const session = await this.scope.model.paymentSession.getById(event.paymentSessionId);
       if (!session) this.app.throw(404, 'payment session not found');
       const payScene = this.bean.payScene.get(session.payScene as never);
-      await payScene.onPaymentOutcome(event.payload);
+      if (event.eventType === 'payment.outcome.v1') {
+        await payScene.onPaymentOutcome(event.payload as IPaymentOutcomeEvent);
+      } else if (event.eventType === 'refund.outcome.v1') {
+        await payScene.onRefundOutcome(event.payload as IRefundOutcomeEvent);
+      } else {
+        this.app.throw(409, `unsupported payment outbox event: ${event.eventType}`);
+      }
       await this.scope.service.outbox.markDispatched(event.id, event.claimToken!);
     } catch (error) {
       await this.scope.service.outbox.release(event.id, event.claimToken!, error);

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/bean/schedule.providerOperationDispatch.ts

@@ -0,0 +1,11 @@
+import type { IScheduleExecute } from 'vona-module-a-schedule';
+
+import { BeanBase } from 'vona';
+import { Schedule } from 'vona-module-a-schedule';
+
+@Schedule({ repeat: { every: 60 * 1000 } })
+export class ScheduleProviderOperationDispatch extends BeanBase implements IScheduleExecute {
+  async execute() {
+    await this.scope.service.providerOperation.queueDue();
+  }
+}

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/entity/outboxEvent.tsx

@@ -5,20 +5,27 @@ import { Api, v } from 'vona-module-a-openapiutils';
 import { Entity, EntityBase } from 'vona-module-a-orm';
 import { z } from 'zod';
 
-import type { IPaymentOutcomeEvent, TypeOutboxEventState } from '../types/payment.ts';
+import type {
+  IPaymentOutcomeEvent,
+  IRefundOutcomeEvent,
+  TypeOutboxEventState,
+} from '../types/payment.ts';
 
 export interface IEntityOptionsOutboxEvent extends IDecoratorEntityOptions {}
 
 @Entity<IEntityOptionsOutboxEvent>('payOutboxEvent')
 export class EntityOutboxEvent extends EntityBase {
-  @Api.field(z.literal('payment.outcome.v1'))
-  eventType: 'payment.outcome.v1';
+  @Api.field(z.enum(['payment.outcome.v1', 'refund.outcome.v1']))
+  eventType: 'payment.outcome.v1' | 'refund.outcome.v1';
 
   @Api.field(v.tableIdentity())
   paymentSessionId: TableIdentity;
 
+  @Api.field(v.optional(), v.tableIdentity())
+  refundOperationId?: TableIdentity;
+
   @Api.field(v.required())
-  payload: IPaymentOutcomeEvent;
+  payload: IPaymentOutcomeEvent | IRefundOutcomeEvent;
 
   @Api.field(z.enum(['pending', 'claimed', 'dispatched', 'failed']))
   state: TypeOutboxEventState;

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/entity/providerOperation.tsx

@@ -14,6 +14,9 @@ export class EntityProviderOperation extends EntityBase {
   @Api.field(v.tableIdentity())
   paymentSessionId: TableIdentity;
 
+  @Api.field(v.optional(), v.tableIdentity())
+  refundOperationId?: TableIdentity;
+
   @Api.field(z.enum(['start', 'confirm', 'query', 'refund']))
   kind: TypeProviderOperationKind;
 
@@ -40,6 +43,15 @@ export class EntityProviderOperation extends EntityBase {
   @Api.field(v.optional())
   claimedAt?: Date;
 
+  @Api.field(v.optional(), v.max(100))
+  claimToken?: string;
+
+  @Api.field(v.optional())
+  claimExpiresAt?: Date;
+
+  @Api.field(v.optional())
+  submittedAt?: Date;
+
   @Api.field(v.optional())
   nextAttemptAt?: Date;
 

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/entity/webhookInbox.tsx

@@ -33,6 +33,9 @@ export class EntityWebhookInbox extends EntityBase {
   @Api.field(v.optional(), z.enum(['succeeded', 'failed', 'cancelled']))
   paymentState?: 'succeeded' | 'failed' | 'cancelled';
 
+  @Api.field(v.optional(), z.enum(['pending', 'succeeded', 'failed', 'cancelled']))
+  refundState?: 'pending' | 'succeeded' | 'failed' | 'cancelled';
+
   @Api.field(v.optional(), z.number().int().nonnegative())
   amountMinor?: number;
 
@@ -42,6 +45,9 @@ export class EntityWebhookInbox extends EntityBase {
   @Api.field(v.optional(), v.max(255))
   providerCaptureId?: string;
 
+  @Api.field(v.optional(), v.max(255))
+  providerRefundId?: string;
+
   @Api.field(v.required(), v.min(64), v.max(64))
   payloadHash: string;
 

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/outbox.ts

@@ -5,7 +5,7 @@ import { BeanBase } from 'vona';
 import { Service } from 'vona-module-a-bean';
 import { Core } from 'vona-module-a-core';
 
-import type { IPaymentOutcomeEvent } from '../types/payment.ts';
+import type { IPaymentOutcomeEvent, IRefundOutcomeEvent } from '../types/payment.ts';
 
 const ClaimLeaseMilliseconds = 60_000;
 const MaxAttempts = 10;
@@ -14,16 +14,21 @@ const MaxAttempts = 10;
 export class ServiceOutbox extends BeanBase {
   async enqueue(
     paymentSessionId: TableIdentity,
-    eventType: 'payment.outcome.v1',
-    payload: IPaymentOutcomeEvent,
+    eventType: 'payment.outcome.v1' | 'refund.outcome.v1',
+    payload: IPaymentOutcomeEvent | IRefundOutcomeEvent,
   ) {
     const event = await this.scope.model.outboxEvent.insert({
       eventType,
       paymentSessionId,
+      refundOperationId:
+        eventType === 'refund.outcome.v1'
+          ? (payload as IRefundOutcomeEvent).refundOperationId
+          : undefined,
       payload,
       state: 'pending',
       attemptCount: 0,
-      nextAttemptAt: new Date(),
+      // Keep newly committed events due after database timestamp precision is applied.
+      nextAttemptAt: new Date(Date.now() - 1_000),
     });
     if (!this.app.meta.isTest) {
       this.ctx.db.commit(() => {
@@ -102,7 +107,9 @@ export class ServiceOutbox extends BeanBase {
       });
       return { ...event, state: 'failed' as const, errorSummary };
     }
-    const nextAttemptAt = new Date(Date.now() + retryDelayMilliseconds(event.attemptCount));
+    const nextAttemptAt = new Date(
+      Math.ceil((Date.now() + retryDelayMilliseconds(event.attemptCount)) / 1_000) * 1_000,
+    );
     await this.scope.model.outboxEvent.updateById(event.id, {
       state: 'pending',
       claimedAt: undefined,

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentSession.ts

@@ -77,35 +77,7 @@ export class ServicePaymentSession extends BeanBase {
   }
 
   async start(paymentSessionId: TableIdentity): Promise<EntityPaymentSession> {
-    const session = await this.beginStart(paymentSessionId);
-    const { provider, clientOptions } = this.bean.payProvider.resolveByName(
-      session.providerName,
-      session.clientName,
-    );
-    if (clientOptions.environment !== session.environment) {
-      this.app.throw(500, 'payment session provider environment is inconsistent');
-    }
-    const snapshot = await provider.startPayment(
-      {
-        paymentSessionId: session.id,
-        businessReference: session.businessReference,
-        idempotencyKey: `${session.correlationId}:start`,
-        amountMinor: session.amountMinor,
-        currency: session.currency,
-        providerOrderId: session.providerOrderId,
-      },
-      clientOptions,
-    );
-    if (isTerminalPaymentSnapshot(snapshot)) {
-      return await this.settleStartSnapshot(session.id, snapshot);
-    }
-    return await this.transition(session.id, snapshot.state, {
-      nextAction: snapshot.nextAction,
-      providerPaymentId: snapshot.providerPaymentId,
-      providerOrderId: snapshot.providerOrderId,
-      providerCaptureId: snapshot.providerCaptureId,
-      source: 'paymentSession.startProvider',
-    });
+    return await this.scope.service.providerOperation.start(paymentSessionId);
   }
 
   @Core.transaction()
@@ -268,11 +240,3 @@ export class ServicePaymentSession extends BeanBase {
     return { ...session, ...options, state, finalizedAt };
   }
 }
-
-function isTerminalPaymentSnapshot(
-  snapshot: IPayProviderPaymentSnapshot,
-): snapshot is IPayProviderPaymentSnapshot & {
-  state: 'succeeded' | 'failed' | 'cancelled';
-} {
-  return ['succeeded', 'failed', 'cancelled'].includes(snapshot.state);
-}

package/vona/src/suite-vendor/a-pay/modules/a-pay/src/service/providerOperation.ts

@@ -1,5 +1,359 @@
+import type { TableIdentity } from 'table-identity';
+
+import { randomUUID } from 'node:crypto';
 import { BeanBase } from 'vona';
 import { Service } from 'vona-module-a-bean';
+import { Core } from 'vona-module-a-core';
+
+import type { EntityPaymentSession } from '../entity/paymentSession.tsx';
+import type { EntityProviderOperation } from '../entity/providerOperation.tsx';
+import type { IPayProviderPaymentSnapshot } from '../types/payment.ts';
+
+const ClaimLeaseMilliseconds = 60_000;
+const MaxAttempts = 10;
 
 @Service()
-export class ServiceProviderOperation extends BeanBase {}
+export class ServiceProviderOperation extends BeanBase {
+  async start(paymentSessionId: TableIdentity): Promise<EntityPaymentSession> {
+    return await this.scope.redlock.lock(
+      `pay.providerOperation.start.${paymentSessionId}`,
+      async () => {
+        const operation = await this.ensureStart(paymentSessionId);
+        await this.execute(operation.id);
+        const session = await this.scope.model.paymentSession.getById(paymentSessionId);
+        if (!session) this.app.throw(404, 'payment session not found');
+        return session;
+      },
+    );
+  }
+
+  @Core.transaction()
+  async ensureStart(paymentSessionId: TableIdentity): Promise<EntityProviderOperation> {
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(paymentSessionId);
+    if (!session) this.app.throw(404, 'payment session not found');
+
+    const existing = await this.scope.model.providerOperation.getForUpdate({
+      paymentSessionId: session.id,
+      kind: 'start',
+    });
+    if (existing) return existing;
+    if (session.state !== 'created') this.app.throw(409, 'payment session is not ready to start');
+    if (session.expiresAt <= new Date()) this.app.throw(409, 'payment session is expired');
+
+    const now = new Date();
+    await this.scope.model.paymentSession.updateById(session.id, { state: 'starting' });
+    await this.scope.model.paymentAudit.insert({
+      paymentSessionId: session.id,
+      fromState: session.state,
+      toState: 'starting',
+      correlationId: session.correlationId,
+      source: 'providerOperation.start',
+      occurredAt: now,
+    });
+    return await this.scope.model.providerOperation.insert({
+      paymentSessionId: session.id,
+      kind: 'start',
+      state: 'created',
+      idempotencyKey: `${session.correlationId}:start`,
+      correlationId: session.correlationId,
+      attemptCount: 0,
+      nextAttemptAt: new Date(now.getTime() - 1_000),
+    });
+  }
+
+  async execute(providerOperationId: TableIdentity) {
+    const operation = await this.claim(providerOperationId);
+    if (!operation) return undefined;
+    try {
+      const session = await this.scope.model.paymentSession.getById(operation.paymentSessionId);
+      if (!session) this.app.throw(404, 'payment session not found');
+      const { provider, clientOptions } = this.bean.payProvider.resolveByName(
+        session.providerName,
+        session.clientName,
+      );
+      if (clientOptions.environment !== session.environment) {
+        this.app.throw(500, 'payment session provider environment is inconsistent');
+      }
+      const isReconciliation =
+        operation.state === 'reconciliation_required' ||
+        operation.state === 'claimed' ||
+        operation.state === 'submitted';
+      await this.markSubmitted(operation.id, operation.claimToken!);
+      if (operation.kind === 'refund') {
+        const refundOperationId = operation.refundOperationId;
+        if (!refundOperationId) this.app.throw(500, 'refund provider operation is not linked');
+        const refund = await this.scope.model.refundOperation.getById(refundOperationId);
+        if (!refund) this.app.throw(404, 'refund operation not found');
+        if (!session.providerCaptureId)
+          this.app.throw(409, 'payment session has no provider capture');
+        const input = {
+          paymentSessionId: session.id,
+          refundOperationId: refund.id,
+          businessReference: refund.businessReference,
+          idempotencyKey: operation.idempotencyKey,
+          amountMinor: refund.amountMinor,
+          currency: refund.currency,
+          providerCaptureId: session.providerCaptureId,
+        };
+        const snapshot =
+          isReconciliation && provider.queryRefund
+            ? await provider.queryRefund(input, clientOptions)
+            : await provider.createRefund(input, clientOptions);
+        await this.scope.service.refundOperation.settleProviderSnapshot(
+          operation.id,
+          operation.claimToken!,
+          snapshot,
+        );
+        return snapshot;
+      }
+      const input = {
+        paymentSessionId: session.id,
+        businessReference: session.businessReference,
+        idempotencyKey: operation.idempotencyKey,
+        amountMinor: session.amountMinor,
+        currency: session.currency,
+        providerOrderId: session.providerOrderId,
+      };
+      const snapshot =
+        operation.state === 'reconciliation_required'
+          ? await provider.queryPayment(input, clientOptions)
+          : await provider.startPayment(input, clientOptions);
+      await this.settlePaymentSnapshot(operation.id, operation.claimToken!, snapshot);
+      return snapshot;
+    } catch (error) {
+      await this.releaseForReconciliation(operation.id, operation.claimToken!, error);
+      return undefined;
+    }
+  }
+
+  @Core.transaction()
+  async claim(id: TableIdentity) {
+    const operation = await this.scope.model.providerOperation.getByIdForUpdate(id);
+    if (!operation || ['succeeded', 'failed'].includes(operation.state)) return undefined;
+    const now = new Date();
+    const eligible =
+      (operation.state === 'created' &&
+        (!operation.nextAttemptAt || operation.nextAttemptAt <= now)) ||
+      (operation.state === 'reconciliation_required' &&
+        (!operation.nextAttemptAt || operation.nextAttemptAt <= now)) ||
+      (['claimed', 'submitted'].includes(operation.state) &&
+        !!operation.claimExpiresAt &&
+        operation.claimExpiresAt <= now);
+    if (!eligible) return undefined;
+    if (operation.attemptCount >= MaxAttempts) {
+      await this.scope.model.providerOperation.updateById(operation.id, {
+        state: 'failed',
+        finalizedAt: now,
+        errorSummary: 'provider operation attempts exhausted',
+      });
+      return undefined;
+    }
+    const claimToken = randomUUID();
+    const claimExpiresAt = new Date(now.getTime() + ClaimLeaseMilliseconds);
+    await this.scope.model.providerOperation.updateById(operation.id, {
+      state: 'claimed',
+      claimedAt: now,
+      claimToken,
+      claimExpiresAt,
+      attemptCount: operation.attemptCount + 1,
+      errorCode: undefined,
+      errorSummary: undefined,
+    });
+    return {
+      ...operation,
+      state: operation.state,
+      claimedAt: now,
+      claimToken,
+      claimExpiresAt,
+      attemptCount: operation.attemptCount + 1,
+    };
+  }
+
+  @Core.transaction()
+  async markSubmitted(id: TableIdentity, claimToken: string) {
+    const operation = await this.scope.model.providerOperation.getByIdForUpdate(id);
+    if (!operation || operation.state !== 'claimed' || operation.claimToken !== claimToken)
+      return undefined;
+    const submittedAt = new Date();
+    await this.scope.model.providerOperation.updateById(operation.id, {
+      state: 'submitted',
+      submittedAt,
+    });
+    return { ...operation, state: 'submitted' as const, submittedAt };
+  }
+
+  @Core.transaction()
+  async settlePaymentSnapshot(
+    id: TableIdentity,
+    claimToken: string,
+    snapshot: IPayProviderPaymentSnapshot,
+  ) {
+    const operation = await this.scope.model.providerOperation.getByIdForUpdate(id);
+    if (
+      !operation ||
+      !['claimed', 'submitted'].includes(operation.state) ||
+      operation.claimToken !== claimToken
+    ) {
+      return undefined;
+    }
+    const session = await this.scope.model.paymentSession.getByIdForUpdate(
+      operation.paymentSessionId,
+    );
+    if (!session) this.app.throw(404, 'payment session not found');
+    if (['succeeded', 'failed', 'cancelled', 'expired'].includes(session.state)) {
+      await this._complete(operation, {
+        providerResourceId: snapshot.providerCaptureId ?? snapshot.providerOrderId,
+      });
+      return session;
+    }
+
+    if (isTerminalPaymentState(snapshot.state)) {
+      const finalizedAt = new Date();
+      await this.scope.model.paymentSession.updateById(session.id, {
+        state: snapshot.state,
+        nextAction: snapshot.nextAction,
+        providerPaymentId: snapshot.providerPaymentId,
+        providerOrderId: snapshot.providerOrderId,
+        providerCaptureId: snapshot.providerCaptureId,
+        finalizedAt,
+      });
+      await this.scope.model.paymentAudit.insert({
+        paymentSessionId: session.id,
+        providerOperationId: operation.id,
+        fromState: session.state,
+        toState: snapshot.state,
+        correlationId: session.correlationId,
+        source: 'providerOperation',
+        occurredAt: finalizedAt,
+      });
+      await this.scope.service.outbox.enqueue(session.id, 'payment.outcome.v1', {
+        eventId: `${operation.correlationId}:${operation.kind}`,
+        paymentSessionId: session.id,
+        businessReference: session.businessReference,
+        providerName: session.providerName,
+        state: snapshot.state,
+        providerCaptureId: snapshot.providerCaptureId,
+        amountMinor: session.amountMinor,
+        currency: session.currency,
+      });
+    } else {
+      await this.scope.model.paymentSession.updateById(session.id, {
+        state: snapshot.state,
+        nextAction: snapshot.nextAction,
+        providerPaymentId: snapshot.providerPaymentId,
+        providerOrderId: snapshot.providerOrderId,
+        providerCaptureId: snapshot.providerCaptureId,
+      });
+      await this.scope.model.paymentAudit.insert({
+        paymentSessionId: session.id,
+        providerOperationId: operation.id,
+        fromState: session.state,
+        toState: snapshot.state,
+        correlationId: session.correlationId,
+        source: 'providerOperation',
+        occurredAt: new Date(),
+      });
+    }
+    await this._complete(operation, {
+      providerResourceId: snapshot.providerCaptureId ?? snapshot.providerOrderId,
+    });
+    return { ...session, ...snapshot };
+  }
+
+  @Core.transaction()
+  async releaseForReconciliation(id: TableIdentity, claimToken: string, error: unknown) {
+    const operation = await this.scope.model.providerOperation.getByIdForUpdate(id);
+    if (
+      !operation ||
+      !['claimed', 'submitted'].includes(operation.state) ||
+      operation.claimToken !== claimToken
+    ) {
+      return undefined;
+    }
+    const errorSummary = summarizeError(error);
+    const now = new Date();
+    if (operation.attemptCount >= MaxAttempts) {
+      await this.scope.model.providerOperation.updateById(operation.id, {
+        state: 'failed',
+        claimToken: undefined,
+        claimExpiresAt: undefined,
+        finalizedAt: now,
+        errorSummary,
+      });
+      return undefined;
+    }
+    const nextAttemptAt = new Date(
+      Math.ceil((now.getTime() + retryDelayMilliseconds(operation.attemptCount)) / 1_000) * 1_000,
+    );
+    await this.scope.model.providerOperation.updateById(operation.id, {
+      state: 'reconciliation_required',
+      claimToken: undefined,
+      claimExpiresAt: undefined,
+      nextAttemptAt,
+      errorSummary,
+    });
+    return { ...operation, state: 'reconciliation_required' as const, nextAttemptAt, errorSummary };
+  }
+
+  async queueDue(limit = 100) {
+    const now = new Date();
+    const due = await this.scope.model.providerOperation.select({
+      where: {
+        state: ['created', 'reconciliation_required'],
+        nextAttemptAt: { _lte_: now },
+      },
+      orders: [
+        ['nextAttemptAt', 'asc'],
+        ['id', 'asc'],
+      ],
+      limit,
+    });
+    const expiredClaims = await this.scope.model.providerOperation.select({
+      where: {
+        state: ['claimed', 'submitted'],
+        claimExpiresAt: { _lte_: now },
+      },
+      orders: [
+        ['claimExpiresAt', 'asc'],
+        ['id', 'asc'],
+      ],
+      limit: Math.max(0, limit - due.length),
+    });
+    const operations = [...due, ...expiredClaims];
+    for (const operation of operations) {
+      await this.execute(operation.id);
+    }
+    return operations.length;
+  }
+
+  private async _complete(
+    operation: EntityProviderOperation,
+    options: { providerResourceId?: string },
+  ) {
+    await this.scope.model.providerOperation.updateById(operation.id, {
+      state: 'succeeded',
+      providerResourceId: options.providerResourceId,
+      claimToken: undefined,
+      claimExpiresAt: undefined,
+      nextAttemptAt: undefined,
+      finalizedAt: new Date(),
+      errorCode: undefined,
+      errorSummary: undefined,
+    });
+  }
+}
+
+function isTerminalPaymentState(
+  state: IPayProviderPaymentSnapshot['state'],
+): state is 'succeeded' | 'failed' | 'cancelled' {
+  return ['succeeded', 'failed', 'cancelled'].includes(state);
+}
+
+function retryDelayMilliseconds(attemptCount: number) {
+  return Math.min(60_000, 1_000 * 2 ** Math.max(0, attemptCount - 1));
+}
+
+function summarizeError(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.slice(0, 255);
+}