@dainamite/billing 0.17.0 → 0.19.0

package/src/modules/billing/__tests__/commands/topups.test.ts

@@ -0,0 +1,104 @@
+import { createTopupCommand } from '../../commands/topups'
+import { createPrepaidMockEm, type MockEm } 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 prepaidAccount(overrides: Record<string, unknown> = {}) {
+  return {
+    id: ACCT,
+    tenantId: TENANT,
+    organizationId: ORG,
+    currencyCode: 'EUR',
+    billingMode: 'prepaid',
+    creditLimit: '0',
+    ...overrides,
+  }
+}
+
+function makeCtx(em: MockEm, gateway: unknown) {
+  const dataEngine = {
+    markOrmEntityChange: jest.fn(),
+    flushOrmEntityChanges: jest.fn(async () => undefined),
+  }
+  return {
+    auth: { sub: '99999999-9999-4999-8999-999999999999', tenantId: TENANT, orgId: ORG },
+    container: {
+      resolve: jest.fn((name: string) => {
+        if (name === 'em') return em
+        if (name === 'dataEngine') return dataEngine
+        if (name === 'paymentGatewayService') return gateway
+        return null
+      }),
+    },
+  }
+}
+
+const baseInput = {
+  tenantId: TENANT,
+  organizationId: ORG,
+  billAccountId: ACCT,
+  amount: 100,
+  successUrl: 'https://app.example/return',
+  cancelUrl: 'https://app.example/cancel',
+}
+
+describe('createTopupCommand', () => {
+  it('registers a pending top-up and opens an automatic-capture session', async () => {
+    const em = createPrepaidMockEm({ account: prepaidAccount(), topup: null })
+    const gateway = {
+      createPaymentSession: jest.fn(async (_input: unknown) => ({
+        transaction: { id: 'gw-txn-1' },
+        session: { sessionId: 'sess-1', redirectUrl: 'https://pay.example/x', clientSecret: null },
+      })),
+    }
+    const ctx = makeCtx(em, gateway)
+    const result = await createTopupCommand.execute(baseInput as never, ctx as never)
+
+    expect(result.status).toBe('pending')
+    expect(result.transactionId).toBe('gw-txn-1')
+    expect(result.redirectUrl).toBe('https://pay.example/x')
+    expect(result.paymentId).toBeTruthy()
+
+    // The gateway was asked for an automatic-capture prepaid_topup session.
+    const sessionArg = gateway.createPaymentSession.mock.calls[0][0] as Record<string, unknown>
+    expect(sessionArg.captureMethod).toBe('automatic')
+    expect(sessionArg.amount).toBe(100)
+    expect((sessionArg.metadata as Record<string, unknown>).kind).toBe('prepaid_topup')
+  })
+
+  it('rejects a top-up on a postpaid account with 409', async () => {
+    const em = createPrepaidMockEm({ account: prepaidAccount({ billingMode: 'postpaid' }) })
+    const gateway = { createPaymentSession: jest.fn() }
+    const ctx = makeCtx(em, gateway)
+    await expect(
+      createTopupCommand.execute(baseInput as never, ctx as never),
+    ).rejects.toMatchObject({
+      status: 409,
+      body: expect.objectContaining({ code: 'billing.account.not_prepaid' }),
+    })
+    expect(gateway.createPaymentSession).not.toHaveBeenCalled()
+  })
+
+  it('is idempotent on sourceRef — returns the prior top-up without a new session', async () => {
+    const existing = {
+      id: 'topup-prior',
+      paymentId: 'pay-prior',
+      status: 'pending',
+      gatewayTransactionId: 'gw-prior',
+      metadata: { redirect_url: 'https://pay.example/prior', client_secret: null },
+    }
+    const em = createPrepaidMockEm({ account: prepaidAccount(), topup: existing })
+    const gateway = { createPaymentSession: jest.fn() }
+    const ctx = makeCtx(em, gateway)
+
+    const result = await createTopupCommand.execute(
+      { ...baseInput, sourceRef: 'req-7' } as never,
+      ctx as never,
+    )
+    expect(result.topupId).toBe('topup-prior')
+    expect(result.redirectUrl).toBe('https://pay.example/prior')
+    expect(gateway.createPaymentSession).not.toHaveBeenCalled()
+  })
+})

