@dainamite/billing 0.19.0 → 0.21.0

package/dist/modules/billing/lib/billRunEngine.js

@@ -1,24 +1,35 @@
+import { UniqueConstraintViolationException } from "@mikro-orm/core";
 import {
   BillingAccount,
   BillingAccountUsage,
+  BillingInvoice,
   BillingItem,
-  BillRun,
-  BillRunOutcome
+  BillingRun,
+  BillingRunOutcome
 } from "../data/entities.js";
-import { advanceNextBillDate, deriveBillPeriod, isCycleDue } from "./billPeriod.js";
 import {
-  selectItemsForPeriod
-} from "./itemSelector.js";
+  addDays,
+  advanceNextBillDate,
+  cloneAtMidnight,
+  deriveBillPeriod,
+  isCycleDue,
+  shiftCycles
+} from "./billPeriod.js";
+import { shouldIncludeItem } from "./itemSelector.js";
 import {
   buildInvoiceLinesFromItems,
+  buildRecurringLineDescriptors,
+  displayPeriod,
   writeDraftInvoice
 } from "./invoiceWriter.js";
+import { computeRecurringLines } from "./servicePeriods.js";
 import { withTenantLock } from "./tenantLock.js";
 import { processUsageForAccount } from "./usageRunner.js";
 import { processPrepaidAccount } from "./prepaidPeriodClose.js";
 import { emitBillingEvent } from "../events.js";
-const SCHEDULED_CYCLE_LIMIT = 1;
 const CATCH_UP_HARD_CAP = 60;
