@dainamite/billing 0.19.0 → 0.20.0

package/src/modules/billing/backend/billing/invoices/page.tsx

@@ -1,7 +1,7 @@
 "use client"
 import * as React from 'react'
 import { useRouter } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'

package/src/modules/billing/backend/billing/items/page.tsx

@@ -3,7 +3,7 @@ import * as React from 'react'
 import Link from 'next/link'
 import { useRouter, useSearchParams } from 'next/navigation'
 import { Plus } from 'lucide-react'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'

package/src/modules/billing/backend/billing/runs/[id]/page.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import Link from 'next/link'
 import { useParams } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { Page, PageBody, PageHeader } from '@open-mercato/ui/backend/Page'
 import { FormHeader } from '@open-mercato/ui/backend/forms'

package/src/modules/billing/backend/billing/runs/page.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import { useRouter } from 'next/navigation'
 import { Play } from 'lucide-react'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'

package/src/modules/billing/backend/billing/statements/[id]/page.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import Link from 'next/link'
 import { useParams } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { FormHeader } from '@open-mercato/ui/backend/forms'

package/src/modules/billing/backend/billing/statements/page.tsx

@@ -1,7 +1,7 @@
 "use client"
 import * as React from 'react'
 import { useRouter } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'

package/src/modules/billing/backend/billing/topups/page.tsx

@@ -1,7 +1,7 @@
 "use client"
 import * as React from 'react'
 import { useRouter } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'

package/src/modules/billing/backend/billing/transactions/page.tsx

@@ -1,7 +1,7 @@
 "use client"
 import * as React from 'react'
 import { useRouter } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'

package/src/modules/billing/ce.ts

