@dainamite/billing 0.17.0 → 0.19.0

package/src/modules/billing/__tests__/lib/balanceStatus.test.ts

@@ -0,0 +1,65 @@
+import {
+  computeBalanceStatus,
+  detectBalanceCrossing,
+  resolveLowBalanceThreshold,
+} from '../../lib/balanceStatus'
+
+describe('balanceStatus — classification', () => {
+  it('classifies ok / low / exhausted', () => {
+    expect(computeBalanceStatus('100.0000', '10.0000')).toBe('ok')
+    expect(computeBalanceStatus('10.0000', '10.0000')).toBe('low') // boundary is low
+    expect(computeBalanceStatus('5.0000', '10.0000')).toBe('low')
+    expect(computeBalanceStatus('0.0000', '10.0000')).toBe('exhausted')
+    expect(computeBalanceStatus('-3.0000', '10.0000')).toBe('exhausted')
+  })
+
+  it('threshold 0 disables the low band (only ok / exhausted)', () => {
+    expect(computeBalanceStatus('0.0001', '0')).toBe('ok')
+    expect(computeBalanceStatus('0', '0')).toBe('exhausted')
+  })
+
+  it('resolves threshold: account row → config default → 0', () => {
+    expect(resolveLowBalanceThreshold('25.0000', '10')).toBe('25.0000')
+    expect(resolveLowBalanceThreshold(null, '10')).toBe('10')
+    expect(resolveLowBalanceThreshold(null, null)).toBe('0')
+    expect(resolveLowBalanceThreshold(undefined, undefined)).toBe('0')
+  })
+})
+
+describe('balanceStatus — downward crossings (events fire once)', () => {
+  it('fires exhausted only when crossing from > 0 to <= 0', () => {
+    expect(detectBalanceCrossing('5.0000', '-3.0000', '10.0000')).toEqual({
+      lowCrossedDown: false,
+      exhaustedCrossedDown: true,
+    })
+    // Already negative — pushing further does NOT re-fire (no spam).
+    expect(detectBalanceCrossing('-3.0000', '-8.0000', '10.0000')).toEqual({
+      lowCrossedDown: false,
+      exhaustedCrossedDown: false,
+    })
+  })
+
+  it('fires low only when landing in the (0, threshold] band', () => {
+    expect(detectBalanceCrossing('100.0000', '8.0000', '10.0000')).toEqual({
+      lowCrossedDown: true,
+      exhaustedCrossedDown: false,
+    })
+    // Jumped past low straight to exhausted → only exhausted fires.
+    expect(detectBalanceCrossing('100.0000', '-1.0000', '10.0000')).toEqual({
+      lowCrossedDown: false,
+      exhaustedCrossedDown: true,
+    })
+    // Already low, dropping further within the band → no re-fire.
+    expect(detectBalanceCrossing('8.0000', '4.0000', '10.0000')).toEqual({
+      lowCrossedDown: false,
+      exhaustedCrossedDown: false,
+    })
+  })
+
+  it('does not fire low when threshold is 0', () => {
+    expect(detectBalanceCrossing('100.0000', '1.0000', '0')).toEqual({
+      lowCrossedDown: false,
+      exhaustedCrossedDown: false,
+    })
+  })
+})

package/src/modules/billing/__tests__/lib/creditStatus.test.ts