package/src/modules/billing/__tests__/commands/transactions.test.ts

@@ -0,0 +1,107 @@
+import { adjustTransactionCommand } from '../../commands/transactions'
+import { createPrepaidMockEm, type MockEm } 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 prepaidAccount(overrides: Record<string, unknown> = {}) {
+  return {
+    id: ACCT,
+    tenantId: TENANT,
+    organizationId: ORG,
+    currencyCode: 'EUR',
+    billingMode: 'prepaid',
+    creditLimit: '0',
+    ...overrides,
+  }
+}
+
+type CtxAuth = { sub?: string; tenantId?: string; orgId?: string } | null
+
+function makeCtx(em: MockEm, auth: CtxAuth = { sub: '99999999-9999-4999-8999-999999999999', tenantId: TENANT, orgId: ORG }) {
+  const dataEngine = {
+    markOrmEntityChange: jest.fn(),
+    flushOrmEntityChanges: jest.fn(async () => undefined),
+  }
+  return {
+    auth,
+    container: {
+      resolve: jest.fn((name: string) => {
+        if (name === 'em') return em
+        if (name === 'dataEngine') return dataEngine
+        return null
+      }),
+    },
+  }
+}
+
+describe('adjustTransactionCommand', () => {
+  it('debits the balance and returns the new balance + status', async () => {
+    const em = createPrepaidMockEm({
+      account: prepaidAccount(),
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '100.0000' },
+    })
+    const ctx = makeCtx(em)
+    const result = await adjustTransactionCommand.execute(
+      { tenantId: TENANT, organizationId: ORG, billAccountId: ACCT, amount: -30, description: 'Goodwill debit' } as never,
+      ctx as never,
+    )
+    expect(result.balance).toBe('70.0000')
+    expect(result.balanceStatus).toBe('ok')
+    expect(result.transactionId).toBeTruthy()
+    expect(em.transactions).toHaveLength(1)
+    expect(em.transactions[0].type).toBe('adjustment')
+    expect(em.transactions[0].amount).toBe('-30.0000')
+    expect(em.transactions[0].userId).toBe('99999999-9999-4999-8999-999999999999')
+  })
+
+  // The CPQ↔billing connector runs as a system identity, not a user: it calls
+  // the command bus with `auth: null` and carries tenant/organization in the
+  // payload instead. Open Mercato 0.6.7 hardened ensureTenantScope from
+  // fail-open to fail-closed, but kept `auth: null` a no-op — this test pins
+  // that, because the connector has no other guarantee than prose. If a future
+  // release closes this branch too, the connector breaks and this fails first.
+  it('accepts a system-identity call (auth: null) without a scope error', async () => {
+    const em = createPrepaidMockEm({
+      account: prepaidAccount(),
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '100.0000' },
+    })
+    const ctx = makeCtx(em, null)
+    const result = await adjustTransactionCommand.execute(
+      { tenantId: TENANT, organizationId: ORG, billAccountId: ACCT, amount: -10, description: 'Connector debit' } as never,
+      ctx as never,
+    )
+    expect(result.balance).toBe('90.0000')
+    expect(em.transactions).toHaveLength(1)
+    expect(em.transactions[0].userId).toBeFalsy()
+  })
+
+  it('credits the balance', async () => {
+    const em = createPrepaidMockEm({
+      account: prepaidAccount(),
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '-5.0000' },
+    })
+    const ctx = makeCtx(em)
+    const result = await adjustTransactionCommand.execute(
+      { tenantId: TENANT, organizationId: ORG, billAccountId: ACCT, amount: 25, description: 'Refund credit' } as never,
+      ctx as never,
+    )
+    expect(result.balance).toBe('20.0000')
+    expect(em.transactions[0].amount).toBe('25.0000')
+  })
+
+  it('rejects a non-zero amount on a postpaid account with 409', async () => {
+    const em = createPrepaidMockEm({ account: prepaidAccount({ billingMode: 'postpaid' }) })
+    const ctx = makeCtx(em)
+    await expect(
+      adjustTransactionCommand.execute(
+        { tenantId: TENANT, organizationId: ORG, billAccountId: ACCT, amount: 10, description: 'x' } as never,
+        ctx as never,
+      ),
+    ).rejects.toMatchObject({
+      status: 409,
+      body: expect.objectContaining({ code: 'billing.account.not_prepaid' }),
+    })
+  })
+})

