fix(billing): cache enterprise reporting-window usage sums for soft usage gates

An enterprise payer's usage is summed over its reporting window, which can be
a year long, so every soft usage check re-scanned the whole year of that
payer's ledger. Admission gates (pooled organization usage behind
checkUsageStatus, checkServerSideUsageLimits and checkAttributedUsageLimits),
the execution logger's threshold-email baseline, and the v1 API usage
envelope each ran it once per billable event or request, so a busy
enterprise organization kept the database busy re-adding the same rows.

Reporting-window sums for these soft readers now go through a per-process
LRUCache keyed by payer and window (max 1000, 30 s TTL). fetchMethod
coalesces concurrent misses into one sum, and a failed sum is evicted rather
than cached, so callers keep their existing fail-closed or fail-open handling
and the next call sums again. Stripe and default periods are unchanged and
always summed exactly, as is any read on a caller-supplied executor.

The ledger only grows within a window, so a cached sum can only under-count,
by at most the usage written in the last 30 s: an admission gate may let a
payer run up to 30 s past its limit, and never refuses one the exact sum
would admit. Threshold emails fire on an edge, where a stale baseline could
drop or repeat a crossing, so the logger uses the cached sum only when it is
at or above the limit or more than 5 points below the warning threshold, and
reads exactly in the band where emails actually fire.

getBillingPeriodUsageCost itself is unchanged, and invoicing, threshold
billing (which already skips enterprise), cycle close, analytics, settings
displays and the per-member cap keep reading the ledger exactly.

Author: waleedlatif1

apps/sim/lib/billing/calculations/usage-monitor.test.ts

@@ -105,6 +105,58 @@ describe('checkUsageStatus', () => {
     )
   })
 