@@ -0,0 +1,111 @@
+import {
+  computeAvailableCredit,
+  computeCreditSnapshot,
+  computeCreditStatus,
+  computeCreditUsed,
+  detectCreditCrossing,
+  prepaidCreditUsed,
+} from '../../lib/creditStatus'
+
+describe('creditStatus — credit_used per mode', () => {
+  it('prepaid: max(0, −balance)', () => {
+    expect(prepaidCreditUsed('100.0000')).toBe('0.0000')
+    expect(prepaidCreditUsed('0.0000')).toBe('0.0000')
+    expect(prepaidCreditUsed('-30.0000')).toBe('30.0000')
+    expect(computeCreditUsed('prepaid', { balance: '-12.5000' })).toBe('12.5000')
+  })
+
+  it('postpaid: Σ outstanding', () => {
+    expect(computeCreditUsed('postpaid', { outstanding: '4200.0000' })).toBe('4200.0000')
+    expect(computeCreditUsed('postpaid', { outstanding: null })).toBe('0.0000')
+  })
+
+  it('available = limit − used (both modes)', () => {
+    expect(computeAvailableCredit('5000.0000', '4200.0000')).toBe('800.0000')
+    expect(computeAvailableCredit('50.0000', '53.0000')).toBe('-3.0000')
+  })
+})
+
+describe('creditStatus — status thresholds', () => {
+  it('within / near / over', () => {
+    expect(computeCreditStatus('800.0000', '0')).toBe('within_limit')
+    expect(computeCreditStatus('100.0000', '100.0000')).toBe('near_limit')
+    expect(computeCreditStatus('50.0000', '100.0000')).toBe('near_limit')
+    expect(computeCreditStatus('0.0000', '100.0000')).toBe('over_limit')
+    expect(computeCreditStatus('-3.0000', '0')).toBe('over_limit')
+  })
+
+  it('prepaid snapshot: exhausted funds but within credit line', () => {
+    // balance -3, credit_limit 50 → used 3, available 47, within_limit.
+    const snap = computeCreditSnapshot({
+      mode: 'prepaid',
+      creditLimit: '50.0000',
+      nearLimitBuffer: '0',
+      balance: '-3.0000',
+    })
+    expect(snap).toEqual({
+      mode: 'prepaid',
+      creditLimit: '50.0000',
+      creditUsed: '3.0000',
+      availableCredit: '47.0000',
+      creditStatus: 'within_limit',
+    })
+  })
+
+  it('postpaid snapshot from outstanding', () => {
+    const snap = computeCreditSnapshot({
+      mode: 'postpaid',
+      creditLimit: '5000.0000',
+      nearLimitBuffer: '1000.0000',
+      outstanding: '4200.0000',
+    })
+    expect(snap.creditUsed).toBe('4200.0000')
+    expect(snap.availableCredit).toBe('800.0000')
+    expect(snap.creditStatus).toBe('near_limit')
+  })
+})
+
+describe('creditStatus — over_limit upward crossing', () => {
+  it('fires once when used crosses the limit (prepaid balance below −limit)', () => {
+    // limit 50: balance -45 → used 45 (under); balance -55 → used 55 (over).
+    expect(
+      detectCreditCrossing({
+        creditLimit: '50.0000',
+        nearLimitBuffer: '0',
+        usedBefore: '45.0000',
+        usedAfter: '55.0000',
+      }).overLimitCrossedUp,
+    ).toBe(true)
+    // Already over — no re-fire.
+    expect(
+      detectCreditCrossing({
+        creditLimit: '50.0000',
+        nearLimitBuffer: '0',
+        usedBefore: '55.0000',
+        usedAfter: '60.0000',
+      }).overLimitCrossedUp,
+    ).toBe(false)
+  })
+
+  it('no crossing when there is no credit line (limit 0)', () => {
+    expect(
+      detectCreditCrossing({
+        creditLimit: '0',
+        nearLimitBuffer: '0',
+        usedBefore: '0.0000',
+        usedAfter: '5.0000',
+      }),
+    ).toEqual({ overLimitCrossedUp: false, nearLimitCrossedUp: false })
+  })
+
+  it('near_limit crossing into the buffer band', () => {
+    expect(
+      detectCreditCrossing({
+        creditLimit: '100.0000',
+        nearLimitBuffer: '20.0000',
+        usedBefore: '70.0000', // available 30
+        usedAfter: '85.0000', // available 15 → near
+      }).nearLimitCrossedUp,
+    ).toBe(true)
+  })
+})

package/src/modules/billing/__tests__/lib/money.test.ts

