@dainamite/billing 0.17.0 → 0.18.0

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

@@ -0,0 +1,258 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  BillingAccountBalance,
+  BillingAccountTransaction,
+} from '../data/entities'
+import type { TransactionType } from '../data/validators'
+import { fromUnits, subMoney, toUnits } from './money'
+
+/**
+ * Prepaid balance ledger (SPEC-002).
+ *
+ * Two append-only primitives back every balance change:
+ *   - `BillingAccountBalance` — the O(1) running-balance cache, one row per
+ *     prepaid account; the row the atomic `UPDATE … RETURNING` locks.
+ *   - `BillingAccountTransaction` — the source of truth; `balance == SUM(amount)`.
+ *
+ * Concurrency correctness: the single-statement `UPDATE … RETURNING`
+ * serializes via the Postgres row lock on the balance row, so N concurrent
+ * uploads apply N debits with no lost update and each gets a distinct
+ * `balance_after`. The transaction insert in the SAME DB transaction carries
+ * that exact snapshot.
+ *
+ * **All functions here MUST be called inside an `em.transactional(...)`** so
+ * the balance move and the transaction insert commit (or roll back) together.
+ */
+
+// Sentinel `rated_in_bill_run_id` stamped on a usage record the moment it is
+// rated in real time, so a postpaid-style Bill Run never re-rates it. It is a
+// fixed, recognizable UUID (not a real run id) — its presence simply means
+// "already rated at ingest, paired with a BillingAccountTransaction".
+export const PREPAID_USAGE_SENTINEL_RUN_ID = 'dddddddd-dddd-4ddd-8ddd-dddddddddddd'
+
+export type BalanceRowInit = {
+  organizationId: string
+  tenantId: string
+  billAccountId: string
+  currencyCode: string
+  lowBalanceThreshold?: string | null
+}
+
+/**
+ * Find-or-create the 1:1 balance row for an account. Idempotent — safe to
+ * call on every prepaid account create. Uses the ORM (this runs at account
+ * create, not on the hot consume path).
+ */
+export async function ensureBalanceRow(
+  em: EntityManager,
+  init: BalanceRowInit,
+): Promise<BillingAccountBalance> {
+  const existing = await em.findOne(BillingAccountBalance, {
+    tenantId: init.tenantId,
+    billAccountId: init.billAccountId,
+  })
+  if (existing) {
+    // Allow create-time threshold to land even if a prior (defensive) row
+    // already exists with no threshold set.
+    if (
+      init.lowBalanceThreshold !== undefined &&
+      init.lowBalanceThreshold !== null &&
+      (existing.lowBalanceThreshold === null || existing.lowBalanceThreshold === undefined)
+    ) {
+      existing.lowBalanceThreshold = init.lowBalanceThreshold
+      existing.updatedAt = new Date()
+    }
+    return existing
+  }
+  const now = new Date()
+  const row = em.create(BillingAccountBalance, {
+    organizationId: init.organizationId,
+    tenantId: init.tenantId,
+    billAccountId: init.billAccountId,
+    currencyCode: init.currencyCode,
+    balance: '0',
+    lowBalanceThreshold: init.lowBalanceThreshold ?? null,
+    lastMovementAt: null,
+    createdAt: now,
+    updatedAt: now,
+  })
+  em.persist(row)
+  await em.flush()
+  return row
+}
+
+export type ApplyMovementParams = {
+  organizationId: string
+  tenantId: string
+  billAccountId: string
+  currencyCode: string
+  /** Transaction type. */
+  type: TransactionType
+  /** SIGNED amount: > 0 credit, < 0 debit. */
+  amount: string
+  description: string
+  usageId?: string | null
+  billingItemId?: string | null
+  topupId?: string | null
+  statementId?: string | null
+  /** Idempotency key — when set, a duplicate is a no-op (returns the prior row). */
+  sourceRef?: string | null
+  metadata?: Record<string, unknown> | null
+  userId?: string | null
+}
+
+export type ApplyMovementResult = {
+  /** Running balance BEFORE this movement (4dp string). */
+  balanceBefore: string
+  /** Running balance AFTER this movement — authoritative (4dp string). */
+  balanceAfter: string
+  transaction: BillingAccountTransaction
+  /** True when `sourceRef` already existed — no balance was moved. */
+  deduplicated: boolean
+}
+
+/**
+ * Atomically move the balance and append the paired transaction.
+ *
+ * Idempotent on `sourceRef`: if a transaction with the same
+ * `(tenant_id, bill_account_id, source_ref)` already exists, NO balance move
+ * happens and the existing row is returned (`deduplicated: true`). The unique
+ * constraint is the correctness backstop if a race slips past the pre-check —
+ * the duplicate insert fails and rolls back the whole (caller's) transaction,
+ * so the balance move is undone too. Never double-moves.
+ */
+export async function applyBalanceMovement(
+  em: EntityManager,
+  params: ApplyMovementParams,
+): Promise<ApplyMovementResult> {
+  if (params.sourceRef) {
+    const existing = await em.findOne(BillingAccountTransaction, {
+      tenantId: params.tenantId,
+      billAccountId: params.billAccountId,
+      sourceRef: params.sourceRef,
+      deletedAt: null,
+    })
+    if (existing) {
+      return {
+        balanceBefore: subMoney(existing.balanceAfter, existing.amount),
+        balanceAfter: existing.balanceAfter,
+        transaction: existing,
+        deduplicated: true,
+      }
+    }
+  }
+
+  const now = new Date()
+  // Self-healing: ensure the balance row exists (race-safe via the unique
+  // constraint), then the atomic single-statement move. `amount` is signed
+  // so one statement covers both credit and debit.
+  await em.execute(
+    `INSERT INTO billing_account_balances
+       (id, organization_id, tenant_id, bill_account_id, currency_code, balance, created_at, updated_at)
+     VALUES (gen_random_uuid(), ?, ?, ?, ?, 0, ?, ?)
+     ON CONFLICT (tenant_id, bill_account_id) DO NOTHING`,
+    [
+      params.organizationId,
+      params.tenantId,
+      params.billAccountId,
+      params.currencyCode,
+      now,
+      now,
+    ],
+  )
+  const rows = (await em.execute(
+    `UPDATE billing_account_balances
+        SET balance = balance + ?, last_movement_at = ?, updated_at = ?
+      WHERE tenant_id = ? AND bill_account_id = ?
+      RETURNING balance`,
+    [params.amount, now, now, params.tenantId, params.billAccountId],
+  )) as unknown as Array<{ balance: string }>
+
+  if (!rows || rows.length === 0) {
+    // Should be unreachable — the upsert above guarantees a row exists.
+    throw new Error(
+      `balanceLedger: balance row missing for account ${params.billAccountId} after upsert`,
+    )
+  }
+  // Normalize whatever the driver hands back (string or number) to 4dp.
+  const balanceAfter = fromUnits(toUnits(rows[0].balance))
+  const balanceBefore = subMoney(balanceAfter, params.amount)
+
+  const transaction = em.create(BillingAccountTransaction, {
+    organizationId: params.organizationId,
+    tenantId: params.tenantId,
+    billAccountId: params.billAccountId,
+    type: params.type,
+    amount: params.amount,
+    currencyCode: params.currencyCode,
+    balanceAfter,
+    usageId: params.usageId ?? null,
+    billingItemId: params.billingItemId ?? null,
+    topupId: params.topupId ?? null,
+    statementId: params.statementId ?? null,
+    description: params.description,
+    sourceRef: params.sourceRef ?? null,
+    metadata: params.metadata ?? null,
+    userId: params.userId ?? null,
+    createdAt: now,
+  })
+  em.persist(transaction)
+  await em.flush()
+
+  return { balanceBefore, balanceAfter, transaction, deduplicated: false }
+}
+
+export type ReconcileResult = {
+  /** The denormalized running balance (cache). */
+  cachedBalance: string
+  /** SUM(amount) over all (non-deleted) transactions. */
+  sumOfAmounts: string
+  /** The most recent transaction's balance_after, or '0.0000' if none. */
+  latestBalanceAfter: string
+  /** True when all three agree. */
+  reconciled: boolean
+}
+
+/**
+ * Assert the ledger invariant for one account:
+ * `cachedBalance == SUM(amount) == latest.balance_after`.
+ *
+ * The optional reconciliation worker (P5) runs this per account and alerts on
+ * drift — a cheap guard against any future non-atomic write slipping in.
+ */
+export async function reconcileAccountBalance(
+  em: EntityManager,
+  scope: { tenantId: string; organizationId: string; billAccountId: string },
+): Promise<ReconcileResult> {
+  const balanceRow = await em.findOne(BillingAccountBalance, {
+    tenantId: scope.tenantId,
+    billAccountId: scope.billAccountId,
+  })
+  const cachedBalance = balanceRow ? fromUnits(toUnits(balanceRow.balance)) : '0.0000'
+
+  const sumRows = (await em.execute(
+    `SELECT COALESCE(SUM(amount), 0) AS sum_amount
+       FROM billing_account_transactions
+      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND deleted_at IS NULL`,
+    [scope.tenantId, scope.organizationId, scope.billAccountId],
+  )) as unknown as Array<{ sum_amount: string }>
+  const sumOfAmounts = fromUnits(toUnits(sumRows?.[0]?.sum_amount ?? 0))
+
+  const latest = await em.findOne(
+    BillingAccountTransaction,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      billAccountId: scope.billAccountId,
+      deletedAt: null,
+    },
+    { orderBy: { createdAt: 'DESC' } },
+  )
+  const latestBalanceAfter = latest ? fromUnits(toUnits(latest.balanceAfter)) : '0.0000'
+
+  const reconciled =
+    toUnits(cachedBalance) === toUnits(sumOfAmounts) &&
+    (latest === null || toUnits(cachedBalance) === toUnits(latestBalanceAfter))
+
+  return { cachedBalance, sumOfAmounts, latestBalanceAfter, reconciled }
+}

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