package/src/modules/billing/__tests__/helpers/prepaidMockEm.ts

@@ -0,0 +1,235 @@
+/**
+ * In-memory mock EntityManager for the prepaid ledger libs (SPEC-002).
+ *
+ * Models the subset of operations `balanceLedger` / `prepaidConsume` /
+ * `accountStatus` touch: the raw `INSERT … ON CONFLICT` + `UPDATE … RETURNING`
+ * balance statements, the `SUM(amount)` reconciliation query, the postpaid
+ * `SUM(outstanding_amount)` query, plus findOne/find/create/persist/flush.
+ *
+ * The balance math reuses the real `money` helpers so the mock's rounding
+ * matches production exactly — that is the whole point of the reconciliation
+ * tests.
+ */
+
+import { addMoney } from '../../lib/money'
+
+type Row = Record<string, unknown>
+
+export type MockEmOptions = {
+  account?: Row | null
+  /** Pre-seed the balance row: { tenantId, billAccountId, balance, lowBalanceThreshold? }. */
+  balance?: Row | null
+  /** The active type=usage item returned by findUsageItem (or null). */
+  usageItem?: Row | null
+  /** An existing usage record returned for a matching sourceRef (dedup tests). */
+  existingUsage?: Row | null
+  /** A BillingTopup returned by findOne (capture tests). */
+  topup?: Row | null
+  /** Billing items returned by find(BillingItem) (period-close tests). */
+  items?: Row[]
+  /** An existing BillingStatement for the SAME period returned by findOne (anti-dup tests). */
+  existingStatement?: Row | null
+  /** A PRIOR BillingStatement (periodEnd < periodStart) for opening-chaining tests. */
+  priorStatement?: Row | null
+  /** Module config values keyed by name (e.g. { 'prepaid.topup_tax_rate': 23 }). */
+  configs?: Record<string, unknown>
+  /** Postpaid outstanding total returned by the SUM(outstanding_amount) query. */
+  postpaidOutstanding?: string | number
+}
+
+export type MockEm = {
+  // stores
+  transactions: Row[]
+  usages: Row[]
+  balances: Map<string, Row>
+  persisted: Row[]
+  // jest mocks
+  findOne: jest.Mock
+  find: jest.Mock
+  create: jest.Mock
+  persist: jest.Mock
+  flush: jest.Mock
+  execute: jest.Mock
+  nativeUpdate: jest.Mock
+  transactional: jest.Mock
+  fork: () => MockEm
+}
+
+function key(tenantId: unknown, billAccountId: unknown): string {
+  return `${tenantId}:${billAccountId}`
+}
+
+export function createPrepaidMockEm(options: MockEmOptions = {}): MockEm {
+  let idCounter = 0
+  const transactions: Row[] = []
+  const usages: Row[] = []
+  const persisted: Row[] = []
+  const balances = new Map<string, Row>()
+  if (options.balance) {
+    balances.set(key(options.balance.tenantId, options.balance.billAccountId), {
+      balance: '0.0000',
+      lowBalanceThreshold: null,
+      lastMovementAt: null,
+      ...options.balance,
+    })
+  }
+  if (options.existingUsage) usages.push(options.existingUsage)
+
+  const em = {
+    transactions,
+    usages,
+    balances,
+    persisted,
+  } as MockEm
+
+  em.create = jest.fn((entity: unknown, data: Row) => {
+    const ctor = (entity as { name?: string }).name ?? ''
+    idCounter += 1
+    const created: Row = { ...data, id: (data.id as string) ?? `gen-${ctor}-${idCounter}` }
+    if (ctor === 'BillingAccountTransaction') transactions.push(created)
+    else if (ctor === 'BillingAccountUsage') usages.push(created)
+    else if (ctor === 'BillingAccountBalance') {
+      balances.set(key(created.tenantId, created.billAccountId), created)
+    }
+    return created
+  }) as never
+
+  em.persist = jest.fn((entity: Row) => {
+    persisted.push(entity)
+  }) as never
+
+  em.flush = jest.fn(async () => undefined) as never
+
+  em.findOne = jest.fn(async (entity: unknown, where: Row, opts?: { orderBy?: Row }) => {
+    const ctor = (entity as { name?: string }).name ?? ''
+    if (ctor === 'BillingAccount') return options.account ?? null
+    if (ctor === 'BillingAccountBalance') {
+      return balances.get(key(where.tenantId, where.billAccountId)) ?? null
+    }
+    if (ctor === 'BillingAccountUsage') {
+      return (
+        usages.find(
+          (u) =>
+            (where.sourceRef === undefined || u.sourceRef === where.sourceRef) &&
+            (where.id === undefined || u.id === where.id) &&
+            (where.billAccountId === undefined || u.billAccountId === where.billAccountId),
+        ) ?? null
+      )
+    }
+    if (ctor === 'BillingAccountTransaction') {
+      const matches = transactions.filter(
+        (t) =>
+          (where.sourceRef === undefined || t.sourceRef === where.sourceRef) &&
+          (where.usageId === undefined || t.usageId === where.usageId) &&
+          (where.billAccountId === undefined || t.billAccountId === where.billAccountId),
+      )
+      // Insertion order IS chronological in this mock, so the last inserted
+      // matching row is the most recent — correct for both a key lookup and
+      // an `orderBy: { createdAt: 'DESC' }` "latest transaction" query (real
+      // millisecond timestamps can collide and break a createdAt sort).
+      void opts
+      return matches[matches.length - 1] ?? null
+    }
+    if (ctor === 'BillingItem') {
+      const item = options.usageItem
+      if (!item) return null
+      if (where.uomCode !== undefined && item.uomCode !== where.uomCode) return null
+      return item
+    }
+    if (ctor === 'BillingTopup') return options.topup ?? null
+    if (ctor === 'BillingStatement') {
+      // A `periodEnd: { $lt }` range query is the prior-statement (opening
+      // chaining) lookup; an exact period match is the anti-duplicate check.
+      const pe = where.periodEnd as { $lt?: unknown } | undefined
+      if (pe && typeof pe === 'object' && '$lt' in pe) {
+        return options.priorStatement ?? null
+      }
+      return options.existingStatement ?? null
+    }
+    // resolveInvoiceStatusEntryId looks up Dictionary then DictionaryEntry.
+    if (ctor === 'Dictionary') return { id: 'dict-invoice-status' }
+    if (ctor === 'DictionaryEntry') return { id: `status-${(where.value as string) ?? 'x'}` }
+    if (ctor === 'ModuleConfig') {
+      const name = where.name as string
+      const configs = options.configs ?? {}
+      if (name in configs) return { moduleId: 'billing', name, valueJson: configs[name] }
+      return null
+    }
+    return null
+  }) as never
+
+  em.find = jest.fn(async (entity: unknown) => {
+    const ctor = (entity as { name?: string }).name ?? ''
+    if (ctor === 'BillingItem') return options.items ?? []
+    return []
+  }) as never
+
+  em.execute = jest.fn(async (sql: string, params: unknown[] = []) => {
+    if (sql.includes('INSERT INTO billing_account_balances')) {
+      // params: [org, tenant, acct, ccy, now, now]
+      const [organizationId, tenantId, billAccountId, currencyCode] = params as string[]
+      const k = key(tenantId, billAccountId)
+      if (!balances.has(k)) {
+        balances.set(k, {
+          organizationId,
+          tenantId,
+          billAccountId,
+          currencyCode,
+          balance: '0.0000',
+          lowBalanceThreshold: null,
+          lastMovementAt: null,
+        })
+      }
+      return []
+    }
+    if (sql.includes('UPDATE billing_account_balances')) {
+      // params: [amount, now, now, tenant, acct]
+      const amount = params[0] as string
+      const tenantId = params[3]
+      const billAccountId = params[4]
+      const k = key(tenantId, billAccountId)
+      const row = balances.get(k)
+      if (!row) return []
+      row.balance = addMoney((row.balance as string) ?? '0', amount)
+      row.lastMovementAt = params[1] as Date
+      return [{ balance: row.balance }]
+    }
+    if (sql.includes('SUM(amount)') && sql.includes('billing_account_transactions')) {
+      // sumByTypeInWindow: params [tenant, org, acct, type, from, to]
+      if (sql.includes('type = ?') && sql.includes('created_at >= ?')) {
+        const type = params[3] as string
+        const from = new Date(params[4] as string).getTime()
+        const to = new Date(params[5] as string).getTime()
+        const total = transactions
+          .filter((t) => {
+            if (t.type !== type || !t.createdAt) return false
+            const ts = new Date(t.createdAt as Date).getTime()
+            return ts >= from && ts < to
+          })
+          .reduce((acc, t) => addMoney(acc, (t.amount as string) ?? '0'), '0')
+        return [{ total }]
+      }
+      // sumAmountsBefore: params [tenant, org, acct, before]
+      if (sql.includes('created_at < ?')) {
+        const before = new Date(params[3] as string).getTime()
+        const total = transactions
+          .filter((t) => t.createdAt && new Date(t.createdAt as Date).getTime() < before)
+          .reduce((acc, t) => addMoney(acc, (t.amount as string) ?? '0'), '0')
+        return [{ total }]
+      }
+      // reconcile (whole ledger)
+      const sum = transactions.reduce((acc, t) => addMoney(acc, (t.amount as string) ?? '0'), '0')
+      return [{ sum_amount: sum }]
+    }
+    if (sql.includes('SUM(outstanding_amount)')) {
+      return [{ total: String(options.postpaidOutstanding ?? '0') }]
+    }
+    return []
+  }) as never
+
+  em.nativeUpdate = jest.fn(async () => 0) as never
+  em.transactional = jest.fn(async (cb: (tem: MockEm) => unknown) => cb(em)) as never
+  em.fork = () => em
+
+  return em
+}

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