@@ -0,0 +1,56 @@
+import {
+  addMoney,
+  absMoney,
+  compareMoney,
+  formatMoney,
+  fromUnits,
+  negateMoney,
+  subMoney,
+  toUnits,
+} from '../../lib/money'
+
+describe('money — exact decimal arithmetic', () => {
+  it('round-trips numeric(18,4) strings through units', () => {
+    expect(toUnits('12.3400')).toBe(123400)
+    expect(fromUnits(123400)).toBe('12.3400')
+    expect(fromUnits(toUnits('0.0001'))).toBe('0.0001')
+    expect(fromUnits(toUnits('-7.5000'))).toBe('-7.5000')
+  })
+
+  it('formats whole + negative + sub-cent values', () => {
+    expect(formatMoney('100')).toBe('100.0000')
+    expect(formatMoney(0)).toBe('0.0000')
+    expect(formatMoney('-3')).toBe('-3.0000')
+    expect(fromUnits(-0)).toBe('0.0000') // no negative zero
+  })
+
+  it('adds/subtracts without floating-point drift', () => {
+    // 0.1 + 0.2 !== 0.3 in IEEE-754 — units math makes it exact.
+    expect(addMoney('0.1000', '0.2000')).toBe('0.3000')
+    let acc = '0.0000'
+    for (let i = 0; i < 100; i++) acc = addMoney(acc, '0.0010')
+    expect(acc).toBe('0.1000')
+    expect(subMoney('100.0000', '0.0010')).toBe('99.9990')
+  })
+
+  it('negates and takes absolute value', () => {
+    expect(negateMoney('5.0000')).toBe('-5.0000')
+    expect(negateMoney('-5.0000')).toBe('5.0000')
+    expect(negateMoney('0')).toBe('0.0000')
+    expect(absMoney('-12.3400')).toBe('12.3400')
+    expect(absMoney('12.3400')).toBe('12.3400')
+  })
+
+  it('compares values', () => {
+    expect(compareMoney('1.0000', '2.0000')).toBe(-1)
+    expect(compareMoney('2.0000', '2.0000')).toBe(0)
+    expect(compareMoney('3.0000', '2.0000')).toBe(1)
+    expect(compareMoney('-0.0001', '0')).toBe(-1)
+  })
+
+  it('treats null/undefined as zero', () => {
+    expect(toUnits(null)).toBe(0)
+    expect(toUnits(undefined)).toBe(0)
+    expect(addMoney('5', null as unknown as string)).toBe('5.0000')
+  })
+})

package/src/modules/billing/__tests__/lib/prepaidConsume.test.ts