@@ -0,0 +1,78 @@
+import type { BalanceStatus } from '../data/validators'
+import { compareMoney, toUnits } from './money'
+
+/**
+ * Prepaid funds status & threshold-crossing detection (SPEC-002).
+ *
+ * Usage is NEVER rejected — we only classify and report. Events fire ONLY on
+ * a downward crossing (compare `balance_before` vs `balance_after`), so a
+ * client sitting at `exhausted` and still pushing usage is not spammed.
+ */
+
+/**
+ * Resolve the effective low-balance threshold:
+ *   account row's own threshold → tenant config default → 0 (off).
+ */
+export function resolveLowBalanceThreshold(
+  accountThreshold: string | null | undefined,
+  configDefault: string | number | null | undefined,
+): string {
+  if (accountThreshold !== null && accountThreshold !== undefined) {
+    return accountThreshold
+  }
+  if (configDefault !== null && configDefault !== undefined) {
+    return String(configDefault)
+  }
+  return '0'
+}
+
+/**
+ * | status     | condition                          |
+ * |------------|------------------------------------|
+ * | exhausted  | balance <= 0 (incl. negative)      |
+ * | low        | 0 < balance <= threshold           |
+ * | ok         | balance > threshold                |
+ */
+export function computeBalanceStatus(
+  balance: string | number,
+  threshold: string | number,
+): BalanceStatus {
+  if (compareMoney(balance, 0) <= 0) return 'exhausted'
+  if (compareMoney(balance, threshold) <= 0) return 'low'
+  return 'ok'
+}
+
+export type BalanceCrossing = {
+  /** Crossed downward from > threshold into the (0, threshold] low band. */
+  lowCrossedDown: boolean
+  /** Crossed downward from > 0 to <= 0. */
+  exhaustedCrossedDown: boolean
+}
+
+/**
+ * Detect downward threshold crossings between two balances.
+ *
+ * A single large debit that jumps straight past the low band into exhausted
+ * fires ONLY `exhausted` (the customer is already negative — "you're low" is
+ * moot). `low` fires only when the balance lands in the (0, threshold] band.
+ * When `threshold <= 0` the low band is empty, so `low` never fires (the
+ * config default 0 = "off"); `exhausted` still works.
+ */
+export function detectBalanceCrossing(
+  balanceBefore: string | number,
+  balanceAfter: string | number,
+  threshold: string | number,
+): BalanceCrossing {
+  const beforeUnits = toUnits(balanceBefore)
+  const afterUnits = toUnits(balanceAfter)
+  const thresholdUnits = toUnits(threshold)
+
+  const exhaustedCrossedDown = beforeUnits > 0 && afterUnits <= 0
+  const lowCrossedDown =
+    thresholdUnits > 0 &&
+    beforeUnits > thresholdUnits &&
+    afterUnits <= thresholdUnits &&
+    afterUnits > 0
+
+  return { lowCrossedDown, exhaustedCrossedDown }
+}

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