@@ -0,0 +1,93 @@
+import {
+  buildPostpaidCreditCrossingEvents,
+  getBalanceSnapshot,
+  getCreditSnapshot,
+} from '../../lib/accountStatus'
+import { createPrepaidMockEm } from '../helpers/prepaidMockEm'
+
+const TENANT = 'ten-1'
+const ORG = 'org-1'
+const ACCT = 'acct-1'
+
+function account(overrides: Record<string, unknown> = {}) {
+  return {
+    id: ACCT,
+    tenantId: TENANT,
+    organizationId: ORG,
+    currencyCode: 'EUR',
+    billingMode: 'prepaid',
+    creditLimit: '0',
+    ...overrides,
+  }
+}
+
+describe('getBalanceSnapshot', () => {
+  it('reports balance + resolved threshold + status', async () => {
+    const em = createPrepaidMockEm({
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '7.0000', lowBalanceThreshold: '10.0000' },
+    })
+    const snap = await getBalanceSnapshot(em as never, account() as never)
+    expect(snap.balance).toBe('7.0000')
+    expect(snap.lowBalanceThreshold).toBe('10.0000')
+    expect(snap.balanceStatus).toBe('low')
+  })
+})
+
+describe('getCreditSnapshot — both modes', () => {
+  it('prepaid: credit_used = max(0,−balance)', async () => {
+    const em = createPrepaidMockEm({
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '-30.0000' },
+    })
+    const snap = await getCreditSnapshot(em as never, account({ creditLimit: '50.0000' }) as never)
+    expect(snap.mode).toBe('prepaid')
+    expect(snap.creditUsed).toBe('30.0000')
+    expect(snap.availableCredit).toBe('20.0000')
+    expect(snap.creditStatus).toBe('within_limit')
+  })
+
+  it('postpaid: credit_used = Σ posted-unpaid outstanding', async () => {
+    const em = createPrepaidMockEm({ postpaidOutstanding: '4200.0000' })
+    const snap = await getCreditSnapshot(
+      em as never,
+      account({ billingMode: 'postpaid', creditLimit: '5000.0000' }) as never,
+    )
+    expect(snap.mode).toBe('postpaid')
+    expect(snap.creditUsed).toBe('4200.0000')
+    expect(snap.availableCredit).toBe('800.0000')
+    expect(snap.creditStatus).toBe('within_limit')
+  })
+})
+
+describe('buildPostpaidCreditCrossingEvents', () => {
+  it('emits over_limit when a posted invoice pushes outstanding past the limit', async () => {
+    // After posting, total outstanding 5200; this invoice contributed 300 →
+    // before 4900 (under 5000), after 5200 (over) → crossing.
+    const em = createPrepaidMockEm({ postpaidOutstanding: '5200.0000' })
+    const events = await buildPostpaidCreditCrossingEvents(
+      em as never,
+      account({ billingMode: 'postpaid', creditLimit: '5000.0000' }) as never,
+      '300.0000',
+    )
+    expect(events.map((e) => e.id)).toContain('billing.credit.over_limit')
+  })
+
+  it('no event when still under the limit', async () => {
+    const em = createPrepaidMockEm({ postpaidOutstanding: '4800.0000' })
+    const events = await buildPostpaidCreditCrossingEvents(
+      em as never,
+      account({ billingMode: 'postpaid', creditLimit: '5000.0000' }) as never,
+      '300.0000',
+    )
+    expect(events).toHaveLength(0)
+  })
+
+  it('no event for a prepaid account (handled on the consume path)', async () => {
+    const em = createPrepaidMockEm({ postpaidOutstanding: '9999.0000' })
+    const events = await buildPostpaidCreditCrossingEvents(
+      em as never,
+      account({ billingMode: 'prepaid', creditLimit: '5000.0000' }) as never,
+      '300.0000',
+    )
+    expect(events).toHaveLength(0)
+  })
+})

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

