@dainamite/billing 0.20.0 → 0.21.0

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

@@ -0,0 +1,319 @@
+import {
+  allocate,
+  applyAccountCredit,
+  fromCents,
+  paymentStatusFor,
+  planAllocation,
+  recomputeReceivable,
+  sortOpenReceivables,
+  toCents,
+  unallocate,
+} from '../../lib/allocation'
+import { accountLockKey, withAccountLock } from '../../lib/accountLock'
+
+const scope = { tenantId: 't-1', organizationId: 'o-1' }
+
+describe('allocation — pure helpers', () => {
+  it('converts money to cents and back (4 dp column format)', () => {
+    expect(toCents('123.4500')).toBe(12345)
+    expect(toCents(0.1 + 0.2)).toBe(30)
+    expect(toCents(null)).toBe(0)
+    expect(fromCents(12345)).toBe('123.4500')
+  })
+
+  it('orders receivables oldest due first, nulls last, then issue date and number', () => {
+    const rows = [
+      { id: 'c', dueDate: null, issueDate: '2026-01-01', number: 'C' },
+      { id: 'b', dueDate: '2026-02-01', issueDate: '2026-01-10', number: 'B' },
+      { id: 'a', dueDate: '2026-01-15', issueDate: '2026-01-01', number: 'A' },
+      { id: 'a2', dueDate: '2026-01-15', issueDate: '2026-01-01', number: 'A2' },
+    ]
+    expect(sortOpenReceivables(rows).map((r) => r.id)).toEqual(['a', 'a2', 'b', 'c'])
+  })
+
+  it('plans allocations never above outstanding and returns the remainder', () => {
+    expect(
+      planAllocation(15000, [
+        { id: 'i1', outstandingCents: 10000 },
+        { id: 'i2', outstandingCents: 0 },
+        { id: 'i3', outstandingCents: 3000 },
+      ]),
+    ).toEqual({
+      allocations: [
+        { invoiceId: 'i1', amountCents: 10000 },
+        { invoiceId: 'i3', amountCents: 3000 },
+      ],
+      remainderCents: 2000,
+    })
+    expect(planAllocation(500, [{ id: 'i1', outstandingCents: 10000 }])).toEqual({
+      allocations: [{ invoiceId: 'i1', amountCents: 500 }],
+      remainderCents: 0,
+    })
+  })
+
+  it.each([
+    [{ status: 'posted', totalGrossCents: 12300, paidCents: 0, creditedCents: 0 }, 'posted', 12300],
+    [{ status: 'posted', totalGrossCents: 12300, paidCents: 5000, creditedCents: 0 }, 'partially_paid', 7300],
+    [{ status: 'partially_paid', totalGrossCents: 12300, paidCents: 12300, creditedCents: 0 }, 'paid', 0],
+    [{ status: 'posted', totalGrossCents: 12300, paidCents: 0, creditedCents: 12300 }, 'credited', 0],
+    [{ status: 'posted', totalGrossCents: 12300, paidCents: 2300, creditedCents: 10000 }, 'paid', 0],
+    [{ status: 'paid', totalGrossCents: 12300, paidCents: 0, creditedCents: 0 }, 'posted', 12300],
+    [{ status: 'draft', totalGrossCents: 12300, paidCents: 0, creditedCents: 0 }, 'draft', 12300],
+  ])('recomputes %j → %s', (state, status, outstanding) => {
+    expect(recomputeReceivable(state)).toMatchObject({ status, outstandingCents: outstanding })
+  })
+
+  it('derives payment status from the unallocated amount', () => {
+    const base = { status: 'matched', billAccountId: 'a', amountCents: 10000 }
+    expect(paymentStatusFor({ ...base, unallocatedCents: 10000 })).toBe('matched')
+    expect(paymentStatusFor({ ...base, unallocatedCents: 4000 })).toBe('partially_allocated')
+    expect(paymentStatusFor({ ...base, unallocatedCents: 0 })).toBe('allocated')
+    expect(paymentStatusFor({ ...base, billAccountId: null, unallocatedCents: 10000 })).toBe('unmatched')
+    expect(paymentStatusFor({ ...base, status: 'ignored', unallocatedCents: 10000 })).toBe('ignored')
+    expect(paymentStatusFor({ ...base, status: 'converted_to_topup', unallocatedCents: 0 })).toBe('converted_to_topup')
+  })
+})
+
+// ─── DB service with an in-memory SQL fake ───────────────────────
+
+type Invoice = {
+  id: string
+  bill_account_id: string
+  currency_code: string
+  status: string
+  document_type: string
+  test_run: boolean
+  total_gross: string
+  outstanding: string
+  paid_total: string
+  credited_total: string
+  due_date: string | null
+  issue_date: string | null
+  number: string
+}
+type Payment = { id: string; bill_account_id: string | null; currency_code: string; amount: string; unallocated_amount: string; status: string; received_at: string; created_at: string }
+type Allocation = { id: string; source_type: string; source_id: string; invoice_id: string; amount: string; deleted_at: Date | null }
+
+function fakeDb(state: { invoices: Invoice[]; payments: Payment[] }) {
+  const allocations: Allocation[] = []
+  let seq = 0
+  const cents = (v: unknown) => Math.round(Number.parseFloat(String(v)) * 100)
+  const execute = jest.fn(async (sql: string, p: unknown[] = []) => {
+    const s = sql.replace(/\s+/g, ' ').trim()
+    if (s.startsWith('SELECT id, bill_account_id, currency_code, status, document_type')) {
+      return state.invoices.filter((i) => i.id === p[0]).map((i) => ({ ...i }))
+    }
+    if (s.startsWith('SELECT id, bill_account_id, currency_code, unallocated_amount AS unallocated')) {
+      return state.payments.filter((x) => x.id === p[0]).map((x) => ({ ...x, unallocated: x.unallocated_amount }))
+    }
+    if (s.startsWith('SELECT id, bill_account_id, currency_code, outstanding AS unallocated')) {
+      return state.invoices.filter((i) => i.id === p[0] && i.document_type === 'credit_memo').map((i) => ({ ...i, unallocated: i.outstanding }))
+    }
+    if (s.startsWith('UPDATE billing_invoices SET outstanding = outstanding -')) {
+      const memo = state.invoices.find((i) => i.id === p[2])
+      if (!memo || cents(memo.outstanding) < cents(p[0])) return []
+      const left = cents(memo.outstanding) - cents(p[0])
+      memo.outstanding = (left / 100).toFixed(4)
+      memo.status = left <= 0 ? 'paid' : 'posted'
+      return [{ id: memo.id }]
+    }
+    if (s.startsWith('UPDATE billing_invoices SET outstanding = LEAST')) {
+      const memo = state.invoices.find((i) => i.id === p[1])!
+      memo.outstanding = (Math.min(cents(memo.total_gross), cents(memo.outstanding) + cents(p[0])) / 100).toFixed(4)
+      memo.status = 'posted'
+      return [{ id: memo.id }]
+    }
+    if (s.startsWith('UPDATE billing_payments SET unallocated_amount = unallocated_amount -')) {
+      const pay = state.payments.find((x) => x.id === p[1])
+      if (!pay || cents(pay.unallocated_amount) < cents(p[0])) return []
+      pay.unallocated_amount = ((cents(pay.unallocated_amount) - cents(p[0])) / 100).toFixed(4)
+      return [{ id: pay.id }]
+    }
+    if (s.startsWith('UPDATE billing_payments SET unallocated_amount = LEAST')) {
+      const pay = state.payments.find((x) => x.id === p[1])!
+      pay.unallocated_amount = (Math.min(cents(pay.amount), cents(pay.unallocated_amount) + cents(p[0])) / 100).toFixed(4)
+      return [{ id: pay.id }]
+    }
+    if (s.startsWith('UPDATE billing_payments SET status = CASE')) {
+      const pay = state.payments.find((x) => x.id === p[0])!
+      const u = cents(pay.unallocated_amount)
+      pay.status = u <= 0 ? 'allocated' : u < cents(pay.amount) ? 'partially_allocated' : 'matched'
+      return []
+    }
+    if (s.startsWith('SELECT COALESCE(SUM(amount) FILTER')) {
+      const active = allocations.filter((a) => a.invoice_id === p[0] && !a.deleted_at)
+      const sum = (type: string) => active.filter((a) => a.source_type === type).reduce((t, a) => t + cents(a.amount), 0) / 100
+      return [{ paid: String(sum('payment')), credited: String(sum('credit_memo')) }]
+    }
+    if (s.startsWith('UPDATE billing_invoices SET paid_total')) {
+      const inv = state.invoices.find((i) => i.id === p[4])!
+      Object.assign(inv, { paid_total: p[0], credited_total: p[1], outstanding: p[2], status: p[3] })
+      return []
+    }
+    if (s.startsWith('UPDATE billing_allocations SET deleted_at')) {
+      const a = allocations.find((x) => x.id === p[1] && !x.deleted_at)
+      if (!a) return []
+      a.deleted_at = new Date()
+      return [a]
+    }
+    if (s.startsWith('SELECT id, outstanding, due_date, issue_date, number')) {
+      return state.invoices.filter(
+        (i) =>
+          i.bill_account_id === p[2] &&
+          i.currency_code === p[3] &&
+          ['posted', 'partially_paid'].includes(i.status) &&
+          ['invoice', 'debit_memo'].includes(i.document_type) &&
+          cents(i.outstanding) > 0,
+      )
+    }
+    if (s.startsWith("SELECT 'payment' AS source_type")) {
+      return state.payments
+        .filter((x) => x.bill_account_id === p[2] && x.currency_code === p[3] && ['matched', 'partially_allocated'].includes(x.status) && cents(x.unallocated_amount) > 0)
+        .sort((a, b) => (a.received_at < b.received_at ? -1 : 1))
+        .map((x) => ({ source_type: 'payment', id: x.id, available: x.unallocated_amount }))
+    }
+    throw new Error(`unexpected SQL: ${s.slice(0, 80)}`)
+  })
+  const em = {
+    execute,
+    create: jest.fn((_e: unknown, data: Record<string, unknown>) => {
+      const row = { id: `alloc-${++seq}`, ...data }
+      allocations.push({
+        id: row.id,
+        source_type: String(data.sourceType),
+        source_id: String(data.sourceId),
+        invoice_id: String(data.invoiceId),
+        amount: String(data.amount),
+        deleted_at: null,
+      })
+      return row
+    }),
+    persist: jest.fn(),
+    flush: jest.fn(async () => undefined),
+  }
+  return { em, allocations }
+}
+
+function invoice(overrides: Partial<Invoice>): Invoice {
+  return {
+    id: 'inv-1',
+    bill_account_id: 'acc-1',
+    currency_code: 'PLN',
+    status: 'posted',
+    document_type: 'invoice',
+    test_run: false,
+    total_gross: '123.0000',
+    outstanding: '123.0000',
+    paid_total: '0',
+    credited_total: '0',
+    due_date: '2026-11-28',
+    issue_date: '2026-11-14',
+    number: 'INV/2026/11/0001',
+    ...overrides,
+  }
+}
+
+function payment(overrides: Partial<Payment>): Payment {
+  return {
+    id: 'pay-1',
+    bill_account_id: 'acc-1',
+    currency_code: 'PLN',
+    amount: '200.0000',
+    unallocated_amount: '200.0000',
+    status: 'matched',
+    received_at: '2026-11-20',
+    created_at: '2026-11-20T10:00:00Z',
+    ...overrides,
+  }
+}
+
+describe('allocation — DB service', () => {
+  it('allocates part of a payment: invoice partially paid, payment partially allocated', async () => {
+    const state = { invoices: [invoice({})], payments: [payment({})] }
+    const { em } = fakeDb(state)
+    const effects = await allocate(em as never, scope, {
+      source: { type: 'payment', id: 'pay-1' },
+      invoiceId: 'inv-1',
+      amountCents: 5000,
+      by: 'user',
+    })
+    expect(state.invoices[0]).toMatchObject({ status: 'partially_paid', outstanding: '73.0000', paid_total: '50.0000' })
+    expect(state.payments[0]).toMatchObject({ unallocated_amount: '150.0000', status: 'partially_allocated' })
+    expect(effects.invoiceStatusChanges).toEqual([{ invoiceId: 'inv-1', from: 'posted', to: 'partially_paid' }])
+  })
+
+  it('refuses over-allocation, other accounts, other currencies and settled invoices', async () => {
+    const make = (inv: Partial<Invoice>, pay: Partial<Payment> = {}) =>
+      fakeDb({ invoices: [invoice(inv)], payments: [payment(pay)] }).em
+    const call = (em: unknown, amountCents = 1000) =>
+      allocate(em as never, scope, { source: { type: 'payment', id: 'pay-1' }, invoiceId: 'inv-1', amountCents, by: 'user' })
+    await expect(call(make({}), 20000)).rejects.toMatchObject({ body: expect.objectContaining({ code: 'billing.allocation.exceeds_outstanding' }) })
+    await expect(call(make({ bill_account_id: 'acc-2' }))).rejects.toMatchObject({ body: expect.objectContaining({ code: 'billing.allocation.account_mismatch' }) })
+    await expect(call(make({ currency_code: 'EUR' }))).rejects.toMatchObject({ body: expect.objectContaining({ code: 'billing.allocation.currency_mismatch' }) })
+    await expect(call(make({ status: 'paid', outstanding: '0' }))).rejects.toMatchObject({ body: expect.objectContaining({ code: 'billing.allocation.invoice_not_open' }) })
+    await expect(call(make({}, { unallocated_amount: '5.0000' }))).rejects.toMatchObject({ body: expect.objectContaining({ code: 'billing.allocation.insufficient_unallocated' }) })
+  })
+
+  it('un-allocates: restores the payment and reopens the invoice', async () => {
+    const state = { invoices: [invoice({})], payments: [payment({})] }
+    const { em } = fakeDb(state)
+    const created = await allocate(em as never, scope, { source: { type: 'payment', id: 'pay-1' }, invoiceId: 'inv-1', amountCents: 12300, by: 'user' })
+    expect(state.invoices[0].status).toBe('paid')
+    const effects = await unallocate(em as never, scope, { allocationId: created.created[0].allocationId })
+    expect(state.invoices[0]).toMatchObject({ status: 'posted', outstanding: '123.0000' })
+    expect(state.payments[0]).toMatchObject({ unallocated_amount: '200.0000', status: 'matched' })
+    expect(effects.removed).toHaveLength(1)
+    await expect(unallocate(em as never, scope, { allocationId: created.created[0].allocationId })).rejects.toMatchObject({ status: 404 })
+  })
+
+  it('applies account credit to the oldest due invoices first, oldest payment first', async () => {
+    const state = {
+      invoices: [
+        invoice({ id: 'late', due_date: '2026-12-28', number: 'INV/2' }),
+        invoice({ id: 'early', due_date: '2026-11-28', number: 'INV/1' }),
+      ],
+      payments: [payment({ id: 'p-new', received_at: '2026-11-25', amount: '100.0000', unallocated_amount: '100.0000' }), payment({ id: 'p-old', received_at: '2026-11-20', amount: '50.0000', unallocated_amount: '50.0000' })],
+    }
+    const { em, allocations } = fakeDb(state)
+    await applyAccountCredit(em as never, scope, { id: 'acc-1', currencyCode: 'PLN' })
+    expect(allocations.map((a) => [a.source_id, a.invoice_id, a.amount])).toEqual([
+      ['p-old', 'early', '50.0000'],
+      ['p-new', 'early', '73.0000'],
+      ['p-new', 'late', '27.0000'],
+    ])
+    expect(state.invoices.find((i) => i.id === 'early')!.status).toBe('paid')
+    expect(state.invoices.find((i) => i.id === 'late')!.outstanding).toBe('96.0000')
+  })
+
+  it('withAccountLock takes a per-account advisory lock inside a transaction', async () => {
+    const tem = { execute: jest.fn(async () => []) }
+    const em = { transactional: jest.fn(async (fn: (t: unknown) => Promise<unknown>) => fn(tem)) }
+    const result = await withAccountLock(em as never, { tenantId: 't-1', billAccountId: 'acc-1' }, async () => 'done')
+    expect(result).toBe('done')
+    expect(tem.execute).toHaveBeenCalledWith(expect.stringContaining('pg_advisory_xact_lock'), [accountLockKey({ tenantId: 't-1', billAccountId: 'acc-1' })])
+  })
+
+  it('credit memo source (Spec D): full credit marks the original credited and the memo settled; un-allocate reverts', async () => {
+    const memo = invoice({ id: 'cm-1', document_type: 'credit_memo', number: 'CN/1', total_gross: '123.0000', outstanding: '123.0000' })
+    const state = { invoices: [invoice({}), memo], payments: [] as Payment[] }
+    const { em } = fakeDb(state)
+    const effects = await allocate(em as never, scope, { source: { type: 'credit_memo', id: 'cm-1' }, invoiceId: 'inv-1', amountCents: 12300, by: 'credit' })
+    expect(state.invoices[0]).toMatchObject({ status: 'credited', outstanding: '0.0000', credited_total: '123.0000', paid_total: '0.0000' })
+    expect(memo).toMatchObject({ status: 'paid', outstanding: '0.0000' })
+    expect(effects.invoiceStatusChanges).toEqual([{ invoiceId: 'inv-1', from: 'posted', to: 'credited' }])
+    await unallocate(em as never, scope, { allocationId: effects.created[0].allocationId })
+    expect(state.invoices[0]).toMatchObject({ status: 'posted', outstanding: '123.0000' })
+    expect(memo).toMatchObject({ status: 'posted', outstanding: '123.0000' })
+  })
+
+  it('partial credit plus a payment settles the invoice as paid (not credited)', async () => {
+    const memo = invoice({ id: 'cm-1', document_type: 'credit_memo', number: 'CN/1', total_gross: '23.0000', outstanding: '23.0000' })
+    const state = { invoices: [invoice({}), memo], payments: [payment({ amount: '100.0000', unallocated_amount: '100.0000' })] }
+    const { em } = fakeDb(state)
+    await allocate(em as never, scope, { source: { type: 'credit_memo', id: 'cm-1' }, invoiceId: 'inv-1', amountCents: 2300, by: 'credit' })
+    expect(state.invoices[0]).toMatchObject({ status: 'partially_paid', outstanding: '100.0000' })
+    await allocate(em as never, scope, { source: { type: 'payment', id: 'pay-1' }, invoiceId: 'inv-1', amountCents: 10000, by: 'user' })
+    expect(state.invoices[0]).toMatchObject({ status: 'paid', outstanding: '0.0000', paid_total: '100.0000', credited_total: '23.0000' })
+  })
+})
+

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

