@dainamite/billing 0.20.0 → 0.21.0

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

@@ -8,43 +8,97 @@ import {
   BillingRun,
 } from '../data/entities'
 import type { BillCycle } from '../data/validators'
-import { advanceNextBillDate, addDays, deriveBillPeriod, isCycleDue, type BillPeriod } from './billPeriod'
+import {
+  addDays,
+  advanceNextBillDate,
+  deriveBillPeriod,
+  isCycleDue,
+  shiftCycles,
+  type BillPeriod,
+} from './billPeriod'
 import { applyBalanceMovement } from './balanceLedger'
 import { resolveLowBalanceThreshold } from './balanceStatus'
-import { buildInvoiceLinesFromItems } from './invoiceWriter'
-import { selectItemsForPeriod, type SelectableItem } from './itemSelector'
+import {
+  buildInvoiceLinesFromItems,
+  buildRecurringLineDescriptors,
+  type InvoiceLineDescriptor,
+} from './invoiceWriter'
+import { shouldIncludeItem, type SelectableItem } from './itemSelector'
+import { computeRecurringLines, type RecurringSkip } from './servicePeriods'
 import { absMoney, addMoney, fromUnits, subMoney, toUnits } from './money'
 import {
   getLowBalanceThresholdDefault,
   getNearLimitBufferDefault,
+  getPrepaidTaxPoint,
   getStatementEnabled,
 } from './prepaidConfig'
+import {
+  buildVatSummary,
+  resolvePrepaidDebit,
+  type PrepaidDebit,
+  type PrepaidTaxPoint,
+  type VatSummaryRow,
+} from './prepaidTaxPoint'
 import { buildBalanceCrossingEvents, type DomainEvent } from './balanceEvents'
+import { toIsoDate, toUtcMidnight } from './dateOnly'
 
 /**
- * Prepaid period close (SPEC-002 P3).
+ * Prepaid period close (SPEC-002 P3, reworked by Spec F).
+ *
+ * A prepaid account never gets a payable draft invoice. For every due bill
+ * date D (catch-up up to `asOfDate`, one rule for every trigger) the run:
+ *   1. charges `recurring` items per their `charge_timing` and `prorate`
+ *      (Spec F, F-D4 — the same `computeRecurringLines` the postpaid engine
+ *      uses: in advance → `[D, D + cycle − 1]`, in arrears → `[D − cycle,
+ *      D − 1]`) and `one_time` items on the first bill date whose window
+ *      overlaps them, debiting the balance through the org's tax point
+ *      (Spec F, F-D3 — `resolvePrepaidDebit`);
+ *   2. builds a non-fiscal **BillingStatement** for `[D − cycle, D − 1]`
+ *      (opening, top-ups, usage, charges taken at D, closing, per-line
+ *      breakdown, VAT summary).
  *
- * A prepaid account never gets a payable draft invoice. Instead the Bill Run,
- * for a due prepaid account:
- *   1. charges its `recurring` / `one_time` items to the **balance** (atomic
- *      debit + transaction, deterministic `source_ref =
- *      recurring-{itemId}-{periodEndISO}`, then `billed_to_date = period_end`),
- *   2. builds a non-fiscal **BillingStatement** (opening, topups, usage,
- *      recurring, closing + per-item breakdown).
+ * Metered usage was rated + debited in real time during the period — it is
+ * NOT re-rated here; the statement only summarises it.
  *
- * Metered usage was already rated + debited in real time during the period —
- * it is NOT re-rated here; the statement only summarizes it.
+ * Bill date and item watermarks advance in memory, so test and dry runs
+ * simulate every due cycle exactly like a real run; only persistence differs.
  *
- * Three anti-duplicate guards: the statement unique
- * `(bill_account_id, period_start, period_end)`, the per-item `billed_to_date`,
- * and the deterministic charge `source_ref`.
+ * Anti-duplicate guards: the per-item `billed_to_date` watermark, the
+ * deterministic charge `source_ref`, and the statement unique
+ * `(bill_account_id, period_start, period_end)`. A statement that already
+ * exists for a period means that period was closed: the run skips the
+ * statement, still applies (idempotent) charges, and advances — it never
+ * leaves the account stuck behind an existing statement.
  */
 
 export type PrepaidCloseMode = 'real' | 'test' | 'dry'
 