@@ -1,14 +1,15 @@
 import type { CustomEntitySpec } from '@open-mercato/shared/modules/entities'
 
 /**
- * Billing module entity registry.
+ * Billing module custom-entity specs (labels / custom-field surfaces).
  *
- * Listing our MikroORM entities here gets them into the framework's
- * `E.billing.<entity>` generated registry (`entities.ids.generated.ts`),
- * which the CRUD factory, query engine, and indexers reference. Phase 0
- * shipped with no entries because the standalone CLI didn't traverse
- * `@dainamite/*` packages — adding them in Phase 1 once the resolver
- * patch lands.
+ * These ids are real MikroORM tables, not virtual custom entities. The
+ * framework only knows that while each id is also in the app's generated
+ * `E.billing` registry (fed by the package's shipped
+ * `generated/entities.ids.generated.ts`). For an id missing there,
+ * `mercato entities install` writes an active `custom_entities` row, and the
+ * query engine then reads the id from custom-entity storage instead of its
+ * table — every billing list comes back empty.
  *
  * `fields: []` means billing does NOT expose custom-field surfaces on
  * these entities today (no EAV). Adding fields here is reserved for

package/src/modules/billing/commands/invoices.ts

@@ -8,7 +8,7 @@ import {
 } from '@open-mercato/shared/lib/commands/scope'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { SalesInvoice, SalesInvoiceLine } from '@open-mercato/core/modules/sales/data/entities'
-import { BillingAccount, DraftInvoiceEdit } from '../data/entities'
+import { BillingAccount, BillingDraftInvoiceEdit } from '../data/entities'
 import { emitBillingEvent, type BillingEventId } from '../events'
 import { buildPostpaidCreditCrossingEvents } from '../lib/accountStatus'
 import {
@@ -182,7 +182,7 @@ const postInvoiceCommand: CommandHandler<BillingInvoicePostInput, PostResult> =
 // Three commands sharing the same shape:
 //   1. Assert the invoice is still a draft (refuse otherwise).
 //   2. Mutate the line / collection.
-//   3. Write a `DraftInvoiceEdit` audit row carrying before+after
+//   3. Write a `BillingDraftInvoiceEdit` audit row carrying before+after
 //      snapshots (`null` on the "no prior state" / "no resulting state"
 //      side per the spec — see entity column docs).
 //   4. Recompute the invoice totals from the surviving lines.
@@ -267,7 +267,7 @@ async function recomputeInvoiceTotals(
 
 function getUserIdFromCtx(ctx: CommandRuntimeContext): string {
   const userId = (ctx.auth?.sub as string | undefined) ?? null
-  // The DraftInvoiceEdit.user_id column is NOT NULL. For system-driven
+  // The BillingDraftInvoiceEdit.user_id column is NOT NULL. For system-driven
   // edits (e.g. catch-up flow that revises a value), we fall back to
   // a sentinel UUID. Operator-driven edits always have a real
   // ctx.auth.sub.
@@ -303,7 +303,7 @@ const editDraftLineCommand: CommandHandler<
     }
 
     const before = snapshotLine(line)
-    let audit: DraftInvoiceEdit | null = null
+    let audit: BillingDraftInvoiceEdit | null = null
 
     await withAtomicFlush(em, [
       () => {
@@ -339,7 +339,7 @@ const editDraftLineCommand: CommandHandler<
       },
       () => {
         const after = snapshotLine(line)
-        audit = em.create(DraftInvoiceEdit, {
+        audit = em.create(BillingDraftInvoiceEdit, {
           tenantId: parsed.tenantId,
           organizationId: parsed.organizationId,
           invoiceId: invoice.id,
@@ -408,7 +408,7 @@ const addDraftLineCommand: CommandHandler<
         operator_added: true,
       },
     })
-    let audit: DraftInvoiceEdit | null = null
+    let audit: BillingDraftInvoiceEdit | null = null
 
     await withAtomicFlush(em, [
       () => {
@@ -419,7 +419,7 @@ const addDraftLineCommand: CommandHandler<
       },
       () => {
         const after = snapshotLine(line)
-        audit = em.create(DraftInvoiceEdit, {
+        audit = em.create(BillingDraftInvoiceEdit, {
           tenantId: parsed.tenantId,
           organizationId: parsed.organizationId,
           invoiceId: invoice.id,
@@ -466,7 +466,7 @@ const removeDraftLineCommand: CommandHandler<
     }
 
     const before = snapshotLine(line)
-    let audit: DraftInvoiceEdit | null = null
+    let audit: BillingDraftInvoiceEdit | null = null
 
     await withAtomicFlush(em, [
       () => {
@@ -476,7 +476,7 @@ const removeDraftLineCommand: CommandHandler<
         await recomputeInvoiceTotals(em, invoice)
       },
       () => {
-        audit = em.create(DraftInvoiceEdit, {
+        audit = em.create(BillingDraftInvoiceEdit, {
           tenantId: parsed.tenantId,
           organizationId: parsed.organizationId,
           invoiceId: invoice.id,

package/src/modules/billing/commands/runs.ts

@@ -7,7 +7,7 @@ import {
   ensureTenantScope,
 } from '@open-mercato/shared/lib/commands/scope'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
-import { BillRun, BillRunOutcome } from '../data/entities'
+import { BillingRun, BillingRunOutcome } from '../data/entities'
 import {
   billingRunRetryFailedSchema,
   billingRunTriggerSchema,
@@ -107,7 +107,7 @@ const retryFailedCommand: CommandHandler<BillingRunRetryFailedInput, TriggerResu
     ensureOrganizationScope(ctx, parsed.organizationId)
 
     const em = getEm(ctx)
-    const parentRun = await em.findOne(BillRun, {
+    const parentRun = await em.findOne(BillingRun, {
       id: parsed.billRunId,
       tenantId: parsed.tenantId,
       organizationId: parsed.organizationId,
@@ -116,7 +116,7 @@ const retryFailedCommand: CommandHandler<BillingRunRetryFailedInput, TriggerResu
     if (!parentRun) {
       throw new CrudHttpError(404, { error: 'Parent Bill Run not found' })
     }
-    const failedOutcomes = await em.find(BillRunOutcome, {
+    const failedOutcomes = await em.find(BillingRunOutcome, {
       billRunId: parentRun.id,
       tenantId: parsed.tenantId,
       organizationId: parsed.organizationId,

package/src/modules/billing/components/PrepaidPanel.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import { useRouter } from 'next/navigation'
 import { Plus, SlidersHorizontal } from 'lucide-react'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { DataTable } from '@open-mercato/ui/backend/DataTable'
 import { Tag } from '@open-mercato/ui/primitives/tag'

package/src/modules/billing/data/entities.ts

@@ -318,13 +318,20 @@ export class BillingAccountUsage {
   deletedAt?: Date | null
 }
 
-// ─── BillRun ─────────────────────────────────────────────────────
+// ─── BillingRun ──────────────────────────────────────────────────
 //
 // A single execution of the engine — one row per trigger (schedule or
 // manual). The concurrency lock is a Postgres transaction-scoped advisory
 // lock keyed by hash(tenant_id || 'billing-run'); it is NOT stored on this
 // row. Crash recovery for zombie `status='running'` rows is handled by
 // workers/reap-stale-bill-runs.ts.
+//
+// Class names must be the PascalCase of the entity-id suffix (`billing:
+// billing_run` → `BillingRun`) — that is how Open Mercato maps an id to its
+// table. Until 0.20.0 this class was `BillRun` (likewise `BillRunOutcome`,
+// `DraftInvoiceEdit`), and those three ids resolved to no table; see
+// data/entityIds.ts. Type-only aliases for the old names are at the end of
+// this file.
 
 @Entity({ tableName: 'billing_runs' })
 @Index({
@@ -335,7 +342,7 @@ export class BillingAccountUsage {
   name: 'billing_runs_parent_idx',
   properties: ['parentRunId'],
 })
-export class BillRun {
+export class BillingRun {
   [OptionalProps]?:
     | 'parentRunId'
     | 'dryRun'
@@ -417,10 +424,10 @@ export class BillRun {
   deletedAt?: Date | null
 }
 
-// ─── BillRunOutcome ──────────────────────────────────────────────
+// ─── BillingRunOutcome ───────────────────────────────────────────
 //
 // Per-account outcome of a Bill Run. Stored in its own table (not as a
-// JSONB array on BillRun.summary) so operators can query failures across
+// JSONB array on BillingRun.summary) so operators can query failures across
 // runs without jsonb_array_elements gymnastics. See spec rationale.
 
 @Entity({ tableName: 'billing_run_outcomes' })
@@ -432,7 +439,7 @@ export class BillRun {
   name: 'billing_run_outcomes_account_history_idx',
   properties: ['organizationId', 'tenantId', 'billAccountId', 'createdAt'],
 })
-export class BillRunOutcome {
+export class BillingRunOutcome {
   [OptionalProps]?:
     | 'errorMessage'
     | 'warnings'
@@ -493,7 +500,7 @@ export class BillRunOutcome {
   deletedAt?: Date | null
 }
 
-// ─── DraftInvoiceEdit (audit) ────────────────────────────────────
+// ─── BillingDraftInvoiceEdit (audit) ─────────────────────────────
 //
 // Append-only audit of every operator edit on a draft invoice line.
 // Pattern mirrors `cpq_subscription_change_logs` — minimal columns
@@ -509,7 +516,7 @@ export class BillRunOutcome {
   name: 'billing_draft_invoice_edits_user_idx',
   properties: ['organizationId', 'tenantId', 'userId', 'createdAt'],
 })
-export class DraftInvoiceEdit {
+export class BillingDraftInvoiceEdit {
   [OptionalProps]?: 'invoiceLineId' | 'beforeJson' | 'afterJson' | 'createdAt' | 'deletedAt'
 
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
@@ -630,8 +637,8 @@ export class BillingAccountBalance {
 // ─── BillingAccountTransaction (SPEC-002, append-only) ───────────
 //
 // The source of truth for every balance movement. Append-only — pattern
-// mirrors DraftInvoiceEdit (no `updated_at` / `is_active`; `deleted_at`
-// reserved for compliance erasure only). `balance = SUM(amount)`.
+// mirrors BillingDraftInvoiceEdit (no `updated_at` / `is_active`;
+// `deleted_at` reserved for compliance erasure only). `balance = SUM(amount)`.
 //
 // The unique `(tenant_id, bill_account_id, source_ref)` is the idempotency
 // gate: a deduplicated usage upload or a retried recurring charge can never
@@ -860,7 +867,7 @@ export class BillingStatement {
   @Property({ name: 'bill_account_id', type: 'uuid' })
   billAccountId!: string
 
-  // FK (string) to the BillRun that generated it (period close reuses the
+  // FK (string) to the BillingRun that generated it (period close reuses the
   // run engine). Null for a manually-generated statement.
   @Property({ name: 'bill_run_id', type: 'uuid', nullable: true })
   billRunId?: string | null
@@ -914,3 +921,17 @@ export class BillingStatement {
   @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
   updatedAt: Date = new Date()
 }
+
+// ─── Deprecated names (0.20.0) ───────────────────────────────────
+//
+// Type-only on purpose: a runtime alias (`export const BillRun = BillingRun`)
+// would make the app's generated `entities` list carry the same class twice.
+// Code that used the old names as values (`em.find(BillRun, …)`) must switch
+// to the new ones — TypeScript flags it.
+
+/** @deprecated Renamed to {@link BillingRun} in 0.20.0. */
+export type BillRun = BillingRun
+/** @deprecated Renamed to {@link BillingRunOutcome} in 0.20.0. */
+export type BillRunOutcome = BillingRunOutcome
+/** @deprecated Renamed to {@link BillingDraftInvoiceEdit} in 0.20.0. */
+export type DraftInvoiceEdit = BillingDraftInvoiceEdit

