PM-4958: Release engagement BA consumption on cancellation

What was broken
Cancelling an engagement payment from wallet-admin updated the finance payment status, but the engagement consumed row in the billing-account ledger stayed in place. The BA details modal still showed the cancelled engagement amount as consumed.

Root cause (if identifiable)
The previous PM-4958 fix only recalculated challenge payment budget rows. Engagement payments were explicitly excluded from that path, and their BA consumed rows are maintained separately from challenge budget rows.

What was changed
Added wallet-admin cancellation handling for engagement payments. After the finance status transaction succeeds, the admin service now recalculates the active non-cancelled engagement ledger amounts and asks the billing-account service to sync the matching consumed rows, deleting stale rows when cancelled payments should no longer reserve budget. The sync supports both the legacy challengeId BA ledger shape and the newer typed externalId/externalType shape.

Any added/updated tests
Added AdminService coverage for engagement payment cancellation triggering BA sync. Added BillingAccountsService coverage for deleting stale engagement consumed rows, syncing active typed rows, and syncing legacy aggregate rows.

Author: jmgasper

src/api/admin/admin.service.spec.ts

@@ -74,6 +74,7 @@ describe('AdminService', () => {
     getBillingAccountById: jest.Mock;
     getBillingAccountsForUser: jest.Mock;
     lockConsumeAmount: jest.Mock;
+    syncEngagementConsumeAmounts: jest.Mock;
   };
   let accessControlService: {
     verifyAccess: jest.Mock;
@@ -120,6 +121,7 @@ describe('AdminService', () => {
         .mockResolvedValue({ id: 80001012, markup: 0.1 }),
       getBillingAccountsForUser: jest.fn().mockResolvedValue(['80001012']),
       lockConsumeAmount: jest.fn().mockResolvedValue(undefined),
+      syncEngagementConsumeAmounts: jest.fn().mockResolvedValue(undefined),
     };
     accessControlService = {
       verifyAccess: jest.fn().mockResolvedValue(undefined),
@@ -457,6 +459,62 @@ describe('AdminService', () => {
     });
   });
 
+  it('releases engagement billing-account rows when an engagement payment is cancelled', async () => {
+    prisma.payment.findMany
+      .mockResolvedValueOnce([
+        {
+          billing_account: '80001012',
+          currency: 'USD',
+          installment_number: 1,
+          payment_id: 'payment-1',
+          payment_status: PaymentStatus.OWED,
+          release_date: new Date('2026-04-28T00:00:00.000Z'),
+          version: 1,
+          winnings: {
+            category: 'ENGAGEMENT_PAYMENT',
+            external_id: 'assignment-1',
+            type: 'PAYMENT',
+          },
+        },
+      ])
+      .mockResolvedValueOnce([]);
+
+    const result = await service.updateWinnings(
+      {
+        paymentId: 'payment-1',
+        paymentStatus: PaymentStatus.CANCELLED,
+        winningsId: 'winning-1',
+      } as any,
+      'admin-1',
+      ['Payment Admin'],
+    );
+
+    expect(result.data).toBe('Successfully updated winnings');
+    expect(prisma.payment.findMany).toHaveBeenNthCalledWith(2, {
+      select: {
+        challenge_fee: true,
+        total_amount: true,
+      },
+      where: {
+        billing_account: '80001012',
+        currency: 'USD',
+        payment_status: { not: PaymentStatus.CANCELLED },
+        winnings: {
+          category: 'ENGAGEMENT_PAYMENT',
+          external_id: 'assignment-1',
+          type: 'PAYMENT',
+        },
+      },
+      orderBy: [{ created_at: 'asc' }, { payment_id: 'asc' }],
+    });
+    expect(baService.syncEngagementConsumeAmounts).toHaveBeenCalledWith({
+      amounts: [],
+      billingAccountId: 80001012,
+      externalId: 'assignment-1',
+    });
+    expect(baService.lockConsumeAmount).not.toHaveBeenCalled();
+  });
+
   it('returns task details for task payment with projectId and approver', async () => {
     prisma.winnings.findFirst.mockResolvedValue({
       winning_id: 'winning-task',

src/api/admin/admin.service.ts

@@ -36,12 +36,18 @@ import {
 import { WinningPaymentDetailsDto } from './dto/payment-details.dto';
 
 const PAYMENT_DECIMAL_PLACES = 2;
+const BUDGET_LEDGER_DECIMAL_PLACES = 4;
 
 interface ChallengeBudgetSyncTarget {
   billingAccountId: number;
   challengeId: string;
 }
 
+interface EngagementBudgetSyncTarget {
+  assignmentId: string;
+  billingAccountId: number;
+}
+
 /**
  * The admin winning service.
  */
@@ -394,6 +400,55 @@ export class AdminService {
     return [...targets.values()];
   }
 
+  /**
+   * Finds engagement billing-account rows that need to be reconciled after a
+   * wallet-admin payment status change.
+   *
+   * @param payments payment rows selected by the update request.
+   * @returns unique engagement assignment and billing-account pairs touched by
+   * USD engagement payments.
+   * @throws This helper does not throw.
+   */
+  private getEngagementBudgetSyncTargets(
+    payments: Awaited<ReturnType<AdminService['getPaymentsByWinningsId']>>,
+  ): EngagementBudgetSyncTarget[] {
+    const targets = new Map<string, EngagementBudgetSyncTarget>();
+
+    payments.forEach((payment) => {
+      const assignmentId =
+        typeof payment.winnings.external_id === 'string'
+          ? payment.winnings.external_id.trim()
+          : '';
+
+      if (
+        !assignmentId ||
+        payment.winnings.type !== winnings_type.PAYMENT ||
+        payment.winnings.category !== winnings_category.ENGAGEMENT_PAYMENT ||
+        (payment.currency ?? '') !== 'USD'
+      ) {
+        return;
+      }
+
+      const billingAccountId = this.normalizeBillingAccountId(
+        payment.billing_account,
+      );
+
+      if (!billingAccountId) {
+        this.logger.warn(
+          `Skipping engagement budget sync for payment ${payment.payment_id}; invalid billing account ${String(payment.billing_account)}`,
+        );
+        return;
+      }
+
+      targets.set(`${assignmentId}:${billingAccountId}`, {
+        assignmentId,
+        billingAccountId,
+      });
+    });
+
+    return [...targets.values()];
+  }
+
   /**
    * Resolves the billing account to synchronize for a challenge.
    *
@@ -465,6 +520,25 @@ export class AdminService {
     );
   }
 
+  /**
+   * Quantizes a billing-account ledger amount to the same four-decimal scale
+   * used by billing-accounts-api-v6.
+   *
+   * @param amount decimal amount to normalize.
+   * @returns JavaScript number rounded to four decimal places.
+   * @throws This helper does not throw.
+   */
+  private toBillingLedgerAmount(amount: Prisma.Decimal): number {
+    return Number(
+      amount
+        .toDecimalPlaces(
+          BUDGET_LEDGER_DECIMAL_PLACES,
+          Prisma.Decimal.ROUND_HALF_UP,
+        )
+        .toFixed(BUDGET_LEDGER_DECIMAL_PLACES),
+    );
+  }
+
   /**
    * Sums non-cancelled USD payment rows for a challenge and billing account.
    *
@@ -547,6 +621,74 @@ export class AdminService {
     );
   }
 
+  /**
+   * Reads active engagement payment ledger amounts for one assignment.
+   *
+   * @param assignmentId engagement assignment external id stored on winnings.
+   * @param billingAccountId billing account stored on payment rows.
+   * @returns ledger-scale consumed amounts for non-cancelled finance payments,
+   * in the same order used when engagement consumed rows were created.
+   * @throws Prisma errors when the payment query fails.
+   */
+  private async getActiveEngagementConsumeAmounts(
+    assignmentId: string,
+    billingAccountId: number,
+  ): Promise<number[]> {
+    const payments = await this.prisma.payment.findMany({
+      select: {
+        challenge_fee: true,
+        total_amount: true,
+      },
+      where: {
+        billing_account: String(billingAccountId),
+        currency: PrizeType.USD,
+        payment_status: { not: payment_status.CANCELLED },
+        winnings: {
+          category: winnings_category.ENGAGEMENT_PAYMENT,
+          external_id: assignmentId,
+          type: winnings_type.PAYMENT,
+        },
+      },
+      orderBy: [{ created_at: 'asc' }, { payment_id: 'asc' }],
+    });
+
+    return payments.map((paymentRow) =>
+      this.toBillingLedgerAmount(
+        new Prisma.Decimal(paymentRow.total_amount ?? 0).plus(
+          new Prisma.Decimal(paymentRow.challenge_fee ?? 0),
+        ),
+      ),
+    );
+  }
+
+  /**
+   * Reconciles engagement billing-account consumed rows after a wallet-admin
+   * cancellation changes the active payment set.
+   *
+   * @param targets unique engagement assignment and billing-account pairs to
+   * synchronize.
+   * @returns promise resolved after every target has been reconciled in BA.
+   * @throws Error when BA synchronization fails.
+   */
+  private async syncEngagementBudgetTargets(
+    targets: EngagementBudgetSyncTarget[],
+  ): Promise<void> {
+    await Promise.all(
+      targets.map(async (target) => {
+        const amounts = await this.getActiveEngagementConsumeAmounts(
+          target.assignmentId,
+          target.billingAccountId,
+        );
+
+        await this.baService.syncEngagementConsumeAmounts({
+          amounts,
+          billingAccountId: target.billingAccountId,
+          externalId: target.assignmentId,
+        });
+      }),
+    );
+  }
+
   /**
    * Verify that a BA admin user has access to the billing account(s)
    * associated with the given winningsId. Throws BadRequestException when
@@ -642,6 +784,10 @@ export class AdminService {
         body.paymentStatus === PaymentStatus.CANCELLED
           ? this.getChallengeBudgetSyncTargets(payments)
           : [];
+      const engagementBudgetSyncTargets =
+        body.paymentStatus === PaymentStatus.CANCELLED
+          ? this.getEngagementBudgetSyncTargets(payments)
+          : [];
 
       // iterate payments and build transaction list
       payments.forEach((payment) => {
@@ -928,6 +1074,10 @@ export class AdminService {
         await this.syncChallengeBudgetTargets(challengeBudgetSyncTargets);
       }
 
+      if (engagementBudgetSyncTargets.length > 0) {
+        await this.syncEngagementBudgetTargets(engagementBudgetSyncTargets);
+      }
+
       if (needsReconciliation) {
         const winning = await this.prisma.winnings.findFirst({
           select: {

src/shared/topcoder/billing-accounts.service.spec.ts

@@ -17,13 +17,34 @@ jest.mock('src/shared/global', () => ({
   },
 }));
 
+const mockBaTx = {
+  $executeRawUnsafe: jest.fn(),
+  $queryRawUnsafe: jest.fn(),
+};
+const mockBaClient = {
+  $transaction: jest.fn(),
+};
+
+jest.mock('src/shared/global/ba-prisma.client', () => ({
+  getBaClient: jest.fn(() => mockBaClient),
+}));
+
 import { ChallengeStatuses } from 'src/dto/challenge.dto';
 import { BillingAccountsService } from './billing-accounts.service';
 
 describe('BillingAccountsService', () => {
   let service: BillingAccountsService;
 
   beforeEach(() => {
+    jest.clearAllMocks();
+    mockBaTx.$executeRawUnsafe.mockResolvedValue(undefined);
+    mockBaTx.$queryRawUnsafe
+      .mockResolvedValueOnce([{ exists: true }])
+      .mockResolvedValueOnce([]);
+    mockBaClient.$transaction.mockImplementation(
+      (callback: (tx: typeof mockBaTx) => unknown) => callback(mockBaTx),
+    );
+
     service = new BillingAccountsService({} as any);
   });
 
@@ -95,4 +116,81 @@ describe('BillingAccountsService', () => {
     });
     expect(consumeAmountSpy).not.toHaveBeenCalled();
   });
+
+  it('deletes stale engagement consumed rows when no active amounts remain', async () => {
+    mockBaTx.$queryRawUnsafe
+      .mockReset()
+      .mockResolvedValueOnce([{ exists: true }])
+      .mockResolvedValueOnce([{ id: 'consumed-row-1' }]);
+
+    await service.syncEngagementConsumeAmounts({
+      amounts: [],
+      billingAccountId: 80001012,
+      externalId: 'assignment-1',
+    });
+
+    expect(mockBaTx.$queryRawUnsafe).toHaveBeenNthCalledWith(
+      2,
+      expect.stringContaining('"externalId" = $2'),
+      80001012,
+      'assignment-1',
+    );
+    expect(mockBaTx.$executeRawUnsafe).toHaveBeenCalledWith(
+      expect.stringContaining('DELETE FROM "ConsumedAmount"'),
+      'consumed-row-1',
+    );
+  });
+
+  it('syncs engagement consumed rows to the active ledger amounts', async () => {
+    mockBaTx.$queryRawUnsafe
+      .mockReset()
+      .mockResolvedValueOnce([{ exists: true }])
+      .mockResolvedValueOnce([{ id: 'consumed-row-1' }, { id: 'stale-row-1' }]);
+
+    await service.syncEngagementConsumeAmounts({
+      amounts: [24.2, 12],
+      billingAccountId: 80001012,
+      externalId: 'assignment-1',
+    });
+
+    expect(mockBaTx.$executeRawUnsafe).toHaveBeenCalledWith(
+      expect.stringContaining('UPDATE "ConsumedAmount"'),
+      24.2,
+      'consumed-row-1',
+    );
+    expect(mockBaTx.$executeRawUnsafe).toHaveBeenCalledWith(
+      expect.stringContaining('UPDATE "ConsumedAmount"'),
+      12,
+      'stale-row-1',
+    );
+    expect(mockBaTx.$executeRawUnsafe).not.toHaveBeenCalledWith(
+      expect.stringContaining('DELETE FROM "ConsumedAmount"'),
+      expect.any(String),
+    );
+  });
+
+  it('syncs legacy consumed rows with the aggregate active amount', async () => {
+    mockBaTx.$queryRawUnsafe
+      .mockReset()
+      .mockResolvedValueOnce([{ exists: false }])
+      .mockResolvedValueOnce([{ id: 'legacy-row-1' }]);
+
+    await service.syncEngagementConsumeAmounts({
+      amounts: [24.2, 12],
+      billingAccountId: 80001012,
+      externalId: 'assignment-1',
+    });
+
+    expect(mockBaTx.$queryRawUnsafe).toHaveBeenNthCalledWith(
+      2,
+      expect.stringContaining('"challengeId" = $2'),
+      80001012,
+      'assignment-1',
+    );
+    expect(mockBaTx.$executeRawUnsafe).toHaveBeenCalledWith(
+      expect.stringContaining('UPDATE "ConsumedAmount"'),
+      36.2,
+      'legacy-row-1',
+    );
+  });
 });