@@ -0,0 +1,179 @@
+import { consumePrepaidUsage, type PrepaidConsumeInput } from '../../lib/prepaidConsume'
+import { createPrepaidMockEm } from '../helpers/prepaidMockEm'
+
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const ACCT = '33333333-3333-4333-8333-333333333333'
+
+function makeAccount(overrides: Record<string, unknown> = {}) {
+  return {
+    id: ACCT,
+    tenantId: TENANT,
+    organizationId: ORG,
+    currencyCode: 'EUR',
+    billingMode: 'prepaid',
+    creditLimit: '0',
+    ...overrides,
+  }
+}
+
+function flatUsageItem() {
+  return {
+    id: 'item-1',
+    type: 'usage',
+    uomCode: 'api_request',
+    isActive: true,
+    deletedAt: null,
+    rateJson: { unit_price: 0.001 },
+    description: 'API requests',
+  }
+}
+
+function baseInput(overrides: Partial<PrepaidConsumeInput> = {}): PrepaidConsumeInput {
+  return {
+    organizationId: ORG,
+    tenantId: TENANT,
+    billAccountId: ACCT,
+    uomCode: 'api_request',
+    quantity: 8000,
+    periodStart: new Date('2026-06-01'),
+    periodEnd: new Date('2026-06-30'),
+    lineDescription: null,
+    sourceRef: null,
+    ...overrides,
+  }
+}
+
+const balanceRow = (balance: string, threshold: string | null = null) => ({
+  tenantId: TENANT,
+  billAccountId: ACCT,
+  balance,
+  lowBalanceThreshold: threshold,
+})
+
+describe('consumePrepaidUsage — happy path', () => {
+  it('rates synchronously, debits, returns the remaining balance', async () => {
+    const em = createPrepaidMockEm({
+      account: makeAccount(),
+      balance: balanceRow('100.0000'),
+      usageItem: flatUsageItem(),
+    })
+    const { result, events } = await consumePrepaidUsage(em as never, makeAccount() as never, baseInput())
+
+    expect(result.deduplicated).toBe(false)
+    expect(result.ratedAmount).toBe('8.0000') // 8000 × 0.001
+    expect(result.balance).toBe('92.0000')
+    expect(result.balanceStatus).toBe('ok')
+    expect(result.creditStatus).toBe('within_limit')
+    expect(result.warning).toBeNull()
+    expect(result.tierBreakdown.length).toBeGreaterThan(0)
+    // One usage record + one debit transaction.
+    expect(em.usages).toHaveLength(1)
+    expect(em.transactions).toHaveLength(1)
+    expect(em.transactions[0].amount).toBe('-8.0000')
+    // usage.rated event emitted (no threshold crossings on a healthy balance).
+    expect(events.map((e) => e.id)).toEqual(['billing.usage.rated'])
+  })
+})
+
+describe('consumePrepaidUsage — never rejected', () => {
+  it('records usage with a 0 debit + warning when no item matches', async () => {
+    const em = createPrepaidMockEm({
+      account: makeAccount(),
+      balance: balanceRow('100.0000'),
+      usageItem: null, // no matching item
+    })
+    const { result } = await consumePrepaidUsage(em as never, makeAccount() as never, baseInput())
+
+    expect(result.warning).toBe('no_matching_item')
+    expect(result.ratedAmount).toBe('0.0000')
+    expect(result.balance).toBe('100.0000') // unchanged
+    expect(em.usages).toHaveLength(1) // still recorded
+    expect(em.transactions[0].amount).toBe('0.0000')
+  })
+
+  it('lets the balance go negative and reports exhausted', async () => {
+    const em = createPrepaidMockEm({
+      account: makeAccount(),
+      balance: balanceRow('5.0000'),
+      usageItem: flatUsageItem(),
+    })
+    const { result, events } = await consumePrepaidUsage(
+      em as never,
+      makeAccount() as never,
+      baseInput(),
+    )
+    expect(result.balance).toBe('-3.0000') // 5 − 8
+    expect(result.balanceStatus).toBe('exhausted')
+    expect(events.map((e) => e.id)).toContain('billing.balance.exhausted')
+  })
+
+  it('emits balance.low when crossing into the low band', async () => {
+    const em = createPrepaidMockEm({
+      account: makeAccount(),
+      balance: balanceRow('15.0000', '10.0000'),
+      usageItem: flatUsageItem(),
+    })
+    const { result, events } = await consumePrepaidUsage(
+      em as never,
+      makeAccount() as never,
+      baseInput(),
+    )
+    expect(result.balance).toBe('7.0000') // 15 − 8
+    expect(result.balanceStatus).toBe('low')
+    expect(events.map((e) => e.id)).toContain('billing.balance.low')
+  })
+})
+
+describe('consumePrepaidUsage — idempotency', () => {
+  it('a duplicate sourceRef does NOT double-debit and returns the prior balance_after', async () => {
+    const em = createPrepaidMockEm({
+      account: makeAccount(),
+      balance: balanceRow('92.0000'),
+      usageItem: flatUsageItem(),
+      existingUsage: { id: 'usage-prior', sourceRef: 'batch-42', billAccountId: ACCT },
+    })
+    // Seed the paired transaction the prior consume wrote.
+    em.transactions.push({
+      id: 'txn-prior',
+      usageId: 'usage-prior',
+      billAccountId: ACCT,
+      amount: '-8.0000',
+      balanceAfter: '92.0000',
+      metadata: { usage_tier_breakdown: [{ tierIndex: 0 }], warning: undefined },
+      createdAt: new Date('2026-06-10'),
+    })
+
+    const { result } = await consumePrepaidUsage(
+      em as never,
+      makeAccount() as never,
+      baseInput({ sourceRef: 'batch-42' }),
+    )
+
+    expect(result.deduplicated).toBe(true)
+    expect(result.id).toBe('usage-prior')
+    expect(result.ratedAmount).toBe('8.0000')
+    expect(result.balance).toBe('92.0000')
+    // No new usage record, no new transaction.
+    expect(em.usages.filter((u) => u.id !== 'usage-prior')).toHaveLength(0)
+    expect(em.transactions).toHaveLength(1)
+  })
+})
+
+describe('consumePrepaidUsage — credit line', () => {
+  it('reports within_limit while exhausted on funds (credit covers the overdraft)', async () => {
+    const em = createPrepaidMockEm({
+      account: makeAccount({ creditLimit: '50.0000' }),
+      balance: balanceRow('5.0000'),
+      usageItem: flatUsageItem(),
+    })
+    const { result, events } = await consumePrepaidUsage(
+      em as never,
+      makeAccount({ creditLimit: '50.0000' }) as never,
+      baseInput(),
+    )
+    expect(result.balanceStatus).toBe('exhausted') // balance -3
+    expect(result.creditStatus).toBe('within_limit') // used 3 of 50
+    expect(events.map((e) => e.id)).not.toContain('billing.credit.over_limit')
+  })
+})

package/src/modules/billing/__tests__/lib/prepaidPeriodClose.test.ts