@@ -0,0 +1,125 @@
+import {
+  applyBalanceMovement,
+  reconcileAccountBalance,
+} from '../../lib/balanceLedger'
+import { createPrepaidMockEm } from '../helpers/prepaidMockEm'
+
+const SCOPE = {
+  organizationId: '22222222-2222-4222-8222-222222222222',
+  tenantId: '11111111-1111-4111-8111-111111111111',
+  billAccountId: '33333333-3333-4333-8333-333333333333',
+  currencyCode: 'EUR',
+}
+
+function newEm() {
+  return createPrepaidMockEm({
+    balance: { tenantId: SCOPE.tenantId, billAccountId: SCOPE.billAccountId, balance: '0.0000' },
+  })
+}
+
+describe('balanceLedger — applyBalanceMovement', () => {
+  it('credits and debits, snapshotting balance_after', async () => {
+    const em = newEm()
+    const credit = await applyBalanceMovement(em as never, {
+      ...SCOPE,
+      type: 'topup',
+      amount: '100.0000',
+      description: 'Top-up',
+    })
+    expect(credit.balanceBefore).toBe('0.0000')
+    expect(credit.balanceAfter).toBe('100.0000')
+    expect(credit.transaction.balanceAfter).toBe('100.0000')
+
+    const debit = await applyBalanceMovement(em as never, {
+      ...SCOPE,
+      type: 'usage',
+      amount: '-12.3400',
+      description: 'API requests',
+    })
+    expect(debit.balanceBefore).toBe('100.0000')
+    expect(debit.balanceAfter).toBe('87.6600')
+    expect(em.transactions).toHaveLength(2)
+  })
+
+  it('allows the balance to go negative (usage is never rejected)', async () => {
+    const em = newEm()
+    await applyBalanceMovement(em as never, {
+      ...SCOPE,
+      type: 'topup',
+      amount: '5.0000',
+      description: 'Top-up',
+    })
+    const debit = await applyBalanceMovement(em as never, {
+      ...SCOPE,
+      type: 'usage',
+      amount: '-8.0000',
+      description: 'Overspend',
+    })
+    expect(debit.balanceAfter).toBe('-3.0000')
+  })
+
+  it('is idempotent on sourceRef — no double-move', async () => {
+    const em = newEm()
+    const first = await applyBalanceMovement(em as never, {
+      ...SCOPE,
+      type: 'recurring',
+      amount: '-20.0000',
+      description: 'Platform fee',
+      sourceRef: 'recurring-item-2026-05-31',
+    })
+    expect(first.deduplicated).toBe(false)
+    expect(first.balanceAfter).toBe('-20.0000')
+
+    const retry = await applyBalanceMovement(em as never, {
+      ...SCOPE,
+      type: 'recurring',
+      amount: '-20.0000',
+      description: 'Platform fee',
+      sourceRef: 'recurring-item-2026-05-31',
+    })
+    expect(retry.deduplicated).toBe(true)
+    expect(retry.balanceAfter).toBe('-20.0000') // unchanged
+    expect(em.transactions).toHaveLength(1) // no second transaction
+  })
+})
+
+describe('balanceLedger — reconciliation invariant', () => {
+  it('balance == SUM(amount) == latest.balance_after after a sequence', async () => {
+    const em = newEm()
+    const moves: Array<{ type: 'topup' | 'usage' | 'recurring'; amount: string }> = [
+      { type: 'topup', amount: '100.0000' },
+      { type: 'usage', amount: '-5.0000' },
+      { type: 'usage', amount: '-3.0000' },
+      { type: 'recurring', amount: '-20.0000' },
+    ]
+    for (const m of moves) {
+      await applyBalanceMovement(em as never, { ...SCOPE, ...m, description: m.type })
+    }
+    const recon = await reconcileAccountBalance(em as never, SCOPE)
+    expect(recon.cachedBalance).toBe('72.0000')
+    expect(recon.sumOfAmounts).toBe('72.0000')
+    expect(recon.latestBalanceAfter).toBe('72.0000')
+    expect(recon.reconciled).toBe(true)
+  })
+
+  it('holds across many small sub-cent debits (no FP drift)', async () => {
+    const em = newEm()
+    await applyBalanceMovement(em as never, {
+      ...SCOPE,
+      type: 'topup',
+      amount: '1.0000',
+      description: 'Top-up',
+    })
+    for (let i = 0; i < 100; i++) {
+      await applyBalanceMovement(em as never, {
+        ...SCOPE,
+        type: 'usage',
+        amount: '-0.0010',
+        description: 'micro',
+      })
+    }
+    const recon = await reconcileAccountBalance(em as never, SCOPE)
+    expect(recon.cachedBalance).toBe('0.9000')
+    expect(recon.reconciled).toBe(true)
+  })
+})