package/src/modules/billing/data/entityIds.ts

@@ -1,17 +1,22 @@
 /**
- * Canonical entity IDs for the billing module.
+ * Canonical entity IDs for the billing module — the single source of truth.
+ * Billing code (CRUD factory `entityId`, indexer `entityType`, response
+ * enricher `targetEntity`, …) imports from here; a package must not import
+ * the app's `#generated/entities.ids.generated`.
  *
- * Mirrors what `E.billing.<entity>` would be in
- * `.mercato/generated/entities.ids.generated.ts` if the standalone-app
- * CLI properly discovered `@dainamite/*` workspace entities (see the
- * Phase 0 deviation note in `xd-249-billing-spec.md`). Until the CLI
- * gap is closed upstream, this is the single source of truth — every
- * place that previously would have referenced `E.billing.*` (CRUD
- * factory `entityId`, indexer `entityType`, response enricher
- * `targetEntity`, etc.) imports from here instead.
+ * The build turns this object into the shipped registry
+ * `generated/entities.ids.generated.ts` (scripts/generate-entity-registry.mjs),
+ * which a consuming app's `mercato generate` reads to register these ids in
+ * its own `E.billing`. Without that, the query index rejects billing writes
+ * and `mercato entities install` treats the ids as virtual custom entities.
  *
- * When the CLI is fixed, this file can be replaced by `import { E }
- * from '#generated/entities.ids.generated'` in one PR.
+ * Adding an entity: add it here, then `yarn workspace @dainamite/billing
+ * build` and commit `generated/`. The id suffix must be the snake_case of
+ * the entity class name (`billing_run` → `BillingRun`): that is how the
+ * framework maps an id to its table, and the build fails otherwise. Do not
+ * rely on its table-name fallback — on Open Mercato 0.9 with MikroORM 7 it
+ * never matches (it iterates `MetadataStorage.getAll()` as an array, but
+ * that returns a Map).
  */
 export const billingEntityIds = {
   account: 'billing:billing_account',

package/src/modules/billing/events.ts

@@ -12,8 +12,34 @@ import { createModuleEvents } from '@open-mercato/shared/modules/events'
  *   - `billing.run.completed` fires once per Bill Run after all per-account
  *     transactions finished (status is one of `completed` / `partial_failure`
  *     / `failed`). Useful for "did the nightly run go OK?" alerts.
+ *
+ * CRUD events (`billing.<entity>.<action>`) are emitted by the data engine
+ * from the commands' `emitCrudSideEffects({ events: { module: 'billing',
+ * entity } })`. Only the (entity, action) pairs a command actually emits are
+ * declared — `__tests__/events.test.ts` fails when a command emits one that
+ * is missing here (the data engine would log "Emitting undeclared event").
  */
 const events = [
+  // ─── CRUD (commands/*.ts) ────────────────────────────────────
+  { id: 'billing.account.created', label: 'Billing Account Created', entity: 'account', category: 'crud' },
+  { id: 'billing.account.updated', label: 'Billing Account Updated', entity: 'account', category: 'crud' },
+  { id: 'billing.account.deleted', label: 'Billing Account Deleted', entity: 'account', category: 'crud' },
+  { id: 'billing.item.created', label: 'Billing Item Created', entity: 'item', category: 'crud' },
+  { id: 'billing.item.updated', label: 'Billing Item Updated', entity: 'item', category: 'crud' },
+  { id: 'billing.item.deleted', label: 'Billing Item Deleted', entity: 'item', category: 'crud' },
+  {
+    // One per usage upload, on the same high-throughput path as
+    // `billing.usage.rated` — excluded from workflow triggers for the same
+    // reason (see Open Question #2).
+    id: 'billing.usage.created',
+    label: 'Billing Usage Record Created',
+    entity: 'usage',
+    category: 'crud',
+    excludeFromTriggers: true,
+  },
+  { id: 'billing.transaction.created', label: 'Billing Balance Transaction Created', entity: 'transaction', category: 'crud' },
+  { id: 'billing.topup.created', label: 'Billing Top-up Created', entity: 'topup', category: 'crud' },
+  // ─── Lifecycle ───────────────────────────────────────────────
   {
     id: 'billing.invoice.posted',
     label: 'Billing Invoice Posted',

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

@@ -4,8 +4,8 @@ import {
   BillingAccount,
   BillingAccountUsage,
   BillingItem,
-  BillRun,
-  BillRunOutcome,
+  BillingRun,
+  BillingRunOutcome,
 } from '../data/entities'
 import { advanceNextBillDate, deriveBillPeriod, isCycleDue } from './billPeriod'
 import {
@@ -72,8 +72,8 @@ export type RunBillRunParams = {
 }
 
 export type RunBillRunResult = {
-  billRun: BillRun
-  outcomes: BillRunOutcome[]
+  billRun: BillingRun
+  outcomes: BillingRunOutcome[]
 }
 
 type RunOutput = RunBillRunResult & {
@@ -136,7 +136,7 @@ async function executeRunWithinLock(
   params: RunBillRunParams,
 ): Promise<RunOutput> {
   const now = new Date()
-  const billRun = em.create(BillRun, {
+  const billRun = em.create(BillingRun, {
     organizationId: params.organizationId,
     tenantId: params.tenantId,
     triggeredBy: params.triggeredBy,
@@ -157,7 +157,7 @@ async function executeRunWithinLock(
   await em.flush()
 
   const accounts = await selectTargetAccounts(em, params)
-  const outcomes: BillRunOutcome[] = []
+  const outcomes: BillingRunOutcome[] = []
   const pendingEvents: DomainEvent[] = []
   let totalUsageRecordsRated = 0
 
@@ -166,7 +166,7 @@ async function executeRunWithinLock(
     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,
@@ -222,7 +222,7 @@ async function selectTargetAccounts(
 async function processAccountSafely(
   em: EntityManager,
   container: AwilixContainer,
-  billRun: BillRun,
+  billRun: BillingRun,
   account: BillingAccount,
   params: RunBillRunParams,
 ): Promise<AccountProcessResult> {
@@ -241,7 +241,7 @@ async function processAccountSafely(
 async function processAccount(
   em: EntityManager,
   container: AwilixContainer,
-  billRun: BillRun,
+  billRun: BillingRun,
   account: BillingAccount,
   params: RunBillRunParams,
 ): Promise<AccountProcessResult> {
@@ -438,8 +438,8 @@ async function findExistingDraftForPeriod(
 }
 
 function computeFinalRunStatus(
-  outcomes: readonly BillRunOutcome[],
-): BillRun['status'] {
+  outcomes: readonly BillingRunOutcome[],
+): BillingRun['status'] {
   if (outcomes.length === 0) return 'completed'
   const anyFailed = outcomes.some((o) => o.status === 'failed')
   const anySuccess = outcomes.some(
@@ -451,7 +451,7 @@ function computeFinalRunStatus(
 }
 
 function buildRunSummary(
-  outcomes: readonly BillRunOutcome[],
+  outcomes: readonly BillingRunOutcome[],
   totalAccounts: number,
   usageRecordsRated: number,
 ): Record<string, unknown> {

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

@@ -1,7 +1,7 @@
 /**
  * Human-readable label for a Bill Run.
  *
- * The BillRun entity has no `name` column — the engine keys runs by id.
+ * The BillingRun entity has no `name` column — the engine keys runs by id.
  * The admin UI derives a stable, scannable label from the run's as-of
  * date so operators see `BILL_RUN_2026-05-20` instead of a raw UUID.
  */

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

@@ -5,7 +5,7 @@ import {
   BillingAccountTransaction,
   BillingItem,
   BillingStatement,
-  BillRun,
+  BillingRun,
 } from '../data/entities'
 import type { BillCycle } from '../data/validators'
 import { advanceNextBillDate, addDays, deriveBillPeriod, isCycleDue, type BillPeriod } from './billPeriod'
@@ -75,7 +75,7 @@ export type ProcessPrepaidParams = {
 export async function processPrepaidAccount(
   em: EntityManager,
   account: BillingAccount,
-  billRun: BillRun,
+  billRun: BillingRun,
   params: ProcessPrepaidParams,
 ): Promise<PrepaidAccountResult> {
   const maxCycles =
@@ -212,7 +212,7 @@ async function closePrepaidPeriod(
   em: EntityManager,
   account: BillingAccount,
   period: BillPeriod,
-  billRun: BillRun,
+  billRun: BillingRun,
   opts: {
     mode: PrepaidCloseMode
     statementEnabled: boolean

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

@@ -13,7 +13,7 @@ import type { EntityManager } from '@mikro-orm/postgresql'
  *     signal instead of waiting on a row.
  *   - It's released automatically when the transaction ends (commit,
  *     rollback, or process death) — so there is no lock-leak path even
- *     on `kill -9`. The `BillRun` row's `status='running'` may be left
+ *     on `kill -9`. The `BillingRun` row's `status='running'` may be left
  *     hanging, but the lock itself vanishes; the reaper worker
  *     (workers/reap-stale-bill-runs.ts) handles the orphaned row.
  *   - It works without a sentinel table — we hash a string key into the

package/src/modules/billing/workers/reap-stale-bill-runs.ts

@@ -1,7 +1,7 @@
 import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
 import type { FilterQuery } from '@mikro-orm/core'
 import type { EntityManager } from '@mikro-orm/postgresql'
-import { BillRun } from '../data/entities'
+import { BillingRun } from '../data/entities'
 
 export const metadata: WorkerMeta = {
   queue: 'billing-reap-stale-runs',
@@ -19,7 +19,7 @@ type HandlerContext = JobContext & {
  * Background — the Bill Run engine acquires a per-tenant Postgres
  * transaction-scoped advisory lock (`pg_try_advisory_xact_lock`). When the
  * holding transaction ends (commit / rollback / process death) the lock is
- * released automatically — so there is no lock leak — but the `BillRun`
+ * released automatically — so there is no lock leak — but the `BillingRun`
  * row's `status='running'` stays set forever, blocking restarts and
  * confusing the dashboard.
  *
@@ -38,10 +38,10 @@ const STALE_THRESHOLD_MS = 60 * 60 * 1000 // 1 hour
 export default async function handle(_job: QueuedJob, ctx: HandlerContext): Promise<void> {
   const em = ctx.resolve<EntityManager>('em')
   const threshold = new Date(Date.now() - STALE_THRESHOLD_MS)
-  const stale = await em.find(BillRun, {
+  const stale = await em.find(BillingRun, {
     status: 'running',
     startedAt: { $lt: threshold },
-  } satisfies FilterQuery<BillRun>)
+  } satisfies FilterQuery<BillingRun>)
   if (stale.length === 0) return
   const now = new Date()
   for (const run of stale) {