@@ -20,6 +20,9 @@ import {
 } from './invoiceWriter'
 import { withTenantLock } from './tenantLock'
 import { processUsageForAccount } from './usageRunner'
+import { processPrepaidAccount } from './prepaidPeriodClose'
+import type { DomainEvent } from './balanceEvents'
+import { emitBillingEvent, type BillingEventId } from '../events'
 import type { BillCycle } from '../data/validators'
 
 /**
@@ -73,15 +76,27 @@ export type RunBillRunResult = {
   outcomes: BillRunOutcome[]
 }
 
+type RunOutput = RunBillRunResult & {
+  /** Prepaid statement / crossing events to emit AFTER the outer tx commits. */
+  pendingEvents: DomainEvent[]
+}
+
 type AccountWarnings = {
   currency_mismatch_items?: string[]
   unmatched_usage_uoms?: string[]
 }
 
 type AccountProcessSuccess = {
-  status: 'success' | 'success_with_warnings' | 'skipped_existing_draft'
-  warnings: AccountWarnings | null
+  status:
+    | 'success'
+    | 'success_with_warnings'
+    | 'skipped_existing_draft'
+    | 'skipped_existing_statement'
+  warnings: AccountWarnings | Record<string, unknown> | null
   draftInvoiceId: string | null
+  // SPEC-002: prepaid accounts produce a statement instead of a draft invoice.
+  statementId?: string | null
+  statementEvents?: DomainEvent[]
   cyclesEmitted: number
   usageRecordsRated: number
 }
