fix(billing): bound the cycle-close per-user sum and state the helper's scope precisely

Author: waleedlatif1

apps/sim/lib/billing/core/ledger-read.ts

@@ -3,12 +3,14 @@ import { USAGE_LEDGER_STATEMENT_TIMEOUT_MS } from '@/lib/billing/constants'
 import type { DbClient, DbTransaction } from '@/lib/db/types'
 
 /**
- * Runs one aggregate over the usage ledger in a transaction of its own, bounded by
+ * Runs one aggregate over a payer's usage ledger in a transaction of its own, bounded by
  * {@link USAGE_LEDGER_STATEMENT_TIMEOUT_MS}. `SET LOCAL` scopes the bound to that transaction,
- * so it ends with the read and never reaches the pool. Every ledger aggregate reads through
- * here: a payer whose period has grown past what one statement can sum within the bound fails
- * at the database instead of holding a connection without limit, and a caller that admits on
- * the answer can size its own deadline from the bound.
+ * so it ends with the read and never reaches the pool. Every sum over a payer's billing period
+ * reads through here, whether it admits a run, closes a cycle or previews a bill: a payer whose
+ * period has grown past what one statement can sum within the bound fails at the database
+ * instead of holding a connection without limit, and a caller that admits on the answer can
+ * size its own deadline from the bound. Reads keyed to one execution or one stamped period
+ * boundary, and the platform-wide admin analytics, are not period sums and read directly.
  */
 export function readLedgerBounded<T>(
   executor: DbClient,

apps/sim/lib/billing/core/usage-log.test.ts

@@ -41,6 +41,7 @@ import {
   getBillingPeriodUsageCostByUser,
   getBillingPeriodUsageCostWithSourceSubset,
   getBillingPeriodWorkflowRunCount,
+  getStampedPeriodRangeUsageCostByUser,
   getUserUsageLogs,
   getWorkspaceUsageLogs,
   recordCumulativeUsage,
@@ -598,6 +599,16 @@ describe('ledger aggregates', () => {
       rows: [{ userId: 'user-1', cost: '3' }],
       expected: new Map([['user-1', 3]]),
     },
+    {
+      name: 'getStampedPeriodRangeUsageCostByUser',
+      read: () =>
+        getStampedPeriodRangeUsageCostByUser(billingEntity, {
+          from: billingPeriod.start,
+          to: billingPeriod.end,
+        }),
+      rows: [{ userId: 'user-2', cost: '4' }],
+      expected: new Map([['user-2', 4]]),
+    },
   ]
 
   beforeEach(() => {

apps/sim/lib/billing/core/usage-log.ts

@@ -417,14 +417,16 @@ export async function getStampedPeriodRangeUsageCostByUser(
     )
   }
 
-  const rows = await executor
-    .select({
-      userId: usageLog.userId,
-      cost: sql<string>`COALESCE(SUM(${usageLog.cost}), 0)`,
-    })
-    .from(usageLog)
-    .where(and(...conditions))
-    .groupBy(usageLog.userId)
+  const rows = await readLedgerBounded(executor, (tx) =>
+    tx
+      .select({
+        userId: usageLog.userId,
+        cost: sql<string>`COALESCE(SUM(${usageLog.cost}), 0)`,
+      })
+      .from(usageLog)
+      .where(and(...conditions))
+      .groupBy(usageLog.userId)
+  )
 
   return new Map(rows.map((row) => [row.userId, Number.parseFloat(row.cost ?? '0')]))
 }