+  it('shares one pooled sum across admissions in an enterprise reporting window', async () => {
+    const billingPeriod = {
+      start: new Date('2026-01-01T00:00:00.000Z'),
+      end: new Date('2027-01-01T00:00:00.000Z'),
+      source: 'reporting' as const,
+      anchorDate: '2026-01-01',
+      interval: 'year' as const,
+    }
+    const subscription = {
+      referenceId: 'org-reporting-shared',
+      plan: 'enterprise',
+      status: 'active',
+      seats: 1,
+      periodStart: billingPeriod.start,
+      periodEnd: billingPeriod.end,
+    }
+    const billingContext = {
+      billingEntity: { type: 'organization' as const, id: 'org-reporting-shared' },
+      billingPeriod,
+    }
+
+    await checkUsageStatus('user-1', subscription, billingContext)
+    await checkUsageStatus('user-2', subscription, billingContext)
+
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(1)
+  })
+
+  it('sums a Stripe-period organization pool exactly on every admission', async () => {
+    const billingPeriod = {
+      start: new Date('2026-06-01T00:00:00.000Z'),
+      end: new Date('2026-07-01T00:00:00.000Z'),
+      source: 'stripe' as const,
+    }
+    const subscription = {
+      referenceId: 'org-stripe',
+      plan: 'team',
+      status: 'active',
+      seats: 1,
+      periodStart: null,
+      periodEnd: null,
+    }
+    const billingContext = {
+      billingEntity: { type: 'organization' as const, id: 'org-stripe' },
+      billingPeriod,
+    }
+
+    await checkUsageStatus('user-1', subscription, billingContext)
+    await checkUsageStatus('user-1', subscription, billingContext)
+
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(2)
+  })
+
   it('reads paid personal ledger usage and refresh from one snapshot', async () => {
     const periodStart = new Date('2026-06-01T00:00:00.000Z')
     const periodEnd = new Date('2026-07-01T00:00:00.000Z')

apps/sim/lib/billing/calculations/usage-monitor.ts

@@ -7,6 +7,7 @@ import { isOrganizationBillingBlocked } from '@/lib/billing/core/access'
 import { defaultBillingPeriod } from '@/lib/billing/core/billing-period'
 import { getHighestPrioritySubscription } from '@/lib/billing/core/plan'
 import { resolveSubscriptionUsagePeriod } from '@/lib/billing/core/reporting-period'
+import { readSoftGateUsageCost } from '@/lib/billing/core/reporting-usage-cache'
 import { getUserUsageLimit, type UsageLimitSubscription } from '@/lib/billing/core/usage'
 import {
   type BillingContext,
@@ -44,6 +45,11 @@ interface UsageData {
   organizationId: string | null
 }
 
+/**
+ * The organization's pooled usage for an admission check. An enterprise reporting window is
+ * served through {@link readSoftGateUsageCost}; its weekly refresh is zero, so it always takes
+ * a plain-sum branch below.
+ */
 async function computePooledOrgUsage(
   organizationId: string,
   sub: UsageLimitSubscription,
@@ -58,12 +64,12 @@ async function computePooledOrgUsage(
     }
 
   if (!isPaid(sub.plan) || !sub.periodStart) {
-    return getBillingPeriodUsageCost({ type: 'organization', id: organizationId }, billingPeriod)
+    return readSoftGateUsageCost({ type: 'organization', id: organizationId }, billingPeriod)
   }
 
   const weeklyRefreshDollars = getPlanWeeklyRefreshDollars(sub.plan)
   if (weeklyRefreshDollars <= 0) {
-    return getBillingPeriodUsageCost({ type: 'organization', id: organizationId }, billingPeriod)
+    return readSoftGateUsageCost({ type: 'organization', id: organizationId }, billingPeriod)
   }
 
   const { ledgerUsage, refreshConsumed } = await computeBillingPeriodUsageWithWeeklyRefresh({

apps/sim/lib/billing/constants.ts

@@ -28,6 +28,12 @@ export const BASE_EXECUTION_CHARGE = 0.005
  */
 export const SEARCH_TOOL_COST = 0.01
 
+/**
+ * Share of a usage limit, in percent, at which a payer is sent the "nearing your limit" email.
+ * The "limit reached" email fires at 100%.
+ */
+export const USAGE_WARNING_EMAIL_PERCENT = 80
+
 /**
  * Default threshold (in dollars) for incremental overage billing
  * When unbilled overage reaches this amount, an invoice item is created

apps/sim/lib/billing/core/reporting-usage-cache.test.ts

@@ -0,0 +1,210 @@
+/**
+ * @vitest-environment node
+ */
+import { db } from '@sim/db'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetBillingPeriodUsageCost } = vi.hoisted(() => ({
+  mockGetBillingPeriodUsageCost: vi.fn(),
+}))
+
+vi.mock('@/lib/billing/core/usage-log', () => ({
+  getBillingPeriodUsageCost: mockGetBillingPeriodUsageCost,
+}))
+
+import {
+  getCachedReportingPeriodUsageCost,
+  readSoftGateUsageCost,
+  readThresholdEmailUsageBefore,
+} from '@/lib/billing/core/reporting-usage-cache'
+import type { UsageQueryPeriod } from '@/lib/billing/core/usage-log'
+
+const REPORTING: UsageQueryPeriod = {
+  start: new Date('2026-01-01T00:00:00.000Z'),
+  end: new Date('2027-01-01T00:00:00.000Z'),
+  source: 'reporting',
+}
+const NEXT_REPORTING: UsageQueryPeriod = {
+  start: new Date('2027-01-01T00:00:00.000Z'),
+  end: new Date('2028-01-01T00:00:00.000Z'),
+  source: 'reporting',
+}
+const STRIPE: UsageQueryPeriod = {
+  start: new Date('2026-09-01T00:00:00.000Z'),
+  end: new Date('2026-10-01T00:00:00.000Z'),
+  source: 'stripe',
+}
+
+let nextOrg = 0
+/** A fresh payer per test, since the cache is module state shared across tests. */
+function freshOrg() {
+  nextOrg += 1
+  return { type: 'organization' as const, id: `org-${nextOrg}` }
+}
+
+describe('getCachedReportingPeriodUsageCost', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('coalesces concurrent and repeated reads of one window into one ledger sum', async () => {
+    const org = freshOrg()
+    let resolveSum: (value: number) => void = () => {}
+    mockGetBillingPeriodUsageCost.mockReturnValueOnce(
+      new Promise<number>((resolve) => {
+        resolveSum = resolve
+      })
+    )
+
+    const concurrent = Promise.all([
+      getCachedReportingPeriodUsageCost(org, REPORTING),
+      getCachedReportingPeriodUsageCost(org, REPORTING),
+      getCachedReportingPeriodUsageCost(org, REPORTING),
+    ])
+    resolveSum(42)
+
+    await expect(concurrent).resolves.toEqual([42, 42, 42])
+    await expect(getCachedReportingPeriodUsageCost(org, REPORTING)).resolves.toBe(42)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(1)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledWith(org, REPORTING)
+  })
+
+  it('serves a zero sum from cache rather than re-reading it', async () => {
+    const org = freshOrg()
+    mockGetBillingPeriodUsageCost.mockResolvedValue(0)
+
+    await expect(getCachedReportingPeriodUsageCost(org, REPORTING)).resolves.toBe(0)
+    await expect(getCachedReportingPeriodUsageCost(org, REPORTING)).resolves.toBe(0)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps separate sums for different payers and windows', async () => {
+    const first = freshOrg()
+    const second = freshOrg()
+    mockGetBillingPeriodUsageCost
+      .mockResolvedValueOnce(1)
+      .mockResolvedValueOnce(2)
+      .mockResolvedValueOnce(3)
+      .mockResolvedValueOnce(4)
+
+    await expect(getCachedReportingPeriodUsageCost(first, REPORTING)).resolves.toBe(1)
+    await expect(getCachedReportingPeriodUsageCost(second, REPORTING)).resolves.toBe(2)
+    await expect(getCachedReportingPeriodUsageCost(first, NEXT_REPORTING)).resolves.toBe(3)
+    await expect(
+      getCachedReportingPeriodUsageCost({ type: 'user', id: first.id }, REPORTING)
+    ).resolves.toBe(4)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(4)
+  })
+
+  it('surfaces a failed sum to every waiting caller and never caches it', async () => {
+    const org = freshOrg()
+    const failure = new Error('canceling statement due to statement timeout')
+    mockGetBillingPeriodUsageCost.mockRejectedValueOnce(failure).mockResolvedValueOnce(17)
+
+    const results = await Promise.allSettled([
+      getCachedReportingPeriodUsageCost(org, REPORTING),
+      getCachedReportingPeriodUsageCost(org, REPORTING),
+    ])
+    expect(results).toEqual([
+      { status: 'rejected', reason: failure },
+      { status: 'rejected', reason: failure },
+    ])
+
+    await expect(getCachedReportingPeriodUsageCost(org, REPORTING)).resolves.toBe(17)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('readSoftGateUsageCost', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('serves reporting windows from the cache', async () => {
+    const org = freshOrg()
+    mockGetBillingPeriodUsageCost.mockResolvedValue(10)
+
+    await readSoftGateUsageCost(org, REPORTING)
+    await readSoftGateUsageCost(org, REPORTING)
+
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(1)
+  })
+
+  it.each([
+    ['stripe', STRIPE],
+    ['default', { ...STRIPE, source: 'default' as const }],
+    ['unlabelled', { start: STRIPE.start, end: STRIPE.end }],
+  ])('sums %s periods exactly on every call', async (_label, period) => {
+    const org = freshOrg()
+    mockGetBillingPeriodUsageCost.mockResolvedValue(10)
+
+    await readSoftGateUsageCost(org, period)
+    await readSoftGateUsageCost(org, period)
+
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(2)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledWith(org, period, undefined, db)
+  })
+
+  it('reads a reporting window exactly on a caller-supplied executor', async () => {
+    const org = freshOrg()
+    const executor = { transaction: vi.fn() } as unknown as typeof db
+    mockGetBillingPeriodUsageCost.mockResolvedValue(10)
+
+    await readSoftGateUsageCost(org, REPORTING, executor)
+    await readSoftGateUsageCost(org, REPORTING, executor)
+
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(2)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledWith(org, REPORTING, undefined, executor)
+  })
+})
+
+describe('readThresholdEmailUsageBefore', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('sums non-reporting periods exactly', async () => {
+    const org = freshOrg()
+    mockGetBillingPeriodUsageCost.mockResolvedValue(10)
+
+    await readThresholdEmailUsageBefore(org, STRIPE, 1000)
+    await readThresholdEmailUsageBefore(org, STRIPE, 1000)
+
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(2)
+  })
+
+  it.each([
+    ['far below the warning threshold', 100],
+    ['at the limit', 1000],
+    ['above the limit', 1500],
+  ])('serves the cached sum %s', async (_label, cachedSum) => {
+    const org = freshOrg()
+    mockGetBillingPeriodUsageCost.mockResolvedValue(cachedSum)
+
+    await expect(readThresholdEmailUsageBefore(org, REPORTING, 1000)).resolves.toBe(cachedSum)
+    await expect(readThresholdEmailUsageBefore(org, REPORTING, 1000)).resolves.toBe(cachedSum)
+
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(1)
+  })
+
+  it.each([
+    ['just below the warning band', 760],
+    ['between the thresholds', 900],
+  ])('reads exactly when the cached sum is %s', async (_label, cachedSum) => {
+    const org = freshOrg()
+    mockGetBillingPeriodUsageCost.mockResolvedValueOnce(cachedSum).mockResolvedValueOnce(801)
+
+    await expect(readThresholdEmailUsageBefore(org, REPORTING, 1000)).resolves.toBe(801)
+
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(2)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenLastCalledWith(org, REPORTING)
+  })
+
+  it('serves the cached sum when there is no limit to cross', async () => {
+    const org = freshOrg()
+    mockGetBillingPeriodUsageCost.mockResolvedValue(900)
+
+    await expect(readThresholdEmailUsageBefore(org, REPORTING, 0)).resolves.toBe(900)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(1)
+  })
+})