@@ -0,0 +1,232 @@
+import { processPrepaidAccount } from '../../lib/prepaidPeriodClose'
+import { createPrepaidMockEm, type MockEm } from '../helpers/prepaidMockEm'
+
+const TENANT = 'ten-1'
+const ORG = 'org-1'
+const ACCT = 'acct-1'
+
+function prepaidAccount(overrides: Record<string, unknown> = {}) {
+  return {
+    id: ACCT,
+    tenantId: TENANT,
+    organizationId: ORG,
+    currencyCode: 'EUR',
+    billingMode: 'prepaid',
+    billCycle: 'monthly',
+    nextBillDate: new Date('2026-06-01'),
+    lastBillDate: null,
+    creditLimit: '0',
+    updatedAt: new Date('2026-05-01'),
+    ...overrides,
+  }
+}
+
+const billRun = { id: 'run-1' }
+const realParams = {
+  asOfDate: new Date('2026-06-01'),
+  mode: 'real' as const,
+  triggeredBy: 'manual' as const,
+  catchUp: false,
+}
+
+function recurringItem() {
+  return {
+    id: 'item-rec',
+    type: 'recurring',
+    billStartDate: new Date('2026-01-01'),
+    billEndDate: null,
+    billedToDate: null,
+    isActive: true,
+    deletedAt: null,
+    rateJson: { unit_price: 20 },
+    description: 'Platform fee',
+  }
+}
+
+// Seed the period's real-time movements: a 100 top-up + 103 usage (May 2026).
+function seedWindowActivity(em: MockEm) {
+  em.transactions.push(
+    {
+      id: 't-top',
+      type: 'topup',
+      amount: '100.0000',
+      billAccountId: ACCT,
+      createdAt: new Date('2026-05-02'),
+    },
+    {
+      id: 't-use',
+      type: 'usage',
+      amount: '-103.0000',
+      billAccountId: ACCT,
+      createdAt: new Date('2026-05-15'),
+    },
+  )
+}
+
+describe('processPrepaidAccount — period close (spec story step 6)', () => {
+  it('charges recurring to the balance and builds the statement', async () => {
+    const account = prepaidAccount()
+    const item = recurringItem()
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '-3.0000' },
+      items: [item],
+      existingStatement: null,
+    })
+    seedWindowActivity(em)
+
+    const result = await processPrepaidAccount(em as never, account as never, billRun as never, realParams)
+
+    expect(result.status).toBe('success')
+    if (result.status === 'failed') throw new Error('unexpected failure')
+    expect(result.statementId).toBeTruthy()
+    expect(result.statementEvents.map((e) => e.id)).toEqual(['billing.statement.generated'])
+
+    // The recurring charge hit the balance with a deterministic source_ref.
+    const recurringTxn = em.transactions.find((t) => t.type === 'recurring')
+    expect(recurringTxn).toBeTruthy()
+    expect(recurringTxn!.amount).toBe('-20.0000')
+    expect(recurringTxn!.sourceRef).toBe('recurring-item-rec-2026-05-31')
+
+    // The statement chains: opening 0, +100 topups, −103 usage, −20 recurring = −23.
+    const statement = em.persisted.find(
+      (e) => (e as { status?: string }).status === 'generated',
+    ) as Record<string, unknown>
+    expect(statement).toBeTruthy()
+    expect(statement.openingBalance).toBe('0.0000')
+    expect(statement.totalTopups).toBe('100.0000')
+    expect(statement.totalUsage).toBe('103.0000')
+    expect(statement.totalRecurring).toBe('20.0000')
+    expect(statement.closingBalance).toBe('-23.0000')
+
+    // billed_to_date guard set; the cycle advanced.
+    expect(item.billedToDate).toEqual(new Date('2026-05-31'))
+    expect((account.nextBillDate as Date).toISOString().slice(0, 7)).toBe('2026-07')
+  })
+
+  it('still generates a statement with no recurring items (usage-only account)', async () => {
+    const account = prepaidAccount()
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '-3.0000' },
+      items: [],
+    })
+    seedWindowActivity(em)
+
+    const result = await processPrepaidAccount(em as never, account as never, billRun as never, realParams)
+    if (result.status === 'failed') throw new Error('unexpected failure')
+    expect(result.statementId).toBeTruthy()
+    const statement = em.persisted.find(
+      (e) => (e as { status?: string }).status === 'generated',
+    ) as Record<string, unknown>
+    expect(statement.totalRecurring).toBe('0.0000')
+    expect(statement.closingBalance).toBe('-3.0000') // 0 + 100 − 103 − 0
+  })
+
+  it('chains the opening balance from the prior statement closing', async () => {
+    // Prior month closed at −23. This month: +50 top-ups, −40 usage, −20 recurring
+    // → opening −23, closing −23 + 50 − 40 − 20 = −33. (A created_at sum would
+    // wrongly drop the prior recurring and overstate the opening.)
+    const account = prepaidAccount()
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '-13.0000' },
+      items: [recurringItem()],
+      existingStatement: null,
+      priorStatement: { id: 'stmt-may', closingBalance: '-23.0000' },
+    })
+    em.transactions.push(
+      { id: 't-top2', type: 'topup', amount: '50.0000', billAccountId: ACCT, createdAt: new Date('2026-05-10') },
+      { id: 't-use2', type: 'usage', amount: '-40.0000', billAccountId: ACCT, createdAt: new Date('2026-05-20') },
+    )
+
+    const result = await processPrepaidAccount(em as never, account as never, billRun as never, realParams)
+    if (result.status === 'failed') throw new Error('unexpected failure')
+    const statement = em.persisted.find(
+      (e) => (e as { status?: string }).status === 'generated',
+    ) as Record<string, unknown>
+    expect(statement.openingBalance).toBe('-23.0000')
+    expect(statement.totalTopups).toBe('50.0000')
+    expect(statement.totalUsage).toBe('40.0000')
+    expect(statement.totalRecurring).toBe('20.0000')
+    expect(statement.closingBalance).toBe('-33.0000')
+  })
+
+  it('fires a balance.low crossing when the recurring charge drops into the low band', async () => {
+    // Balance 25 with threshold 10; the €20 recurring fee drops it to 5 → low.
+    const account = prepaidAccount()
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '25.0000', lowBalanceThreshold: '10.0000' },
+      items: [recurringItem()],
+    })
+    const result = await processPrepaidAccount(em as never, account as never, billRun as never, realParams)
+    if (result.status === 'failed') throw new Error('unexpected failure')
+    expect(result.statementEvents.map((e) => e.id)).toContain('billing.balance.low')
+    expect(result.statementEvents.map((e) => e.id)).toContain('billing.statement.generated')
+  })
+
+  it('includes manual adjustments in the statement math (closing stays consistent)', async () => {
+    // Window has a +10 adjustment. opening 0, topups 100, usage 103, adj +10,
+    // recurring 20 → closing 0 + 100 + 10 − 103 − 20 = −13.
+    const account = prepaidAccount()
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '7.0000' },
+      items: [recurringItem()],
+    })
+    seedWindowActivity(em)
+    em.transactions.push({
+      id: 't-adj',
+      type: 'adjustment',
+      amount: '10.0000',
+      billAccountId: ACCT,
+      createdAt: new Date('2026-05-12'),
+    })
+    const result = await processPrepaidAccount(em as never, account as never, billRun as never, realParams)
+    if (result.status === 'failed') throw new Error('unexpected failure')
+    const statement = em.persisted.find(
+      (e) => (e as { status?: string }).status === 'generated',
+    ) as Record<string, unknown>
+    expect(statement.totalAdjustments).toBe('10.0000')
+    expect(statement.closingBalance).toBe('-13.0000')
+  })
+
+  it('skips when a statement already exists for the period (anti-duplicate)', async () => {
+    const account = prepaidAccount()
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '-3.0000' },
+      items: [recurringItem()],
+      existingStatement: { id: 'stmt-prior' },
+    })
+    seedWindowActivity(em)
+
+    const result = await processPrepaidAccount(em as never, account as never, billRun as never, realParams)
+    expect(result.status).toBe('skipped_existing_statement')
+    if (result.status === 'failed') throw new Error('unexpected failure')
+    expect(result.statementId).toBe('stmt-prior')
+    // No recurring charge applied.
+    expect(em.transactions.find((t) => t.type === 'recurring')).toBeUndefined()
+  })
+
+  it('dry run computes nothing persisted and does not advance', async () => {
+    const account = prepaidAccount()
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '-3.0000' },
+      items: [recurringItem()],
+    })
+    seedWindowActivity(em)
+
+    const result = await processPrepaidAccount(em as never, account as never, billRun as never, {
+      ...realParams,
+      mode: 'dry',
+    })
+    if (result.status === 'failed') throw new Error('unexpected failure')
+    expect(result.statementId).toBeNull()
+    expect(em.transactions.find((t) => t.type === 'recurring')).toBeUndefined()
+    // Cycle not advanced (still June 1).
+    expect((account.nextBillDate as Date).toISOString().slice(0, 10)).toBe('2026-06-01')
+  })
+})