@@ -101,18 +116,25 @@ export async function runBillRun(
   container: AwilixContainer,
   params: RunBillRunParams,
 ): Promise<RunBillRunResult> {
-  return withTenantLock(
+  const output = await withTenantLock(
     em,
     { tenantId: params.tenantId, lockName: 'billing-run' },
     async (tem) => executeRunWithinLock(tem, container, params),
   )
+  // Emit prepaid statement / crossing events ONLY after the outer transaction
+  // (held by withTenantLock) has committed — emitting inside the lock would let
+  // a consumer observe an uncommitted statement or a phantom event on rollback.
+  for (const ev of output.pendingEvents) {
+    await emitBillingEvent(ev.id as BillingEventId, ev.payload, { persistent: true })
+  }
+  return { billRun: output.billRun, outcomes: output.outcomes }
 }
 
 async function executeRunWithinLock(
   em: EntityManager,
   container: AwilixContainer,
   params: RunBillRunParams,
-): Promise<RunBillRunResult> {
+): Promise<RunOutput> {
   const now = new Date()
   const billRun = em.create(BillRun, {
     organizationId: params.organizationId,
@@ -136,6 +158,7 @@ async function executeRunWithinLock(
 
   const accounts = await selectTargetAccounts(em, params)
   const outcomes: BillRunOutcome[] = []
+  const pendingEvents: DomainEvent[] = []
   let totalUsageRecordsRated = 0
 
   for (const account of accounts) {
@@ -155,6 +178,7 @@ async function executeRunWithinLock(
           ? null
           : (processResult.warnings as Record<string, unknown> | null),
       draftInvoiceId: processResult.status === 'failed' ? null : processResult.draftInvoiceId,
+      statementId: processResult.status === 'failed' ? null : (processResult.statementId ?? null),
       isActive: true,
       createdAt: new Date(),
       updatedAt: new Date(),
@@ -162,6 +186,12 @@ async function executeRunWithinLock(
     em.persist(outcome)
     await em.flush()
     outcomes.push(outcome)
+
+    // Collect statement / crossing events — runBillRun emits them AFTER the
+    // outer tx commits (see runBillRun), never from inside the lock.
+    if (processResult.status !== 'failed' && processResult.statementEvents) {
+      pendingEvents.push(...processResult.statementEvents)
+    }
   }
 
   billRun.status = computeFinalRunStatus(outcomes)
@@ -170,7 +200,7 @@ async function executeRunWithinLock(
   billRun.summary = buildRunSummary(outcomes, accounts.length, totalUsageRecordsRated)
   await em.flush()
 
-  return { billRun, outcomes }
+  return { billRun, outcomes, pendingEvents }
 }
 
 async function selectTargetAccounts(
@@ -215,6 +245,30 @@ async function processAccount(
   account: BillingAccount,
   params: RunBillRunParams,
 ): Promise<AccountProcessResult> {
+  // SPEC-002: a prepaid account never gets a payable draft invoice. It still
+  // runs in the Bill Run, but charges recurring / one_time items to the
+  // balance and produces a non-fiscal consumption statement.
+  if (account.billingMode === 'prepaid') {
+    const result = await processPrepaidAccount(em, account, billRun, {
+      asOfDate: params.asOfDate,
+      mode: params.mode,
+      triggeredBy: params.triggeredBy,
+      catchUp: params.catchUp,
+    })
+    if (result.status === 'failed') {
+      return { status: 'failed', errorMessage: result.errorMessage }
+    }
+    return {
+      status: result.status,
+      warnings: result.warnings,
+      draftInvoiceId: null,
+      statementId: result.statementId,
+      statementEvents: result.statementEvents,
+      cyclesEmitted: result.cyclesEmitted,
+      usageRecordsRated: 0,
+    }
+  }
+
   const maxCycles =
     params.triggeredBy === 'schedule' || !params.catchUp
       ? SCHEDULED_CYCLE_LIMIT
@@ -408,6 +462,13 @@ function buildRunSummary(
     ).length,
     drafts_skipped_existing: outcomes.filter((o) => o.status === 'skipped_existing_draft')
       .length,
+    // SPEC-002 prepaid period close.
+    statements_created: outcomes.filter(
+      (o) => o.statementId !== null && o.status !== 'skipped_existing_statement',
+    ).length,
+    statements_skipped_existing: outcomes.filter(
+      (o) => o.status === 'skipped_existing_statement',
+    ).length,
     accounts_failed: outcomes.filter((o) => o.status === 'failed').length,
     accounts_with_warnings: outcomes.filter((o) => o.status === 'success_with_warnings')
       .length,

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

@@ -0,0 +1,153 @@
+import type { BillingMode, CreditStatus } from '../data/validators'
+import { compareMoney, fromUnits, subMoney, toUnits } from './money'
+
+/**
+ * Credit-line status (both modes, SPEC-002). Billing **computes and reports**
+ * where an account stands against its `credit_limit` — it NEVER blocks
+ * (assumption #11). A consumer (CPQ order conversion, a dunning job, an
+ * operator) decides what to do with an over-limit signal.
+ *
+ * `credit_used` per mode:
+ *   - prepaid:  max(0, −balance) — the portion of the balance gone negative
+ *     (drawing on the credit line).
+ *   - postpaid: Σ outstanding (posted, not-yet-paid) invoice `outstanding`
+ *     amounts from core/sales.
+ *
+ * `available_credit = credit_limit − credit_used` (unified across both modes;
+ * for prepaid this equals `balance + credit_limit` when balance < 0, else
+ * `credit_limit`).
+ */
+
+/** Prepaid credit drawn = max(0, −balance). */
+export function prepaidCreditUsed(balance: string | number): string {
+  if (compareMoney(balance, 0) >= 0) return '0.0000'
+  return fromUnits(-toUnits(balance))
+}
+
+export function computeCreditUsed(
+  mode: BillingMode,
+  opts: { balance?: string | number | null; outstanding?: string | number | null },
+): string {
+  if (mode === 'prepaid') {
+    return prepaidCreditUsed(opts.balance ?? '0')
+  }
+  // postpaid
+  return fromUnits(toUnits(opts.outstanding ?? '0'))
+}
+
+export function computeAvailableCredit(
+  creditLimit: string | number,
+  creditUsed: string | number,
+): string {
+  return subMoney(creditLimit, creditUsed)
+}
+
+/**
+ * | status        | condition                                  |
+ * |---------------|--------------------------------------------|
+ * | within_limit  | available_credit > near_limit_buffer       |
+ * | near_limit    | 0 < available_credit <= near_limit_buffer  |
+ * | over_limit    | available_credit <= 0 (and credit is drawn)|
+ *
+ * `creditUsed` disambiguates the default "no credit line" case: with
+ * `credit_limit = 0` and nothing drawn (`credit_used = 0`) the available
+ * credit is exactly 0 — that is NOT over-limit (the account simply has no
+ * credit line), so it reports `within_limit`. Once any credit is actually
+ * drawn (prepaid balance negative, or postpaid outstanding > 0) the formula
+ * applies. When `creditUsed` is omitted, a draw is assumed (pure spec
+ * formula) — callers that have the figure should pass it.
+ */
+export function computeCreditStatus(
+  availableCredit: string | number,
+  nearLimitBuffer: string | number,
+  creditUsed?: string | number,
+): CreditStatus {
+  const hasDraw = creditUsed === undefined ? true : compareMoney(creditUsed, 0) > 0
+  if (compareMoney(availableCredit, 0) <= 0) {
+    return hasDraw ? 'over_limit' : 'within_limit'
+  }
+  if (compareMoney(availableCredit, nearLimitBuffer) <= 0) return 'near_limit'
+  return 'within_limit'
+}
+
+export function resolveNearLimitBuffer(
+  configDefault: string | number | null | undefined,
+): string {
+  if (configDefault !== null && configDefault !== undefined) return String(configDefault)
+  return '0'
+}
+
+export type CreditSnapshot = {
+  mode: BillingMode
+  creditLimit: string
+  creditUsed: string
+  availableCredit: string
+  creditStatus: CreditStatus
+}
+
+/** Assemble the full credit snapshot reported on consume responses + the API. */
+export function computeCreditSnapshot(params: {
+  mode: BillingMode
+  creditLimit: string | number
+  nearLimitBuffer: string | number
+  balance?: string | number | null
+  outstanding?: string | number | null
+}): CreditSnapshot {
+  const creditLimit = fromUnits(toUnits(params.creditLimit))
+  const creditUsed = computeCreditUsed(params.mode, {
+    balance: params.balance,
+    outstanding: params.outstanding,
+  })
+  const availableCredit = computeAvailableCredit(creditLimit, creditUsed)
+  return {
+    mode: params.mode,
+    creditLimit,
+    creditUsed,
+    availableCredit,
+    creditStatus: computeCreditStatus(availableCredit, params.nearLimitBuffer, creditUsed),
+  }
+}
+
+export type CreditCrossing = {
+  /** credit_used crossed upward past credit_limit (available ≤ 0). */
+  overLimitCrossedUp: boolean
+  /** available_credit crossed downward into (0, buffer] (optional event). */
+  nearLimitCrossedUp: boolean
+}
+
+/**
+ * Detect upward crossings of `credit_used` (i.e. downward crossings of
+ * `available_credit`) for the `billing.credit.over_limit` /
+ * `billing.credit.near_limit` events. `over_limit` fires once when usage /
+ * recurring pushes credit_used from below the limit to at/above it.
+ *
+ * `credit_limit == 0` (no credit) means available is never > 0 once any
+ * credit is "used"; to avoid firing on every prepaid debit while at 0 balance
+ * with no credit line, the crossing requires a real limit (> 0).
+ */
+export function detectCreditCrossing(params: {
+  creditLimit: string | number
+  nearLimitBuffer: string | number
+  usedBefore: string | number
+  usedAfter: string | number
+}): CreditCrossing {
+  const limitUnits = toUnits(params.creditLimit)
+  if (limitUnits <= 0) {
+    return { overLimitCrossedUp: false, nearLimitCrossedUp: false }
+  }
+  const usedBefore = toUnits(params.usedBefore)
+  const usedAfter = toUnits(params.usedAfter)
+  const bufferUnits = toUnits(params.nearLimitBuffer)
+
+  const overLimitCrossedUp = usedBefore < limitUnits && usedAfter >= limitUnits
+
+  const availBefore = limitUnits - usedBefore
+  const availAfter = limitUnits - usedAfter
+  const nearLimitCrossedUp =
+    bufferUnits > 0 &&
+    availBefore > bufferUnits &&
+    availAfter <= bufferUnits &&
+    availAfter > 0
+
+  return { overLimitCrossedUp, nearLimitCrossedUp }
+}