+const SKIPPED_ITEMS_WARNING_CAP = 200;
+const QUIET_SKIP_REASONS = /* @__PURE__ */ new Set(["item-inactive", "item-soft-deleted"]);
 async function runBillRun(em, container, params) {
   const output = await withTenantLock(
     em,
@@ -32,14 +43,13 @@ async function runBillRun(em, container, params) {
 }
 async function executeRunWithinLock(em, container, params) {
   const now = /* @__PURE__ */ new Date();
-  const billRun = em.create(BillRun, {
+  const billRun = em.create(BillingRun, {
     organizationId: params.organizationId,
     tenantId: params.tenantId,
     triggeredBy: params.triggeredBy,
     parentRunId: params.parentRunId ?? null,
     dryRun: params.mode === "dry",
     testMode: params.mode === "test",
-    catchUp: Boolean(params.catchUp),
     scopedAccountIds: params.scopedAccountIds ?? null,
     asOfDate: params.asOfDate,
     startedAt: now,
@@ -60,7 +70,7 @@ async function executeRunWithinLock(em, container, params) {
     if (processResult.status !== "failed") {
       totalUsageRecordsRated += processResult.usageRecordsRated;
     }
-    const outcome = em.create(BillRunOutcome, {
+    const outcome = em.create(BillingRunOutcome, {
       organizationId: params.organizationId,
       tenantId: params.tenantId,
       billRunId: billRun.id,
@@ -70,6 +80,7 @@ async function executeRunWithinLock(em, container, params) {
       warnings: processResult.status === "failed" ? null : processResult.warnings,
       draftInvoiceId: processResult.status === "failed" ? null : processResult.draftInvoiceId,
       statementId: processResult.status === "failed" ? null : processResult.statementId ?? null,
+      cycles: processResult.status === "failed" ? null : processResult.cycles ?? null,
       isActive: true,
       createdAt: /* @__PURE__ */ new Date(),
       updatedAt: /* @__PURE__ */ new Date()
@@ -117,8 +128,7 @@ async function processAccount(em, container, billRun, account, params) {
     const result = await processPrepaidAccount(em, account, billRun, {
       asOfDate: params.asOfDate,
       mode: params.mode,
-      triggeredBy: params.triggeredBy,
-      catchUp: params.catchUp
+      triggeredBy: params.triggeredBy
     });
     if (result.status === "failed") {
       return { status: "failed", errorMessage: result.errorMessage };
@@ -130,76 +140,190 @@ async function processAccount(em, container, billRun, account, params) {
       statementId: result.statementId,
       statementEvents: result.statementEvents,
       cyclesEmitted: result.cyclesEmitted,
+      cycles: result.cycles,
       usageRecordsRated: 0
     };
   }
-  const maxCycles = params.triggeredBy === "schedule" || !params.catchUp ? SCHEDULED_CYCLE_LIMIT : CATCH_UP_HARD_CAP;
-  let cyclesEmitted = 0;
+  return processPostpaidAccount(em, container, billRun, account, params);
+}
+function isoDate(date) {
+  return cloneAtMidnight(date).toISOString().slice(0, 10);
+}
+function toSkipWarning(skip) {
+  return {
+    item_id: skip.billingItemId,
+    reason: skip.reason,
+    service_period_start: skip.servicePeriodStart ? isoDate(skip.servicePeriodStart) : null,
+    service_period_end: skip.servicePeriodEnd ? isoDate(skip.servicePeriodEnd) : null
+  };
+}
+async function processPostpaidAccount(em, container, billRun, account, params) {
+  const cycle = account.billCycle;
+  const testRun = params.mode === "test";
+  const items = await em.find(BillingItem, {
+    tenantId: account.tenantId,
+    organizationId: account.organizationId,
+    billAccountId: account.id,
+    deletedAt: null
+  });
+  const recurringItems = items.filter((it) => it.type === "recurring");
+  const oneTimeItems = items.filter((it) => it.type === "one_time");
+  const usageItems = items.filter((it) => it.type === "usage");
+  const watermarks = new Map(
+    recurringItems.map((it) => [it.id, it.billedToDate ? cloneAtMidnight(it.billedToDate) : null])
+  );
+  const billedOneTimes = new Set(oneTimeItems.filter((it) => it.billedToDate).map((it) => it.id));
+  let billDate = cloneAtMidnight(account.nextBillDate);
+  let usageCountedThrough = null;
+  const cycles = [];
+  const warnings = {};
+  const skippedItems = [];
   let lastDraftInvoiceId = null;
-  let totalUsageRatedThisAccount = 0;
-  const aggregatedWarnings = {};
-  while (cyclesEmitted < maxCycles && isCycleDue(account.nextBillDate, params.asOfDate)) {
-    const period = deriveBillPeriod(account.nextBillDate, account.billCycle);
-    if (params.mode !== "dry") {
-      const existing = await findExistingDraftForPeriod(em, account, period);
-      if (existing) {
-        return {
-          status: "skipped_existing_draft",
-          warnings: null,
-          draftInvoiceId: existing,
-          cyclesEmitted,
-          usageRecordsRated: totalUsageRatedThisAccount
-        };
-      }
+  let usageRecordsRated = 0;
+  const pushSkips = (skips) => {
+    for (const skip of skips) {
+      if (QUIET_SKIP_REASONS.has(skip.reason)) continue;
+      if (skippedItems.length < SKIPPED_ITEMS_WARNING_CAP) skippedItems.push(toSkipWarning(skip));
     }
-    const items = await em.find(BillingItem, {
-      tenantId: account.tenantId,
-      organizationId: account.organizationId,
-      billAccountId: account.id,
-      deletedAt: null
-    });
-    const usageItems = items.filter((it) => it.type === "usage");
-    const { included } = selectItemsForPeriod(items, period);
-    const billableItems = included;
-    const currencyMismatchIds = billableItems.filter((it) => it.currencyMismatch).map((it) => it.id);
-    if (currencyMismatchIds.length > 0) {
-      aggregatedWarnings.currency_mismatch_items = [
-        ...aggregatedWarnings.currency_mismatch_items ?? [],
-        ...currencyMismatchIds
-      ];
-    }
-    const itemLines = buildInvoiceLinesFromItems(billableItems);
-    const usageResult = await processUsageForAccount(em, account, period, usageItems);
-    if (usageResult.unmatchedUoms.length > 0) {
-      aggregatedWarnings.unmatched_usage_uoms = [
-        ...aggregatedWarnings.unmatched_usage_uoms ?? [],
-        ...usageResult.unmatchedUoms
-      ];
+  };
+  const addWarning = (key, values) => {
+    if (values.length === 0) return;
+    warnings[key] = Array.from(/* @__PURE__ */ new Set([...warnings[key] ?? [], ...values]));
+  };
+  while (isCycleDue(billDate, params.asOfDate)) {
+    if (cycles.length >= CATCH_UP_HARD_CAP) {
+      warnings.catch_up_cap_reached = true;
+      break;
     }
-    const allLines = [...itemLines, ...usageResult.lines];
-    if (allLines.length === 0) {
-      if (params.mode !== "real") break;
-      account.nextBillDate = advanceNextBillDate(
-        account.nextBillDate,
-        account.billCycle
+    const nextBillDate = advanceNextBillDate(billDate, cycle);
+    const arrearsPeriod = deriveBillPeriod(billDate, cycle);
+    const lines = [];
+    const watermarkUpdates = /* @__PURE__ */ new Map();
+    const chargedItems = [];
+    for (const item of recurringItems) {
+      const unitPrice = item.rateJson?.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 }
       );
-      account.lastBillDate = period.periodEnd;
-      account.updatedAt = /* @__PURE__ */ new Date();
-      cyclesEmitted += 1;
-      continue;
+      pushSkips(computed.skipped);
+      if (computed.newBilledToDate?.getTime() !== watermarks.get(item.id)?.getTime()) {
+        watermarkUpdates.set(item.id, computed.newBilledToDate);
+      }
+      if (computed.lines.length > 0) {
+        lines.push(...buildRecurringLineDescriptors(item, computed.lines));
+        chargedItems.push(item);
+      }
     }
-    const written = await writeDraftInvoice(em, container, {
-      mode: params.mode,
-      account,
-      period,
-      billRunId: billRun.id,
-      lines: allLines
+    const oneTimeWindow = {
+      periodStart: shiftCycles(billDate, cycle, -1),
+      periodEnd: addDays(nextBillDate, -1)
+    };
+    const oneTimesThisCycle = oneTimeItems.filter(
+      (it) => !billedOneTimes.has(it.id) && shouldIncludeItem(it, oneTimeWindow).include
+    );
+    lines.push(...buildInvoiceLinesFromItems(oneTimesThisCycle));
+    chargedItems.push(...oneTimesThisCycle);
+    const usageResult = await processUsageForAccount(em, account, arrearsPeriod, usageItems, {
+      after: usageCountedThrough
     });
-    lastDraftInvoiceId = written.invoiceId;
+    addWarning("unmatched_usage_uoms", usageResult.unmatchedUoms);
+    lines.push(
+      ...usageResult.lines.map((line) => ({
+        ...line,
+        servicePeriodStart: arrearsPeriod.periodStart,
+        servicePeriodEnd: arrearsPeriod.periodEnd
+      }))
+    );
+    addWarning(
+      "currency_mismatch_items",
+      chargedItems.filter((it) => it.currencyMismatch).map((it) => it.id)
+    );
+    const period = displayPeriod(lines, arrearsPeriod);
+    const record = {
+      bill_date: isoDate(billDate),
+      period_start: lines.length ? isoDate(period.periodStart) : null,
+      period_end: lines.length ? isoDate(period.periodEnd) : null,
+      status: "empty",
+      line_count: lines.length,
+      total_net: "0.0000",
+      invoice_id: null
+    };
+    const existing = params.mode === "dry" ? null : await findExistingDraftForBillDate(em, account, billDate, testRun);
+    if (existing && params.mode === "real") {
+      cycles.push({ ...record, status: "skipped_existing", invoice_id: existing });
+      return {
+        status: "skipped_existing_draft",
+        warnings: finalizeWarnings(warnings, skippedItems),
+        draftInvoiceId: existing,
+        cyclesEmitted: cycles.filter((c) => c.status === "invoiced").length,
+        usageRecordsRated,
+        cycles
+      };
+    }
+    if (existing) {
+      cycles.push({ ...record, status: "skipped_existing", invoice_id: existing });
+    } else if (lines.length > 0) {
+      const written = await writeDraftOnce(em, {
+        mode: params.mode,
+        account,
+        billDate,
+        period,
+        billRunId: billRun.id,
+        lines
+      });
+      if (written === "conflict") {
+        cycles.push({ ...record, status: "skipped_existing" });
+        if (params.mode === "real") {
+          return {
+            status: "skipped_existing_draft",
+            warnings: finalizeWarnings(warnings, skippedItems),
+            draftInvoiceId: lastDraftInvoiceId,
+            cyclesEmitted: cycles.filter((c) => c.status === "invoiced").length,
+            usageRecordsRated,
+            cycles
+          };
+        }
+        billDate = nextBillDate;
+        for (const [itemId, date] of watermarkUpdates) watermarks.set(itemId, date);
+        for (const it of oneTimesThisCycle) billedOneTimes.add(it.id);
+        usageCountedThrough = arrearsPeriod.periodEnd;
+        continue;
+      }
+      if (written.invoiceId) lastDraftInvoiceId = written.invoiceId;
+      if (Number.parseFloat(written.totalNet) < 0) addWarning("negative_total_bill_dates", [record.bill_date]);
+      cycles.push({
+        ...record,
+        status: params.mode === "dry" ? "previewed" : "invoiced",
+        total_net: written.totalNet,
+        invoice_id: written.invoiceId
+      });
+    } else {
+      cycles.push(record);
+    }
+    for (const [itemId, date] of watermarkUpdates) watermarks.set(itemId, date);
+    for (const it of oneTimesThisCycle) billedOneTimes.add(it.id);
+    usageCountedThrough = arrearsPeriod.periodEnd;
     if (params.mode === "real") {
       const now = /* @__PURE__ */ new Date();
-      for (const item of billableItems) {
-        item.billedToDate = period.periodEnd;
+      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 = oneTimeWindow.periodEnd;
         item.updatedAt = now;
       }
       if (usageResult.matchedUoms.length > 0) {
@@ -211,53 +335,62 @@ async function processAccount(em, container, billRun, account, params) {
             billAccountId: account.id,
             uomCode: { $in: usageResult.matchedUoms },
             ratedInBillRunId: null,
-            periodEnd: { $lte: period.periodEnd },
+            periodEnd: { $lte: arrearsPeriod.periodEnd },
             deletedAt: null
           },
           { ratedInBillRunId: billRun.id, updatedAt: now }
         );
+        usageRecordsRated += usageResult.ratedCount;
       }
-      totalUsageRatedThisAccount += usageResult.ratedCount;
-      account.nextBillDate = advanceNextBillDate(
-        account.nextBillDate,
-        account.billCycle
-      );
-      account.lastBillDate = period.periodEnd;
+      account.nextBillDate = nextBillDate;
+      account.lastBillDate = arrearsPeriod.periodEnd;
       account.updatedAt = now;
       await em.flush();
-    } else {
-      break;
     }
-    cyclesEmitted += 1;
+    billDate = nextBillDate;
   }
-  const hasCurrencyWarnings = (aggregatedWarnings.currency_mismatch_items ?? []).length > 0;
-  const hasUnmatchedUsage = (aggregatedWarnings.unmatched_usage_uoms ?? []).length > 0;
-  const hasWarnings = hasCurrencyWarnings || hasUnmatchedUsage;
+  const finalWarnings = finalizeWarnings(warnings, skippedItems);
   return {
-    status: hasWarnings ? "success_with_warnings" : "success",
-    warnings: hasWarnings ? aggregatedWarnings : null,
+    status: hasRealWarnings(warnings) ? "success_with_warnings" : "success",
+    warnings: finalWarnings,
     draftInvoiceId: lastDraftInvoiceId,
-    cyclesEmitted,
-    usageRecordsRated: totalUsageRatedThisAccount
+    cyclesEmitted: cycles.filter((c) => c.status === "invoiced").length,
+    usageRecordsRated,
+    cycles
   };
 }
-async function findExistingDraftForPeriod(em, account, period) {
-  const periodStartISO = period.periodStart.toISOString().slice(0, 10);
-  const periodEndISO = period.periodEnd.toISOString().slice(0, 10);
-  const rows = await em.execute(
-    `SELECT id FROM sales_invoices
-     WHERE tenant_id = ?
-       AND organization_id = ?
-       AND deleted_at IS NULL
-       AND status = 'draft'
-       AND metadata->>'bill_account_id' = ?
-       AND metadata->>'bill_period_start' = ?
-       AND metadata->>'bill_period_end' = ?
-     LIMIT 1`,
-    [account.tenantId, account.organizationId, account.id, periodStartISO, periodEndISO]
+function finalizeWarnings(warnings, skippedItems) {
+  const merged = { ...warnings, ...skippedItems.length ? { skipped_items: skippedItems } : {} };
+  return Object.keys(merged).length > 0 ? merged : null;
+}
+function hasRealWarnings(warnings) {
+  return Boolean(
+    warnings.currency_mismatch_items?.length || warnings.unmatched_usage_uoms?.length || warnings.negative_total_bill_dates?.length || warnings.catch_up_cap_reached
+  );
+}
+async function findExistingDraftForBillDate(em, account, billDate, testRun) {
+  const existing = await em.findOne(
+    BillingInvoice,
+    {
+      tenantId: account.tenantId,
+      organizationId: account.organizationId,
+      billAccountId: account.id,
+      billDate,
+      testRun,
+      documentType: "invoice",
+      deletedAt: null
+    }
   );
-  if (!rows || rows.length === 0) return null;
-  return rows[0].id ?? null;
+  return existing?.id ?? null;
+}
+async function writeDraftOnce(em, params) {
+  if (params.mode === "dry") return writeDraftInvoice(em, params);
+  try {
+    return await em.transactional((tem) => writeDraftInvoice(tem, params));
+  } catch (err) {
+    if (err instanceof UniqueConstraintViolationException) return "conflict";
+    throw err;
+  }
 }
 function computeFinalRunStatus(outcomes) {
   if (outcomes.length === 0) return "completed";
@@ -270,11 +403,12 @@ function computeFinalRunStatus(outcomes) {
   return "completed";
 }
 function buildRunSummary(outcomes, totalAccounts, usageRecordsRated) {
+  const allCycles = outcomes.flatMap((o) => Array.isArray(o.cycles) ? o.cycles : []);
   return {
     accounts_processed: totalAccounts,
-    drafts_created: outcomes.filter(
-      (o) => o.draftInvoiceId !== null && o.status !== "skipped_existing_draft"
-    ).length,
+    // Spec A: one draft per invoiced cycle (catch-up writes several per account).
+    drafts_created: allCycles.filter((c) => c.status === "invoiced" && c.invoice_id).length,
+    cycles_processed: allCycles.length,
     drafts_skipped_existing: outcomes.filter((o) => o.status === "skipped_existing_draft").length,
     // SPEC-002 prepaid period close.
     statements_created: outcomes.filter(
@@ -289,6 +423,7 @@ function buildRunSummary(outcomes, totalAccounts, usageRecordsRated) {
   };
 }
 export {
+  CATCH_UP_HARD_CAP,
   runBillRun
 };
 //# sourceMappingURL=billRunEngine.js.map

package/dist/modules/billing/lib/billRunEngine.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/lib/billRunEngine.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport {\n  BillingAccount,\n  BillingAccountUsage,\n  BillingItem,\n  BillRun,\n  BillRunOutcome,\n} from '../data/entities'\nimport { advanceNextBillDate, deriveBillPeriod, isCycleDue } from './billPeriod'\nimport {\n  selectItemsForPeriod,\n  type SelectableItem,\n} from './itemSelector'\nimport {\n  buildInvoiceLinesFromItems,\n  writeDraftInvoice,\n  type InvoiceLineDescriptor,\n  type WriteMode,\n} from './invoiceWriter'\nimport { withTenantLock } from './tenantLock'\nimport { processUsageForAccount } from './usageRunner'\nimport { processPrepaidAccount } from './prepaidPeriodClose'\nimport type { DomainEvent } from './balanceEvents'\nimport { emitBillingEvent, type BillingEventId } from '../events'\nimport type { BillCycle } from '../data/validators'\n\n/**\n * Bill Run engine \u2014 orchestrates one execution of the billing cycle for\n * a single tenant.\n *\n * Concurrency / locking:\n *   - The whole run is wrapped in `withTenantLock(...)`, which holds a\n *     transaction-scoped Postgres advisory lock keyed by\n *     `hash(tenant_id || ':billing-run')`. A second trigger fired while a\n *     run is in flight short-circuits with `TenantLockBusyError` (the\n *     command layer maps that to HTTP 409).\n *   - Within the outer transaction, every account is processed inside a\n *     nested `em.transactional(...)` (PG SAVEPOINT). A per-account failure\n *     rolls back only that account's work, leaving siblings unaffected.\n *\n * Run modes:\n *   - `real` (default) \u2014 persist drafts, advance `next_bill_date`, mark\n *     items `billed_to_date`. Production path.\n *   - `test` \u2014 persist drafts flagged with `metadata.test_run=true`, but\n *     do NOT advance state. Repeatable.\n *   - `dry`  \u2014 compute everything; persist nothing. Preview only.\n *\n * Catch-up:\n *   - Manual triggers may set `catchUp=true`. The engine then loops cycles\n *     per account until `next_bill_date > as_of_date`, emitting one draft\n *     per missed cycle (never combined).\n *   - Scheduled triggers always process exactly ONE cycle per account per\n *     run, regardless of how far behind the account is.\n *\n * Anti-duplicate guards (both run in every mode except `dry`):\n *   1. Open-draft check on `core/sales` invoice (per period boundary).\n *   2. `billed_to_date` per BillingItem.\n */\n\nexport type RunMode = WriteMode\n\nexport type RunBillRunParams = {\n  tenantId: string\n  organizationId: string\n  asOfDate: Date\n  triggeredBy: 'schedule' | 'manual'\n  mode: RunMode\n  scopedAccountIds?: string[]\n  parentRunId?: string | null\n  catchUp?: boolean\n}\n\nexport type RunBillRunResult = {\n  billRun: BillRun\n  outcomes: BillRunOutcome[]\n}\n\ntype RunOutput = RunBillRunResult & {\n  /** Prepaid statement / crossing events to emit AFTER the outer tx commits. */\n  pendingEvents: DomainEvent[]\n}\n\ntype AccountWarnings = {\n  currency_mismatch_items?: string[]\n  unmatched_usage_uoms?: string[]\n}\n\ntype AccountProcessSuccess = {\n  status:\n    | 'success'\n    | 'success_with_warnings'\n    | 'skipped_existing_draft'\n    | 'skipped_existing_statement'\n  warnings: AccountWarnings | Record<string, unknown> | null\n  draftInvoiceId: string | null\n  // SPEC-002: prepaid accounts produce a statement instead of a draft invoice.\n  statementId?: string | null\n  statementEvents?: DomainEvent[]\n  cyclesEmitted: number\n  usageRecordsRated: number\n}\n\ntype AccountProcessFailed = {\n  status: 'failed'\n  errorMessage: string\n}\n\ntype AccountProcessResult = AccountProcessSuccess | AccountProcessFailed\n\nconst SCHEDULED_CYCLE_LIMIT = 1\nconst CATCH_UP_HARD_CAP = 60 // safety net so a misconfigured account can't loop forever\n\nexport async function runBillRun(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: RunBillRunParams,\n): Promise<RunBillRunResult> {\n  const output = await withTenantLock(\n    em,\n    { tenantId: params.tenantId, lockName: 'billing-run' },\n    async (tem) => executeRunWithinLock(tem, container, params),\n  )\n  // Emit prepaid statement / crossing events ONLY after the outer transaction\n  // (held by withTenantLock) has committed \u2014 emitting inside the lock would let\n  // a consumer observe an uncommitted statement or a phantom event on rollback.\n  for (const ev of output.pendingEvents) {\n    await emitBillingEvent(ev.id as BillingEventId, ev.payload, { persistent: true })\n  }\n  return { billRun: output.billRun, outcomes: output.outcomes }\n}\n\nasync function executeRunWithinLock(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: RunBillRunParams,\n): Promise<RunOutput> {\n  const now = new Date()\n  const billRun = em.create(BillRun, {\n    organizationId: params.organizationId,\n    tenantId: params.tenantId,\n    triggeredBy: params.triggeredBy,\n    parentRunId: params.parentRunId ?? null,\n    dryRun: params.mode === 'dry',\n    testMode: params.mode === 'test',\n    catchUp: Boolean(params.catchUp),\n    scopedAccountIds: params.scopedAccountIds ?? null,\n    asOfDate: params.asOfDate,\n    startedAt: now,\n    status: 'running',\n    summary: null,\n    isActive: true,\n    createdAt: now,\n    updatedAt: now,\n  })\n  em.persist(billRun)\n  await em.flush()\n\n  const accounts = await selectTargetAccounts(em, params)\n  const outcomes: BillRunOutcome[] = []\n  const pendingEvents: DomainEvent[] = []\n  let totalUsageRecordsRated = 0\n\n  for (const account of accounts) {\n    const processResult = await processAccountSafely(em, container, billRun, account, params)\n    if (processResult.status !== 'failed') {\n      totalUsageRecordsRated += processResult.usageRecordsRated\n    }\n    const outcome = em.create(BillRunOutcome, {\n      organizationId: params.organizationId,\n      tenantId: params.tenantId,\n      billRunId: billRun.id,\n      billAccountId: account.id,\n      status: processResult.status,\n      errorMessage: processResult.status === 'failed' ? processResult.errorMessage : null,\n      warnings:\n        processResult.status === 'failed'\n          ? null\n          : (processResult.warnings as Record<string, unknown> | null),\n      draftInvoiceId: processResult.status === 'failed' ? null : processResult.draftInvoiceId,\n      statementId: processResult.status === 'failed' ? null : (processResult.statementId ?? null),\n      isActive: true,\n      createdAt: new Date(),\n      updatedAt: new Date(),\n    })\n    em.persist(outcome)\n    await em.flush()\n    outcomes.push(outcome)\n\n    // Collect statement / crossing events \u2014 runBillRun emits them AFTER the\n    // outer tx commits (see runBillRun), never from inside the lock.\n    if (processResult.status !== 'failed' && processResult.statementEvents) {\n      pendingEvents.push(...processResult.statementEvents)\n    }\n  }\n\n  billRun.status = computeFinalRunStatus(outcomes)\n  billRun.finishedAt = new Date()\n  billRun.updatedAt = billRun.finishedAt\n  billRun.summary = buildRunSummary(outcomes, accounts.length, totalUsageRecordsRated)\n  await em.flush()\n\n  return { billRun, outcomes, pendingEvents }\n}\n\nasync function selectTargetAccounts(\n  em: EntityManager,\n  params: RunBillRunParams,\n): Promise<BillingAccount[]> {\n  const where: Record<string, unknown> = {\n    tenantId: params.tenantId,\n    organizationId: params.organizationId,\n    deletedAt: null,\n    nextBillDate: { $lte: params.asOfDate },\n  }\n  if (params.scopedAccountIds && params.scopedAccountIds.length > 0) {\n    where.id = { $in: params.scopedAccountIds }\n  }\n  return em.find(BillingAccount, where as never)\n}\n\nasync function processAccountSafely(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  try {\n    return await em.transactional(async (subEm) => {\n      return processAccount(subEm, container, billRun, account, params)\n    })\n  } catch (err) {\n    return {\n      status: 'failed',\n      errorMessage: err instanceof Error ? err.message : String(err),\n    }\n  }\n}\n\nasync function processAccount(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  // SPEC-002: a prepaid account never gets a payable draft invoice. It still\n  // runs in the Bill Run, but charges recurring / one_time items to the\n  // balance and produces a non-fiscal consumption statement.\n  if (account.billingMode === 'prepaid') {\n    const result = await processPrepaidAccount(em, account, billRun, {\n      asOfDate: params.asOfDate,\n      mode: params.mode,\n      triggeredBy: params.triggeredBy,\n      catchUp: params.catchUp,\n    })\n    if (result.status === 'failed') {\n      return { status: 'failed', errorMessage: result.errorMessage }\n    }\n    return {\n      status: result.status,\n      warnings: result.warnings,\n      draftInvoiceId: null,\n      statementId: result.statementId,\n      statementEvents: result.statementEvents,\n      cyclesEmitted: result.cyclesEmitted,\n      usageRecordsRated: 0,\n    }\n  }\n\n  const maxCycles =\n    params.triggeredBy === 'schedule' || !params.catchUp\n      ? SCHEDULED_CYCLE_LIMIT\n      : CATCH_UP_HARD_CAP\n\n  let cyclesEmitted = 0\n  let lastDraftInvoiceId: string | null = null\n  let totalUsageRatedThisAccount = 0\n  const aggregatedWarnings: AccountWarnings = {}\n\n  while (cyclesEmitted < maxCycles && isCycleDue(account.nextBillDate, params.asOfDate)) {\n    const period = deriveBillPeriod(account.nextBillDate, account.billCycle as BillCycle)\n\n    // Open-draft anti-duplicate \u2014 only applies when we'd actually persist.\n    if (params.mode !== 'dry') {\n      const existing = await findExistingDraftForPeriod(em, account, period)\n      if (existing) {\n        return {\n          status: 'skipped_existing_draft',\n          warnings: null,\n          draftInvoiceId: existing,\n          cyclesEmitted,\n          usageRecordsRated: totalUsageRatedThisAccount,\n        }\n      }\n    }\n\n    const items = await em.find(BillingItem, {\n      tenantId: account.tenantId,\n      organizationId: account.organizationId,\n      billAccountId: account.id,\n      deletedAt: null,\n    } as never)\n\n    const usageItems = (items as BillingItem[]).filter((it) => it.type === 'usage')\n\n    // Non-usage path: one_time + recurring filtered by the selector.\n    const { included } = selectItemsForPeriod(items as SelectableItem[], period)\n    const billableItems = included as unknown as BillingItem[]\n\n    const currencyMismatchIds = billableItems\n      .filter((it) => it.currencyMismatch)\n      .map((it) => it.id)\n    if (currencyMismatchIds.length > 0) {\n      aggregatedWarnings.currency_mismatch_items = [\n        ...(aggregatedWarnings.currency_mismatch_items ?? []),\n        ...currencyMismatchIds,\n      ]\n    }\n    const itemLines = buildInvoiceLinesFromItems(billableItems)\n\n    // Usage path: aggregate matching usage records per uom_code, rate,\n    // emit one line per matched usage item, warn about unmatched UoMs.\n    const usageResult = await processUsageForAccount(em, account, period, usageItems)\n    if (usageResult.unmatchedUoms.length > 0) {\n      aggregatedWarnings.unmatched_usage_uoms = [\n        ...(aggregatedWarnings.unmatched_usage_uoms ?? []),\n        ...usageResult.unmatchedUoms,\n      ]\n    }\n\n    const allLines: InvoiceLineDescriptor[] = [...itemLines, ...usageResult.lines]\n    if (allLines.length === 0) {\n      // Nothing to bill this cycle \u2014 still advance so the account moves\n      // forward in real mode. In test / dry, no advance, so we'd loop\n      // forever; break out.\n      if (params.mode !== 'real') break\n      account.nextBillDate = advanceNextBillDate(\n        account.nextBillDate,\n        account.billCycle as BillCycle,\n      )\n      account.lastBillDate = period.periodEnd\n      account.updatedAt = new Date()\n      cyclesEmitted += 1\n      continue\n    }\n\n    const written = await writeDraftInvoice(em, container, {\n      mode: params.mode,\n      account,\n      period,\n      billRunId: billRun.id,\n      lines: allLines,\n    })\n    lastDraftInvoiceId = written.invoiceId\n\n    if (params.mode === 'real') {\n      const now = new Date()\n      for (const item of billableItems) {\n        item.billedToDate = period.periodEnd\n        item.updatedAt = now\n      }\n      // Mark consumed usage records \u2014 single bulk update so we don't\n      // round-trip per record on accounts with thousands of usage rows.\n      if (usageResult.matchedUoms.length > 0) {\n        // Predicate-based bulk update: marks every still-unrated record\n        // for the matched uoms in the account's period with a single\n        // SQL UPDATE \u2014 no id list ever leaves Postgres. Stays\n        // memory-bounded even for telco accounts with millions of\n        // usage records per cycle (spec Performance Considerations\n        // \"Shape B\").\n        await em.nativeUpdate(\n          BillingAccountUsage,\n          {\n            tenantId: account.tenantId,\n            organizationId: account.organizationId,\n            billAccountId: account.id,\n            uomCode: { $in: usageResult.matchedUoms },\n            ratedInBillRunId: null,\n            periodEnd: { $lte: period.periodEnd },\n            deletedAt: null,\n          } as never,\n          { ratedInBillRunId: billRun.id, updatedAt: now } as never,\n        )\n      }\n      totalUsageRatedThisAccount += usageResult.ratedCount\n      account.nextBillDate = advanceNextBillDate(\n        account.nextBillDate,\n        account.billCycle as BillCycle,\n      )\n      account.lastBillDate = period.periodEnd\n      account.updatedAt = now\n      await em.flush()\n    } else {\n      // Test / dry: do not advance state. One iteration only.\n      break\n    }\n\n    cyclesEmitted += 1\n  }\n\n  const hasCurrencyWarnings =\n    (aggregatedWarnings.currency_mismatch_items ?? []).length > 0\n  const hasUnmatchedUsage =\n    (aggregatedWarnings.unmatched_usage_uoms ?? []).length > 0\n  const hasWarnings = hasCurrencyWarnings || hasUnmatchedUsage\n  return {\n    status: hasWarnings ? 'success_with_warnings' : 'success',\n    warnings: hasWarnings ? aggregatedWarnings : null,\n    draftInvoiceId: lastDraftInvoiceId,\n    cyclesEmitted,\n    usageRecordsRated: totalUsageRatedThisAccount,\n  }\n}\n\nasync function findExistingDraftForPeriod(\n  em: EntityManager,\n  account: BillingAccount,\n  period: { periodStart: Date; periodEnd: Date },\n): Promise<string | null> {\n  const periodStartISO = period.periodStart.toISOString().slice(0, 10)\n  const periodEndISO = period.periodEnd.toISOString().slice(0, 10)\n  const rows = (await em.execute(\n    `SELECT id FROM sales_invoices\n     WHERE tenant_id = ?\n       AND organization_id = ?\n       AND deleted_at IS NULL\n       AND status = 'draft'\n       AND metadata->>'bill_account_id' = ?\n       AND metadata->>'bill_period_start' = ?\n       AND metadata->>'bill_period_end' = ?\n     LIMIT 1`,\n    [account.tenantId, account.organizationId, account.id, periodStartISO, periodEndISO],\n  )) as unknown as Array<{ id: string }> | undefined\n  if (!rows || rows.length === 0) return null\n  return rows[0].id ?? null\n}\n\nfunction computeFinalRunStatus(\n  outcomes: readonly BillRunOutcome[],\n): BillRun['status'] {\n  if (outcomes.length === 0) return 'completed'\n  const anyFailed = outcomes.some((o) => o.status === 'failed')\n  const anySuccess = outcomes.some(\n    (o) => o.status === 'success' || o.status === 'success_with_warnings',\n  )\n  if (anyFailed && anySuccess) return 'partial_failure'\n  if (anyFailed) return 'partial_failure'\n  return 'completed'\n}\n\nfunction buildRunSummary(\n  outcomes: readonly BillRunOutcome[],\n  totalAccounts: number,\n  usageRecordsRated: number,\n): Record<string, unknown> {\n  return {\n    accounts_processed: totalAccounts,\n    drafts_created: outcomes.filter(\n      (o) => o.draftInvoiceId !== null && o.status !== 'skipped_existing_draft',\n    ).length,\n    drafts_skipped_existing: outcomes.filter((o) => o.status === 'skipped_existing_draft')\n      .length,\n    // SPEC-002 prepaid period close.\n    statements_created: outcomes.filter(\n      (o) => o.statementId !== null && o.status !== 'skipped_existing_statement',\n    ).length,\n    statements_skipped_existing: outcomes.filter(\n      (o) => o.status === 'skipped_existing_statement',\n    ).length,\n    accounts_failed: outcomes.filter((o) => o.status === 'failed').length,\n    accounts_with_warnings: outcomes.filter((o) => o.status === 'success_with_warnings')\n      .length,\n    usage_records_rated: usageRecordsRated,\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport { UniqueConstraintViolationException } from '@mikro-orm/core'\nimport {\n  BillingAccount,\n  BillingAccountUsage,\n  BillingInvoice,\n  BillingItem,\n  BillingRun,\n  BillingRunOutcome,\n} from '../data/entities'\nimport {\n  addDays,\n  advanceNextBillDate,\n  cloneAtMidnight,\n  deriveBillPeriod,\n  isCycleDue,\n  shiftCycles,\n  type BillPeriod,\n} from './billPeriod'\nimport { shouldIncludeItem, type SelectableItem } from './itemSelector'\nimport {\n  buildInvoiceLinesFromItems,\n  buildRecurringLineDescriptors,\n  displayPeriod,\n  writeDraftInvoice,\n  type InvoiceLineDescriptor,\n  type WriteMode,\n} from './invoiceWriter'\nimport { computeRecurringLines, type RecurringSkip } from './servicePeriods'\nimport { withTenantLock } from './tenantLock'\nimport { processUsageForAccount } from './usageRunner'\nimport { processPrepaidAccount } from './prepaidPeriodClose'\nimport type { DomainEvent } from './balanceEvents'\nimport { emitBillingEvent, type BillingEventId } from '../events'\nimport type { BillCycle } from '../data/validators'\n\n/**\n * Bill Run engine \u2014 orchestrates one execution of the billing cycle for\n * a single tenant.\n *\n * Concurrency / locking:\n *   - The whole run is wrapped in `withTenantLock(...)`, which holds a\n *     transaction-scoped Postgres advisory lock keyed by\n *     `hash(tenant_id || ':billing-run')`. A second trigger fired while a\n *     run is in flight short-circuits with `TenantLockBusyError` (the\n *     command layer maps that to HTTP 409).\n *   - Within the outer transaction, every account is processed inside a\n *     nested `em.transactional(...)` (PG SAVEPOINT). A per-account failure\n *     rolls back only that account's work, leaving siblings unaffected.\n *\n * Cycles (Spec A): every run \u2014 manual or scheduled, any mode \u2014 bills ALL\n * due bill dates up to `asOfDate`, one draft per bill date (never\n * combined), capped at `CATCH_UP_HARD_CAP` per account. The account's\n * `next_bill_date` and each recurring item's `billed_to_date` watermark are\n * advanced in memory cycle by cycle; only `real` persists them:\n *   - `real` \u2014 persist drafts, advance `next_bill_date` / watermarks, mark\n *     usage rated. Production path.\n *   - `test` \u2014 persist drafts flagged `metadata.test_run=true` for every\n *     cycle, but do NOT advance state. Repeatable.\n *   - `dry`  \u2014 compute every cycle; persist nothing. Preview only.\n *\n * Recurring items are priced by `servicePeriods.computeRecurringLines`\n * (in advance / in arrears, proration, credits). `one_time` items use the\n * selector; usage is always billed in arrears for `[D \u2212 cycle, D \u2212 1]`.\n *\n * Anti-duplicate guards (every mode except `dry`):\n *   1. Open draft for the same `(account, bill_date, test_run)`.\n *   2. `billed_to_date` per BillingItem (the watermark).\n */\n\nexport type RunMode = WriteMode\n\nexport type RunBillRunParams = {\n  tenantId: string\n  organizationId: string\n  asOfDate: Date\n  triggeredBy: 'schedule' | 'manual'\n  mode: RunMode\n  scopedAccountIds?: string[]\n  parentRunId?: string | null\n}\n\nexport type RunBillRunResult = {\n  billRun: BillingRun\n  outcomes: BillingRunOutcome[]\n}\n\ntype RunOutput = RunBillRunResult & {\n  /** Prepaid statement / crossing events to emit AFTER the outer tx commits. */\n  pendingEvents: DomainEvent[]\n}\n\ntype SkippedItemWarning = {\n  item_id: string\n  reason: string\n  service_period_start: string | null\n  service_period_end: string | null\n}\n\ntype AccountWarnings = {\n  currency_mismatch_items?: string[]\n  unmatched_usage_uoms?: string[]\n  /** Spec A: bill dates whose draft has a negative total (credits > charges). */\n  negative_total_bill_dates?: string[]\n  /** Spec A: the account hit CATCH_UP_HARD_CAP; later cycles wait for the next run. */\n  catch_up_cap_reached?: boolean\n  /** Spec A: diagnostic \u2014 partial periods not prorated, no-credit ends, caps. */\n  skipped_items?: SkippedItemWarning[]\n}\n\n/** `charged` is the prepaid analogue of `invoiced` (Spec F, P-D6). */\nexport type CycleStatus = 'invoiced' | 'charged' | 'previewed' | 'empty' | 'skipped_existing'\n\nexport type CycleRecord = {\n  bill_date: string\n  period_start: string | null\n  period_end: string | null\n  status: CycleStatus\n  line_count: number\n  total_net: string\n  invoice_id: string | null\n  /** Prepaid only: what left the balance, and the statement for the period. */\n  total_debit?: string\n  statement_id?: string | null\n}\n\ntype AccountProcessSuccess = {\n  status:\n    | 'success'\n    | 'success_with_warnings'\n    | 'skipped_existing_draft'\n    | 'skipped_existing_statement'\n  warnings: AccountWarnings | Record<string, unknown> | null\n  draftInvoiceId: string | null\n  // SPEC-002: prepaid accounts produce a statement instead of a draft invoice.\n  statementId?: string | null\n  statementEvents?: DomainEvent[]\n  cyclesEmitted: number\n  usageRecordsRated: number\n  /** Spec A: per-bill-date breakdown (postpaid). */\n  cycles?: CycleRecord[]\n}\n\ntype AccountProcessFailed = {\n  status: 'failed'\n  errorMessage: string\n}\n\ntype AccountProcessResult = AccountProcessSuccess | AccountProcessFailed\n\nexport const CATCH_UP_HARD_CAP = 60 // safety net so a misconfigured account can't loop forever\nconst SKIPPED_ITEMS_WARNING_CAP = 200\n/** Skip reasons that are normal state, not worth surfacing on the outcome. */\nconst QUIET_SKIP_REASONS = new Set(['item-inactive', 'item-soft-deleted'])\n\nexport async function runBillRun(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: RunBillRunParams,\n): Promise<RunBillRunResult> {\n  const output = await withTenantLock(\n    em,\n    { tenantId: params.tenantId, lockName: 'billing-run' },\n    async (tem) => executeRunWithinLock(tem, container, params),\n  )\n  // Emit prepaid statement / crossing events ONLY after the outer transaction\n  // (held by withTenantLock) has committed \u2014 emitting inside the lock would let\n  // a consumer observe an uncommitted statement or a phantom event on rollback.\n  for (const ev of output.pendingEvents) {\n    await emitBillingEvent(ev.id as BillingEventId, ev.payload, { persistent: true })\n  }\n  return { billRun: output.billRun, outcomes: output.outcomes }\n}\n\nasync function executeRunWithinLock(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: RunBillRunParams,\n): Promise<RunOutput> {\n  const now = new Date()\n  const billRun = em.create(BillingRun, {\n    organizationId: params.organizationId,\n    tenantId: params.tenantId,\n    triggeredBy: params.triggeredBy,\n    parentRunId: params.parentRunId ?? null,\n    dryRun: params.mode === 'dry',\n    testMode: params.mode === 'test',\n    scopedAccountIds: params.scopedAccountIds ?? null,\n    asOfDate: params.asOfDate,\n    startedAt: now,\n    status: 'running',\n    summary: null,\n    isActive: true,\n    createdAt: now,\n    updatedAt: now,\n  })\n  em.persist(billRun)\n  await em.flush()\n\n  const accounts = await selectTargetAccounts(em, params)\n  const outcomes: BillingRunOutcome[] = []\n  const pendingEvents: DomainEvent[] = []\n  let totalUsageRecordsRated = 0\n\n  for (const account of accounts) {\n    const processResult = await processAccountSafely(em, container, billRun, account, params)\n    if (processResult.status !== 'failed') {\n      totalUsageRecordsRated += processResult.usageRecordsRated\n    }\n    const outcome = em.create(BillingRunOutcome, {\n      organizationId: params.organizationId,\n      tenantId: params.tenantId,\n      billRunId: billRun.id,\n      billAccountId: account.id,\n      status: processResult.status,\n      errorMessage: processResult.status === 'failed' ? processResult.errorMessage : null,\n      warnings:\n        processResult.status === 'failed'\n          ? null\n          : (processResult.warnings as Record<string, unknown> | null),\n      draftInvoiceId: processResult.status === 'failed' ? null : processResult.draftInvoiceId,\n      statementId: processResult.status === 'failed' ? null : (processResult.statementId ?? null),\n      cycles: processResult.status === 'failed' ? null : (processResult.cycles ?? null),\n      isActive: true,\n      createdAt: new Date(),\n      updatedAt: new Date(),\n    })\n    em.persist(outcome)\n    await em.flush()\n    outcomes.push(outcome)\n\n    // Collect statement / crossing events \u2014 runBillRun emits them AFTER the\n    // outer tx commits (see runBillRun), never from inside the lock.\n    if (processResult.status !== 'failed' && processResult.statementEvents) {\n      pendingEvents.push(...processResult.statementEvents)\n    }\n  }\n\n  billRun.status = computeFinalRunStatus(outcomes)\n  billRun.finishedAt = new Date()\n  billRun.updatedAt = billRun.finishedAt\n  billRun.summary = buildRunSummary(outcomes, accounts.length, totalUsageRecordsRated)\n  await em.flush()\n\n  return { billRun, outcomes, pendingEvents }\n}\n\nasync function selectTargetAccounts(\n  em: EntityManager,\n  params: RunBillRunParams,\n): Promise<BillingAccount[]> {\n  const where: Record<string, unknown> = {\n    tenantId: params.tenantId,\n    organizationId: params.organizationId,\n    deletedAt: null,\n    nextBillDate: { $lte: params.asOfDate },\n  }\n  if (params.scopedAccountIds && params.scopedAccountIds.length > 0) {\n    where.id = { $in: params.scopedAccountIds }\n  }\n  return em.find(BillingAccount, where as never)\n}\n\nasync function processAccountSafely(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillingRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  try {\n    return await em.transactional(async (subEm) => {\n      return processAccount(subEm, container, billRun, account, params)\n    })\n  } catch (err) {\n    return {\n      status: 'failed',\n      errorMessage: err instanceof Error ? err.message : String(err),\n    }\n  }\n}\n\nasync function processAccount(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillingRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  // SPEC-002: a prepaid account never gets a payable draft invoice. It still\n  // runs in the Bill Run, but charges recurring / one_time items to the\n  // balance and produces a non-fiscal consumption statement.\n  if (account.billingMode === 'prepaid') {\n    const result = await processPrepaidAccount(em, account, billRun, {\n      asOfDate: params.asOfDate,\n      mode: params.mode,\n      triggeredBy: params.triggeredBy,\n    })\n    if (result.status === 'failed') {\n      return { status: 'failed', errorMessage: result.errorMessage }\n    }\n    return {\n      status: result.status,\n      warnings: result.warnings,\n      draftInvoiceId: null,\n      statementId: result.statementId,\n      statementEvents: result.statementEvents,\n      cyclesEmitted: result.cyclesEmitted,\n      cycles: result.cycles,\n      usageRecordsRated: 0,\n    }\n  }\n\n  return processPostpaidAccount(em, container, billRun, account, params)\n}\n\nfunction isoDate(date: Date): string {\n  return cloneAtMidnight(date).toISOString().slice(0, 10)\n}\n\nfunction toSkipWarning(skip: RecurringSkip): SkippedItemWarning {\n  return {\n    item_id: skip.billingItemId,\n    reason: skip.reason,\n    service_period_start: skip.servicePeriodStart ? isoDate(skip.servicePeriodStart) : null,\n    service_period_end: skip.servicePeriodEnd ? isoDate(skip.servicePeriodEnd) : null,\n  }\n}\n\n/**\n * Postpaid cycle loop (Spec A). Items are loaded once; the bill date and\n * the per-item watermarks advance in memory so test / dry can simulate every\n * due cycle exactly like real does \u2014 only persistence differs by mode.\n */\nasync function processPostpaidAccount(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillingRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  const cycle = account.billCycle as BillCycle\n  const testRun = params.mode === 'test'\n  const items = (await em.find(BillingItem, {\n    tenantId: account.tenantId,\n    organizationId: account.organizationId,\n    billAccountId: account.id,\n    deletedAt: null,\n  } as never)) as BillingItem[]\n  const recurringItems = items.filter((it) => it.type === 'recurring')\n  const oneTimeItems = items.filter((it) => it.type === 'one_time')\n  const usageItems = items.filter((it) => it.type === 'usage')\n\n  // In-memory cycle state \u2014 persisted per cycle only in real mode.\n  const watermarks = new Map<string, Date | null>(\n    recurringItems.map((it) => [it.id, it.billedToDate ? cloneAtMidnight(it.billedToDate) : null]),\n  )\n  const billedOneTimes = new Set<string>(oneTimeItems.filter((it) => it.billedToDate).map((it) => it.id))\n  let billDate = cloneAtMidnight(account.nextBillDate)\n  // Usage already counted by an earlier cycle of THIS run (test / dry never\n  // mark records, so later simulated cycles must not re-count them).\n  let usageCountedThrough: Date | null = null\n\n  const cycles: CycleRecord[] = []\n  const warnings: AccountWarnings = {}\n  const skippedItems: SkippedItemWarning[] = []\n  let lastDraftInvoiceId: string | null = null\n  let usageRecordsRated = 0\n\n  const pushSkips = (skips: readonly RecurringSkip[]) => {\n    for (const skip of skips) {\n      if (QUIET_SKIP_REASONS.has(skip.reason)) continue\n      if (skippedItems.length < SKIPPED_ITEMS_WARNING_CAP) skippedItems.push(toSkipWarning(skip))\n    }\n  }\n  const addWarning = (key: 'currency_mismatch_items' | 'unmatched_usage_uoms' | 'negative_total_bill_dates', values: string[]) => {\n    if (values.length === 0) return\n    warnings[key] = Array.from(new Set([...(warnings[key] ?? []), ...values]))\n  }\n\n  while (isCycleDue(billDate, params.asOfDate)) {\n    if (cycles.length >= CATCH_UP_HARD_CAP) {\n      warnings.catch_up_cap_reached = true\n      break\n    }\n    const nextBillDate = advanceNextBillDate(billDate, cycle)\n    const arrearsPeriod: BillPeriod = deriveBillPeriod(billDate, cycle)\n\n    // \u2500\u2500 Recurring: service periods against the in-memory watermarks \u2500\u2500\n    const lines: InvoiceLineDescriptor[] = []\n    const watermarkUpdates = new Map<string, Date | null>()\n    const chargedItems: BillingItem[] = []\n    for (const item of recurringItems) {\n      const unitPrice = (item.rateJson as { unit_price?: number } | null)?.unit_price\n      if (typeof unitPrice !== 'number') continue\n      const computed = computeRecurringLines(\n        {\n          id: item.id,\n          chargeTiming: item.chargeTiming ?? 'in_advance',\n          prorate: item.prorate ?? true,\n          billStartDate: item.billStartDate,\n          billEndDate: item.billEndDate ?? null,\n          billedToDate: watermarks.get(item.id) ?? null,\n          unitPrice,\n          isActive: item.isActive,\n          deletedAt: item.deletedAt ?? null,\n        },\n        { billDate, cycle },\n      )\n      pushSkips(computed.skipped)\n      if (computed.newBilledToDate?.getTime() !== watermarks.get(item.id)?.getTime()) {\n        watermarkUpdates.set(item.id, computed.newBilledToDate)\n      }\n      if (computed.lines.length > 0) {\n        lines.push(...buildRecurringLineDescriptors(item, computed.lines))\n        chargedItems.push(item)\n      }\n    }\n\n    // \u2500\u2500 One-time: first bill date whose [D \u2212 cycle, D + cycle \u2212 1] window overlaps \u2500\u2500\n    const oneTimeWindow: BillPeriod = {\n      periodStart: shiftCycles(billDate, cycle, -1),\n      periodEnd: addDays(nextBillDate, -1),\n    }\n    const oneTimesThisCycle = oneTimeItems.filter(\n      (it) => !billedOneTimes.has(it.id) && shouldIncludeItem(it as SelectableItem, oneTimeWindow).include,\n    )\n    lines.push(...buildInvoiceLinesFromItems(oneTimesThisCycle))\n    chargedItems.push(...oneTimesThisCycle)\n\n    // \u2500\u2500 Usage: always in arrears \u2500\u2500\n    const usageResult = await processUsageForAccount(em, account, arrearsPeriod, usageItems, {\n      after: usageCountedThrough,\n    })\n    addWarning('unmatched_usage_uoms', usageResult.unmatchedUoms)\n    lines.push(\n      ...usageResult.lines.map((line) => ({\n        ...line,\n        servicePeriodStart: arrearsPeriod.periodStart,\n        servicePeriodEnd: arrearsPeriod.periodEnd,\n      })),\n    )\n    addWarning(\n      'currency_mismatch_items',\n      chargedItems.filter((it) => it.currencyMismatch).map((it) => it.id),\n    )\n\n    const period = displayPeriod(lines, arrearsPeriod)\n    const record: CycleRecord = {\n      bill_date: isoDate(billDate),\n      period_start: lines.length ? isoDate(period.periodStart) : null,\n      period_end: lines.length ? isoDate(period.periodEnd) : null,\n      status: 'empty',\n      line_count: lines.length,\n      total_net: '0.0000',\n      invoice_id: null,\n    }\n\n    // \u2500\u2500 Dedupe: an open draft already exists for this bill date \u2500\u2500\n    const existing =\n      params.mode === 'dry' ? null : await findExistingDraftForBillDate(em, account, billDate, testRun)\n    if (existing && params.mode === 'real') {\n      // Real state is inconsistent (draft written, account not advanced) \u2014\n      // stop here without advancing, as before Spec A.\n      cycles.push({ ...record, status: 'skipped_existing', invoice_id: existing })\n      return {\n        status: 'skipped_existing_draft',\n        warnings: finalizeWarnings(warnings, skippedItems),\n        draftInvoiceId: existing,\n        cyclesEmitted: cycles.filter((c) => c.status === 'invoiced').length,\n        usageRecordsRated,\n        cycles,\n      }\n    }\n\n    if (existing) {\n      cycles.push({ ...record, status: 'skipped_existing', invoice_id: existing })\n    } else if (lines.length > 0) {\n      const written = await writeDraftOnce(em, {\n        mode: params.mode,\n        account,\n        billDate,\n        period,\n        billRunId: billRun.id,\n        lines,\n      })\n      if (written === 'conflict') {\n        // Unique (account, bill_date, test_run) backstop fired: a concurrent\n        // writer got there first. Same semantics as the dedupe check above.\n        cycles.push({ ...record, status: 'skipped_existing' })\n        if (params.mode === 'real') {\n          return {\n            status: 'skipped_existing_draft',\n            warnings: finalizeWarnings(warnings, skippedItems),\n            draftInvoiceId: lastDraftInvoiceId,\n            cyclesEmitted: cycles.filter((c) => c.status === 'invoiced').length,\n            usageRecordsRated,\n            cycles,\n          }\n        }\n        billDate = nextBillDate\n        for (const [itemId, date] of watermarkUpdates) watermarks.set(itemId, date)\n        for (const it of oneTimesThisCycle) billedOneTimes.add(it.id)\n        usageCountedThrough = arrearsPeriod.periodEnd\n        continue\n      }\n      if (written.invoiceId) lastDraftInvoiceId = written.invoiceId\n      if (Number.parseFloat(written.totalNet) < 0) addWarning('negative_total_bill_dates', [record.bill_date])\n      cycles.push({\n        ...record,\n        status: params.mode === 'dry' ? 'previewed' : 'invoiced',\n        total_net: written.totalNet,\n        invoice_id: written.invoiceId,\n      })\n    } else {\n      cycles.push(record)\n    }\n\n    // \u2500\u2500 Advance state: in memory always, persisted in real mode \u2500\u2500\n    for (const [itemId, date] of watermarkUpdates) watermarks.set(itemId, date)\n    for (const it of oneTimesThisCycle) billedOneTimes.add(it.id)\n    usageCountedThrough = arrearsPeriod.periodEnd\n\n    if (params.mode === 'real') {\n      const now = new Date()\n      for (const item of recurringItems) {\n        if (!watermarkUpdates.has(item.id)) continue\n        item.billedToDate = watermarkUpdates.get(item.id) ?? null\n        item.updatedAt = now\n      }\n      for (const item of oneTimesThisCycle) {\n        item.billedToDate = oneTimeWindow.periodEnd\n        item.updatedAt = now\n      }\n      if (usageResult.matchedUoms.length > 0) {\n        // Predicate-based bulk update: marks every still-unrated record for\n        // the matched uoms up to the period end with a single SQL UPDATE \u2014\n        // no id list ever leaves Postgres (spec Performance \"Shape B\").\n        await em.nativeUpdate(\n          BillingAccountUsage,\n          {\n            tenantId: account.tenantId,\n            organizationId: account.organizationId,\n            billAccountId: account.id,\n            uomCode: { $in: usageResult.matchedUoms },\n            ratedInBillRunId: null,\n            periodEnd: { $lte: arrearsPeriod.periodEnd },\n            deletedAt: null,\n          } as never,\n          { ratedInBillRunId: billRun.id, updatedAt: now } as never,\n        )\n        usageRecordsRated += usageResult.ratedCount\n      }\n      account.nextBillDate = nextBillDate\n      account.lastBillDate = arrearsPeriod.periodEnd\n      account.updatedAt = now\n      await em.flush()\n    }\n\n    billDate = nextBillDate\n  }\n\n  const finalWarnings = finalizeWarnings(warnings, skippedItems)\n  return {\n    status: hasRealWarnings(warnings) ? 'success_with_warnings' : 'success',\n    warnings: finalWarnings,\n    draftInvoiceId: lastDraftInvoiceId,\n    cyclesEmitted: cycles.filter((c) => c.status === 'invoiced').length,\n    usageRecordsRated,\n    cycles,\n  }\n}\n\nfunction finalizeWarnings(\n  warnings: AccountWarnings,\n  skippedItems: SkippedItemWarning[],\n): AccountWarnings | null {\n  const merged: AccountWarnings = { ...warnings, ...(skippedItems.length ? { skipped_items: skippedItems } : {}) }\n  return Object.keys(merged).length > 0 ? merged : null\n}\n\n/** Skipped items are diagnostics; they don't downgrade the outcome status. */\nfunction hasRealWarnings(warnings: AccountWarnings): boolean {\n  return Boolean(\n    warnings.currency_mismatch_items?.length ||\n      warnings.unmatched_usage_uoms?.length ||\n      warnings.negative_total_bill_dates?.length ||\n      warnings.catch_up_cap_reached,\n  )\n}\n\n/**\n * Existing invoice for `(account, bill_date, test_run)` in ANY status \u2014 a\n * posted invoice for the same bill date also blocks re-billing (e.g. after\n * an operator moved `next_bill_date` back). Test drafts never block real\n * drafts and vice versa. The partial unique index\n * `billing_invoices_bill_date_uq` is the backstop (see `writeDraftOnce`).\n */\nasync function findExistingDraftForBillDate(\n  em: EntityManager,\n  account: BillingAccount,\n  billDate: Date,\n  testRun: boolean,\n): Promise<string | null> {\n  const existing = await em.findOne(\n    BillingInvoice,\n    {\n      tenantId: account.tenantId,\n      organizationId: account.organizationId,\n      billAccountId: account.id,\n      billDate,\n      testRun,\n      documentType: 'invoice',\n      deletedAt: null,\n    } as never,\n  )\n  return existing?.id ?? null\n}\n\n/**\n * Writes the draft inside its own savepoint so a unique-index conflict\n * (concurrent writer for the same bill date) doesn't abort the account's\n * transaction \u2014 it is reported as 'conflict' and handled like a dedupe hit.\n */\nasync function writeDraftOnce(\n  em: EntityManager,\n  params: Parameters<typeof writeDraftInvoice>[1],\n): Promise<Awaited<ReturnType<typeof writeDraftInvoice>> | 'conflict'> {\n  if (params.mode === 'dry') return writeDraftInvoice(em, params)\n  try {\n    return await em.transactional((tem) => writeDraftInvoice(tem as EntityManager, params))\n  } catch (err) {\n    if (err instanceof UniqueConstraintViolationException) return 'conflict'\n    throw err\n  }\n}\n\nfunction computeFinalRunStatus(\n  outcomes: readonly BillingRunOutcome[],\n): BillingRun['status'] {\n  if (outcomes.length === 0) return 'completed'\n  const anyFailed = outcomes.some((o) => o.status === 'failed')\n  const anySuccess = outcomes.some(\n    (o) => o.status === 'success' || o.status === 'success_with_warnings',\n  )\n  if (anyFailed && anySuccess) return 'partial_failure'\n  if (anyFailed) return 'partial_failure'\n  return 'completed'\n}\n\nfunction buildRunSummary(\n  outcomes: readonly BillingRunOutcome[],\n  totalAccounts: number,\n  usageRecordsRated: number,\n): Record<string, unknown> {\n  const allCycles = outcomes.flatMap((o) => (Array.isArray(o.cycles) ? (o.cycles as CycleRecord[]) : []))\n  return {\n    accounts_processed: totalAccounts,\n    // Spec A: one draft per invoiced cycle (catch-up writes several per account).\n    drafts_created: allCycles.filter((c) => c.status === 'invoiced' && c.invoice_id).length,\n    cycles_processed: allCycles.length,\n    drafts_skipped_existing: outcomes.filter((o) => o.status === 'skipped_existing_draft')\n      .length,\n    // SPEC-002 prepaid period close.\n    statements_created: outcomes.filter(\n      (o) => o.statementId !== null && o.status !== 'skipped_existing_statement',\n    ).length,\n    statements_skipped_existing: outcomes.filter(\n      (o) => o.status === 'skipped_existing_statement',\n    ).length,\n    accounts_failed: outcomes.filter((o) => o.status === 'failed').length,\n    accounts_with_warnings: outcomes.filter((o) => o.status === 'success_with_warnings')\n      .length,\n    usage_records_rated: usageRecordsRated,\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/modules/billing/lib/billRunLabel.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/lib/billRunLabel.ts"],
-  "sourcesContent": ["/**\n * Human-readable label for a Bill Run.\n *\n * The BillRun entity has no `name` column \u2014 the engine keys runs by id.\n * The admin UI derives a stable, scannable label from the run's as-of\n * date so operators see `BILL_RUN_2026-05-20` instead of a raw UUID.\n */\nexport function billRunName(asOfDate: string | null | undefined): string {\n  const date =\n    typeof asOfDate === 'string' && asOfDate.length >= 10\n      ? asOfDate.slice(0, 10)\n      : 'unknown'\n  return `BILL_RUN_${date}`\n}\n"],
+  "sourcesContent": ["/**\n * Human-readable label for a Bill Run.\n *\n * The BillingRun entity has no `name` column \u2014 the engine keys runs by id.\n * The admin UI derives a stable, scannable label from the run's as-of\n * date so operators see `BILL_RUN_2026-05-20` instead of a raw UUID.\n */\nexport function billRunName(asOfDate: string | null | undefined): string {\n  const date =\n    typeof asOfDate === 'string' && asOfDate.length >= 10\n      ? asOfDate.slice(0, 10)\n      : 'unknown'\n  return `BILL_RUN_${date}`\n}\n"],
   "mappings": "AAOO,SAAS,YAAY,UAA6C;AACvE,QAAM,OACJ,OAAO,aAAa,YAAY,SAAS,UAAU,KAC/C,SAAS,MAAM,GAAG,EAAE,IACpB;AACN,SAAO,YAAY,IAAI;AACzB;",
   "names": []
 }