@@ -6,6 +6,7 @@ import {
   BillingAccount,
   BillingAccountUsage,
   BillingItem,
+  BillingInvoice,
 } from '../../data/entities'
 
 /**
@@ -76,8 +77,15 @@ function createEnvironment(
       // test fixture records by uom for the runner.
       if (sql.includes('billing_account_usage') && sql.includes('GROUP BY uom_code')) {
         const accountId = (params?.[2] ?? '') as string
+        // Mirror the SQL bounds by calendar day: period_end <= ? [AND period_end > ?]
+        const day = (v: unknown) => new Date(v as Date).toISOString().slice(0, 10)
+        const upTo = params?.[3] ? day(params[3]) : null
+        const after = params?.[4] ? day(params[4]) : null
         const recs = (options.usageByAccount?.get(accountId) ?? []).filter(
-          (r) => r.ratedInBillRunId === null,
+          (r) =>
+            r.ratedInBillRunId === null &&
+            (!upTo || day(r.periodEnd) <= upTo) &&
+            (!after || day(r.periodEnd) > after),
         )
         const grouped = new Map<string, { sum: number; count: number }>()
         for (const r of recs) {
@@ -128,7 +136,15 @@ function createEnvironment(
       }
       return []
     }),
-    findOne: jest.fn(async (_entity: unknown, _where: unknown) => null),
+    // Dedupe check: an existing billing invoice for (account, bill date).
+    findOne: jest.fn(async (entity: unknown, where: unknown) => {
+      if (entity === BillingInvoice) {
+        const accountId = (where as { billAccountId?: string }).billAccountId
+        const existing = accountId ? options.openDraftIds?.get(accountId) : undefined
+        return existing ? { id: existing } : null
+      }
+      return null
+    }),
     nativeUpdate: jest.fn(async (entity: unknown, where: unknown, data: unknown) => {
       if (entity === BillingAccountUsage) {
         // Predicate-based bulk update (post-Phase-4f refactor): the
@@ -214,14 +230,21 @@ function makeAccount(overrides: Partial<BillingAccount>): BillingAccount {
   } as BillingAccount
 }
 
-function makeRecurringItem(billAccountId: string, id = 'item-mrc'): BillingItem {
+function makeRecurringItem(
+  billAccountId: string,
+  id = 'item-mrc',
+  overrides: Partial<BillingItem> = {},
+): BillingItem {
   return {
     id,
     organizationId: 'org-1',
     tenantId: 'tenant-1',
     billAccountId,
     type: 'recurring',
-    billStartDate: new Date('2026-01-01T00:00:00Z'),
+    // Starts on the account's bill date (Spec A default: billed in advance).
+    billStartDate: new Date('2026-06-01T00:00:00Z'),
+    chargeTiming: 'in_advance',
+    prorate: true,
     billEndDate: null,
     description: 'MRC',
     rateJson: { unit_price: 49.99 },
@@ -235,6 +258,7 @@ function makeRecurringItem(billAccountId: string, id = 'item-mrc'): BillingItem
     createdAt: new Date(),
     updatedAt: new Date(),
     deletedAt: null,
+    ...overrides,
   } as BillingItem
 }
 
@@ -268,7 +292,8 @@ describe('runBillRun — orchestration', () => {
     expect(outcomes[0].draftInvoiceId).toMatch(/^gen-/)
     // Real-mode advances next_bill_date
     expect(account.nextBillDate.toISOString().slice(0, 10)).toBe('2026-07-01')
-    expect(item.billedToDate?.toISOString().slice(0, 10)).toBe('2026-05-31')
+    // In advance: the June bill date bills June (Spec A).
+    expect(item.billedToDate?.toISOString().slice(0, 10)).toBe('2026-06-30')
     // Persisted entities: BillingRun + SalesInvoice + 1 line + BillingAccountUsage advance + BillingRunOutcome
     expect(captured.persisted.length).toBeGreaterThan(0)
   })
@@ -445,11 +470,10 @@ describe('runBillRun — orchestration', () => {
     expect(outcomes[0].status).toBe('success')
     // Persisted SalesInvoiceLine for the usage item with the right total
     const usageLine = captured.persisted.find((p) => {
-      const m = (p as { metadata?: { billing_type?: string } }).metadata
-      return m?.billing_type === 'usage'
+      return (p as { billingType?: string }).billingType === 'usage'
     })
     expect(usageLine).toBeDefined()
-    expect((usageLine as { totalNetAmount?: string }).totalNetAmount).toBe('15.0000')
+    expect((usageLine as { netAmount?: string }).netAmount).toBe('15.0000')
 
     // Real-mode marks records as rated
     expect(u1.ratedInBillRunId).toBe(billRun.id)
@@ -488,12 +512,11 @@ describe('runBillRun — orchestration', () => {
     await runBillRun(em as never, container as never, params({}))
 
     const usageLine = captured.persisted.find((p) => {
-      const m = (p as { metadata?: { billing_type?: string } }).metadata
-      return m?.billing_type === 'usage'
-    }) as { unitPriceNet?: string; totalNetAmount?: string; quantity?: string } | undefined
+      return (p as { billingType?: string }).billingType === 'usage'
+    }) as { unitPriceNet?: string; netAmount?: string; quantity?: string } | undefined
     expect(usageLine?.unitPriceNet).toBe('0.0010')
     expect(usageLine?.quantity).toBe('12000.0000')
-    expect(usageLine?.totalNetAmount).toBe('12.0000')
+    expect(usageLine?.netAmount).toBe('12.0000')
   })
 
   it('test mode: rates usage on draft but does NOT mark records as rated', async () => {
@@ -525,15 +548,15 @@ describe('runBillRun — orchestration', () => {
     await runBillRun(em as never, container as never, params({}))
 
     const lines = captured.persisted.filter((p) => {
-      const m = (p as { metadata?: { billing_type?: string } }).metadata
-      return m?.billing_type === 'recurring' || m?.billing_type === 'usage'
+      const type = (p as { billingType?: string }).billingType
+      return type === 'recurring' || type === 'usage'
     })
     expect(lines).toHaveLength(2)
     // Invoice header totalNet should be 49.99 (MRC) + 12.00 (usage) = 61.99
     const invoice = captured.persisted.find(
-      (p) => (p as { invoiceNumber?: string }).invoiceNumber,
-    ) as { grandTotalNetAmount?: string } | undefined
-    expect(invoice?.grandTotalNetAmount).toBe('61.9900')
+      (p) => (p as { documentType?: string }).documentType === 'invoice',
+    ) as { subtotalNet?: string } | undefined
+    expect(invoice?.subtotalNet).toBe('61.9900')
   })
 
   it('summary aggregates drafts_created / accounts_failed / accounts_with_warnings', async () => {
@@ -559,3 +582,191 @@ describe('runBillRun — orchestration', () => {
     })
   })
 })
+
+// ─── Spec A — cycle semantics ────────────────────────────────────
+
+describe('runBillRun — Spec A cycles', () => {
+  const day = (d: Date | null | undefined) => (d ? new Date(d).toISOString().slice(0, 10) : null)
+  type Cycle = { bill_date: string; status: string; period_start: string | null; period_end: string | null; invoice_id: string | null }
+  const cyclesOf = (outcome: { cycles?: unknown }) => (outcome.cycles ?? []) as Cycle[]
+  const invoicesOf = (persisted: unknown[]) =>
+    persisted.filter((p) => (p as { documentType?: string }).documentType === 'invoice') as Array<{
+      number: string
+      billDate: Date
+      testRun: boolean
+      metadata: Record<string, unknown>
+    }>
+
+  function operatorScenario() {
+    const account = makeAccount({ nextBillDate: new Date('2026-11-14T00:00:00Z') })
+    const item = makeRecurringItem(account.id, 'internet', {
+      billStartDate: new Date('2026-11-14T00:00:00Z'),
+      rateJson: { unit_price: 100 },
+    })
+    return { account, item }
+  }
+  const asOf = new Date('2027-02-01T00:00:00Z')
+
+  it("real: the operator's test bills 3 cycles and advances the account", async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+
+    const { billRun, outcomes } = await runBillRun(env.em as never, env.container as never, params({ asOfDate: asOf }))
+
+    expect(cyclesOf(outcomes[0]).map((c) => [c.bill_date, c.period_start, c.period_end, c.status])).toEqual([
+      ['2026-11-14', '2026-11-14', '2026-12-13', 'invoiced'],
+      ['2026-12-14', '2026-12-14', '2027-01-13', 'invoiced'],
+      ['2027-01-14', '2027-01-14', '2027-02-13', 'invoiced'],
+    ])
+    expect(invoicesOf(env.captured.persisted).map((i) => day(i.billDate))).toEqual([
+      '2026-11-14',
+      '2026-12-14',
+      '2027-01-14',
+    ])
+    expect(day(account.nextBillDate)).toBe('2027-02-14')
+    expect(day(item.billedToDate)).toBe('2027-02-13')
+    expect(billRun.summary).toMatchObject({ drafts_created: 3, cycles_processed: 3 })
+  })
+
+  it('a scheduled run catches up exactly like a manual one', async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+    const { outcomes } = await runBillRun(
+      env.em as never,
+      env.container as never,
+      params({ asOfDate: asOf, triggeredBy: 'schedule' }),
+    )
+    expect(cyclesOf(outcomes[0])).toHaveLength(3)
+  })
+
+  it('test: writes a TEST draft per cycle and leaves the account untouched', async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({ asOfDate: asOf, mode: 'test' }))
+
+    expect(cyclesOf(outcomes[0]).map((c) => c.status)).toEqual(['invoiced', 'invoiced', 'invoiced'])
+    const invoices = invoicesOf(env.captured.persisted)
+    expect(invoices).toHaveLength(3)
+    expect(invoices.every((i) => i.number.startsWith('TEST-') && i.testRun === true)).toBe(true)
+    expect(day(account.nextBillDate)).toBe('2026-11-14')
+    expect(item.billedToDate).toBeNull()
+    expect(env.numberGenerator.generate).not.toHaveBeenCalled()
+  })
+
+  it('dry: previews every cycle and persists no invoice', async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({ asOfDate: asOf, mode: 'dry' }))
+
+    expect(cyclesOf(outcomes[0]).map((c) => [c.status, c.invoice_id])).toEqual([
+      ['previewed', null],
+      ['previewed', null],
+      ['previewed', null],
+    ])
+    expect(invoicesOf(env.captured.persisted)).toHaveLength(0)
+    expect(day(account.nextBillDate)).toBe('2026-11-14')
+    expect(item.billedToDate).toBeNull()
+  })
+
+  it('test re-run: existing test drafts are skipped per cycle, simulation continues', async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({
+      accounts: [account],
+      itemsByAccount: new Map([[account.id, [item]]]),
+      openDraftIds: new Map([[account.id, 'test-draft']]),
+    })
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({ asOfDate: asOf, mode: 'test' }))
+    expect(outcomes[0].status).toBe('success')
+    expect(cyclesOf(outcomes[0]).map((c) => c.status)).toEqual(['skipped_existing', 'skipped_existing', 'skipped_existing'])
+    expect(invoicesOf(env.captured.persisted)).toHaveLength(0)
+  })
+
+  it('test mode never bills the same usage twice across simulated cycles', async () => {
+    const account = makeAccount({ nextBillDate: new Date('2026-06-01T00:00:00Z') })
+    const usageItem = {
+      ...makeRecurringItem(account.id, 'usage-api'),
+      type: 'usage',
+      uomCode: 'api_request',
+      rateJson: { unit_price: 0.01 },
+    } as BillingItem
+    const record = {
+      id: 'u1',
+      organizationId: 'org-1',
+      tenantId: 'tenant-1',
+      billAccountId: account.id,
+      uomCode: 'api_request',
+      quantity: '100.0000',
+      periodStart: new Date('2026-05-01T00:00:00Z'),
+      periodEnd: new Date('2026-05-31T00:00:00Z'),
+      ratedInBillRunId: null,
+      deletedAt: null,
+    } as BillingAccountUsage
+    const env = createEnvironment({
+      accounts: [account],
+      itemsByAccount: new Map([[account.id, [usageItem]]]),
+      usageByAccount: new Map([[account.id, [record]]]),
+    })
+
+    const { outcomes } = await runBillRun(
+      env.em as never,
+      env.container as never,
+      params({ asOfDate: new Date('2026-08-01T00:00:00Z'), mode: 'test' }),
+    )
+
+    expect(cyclesOf(outcomes[0]).map((c) => c.status)).toEqual(['invoiced', 'empty', 'empty'])
+    expect(record.ratedInBillRunId).toBeNull()
+  })
+
+  it('in advance and in arrears items share one invoice with their own service periods', async () => {
+    const account = makeAccount({})
+    const advance = makeRecurringItem(account.id, 'adv')
+    const arrears = makeRecurringItem(account.id, 'arr', {
+      chargeTiming: 'in_arrears',
+      billStartDate: new Date('2026-05-01T00:00:00Z'),
+    })
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [advance, arrears]]]) })
+
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({}))
+
+    const lines = env.captured.persisted.filter((p) => (p as { billingType?: string }).billingType === 'recurring') as Array<{ billingItemId: string; servicePeriodStart: Date; servicePeriodEnd: Date }>
+    expect(lines.map((l) => [l.billingItemId, day(l.servicePeriodStart), day(l.servicePeriodEnd)])).toEqual([
+      ['adv', '2026-06-01', '2026-06-30'],
+      ['arr', '2026-05-01', '2026-05-31'],
+    ])
+    expect(cyclesOf(outcomes[0])[0]).toMatchObject({ period_start: '2026-05-01', period_end: '2026-06-30' })
+  })
+
+  it('an item ended after advance billing gets a credit line (negative total warning)', async () => {
+    const account = makeAccount({ nextBillDate: new Date('2026-07-01T00:00:00Z') })
+    const item = makeRecurringItem(account.id, 'cancelled', {
+      billedToDate: new Date('2026-06-30T00:00:00Z'),
+      billEndDate: new Date('2026-06-15T00:00:00Z'),
+      rateJson: { unit_price: 30 },
+    })
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+
+    const { outcomes } = await runBillRun(
+      env.em as never,
+      env.container as never,
+      params({ asOfDate: new Date('2026-07-01T00:00:00Z') }),
+    )
+
+    const line = env.captured.persisted.find((p) => (p as { metadata?: { credit_for?: string } | null }).metadata?.credit_for) as { netAmount: string; description: string }
+    expect(line.netAmount).toBe('-15.0000')
+    expect(line.description).toBe('MRC · 2026-06-16 – 2026-06-30')
+    expect(day(item.billedToDate)).toBe('2026-06-15')
+    expect(outcomes[0].status).toBe('success_with_warnings')
+    expect((outcomes[0].warnings as { negative_total_bill_dates?: string[] }).negative_total_bill_dates).toEqual(['2026-07-01'])
+  })
+
+  it('stops at the hard cap and warns', async () => {
+    const account = makeAccount({ nextBillDate: new Date('2020-01-01T00:00:00Z') })
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, []]]) })
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({ mode: 'dry' }))
+    expect(cyclesOf(outcomes[0])).toHaveLength(60)
+    expect((outcomes[0].warnings as { catch_up_cap_reached?: boolean }).catch_up_cap_reached).toBe(true)
+    expect(outcomes[0].status).toBe('success_with_warnings')
+  })
+})