+export type PrepaidCycleStatus = 'charged' | 'previewed' | 'empty' | 'skipped_existing'
+
+/** Same shape as the postpaid `CycleRecord` (Spec F, P-D6) plus prepaid fields. */
+export type PrepaidCycleRecord = {
+  bill_date: string
+  period_start: string
+  period_end: string
+  status: PrepaidCycleStatus
+  line_count: number
+  total_net: string
+  /** What left the balance for this bill date (gross in `consumption` mode). */
+  total_debit: string
+  invoice_id: null
+  statement_id: string | null
+}
+
+export type PrepaidSkippedItem = {
+  item_id: string
+  reason: string
+  service_period_start: string | null
+  service_period_end: string | null
+}
+
 export type PrepaidAccountWarnings = {
-  // Reserved for future per-close warnings (e.g. negative-balance close).
-  closed_negative?: boolean
+  skipped_items?: PrepaidSkippedItem[]
+  catch_up_cap_reached?: boolean
 }
 
 export type PrepaidAccountResult =
@@ -53,279 +107,362 @@ export type PrepaidAccountResult =
       warnings: PrepaidAccountWarnings | null
       statementId: string | null
       cyclesEmitted: number
+      cycles: PrepaidCycleRecord[]
       statementEvents: DomainEvent[]
     }
   | { status: 'failed'; errorMessage: string }
 
-const SCHEDULED_CYCLE_LIMIT = 1
 const CATCH_UP_HARD_CAP = 60
+const SKIPPED_ITEMS_WARNING_CAP = 200
+/** Skip reasons that are normal state, not worth surfacing on the outcome. */
+const QUIET_SKIP_REASONS = new Set(['item-inactive', 'item-soft-deleted'])
 
 export type ProcessPrepaidParams = {
   asOfDate: Date
   mode: PrepaidCloseMode
   triggeredBy: 'schedule' | 'manual'
-  catchUp?: boolean
 }
 
-/**
- * Multi-cycle prepaid account processing (mirrors the postpaid engine's
- * catch-up loop). One statement + one set of recurring debits per missed
- * period — never combined.
- */
+type ChargeLine = {
+  descriptor: InvoiceLineDescriptor
+  amounts: PrepaidDebit
+  sourceRef: string
+}
+
+type CycleContext = {
+  mode: PrepaidCloseMode
+  taxPoint: PrepaidTaxPoint
+  statementEnabled: boolean
+  threshold: string
+  nearLimitBuffer: string
+  creditLimit: string
+}
+
+function chargeSourceRef(line: InvoiceLineDescriptor, kind: 'charge' | 'credit'): string {
+  if (line.billingType === 'one_time') return `one_time-${line.billingItemId}`
+  const start = line.servicePeriodStart ? toIsoDate(line.servicePeriodStart) : 'na'
+  const end = line.servicePeriodEnd ? toIsoDate(line.servicePeriodEnd) : 'na'
+  return `recurring-${line.billingItemId}-${kind}-${start}-${end}`
+}
+
+function money4(value: number): string {
+  return fromUnits(Math.round(value * 10000))
+}
+
+function toSkipWarning(skip: RecurringSkip): PrepaidSkippedItem {
+  return {
+    item_id: skip.billingItemId,
+    reason: skip.reason,
+    service_period_start: skip.servicePeriodStart ? toIsoDate(skip.servicePeriodStart) : null,
+    service_period_end: skip.servicePeriodEnd ? toIsoDate(skip.servicePeriodEnd) : null,
+  }
+}
+
+function toCharge(descriptor: InvoiceLineDescriptor, kind: 'charge' | 'credit', taxPoint: PrepaidTaxPoint): ChargeLine {
+  return {
+    descriptor,
+    amounts: resolvePrepaidDebit({
+      lineAmount: descriptor.lineAmount,
+      priceBasis: descriptor.priceBasis,
+      taxRate: descriptor.taxRate,
+      taxPoint,
+    }),
+    sourceRef: chargeSourceRef(descriptor, kind),
+  }
+}
+
 export async function processPrepaidAccount(
   em: EntityManager,
   account: BillingAccount,
   billRun: BillingRun,
   params: ProcessPrepaidParams,
 ): Promise<PrepaidAccountResult> {
-  const maxCycles =
-    params.triggeredBy === 'schedule' || !params.catchUp
-      ? SCHEDULED_CYCLE_LIMIT
-      : CATCH_UP_HARD_CAP
-
-  const statementEnabled = await getStatementEnabled(em)
-  // Resolve the crossing thresholds once — they don't change during the run.
+  const scope = { tenantId: account.tenantId, organizationId: account.organizationId }
+  const cycle = account.billCycle as BillCycle
   const balanceRow = await em.findOne(BillingAccountBalance, {
     tenantId: account.tenantId,
     billAccountId: account.id,
   })
-  const threshold = resolveLowBalanceThreshold(
-    balanceRow?.lowBalanceThreshold ?? null,
-    await getLowBalanceThresholdDefault(em),
+  const ctx: CycleContext = {
+    mode: params.mode,
+    taxPoint: await getPrepaidTaxPoint(em, scope),
+    statementEnabled: await getStatementEnabled(em, scope),
+    threshold: resolveLowBalanceThreshold(
+      balanceRow?.lowBalanceThreshold ?? null,
+      await getLowBalanceThresholdDefault(em, scope),
+    ),
+    nearLimitBuffer: await getNearLimitBufferDefault(em, scope),
+    creditLimit: account.creditLimit ?? '0',
+  }
+
+  const items = (await em.find(BillingItem, {
+    tenantId: account.tenantId,
+    organizationId: account.organizationId,
+    billAccountId: account.id,
+    deletedAt: null,
+  } as never)) as BillingItem[]
+  const recurringItems = items.filter((it) => it.type === 'recurring')
+  const oneTimeItems = items.filter((it) => it.type === 'one_time')
+
+  // In-memory cycle state — persisted per cycle only in real mode.
+  const watermarks = new Map<string, Date | null>(
+    recurringItems.map((it) => [it.id, it.billedToDate ? toUtcMidnight(it.billedToDate) : null]),
   )
-  const nearLimitBuffer = await getNearLimitBufferDefault(em)
-  const creditLimit = account.creditLimit ?? '0'
+  const billedOneTimes = new Set<string>(oneTimeItems.filter((it) => it.billedToDate).map((it) => it.id))
+  let billDate = toUtcMidnight(account.nextBillDate)
+  // Chain opening → closing across cycles. Null on the first cycle →
+  // resolved from the prior statement / ledger.
+  let previousClosing: string | null = null
 
-  let cyclesEmitted = 0
-  let lastStatementId: string | null = null
+  const cycles: PrepaidCycleRecord[] = []
+  const skippedItems: PrepaidSkippedItem[] = []
+  const warnings: PrepaidAccountWarnings = {}
   const statementEvents: DomainEvent[] = []
-  // Chain opening → closing across cycles in a catch-up run. Null on the first
-  // cycle → closePrepaidPeriod resolves it from the prior statement / ledger.
-  let previousClosing: string | null = null
+  let lastStatementId: string | null = null
 
-  while (cyclesEmitted < maxCycles && isCycleDue(account.nextBillDate, params.asOfDate)) {
-    const period = deriveBillPeriod(account.nextBillDate, account.billCycle as BillCycle)
+  const pushSkips = (skips: readonly RecurringSkip[]) => {
+    for (const skip of skips) {
+      if (QUIET_SKIP_REASONS.has(skip.reason)) continue
+      if (skippedItems.length < SKIPPED_ITEMS_WARNING_CAP) skippedItems.push(toSkipWarning(skip))
+    }
+  }
 
-    // Statement anti-duplicate (only when we would actually persist).
-    if (params.mode !== 'dry') {
-      const existing = await em.findOne(BillingStatement, {
-        tenantId: account.tenantId,
-        billAccountId: account.id,
-        periodStart: period.periodStart,
-        periodEnd: period.periodEnd,
-      })
-      if (existing) {
-        return {
-          status: 'skipped_existing_statement',
-          warnings: null,
-          statementId: existing.id,
-          cyclesEmitted,
-          statementEvents,
-        }
-      }
+  while (isCycleDue(billDate, params.asOfDate)) {
+    if (cycles.length >= CATCH_UP_HARD_CAP) {
+      warnings.catch_up_cap_reached = true
+      break
     }
+    const nextBillDate = advanceNextBillDate(billDate, cycle)
+    const period = deriveBillPeriod(billDate, cycle)
 
-    const cycle = await closePrepaidPeriod(em, account, period, billRun, {
-      mode: params.mode,
-      statementEnabled,
-      previousClosing,
-      threshold,
-      nearLimitBuffer,
-      creditLimit,
-    })
-    previousClosing = cycle.closingBalance
-    // Recurring charges move the balance too, so they can trip the same
-    // low/exhausted/over_limit crossings as a usage debit (SPEC-002). These
-    // are accumulated and emitted by the engine AFTER the run commits.
-    statementEvents.push(...cycle.crossingEvents)
-
-    // A negative closing balance is NORMAL for prepaid (the customer overspent;
-    // it's cleared by the next top-up), so it is not flagged as a warning.
-    if (cycle.statementId) {
-      lastStatementId = cycle.statementId
-      statementEvents.push({
-        id: 'billing.statement.generated',
-        payload: {
-          statementId: cycle.statementId,
-          billAccountId: account.id,
-          tenantId: account.tenantId,
-          organizationId: account.organizationId,
-          billRunId: billRun.id,
-          periodStart: period.periodStart.toISOString().slice(0, 10),
-          periodEnd: period.periodEnd.toISOString().slice(0, 10),
-          currencyCode: account.currencyCode,
-          openingBalance: cycle.openingBalance,
-          closingBalance: cycle.closingBalance,
-          totalTopups: cycle.totalTopups,
-          totalUsage: cycle.totalUsage,
-          totalRecurring: cycle.totalRecurring,
-          totalAdjustments: cycle.totalAdjustments,
+    // ── Recurring: service periods against the in-memory watermarks ──
+    const charges: ChargeLine[] = []
+    const watermarkUpdates = new Map<string, Date | null>()
+    for (const item of recurringItems) {
+      const unitPrice = (item.rateJson as { unit_price?: number } | null)?.unit_price
+      if (typeof unitPrice !== 'number') continue
+      const computed = computeRecurringLines(
+        {
+          id: item.id,
+          chargeTiming: item.chargeTiming ?? 'in_advance',
+          prorate: item.prorate ?? true,
+          billStartDate: item.billStartDate,
+          billEndDate: item.billEndDate ?? null,
+          billedToDate: watermarks.get(item.id) ?? null,
+          unitPrice,
+          isActive: item.isActive,
+          deletedAt: item.deletedAt ?? null,
         },
+        { billDate, cycle },
+      )
+      pushSkips(computed.skipped)
+      if (computed.newBilledToDate?.getTime() !== watermarks.get(item.id)?.getTime()) {
+        watermarkUpdates.set(item.id, computed.newBilledToDate)
+      }
+      const descriptors = buildRecurringLineDescriptors(item, computed.lines)
+      descriptors.forEach((descriptor, index) => {
+        charges.push(toCharge(descriptor, computed.lines[index]?.kind ?? 'charge', ctx.taxPoint))
       })
     }
 
+    // ── One-time: first bill date whose [D − cycle, D + cycle − 1] window
+    //    overlaps (same rule as postpaid) ──
+    const oneTimeWindow: BillPeriod = {
+      periodStart: shiftCycles(billDate, cycle, -1),
+      periodEnd: addDays(nextBillDate, -1),
+    }
+    const oneTimesThisCycle = oneTimeItems.filter(
+      (it) => !billedOneTimes.has(it.id) && shouldIncludeItem(it as SelectableItem, oneTimeWindow).include,
+    )
+    for (const descriptor of buildInvoiceLinesFromItems(oneTimesThisCycle)) {
+      charges.push(toCharge(descriptor, 'charge', ctx.taxPoint))
+    }
+
+    const closed = await closePrepaidPeriod(em, account, billRun, { billDate, period, charges, previousClosing }, ctx)
+    previousClosing = closed.closingBalance
+    statementEvents.push(...closed.events)
+    if (closed.statementId) lastStatementId = closed.statementId
+    cycles.push(closed.record)
+
+    // Advance the in-memory state (every mode); persist in real mode only.
+    for (const [itemId, watermark] of watermarkUpdates) watermarks.set(itemId, watermark)
+    for (const item of oneTimesThisCycle) billedOneTimes.add(item.id)
     if (params.mode === 'real') {
-      account.nextBillDate = advanceNextBillDate(
-        account.nextBillDate,
-        account.billCycle as BillCycle,
-      )
+      const now = new Date()
+      for (const item of recurringItems) {
+        if (!watermarkUpdates.has(item.id)) continue
+        item.billedToDate = watermarkUpdates.get(item.id) ?? null
+        item.updatedAt = now
+      }
+      for (const item of oneTimesThisCycle) {
+        item.billedToDate = period.periodEnd
+        item.updatedAt = now
+      }
+      account.nextBillDate = nextBillDate
       account.lastBillDate = period.periodEnd
-      account.updatedAt = new Date()
+      account.updatedAt = now
       await em.flush()
-    } else {
-      // test / dry: do not advance state; one iteration only.
-      cyclesEmitted += 1
-      break
     }
-    cyclesEmitted += 1
+    billDate = nextBillDate
   }
 
+  const finalWarnings: PrepaidAccountWarnings = {
+    ...warnings,
+    ...(skippedItems.length ? { skipped_items: skippedItems } : {}),
+  }
   return {
-    status: 'success',
-    warnings: null,
+    status: warnings.catch_up_cap_reached ? 'success_with_warnings' : 'success',
+    warnings: Object.keys(finalWarnings).length ? finalWarnings : null,
     statementId: lastStatementId,
-    cyclesEmitted,
+    cyclesEmitted: cycles.filter((c) => c.status === 'charged' || c.status === 'previewed').length,
+    cycles,
     statementEvents,
   }
 }
 
+type ClosePeriodInput = {
+  billDate: Date
+  period: BillPeriod
+  charges: ChargeLine[]
+  previousClosing: string | null
+}
+
 type ClosePeriodResult = {
+  record: PrepaidCycleRecord
+  /** The statement CREATED by this close (null when skipped or not written). */
   statementId: string | null
-  openingBalance: string
-  totalTopups: string
-  totalUsage: string
-  totalRecurring: string
-  totalAdjustments: string
   closingBalance: string
-  crossingEvents: DomainEvent[]
+  events: DomainEvent[]
 }
 
 type DebitBreakdownEntry = {
   billing_item_id: string
   billing_type: string
-  uom_code?: string
+  description: string
   quantity: string
+  /** What left the balance (kept as `amount` for older statement readers). */
   amount: string
+  net: string
+  tax: string
+  tax_rate: string
+  service_period_start: string | null
+  service_period_end: string | null
+  proration: unknown
 }
 
 async function closePrepaidPeriod(
   em: EntityManager,
   account: BillingAccount,
-  period: BillPeriod,
   billRun: BillingRun,
-  opts: {
-    mode: PrepaidCloseMode
-    statementEnabled: boolean
-    previousClosing: string | null
-    threshold: string
-    nearLimitBuffer: string
-    creditLimit: string
-  },
+  input: ClosePeriodInput,
+  ctx: CycleContext,
 ): Promise<ClosePeriodResult> {
-  const periodEndISO = period.periodEnd.toISOString().slice(0, 10)
+  const { period, charges } = input
+  const periodStartIso = toIsoDate(period.periodStart)
+  const periodEndIso = toIsoDate(period.periodEnd)
 
-  // Recurring + one_time items eligible for this period (usage excluded by the
-  // selector — it was rated in real time).
-  const items = await em.find(BillingItem, {
-    tenantId: account.tenantId,
-    organizationId: account.organizationId,
-    billAccountId: account.id,
-    deletedAt: null,
-  } as never)
-  const { included } = selectItemsForPeriod(items as unknown as SelectableItem[], period)
-  const billableItems = included as unknown as BillingItem[]
-  const lines = buildInvoiceLinesFromItems(billableItems)
-
-  // Window bounds for categorized sums (topups / usage already in the ledger).
-  const windowStart = period.periodStart
-  const windowEnd = addDays(period.periodEnd, 1) // exclusive upper bound
-
-  // Opening chains from the prior statement's closing — NOT a created_at sum.
-  // Recurring debits are stamped at run time (after period_end), so a
-  // `SUM(amount WHERE created_at < period_start)` would drop the prior period's
-  // recurring charge and break the chain. Resolution order:
-  //   1. previous cycle's closing (catch-up, in this run),
-  //   2. the prior persisted statement's closing (month-over-month),
-  //   3. the ledger balance before the first-ever statement window.
-  const openingBalance = await resolveOpeningBalance(em, account, period, opts.previousClosing)
+  // Statement anti-duplicate (real only — test / dry never write statements).
+  // Date-only parameters go as ISO strings (P-D5).
+  const existingStatement =
+    ctx.mode === 'real'
+      ? await em.findOne(BillingStatement, {
+          tenantId: account.tenantId,
+          billAccountId: account.id,
+          periodStart: periodStartIso,
+          periodEnd: periodEndIso,
+        } as never)
+      : null
+
+  // Ledger window of this statement: (previous bill date, this bill date] —
+  // i.e. from the day after the previous bill date up to and including the
+  // bill date D itself. Charges are taken AT D, so money that arrives on D
+  // (a top-up made on the bill date) belongs to the same statement as the
+  // charges — never an opening balance that pretends the account was short.
+  // Consecutive windows stay contiguous: [D_prev + 1, D + 1).
+  const windowStart = addDays(period.periodStart, 1)
+  const windowEnd = addDays(input.billDate, 1) // exclusive upper bound
+  const openingBalance = await resolveOpeningBalance(em, account, windowStart, period, input.previousClosing)
   const totalTopups = await sumByTypeInWindow(em, account, 'topup', windowStart, windowEnd)
-  const totalUsage = absMoney(
-    await sumByTypeInWindow(em, account, 'usage', windowStart, windowEnd),
-  )
-  // Manual adjustments / reversals that landed in the window — SIGNED (a credit
-  // is +, a debit −). Kept as a first-class term so the statement is
-  // self-consistent and the opening→closing chain never drifts.
+  const totalUsage = absMoney(await sumByTypeInWindow(em, account, 'usage', windowStart, windowEnd))
+  // Manual adjustments / reversals in the window — SIGNED. A first-class term
+  // so the statement stays self-consistent and the chain never drifts.
   const totalAdjustments = addMoney(
     await sumByTypeInWindow(em, account, 'adjustment', windowStart, windowEnd),
     await sumByTypeInWindow(em, account, 'reversal', windowStart, windowEnd),
   )
 
   let totalRecurring = '0.0000'
+  let totalNet = '0.0000'
   const breakdown: DebitBreakdownEntry[] = []
   const chargeTransactionIds: string[] = []
-  // The balance just before / after the recurring batch — for crossing events.
-  let recurringBalanceBefore: string | null = null
-  let recurringBalanceAfter: string | null = null
+  let balanceBefore: string | null = null
+  let balanceAfter: string | null = null
 
-  if (opts.mode === 'real') {
-    const now = new Date()
-    for (const line of lines) {
-      const movement = await applyBalanceMovement(em, {
-        organizationId: account.organizationId,
-        tenantId: account.tenantId,
-        billAccountId: account.id,
-        currencyCode: account.currencyCode,
-        type: line.billingType === 'one_time' ? 'one_time' : 'recurring',
-        amount: fromUnits(-toUnits(line.totalNetAmount)),
-        description: line.description,
-        billingItemId: line.billingItemId,
-        sourceRef: `recurring-${line.billingItemId}-${periodEndISO}`,
-        metadata: {
-          bill_period_start: period.periodStart.toISOString().slice(0, 10),
-          bill_period_end: periodEndISO,
-          bill_run_id: billRun.id,
-        },
-      })
-      if (recurringBalanceBefore === null) recurringBalanceBefore = movement.balanceBefore
-      recurringBalanceAfter = movement.balanceAfter
-      totalRecurring = addMoney(totalRecurring, line.totalNetAmount)
-      if (!movement.deduplicated) chargeTransactionIds.push(movement.transaction.id)
-      breakdown.push({
-        billing_item_id: line.billingItemId,
-        billing_type: line.billingType,
-        quantity: line.quantity,
-        amount: line.totalNetAmount,
-      })
-      const item = billableItems.find((it) => it.id === line.billingItemId)
-      if (item) {
-        item.billedToDate = period.periodEnd
-        item.updatedAt = now
-      }
-    }
-    await em.flush()
-  } else {
-    // test / dry: compute the would-be charges, persist nothing.
-    for (const line of lines) {
-      totalRecurring = addMoney(totalRecurring, line.totalNetAmount)
-      breakdown.push({
-        billing_item_id: line.billingItemId,
-        billing_type: line.billingType,
-        quantity: line.quantity,
-        amount: line.totalNetAmount,
-      })
+  for (const charge of charges) {
+    const { descriptor, amounts } = charge
+    const debit = money4(amounts.debit)
+    totalRecurring = addMoney(totalRecurring, debit)
+    totalNet = addMoney(totalNet, money4(amounts.net))
+    const metadata = {
+      bill_date: toIsoDate(input.billDate),
+      bill_period_start: periodStartIso,
+      bill_period_end: periodEndIso,
+      bill_run_id: billRun.id,
+      service_period_start: descriptor.servicePeriodStart ? toIsoDate(descriptor.servicePeriodStart) : null,
+      service_period_end: descriptor.servicePeriodEnd ? toIsoDate(descriptor.servicePeriodEnd) : null,
+      net: money4(amounts.net),
+      tax: money4(amounts.tax),
+      tax_rate: String(amounts.taxRate),
+      tax_point: ctx.taxPoint,
+      ...(descriptor.metadataExtra ?? {}),
     }
+    breakdown.push({
+      billing_item_id: descriptor.billingItemId,
+      billing_type: descriptor.billingType,
+      description: descriptor.description,
+      quantity: descriptor.quantity,
+      amount: debit,
+      net: metadata.net,
+      tax: metadata.tax,
+      tax_rate: metadata.tax_rate,
+      service_period_start: metadata.service_period_start,
+      service_period_end: metadata.service_period_end,
+      proration: (descriptor.metadataExtra as { proration?: unknown } | undefined)?.proration ?? null,
+    })
+    if (ctx.mode !== 'real') continue
+    const movement = await applyBalanceMovement(em, {
+      organizationId: account.organizationId,
+      tenantId: account.tenantId,
+      billAccountId: account.id,
+      currencyCode: account.currencyCode,
+      // Credits back (an item ended inside a charged period) stay typed as the
+      // charge they reverse: adjustments are summed by date window on
+      // statements and would be counted twice.
+      type: descriptor.billingType === 'one_time' ? 'one_time' : 'recurring',
+      amount: fromUnits(-toUnits(debit)),
+      description: descriptor.description,
+      billingItemId: descriptor.billingItemId,
+      sourceRef: charge.sourceRef,
+      metadata,
+    })
+    if (balanceBefore === null) balanceBefore = movement.balanceBefore
+    balanceAfter = movement.balanceAfter
+    if (!movement.deduplicated) chargeTransactionIds.push(movement.transaction.id)
   }
+  if (ctx.mode === 'real' && charges.length > 0) await em.flush()
 
-  // closing = opening + topups + adjustments − usage − recurring.
+  // closing = opening + top-ups + adjustments − usage − charges.
   const closingBalance = subMoney(
     subMoney(addMoney(addMoney(openingBalance, totalTopups), totalAdjustments), totalUsage),
     totalRecurring,
   )
+  const vatSummary: VatSummaryRow[] = buildVatSummary(
+    charges.map((c) => c.amounts),
+    ctx.taxPoint,
+  )
 
-  // The recurring batch can push the balance low / exhausted / over-limit —
-  // emit those crossings (real mode only; dry/test never move the balance).
-  const crossingEvents =
-    recurringBalanceBefore !== null && recurringBalanceAfter !== null
+  const events: DomainEvent[] =
+    balanceBefore !== null && balanceAfter !== null
       ? buildBalanceCrossingEvents({
           scope: {
             billAccountId: account.id,
@@ -333,16 +470,16 @@ async function closePrepaidPeriod(
             organizationId: account.organizationId,
             currencyCode: account.currencyCode,
           },
-          balanceBefore: recurringBalanceBefore,
-          balanceAfter: recurringBalanceAfter,
-          threshold: opts.threshold,
-          creditLimit: opts.creditLimit,
-          nearLimitBuffer: opts.nearLimitBuffer,
+          balanceBefore,
+          balanceAfter,
+          threshold: ctx.threshold,
+          creditLimit: ctx.creditLimit,
+          nearLimitBuffer: ctx.nearLimitBuffer,
         })
       : []
 
-  let statementId: string | null = null
-  if (opts.mode === 'real' && opts.statementEnabled) {
+  let createdStatementId: string | null = null
+  if (ctx.mode === 'real' && ctx.statementEnabled && !existingStatement) {
     const now = new Date()
     const statement = em.create(BillingStatement, {
       organizationId: account.organizationId,
@@ -358,45 +495,80 @@ async function closePrepaidPeriod(
       totalRecurring,
       totalAdjustments,
       closingBalance,
-      debitBreakdown: { items: breakdown },
+      debitBreakdown: { items: breakdown, bill_date: toIsoDate(input.billDate), tax_point: ctx.taxPoint },
+      vatSummary,
       status: 'generated',
       createdAt: now,
       updatedAt: now,
     })
     em.persist(statement)
     await em.flush()
-    statementId = statement.id
-
-    // Backfill statement_id on the charge transactions for attribution.
+    createdStatementId = statement.id
     if (chargeTransactionIds.length > 0) {
       await em.nativeUpdate(
         BillingAccountTransaction,
         { id: { $in: chargeTransactionIds } } as never,
-        { statementId } as never,
+        { statementId: createdStatementId } as never,
       )
     }
+    events.push({
+      id: 'billing.statement.generated',
+      payload: {
+        statementId: createdStatementId,
+        billAccountId: account.id,
+        tenantId: account.tenantId,
+        organizationId: account.organizationId,
+        billRunId: billRun.id,
+        periodStart: periodStartIso,
+        periodEnd: periodEndIso,
+        currencyCode: account.currencyCode,
+        openingBalance,
+        closingBalance,
+        totalTopups,
+        totalUsage,
+        totalRecurring,
+        totalAdjustments,
+      },
+    })
   }
 
+  let status: PrepaidCycleStatus
+  if (ctx.mode !== 'real') status = charges.length > 0 ? 'previewed' : 'empty'
+  else if (existingStatement && chargeTransactionIds.length === 0) status = 'skipped_existing'
+  else status = chargeTransactionIds.length > 0 ? 'charged' : 'empty'
+
   return {
-    statementId,
-    openingBalance,
-    totalTopups,
-    totalUsage,
-    totalRecurring,
-    totalAdjustments,
+    record: {
+      bill_date: toIsoDate(input.billDate),
+      period_start: periodStartIso,
+      period_end: periodEndIso,
+      status,
+      line_count: charges.length,
+      total_net: totalNet,
+      total_debit: totalRecurring,
+      invoice_id: null,
+      statement_id: createdStatementId ?? existingStatement?.id ?? null,
+    },
+    statementId: createdStatementId,
     closingBalance,
-    crossingEvents,
+    events,
   }
 }
 
 /**
  * Resolve a period's opening balance by chaining from the prior statement's
  * closing (the spec's "chains cleanly"), with a ledger fallback for the very
- * first statement. See the call site for why a created_at sum alone is wrong.
+ * first statement. Charges are stamped at run time (after the window), so a
+ * `SUM(amount WHERE created_at < period_start)` would drop the prior
+ * period's charges and break the chain. Resolution order:
+ *   1. previous cycle's closing (catch-up, in this run),
+ *   2. the prior persisted statement's closing (month-over-month),
+ *   3. the ledger balance before the first-ever statement window.
  */
 async function resolveOpeningBalance(
   em: EntityManager,
   account: BillingAccount,
+  windowStart: Date,
   period: BillPeriod,
   previousClosing: string | null,
 ): Promise<string> {
@@ -407,22 +579,18 @@ async function resolveOpeningBalance(
       tenantId: account.tenantId,
       organizationId: account.organizationId,
       billAccountId: account.id,
-      periodEnd: { $lt: period.periodStart },
+      periodEnd: { $lt: toIsoDate(period.periodStart) },
     } as never,
     { orderBy: { periodEnd: 'DESC' } },
   )
   if (prior) return fromUnits(toUnits(prior.closingBalance))
-  // First-ever statement: the ledger balance just before the period window
-  // (only top-ups/usage exist before the first close, so created_at is safe).
-  return sumAmountsBefore(em, account, period.periodStart)
+  // First-ever statement: the ledger balance just before its window (only
+  // top-ups / usage exist before the first close, so created_at is safe).
+  return sumAmountsBefore(em, account, windowStart)
 }
 
 /** Balance at `before` = SUM(amount) of transactions created strictly before it. */
-async function sumAmountsBefore(
-  em: EntityManager,
-  account: BillingAccount,
-  before: Date,
-): Promise<string> {
+async function sumAmountsBefore(em: EntityManager, account: BillingAccount, before: Date): Promise<string> {
   const rows = (await em.execute(
     `SELECT COALESCE(SUM(amount), 0) AS total
        FROM billing_account_transactions