fix(billing): keep threshold-email usage reads exact and cover cache expiry

A usage email fires on an edge, and a cache TTL bounds how long a sum is stale, not how much usage it omits, so no cached baseline can safely decide a crossing. The execution logger's threshold-email pre-read goes back to the exact sum; the cache now serves only admission gates and the v1 usage report, where an under-count is the safe direction. Adds a test that a cached sum is re-read once it outlives its TTL.

Author: waleedlatif1

apps/sim/lib/billing/constants.ts

@@ -28,12 +28,6 @@ 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

@@ -2,7 +2,8 @@
  * @vitest-environment node
  */
 import { db } from '@sim/db'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { sleep } from '@sim/utils/helpers'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 const { mockGetBillingPeriodUsageCost } = vi.hoisted(() => ({
   mockGetBillingPeriodUsageCost: vi.fn(),
@@ -14,8 +15,8 @@ vi.mock('@/lib/billing/core/usage-log', () => ({
 
 import {
   getCachedReportingPeriodUsageCost,
+  REPORTING_USAGE_CACHE_TTL_MS,
   readSoftGateUsageCost,
-  readThresholdEmailUsageBefore,
 } from '@/lib/billing/core/reporting-usage-cache'
 import type { UsageQueryPeriod } from '@/lib/billing/core/usage-log'
 
@@ -45,6 +46,28 @@ function freshOrg() {
 describe('getCachedReportingPeriodUsageCost', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    mockGetBillingPeriodUsageCost.mockReset()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('sums the ledger again once a cached sum outlives its TTL', async () => {
+    const org = freshOrg()
+    const start = performance.now()
+    const clock = vi.spyOn(performance, 'now').mockReturnValue(start)
+    mockGetBillingPeriodUsageCost.mockResolvedValueOnce(10).mockResolvedValueOnce(25)
+
+    await expect(getCachedReportingPeriodUsageCost(org, REPORTING)).resolves.toBe(10)
+    /** The cache re-reads its clock only after `ttlResolution` (1 ms) of real time. */
+    clock.mockReturnValue(start + REPORTING_USAGE_CACHE_TTL_MS - 1)
+    await sleep(2)
+    await expect(getCachedReportingPeriodUsageCost(org, REPORTING)).resolves.toBe(10)
+    clock.mockReturnValue(start + REPORTING_USAGE_CACHE_TTL_MS + 1)
+    await sleep(2)
+    await expect(getCachedReportingPeriodUsageCost(org, REPORTING)).resolves.toBe(25)
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledTimes(2)
   })
 
   it('coalesces concurrent and repeated reads of one window into one ledger sum', async () => {
@@ -118,6 +141,7 @@ describe('getCachedReportingPeriodUsageCost', () => {
 describe('readSoftGateUsageCost', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    mockGetBillingPeriodUsageCost.mockReset()
   })
 
   it('serves reporting windows from the cache', async () => {
@@ -157,54 +181,3 @@ describe('readSoftGateUsageCost', () => {
     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)
-  })
-})

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

@@ -1,6 +1,5 @@
 import { db } from '@sim/db'
 import { LRUCache } from 'lru-cache'
-import { USAGE_WARNING_EMAIL_PERCENT } from '@/lib/billing/constants'
 import {
   type BillingEntity,
   getBillingPeriodUsageCost,
@@ -81,43 +80,3 @@ export function readSoftGateUsageCost(
   }
   return getBillingPeriodUsageCost(entity, period, undefined, executor)
 }
-
-/**
- * How far below the warning threshold, in percent of the limit, a cached sum must sit before it
- * is trusted for threshold emails.
- */
-const THRESHOLD_EMAIL_EXACT_BAND_PERCENT = 5
-
-/**
- * The payer's usage before this boundary's increment, for deciding whether it crossed a usage
- * email threshold.
- *
- * The email fires on an edge — before below a threshold, after at or above it — so an
- * under-counted "before" can drop a crossing or repeat one; unlike an admission gate, a stale sum
- * is not harmless here. A cached reporting-window sum is used only where it cannot move that
- * decision: with no positive limit, where no email is sent; at or above the limit, where the true
- * sum is too and neither threshold can be crossed; or more than
- * {@link THRESHOLD_EMAIL_EXACT_BAND_PERCENT} points of the limit below the warning threshold,
- * where only that much usage inside one TTL window could hide a crossing. In between, where the
- * emails actually fire, the sum is read exactly.
- */
-export async function readThresholdEmailUsageBefore(
-  entity: BillingEntity,
-  period: UsageQueryPeriod,
-  limit: number
-): Promise<number> {
-  if (period.source !== 'reporting') {
-    return getBillingPeriodUsageCost(entity, period)
-  }
-
-  const cached = await getCachedReportingPeriodUsageCost(entity, period)
-  if (limit <= 0) return cached
-  const percent = (cached / limit) * 100
-  if (
-    percent >= 100 ||
-    percent < USAGE_WARNING_EMAIL_PERCENT - THRESHOLD_EMAIL_EXACT_BAND_PERCENT
-  ) {
-    return cached
-  }
-  return getBillingPeriodUsageCost(entity, period)
-}

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

@@ -4,7 +4,6 @@ import { createLogger } from '@sim/logger'
 import { isOrgAdminRole } from '@sim/platform-authz/workspace'
 import { generateId } from '@sim/utils/id'
 import { and, eq, isNull, sql } from 'drizzle-orm'
-import { USAGE_WARNING_EMAIL_PERCENT } from '@/lib/billing/constants'
 import { getEffectiveBillingStatus } from '@/lib/billing/core/access'
 import { defaultBillingPeriod } from '@/lib/billing/core/billing-period'
 import {
@@ -728,9 +727,7 @@ export async function maybeSendUsageThresholdEmail(params: {
         : `${baseUrl}/account/settings/billing`
 
     // Check for 80% threshold crossing — used for paid users (budget warning) and free users (upgrade nudge)
-    const crosses80 =
-      params.percentBefore < USAGE_WARNING_EMAIL_PERCENT &&
-      params.percentAfter >= USAGE_WARNING_EMAIL_PERCENT
+    const crosses80 = params.percentBefore < 80 && params.percentAfter >= 80
     // Check for 100% threshold — every plan and scope (usage limit reached)
     const crosses100 = params.percentBefore < 100 && params.percentAfter >= 100
 

apps/sim/lib/logs/execution/logger.test.ts

@@ -6,9 +6,7 @@ import {
   resetDbChainMock,
 } from '@sim/testing'
 import { isPlainRecord } from '@sim/utils/object'
-import { afterAll, beforeEach, describe, expect, onTestFinished, test, vi } from 'vitest'
-import { readThresholdEmailUsageBefore } from '@/lib/billing/core/reporting-usage-cache'
-import { maybeSendUsageThresholdEmail } from '@/lib/billing/core/usage'
+import { afterAll, beforeEach, describe, expect, test, vi } from 'vitest'
 import { recordUsage } from '@/lib/billing/core/usage-log'
 import { ExecutionLogger } from '@/lib/logs/execution/logger'
 import { SECRET_PROJECTION_VERSION } from '@/lib/logs/execution/trace-store'
@@ -68,7 +66,6 @@ vi.mock('@/lib/billing/core/billing-attribution', () => ({
     billingPeriod: {
       start: new Date(attribution.billingPeriod.start),
       end: new Date(attribution.billingPeriod.end),
-      ...(attribution.billingPeriod.source ? { source: attribution.billingPeriod.source } : {}),
     },
   })),
 }))
@@ -92,10 +89,6 @@ vi.mock('@/lib/billing/core/usage', () => ({
   maybeSendUsageThresholdEmail: vi.fn(() => Promise.resolve()),
 }))
 
-vi.mock('@/lib/billing/core/reporting-usage-cache', () => ({
-  readThresholdEmailUsageBefore: vi.fn(() => Promise.resolve(250)),
-}))
-
 vi.mock('@/lib/billing/core/usage-log', () => ({
   recordUsage: vi.fn(() => Promise.resolve()),
   stableEventKey: vi.fn((parts: Record<string, unknown>) => JSON.stringify(parts)),
@@ -393,99 +386,6 @@ describe('ExecutionLogger', () => {
       expect(written?.resolvedSecretTraceProvenance).toEqual(RUN_PROVENANCE)
     })
 
-    test('reads the threshold-email baseline through the soft reporting-window reader', async () => {
-      const startedAt = new Date('2026-08-11T00:00:00.000Z')
-      queueTableRows(workflowExecutionLogs, [
-        {
-          id: 'log-1',
-          workflowId: 'workflow-1',
-          workspaceId: 'workspace-1',
-          executionId: 'execution-1',
-          stateSnapshotId: 'snapshot-1',
-          level: 'info',
-          status: 'running',
-          trigger: 'api',
-          startedAt,
-          endedAt: null,
-          totalDurationMs: null,
-          executionData: {},
-          createdAt: startedAt,
-        },
-      ])
-      dbChainMockFns.returning.mockResolvedValue([
-        { id: 'log-1', executionData: {}, startedAt, createdAt: startedAt },
-      ])
-      onTestFinished(resetDbChainMock)
-      const internals = logger as unknown as {
-        applyPiiRedaction: (workspaceId: string, payload: unknown) => unknown
-        recordExecutionUsage: () => Promise<number>
-      }
-      vi.spyOn(internals, 'applyPiiRedaction').mockImplementation(
-        async (_workspaceId: string, payload: unknown) => payload
-      )
-      vi.spyOn(internals, 'recordExecutionUsage').mockResolvedValue(10)
-
-      await logger.completeWorkflowExecution({
-        executionId: 'execution-1',
-        endedAt: '2026-08-11T00:00:02.000Z',
-        totalDurationMs: 2000,
-        costSummary: {
-          totalCost: 0,
-          totalInputCost: 0,
-          totalOutputCost: 0,
-          totalTokens: 0,
-          totalPromptTokens: 0,
-          totalCompletionTokens: 0,
-          baseExecutionCharge: 0,
-          models: {},
-        },
-        finalOutput: {},
-        traceSpans: [],
-        billingAttribution: {
-          actorUserId: 'actor-1',
-          workspaceId: 'workspace-1',
-          organizationId: 'org-enterprise',
-          billedAccountUserId: 'owner-1',
-          billingEntity: { type: 'organization', id: 'org-enterprise' },
-          billingPeriod: {
-            start: '2026-01-01T00:00:00.000Z',
-            end: '2027-01-01T00:00:00.000Z',
-            source: 'reporting',
-          },
-          payerSubscription: {
-            id: 'sub-1',
-            plan: 'enterprise',
-            status: 'active',
-            seats: 10,
-            periodStart: '2026-01-01T00:00:00.000Z',
-            periodEnd: '2027-01-01T00:00:00.000Z',
-          },
-        } as unknown as NonNullable<
-          Parameters<ExecutionLogger['completeWorkflowExecution']>[0]['billingAttribution']
-        >,
-      })
-
-      expect(readThresholdEmailUsageBefore).toHaveBeenCalledWith(
-        { type: 'organization', id: 'org-enterprise' },
-        {
-          start: new Date('2026-01-01T00:00:00.000Z'),
-          end: new Date('2027-01-01T00:00:00.000Z'),
-          source: 'reporting',
-        },
-        1000
-      )
-      expect(maybeSendUsageThresholdEmail).toHaveBeenCalledWith(
-        expect.objectContaining({
-          scope: 'organization',
-          organizationId: 'org-enterprise',
-          percentBefore: 25,
-          percentAfter: 26,
-          currentUsageAfter: 260,
-          limit: 1000,
-        })
-      )
-    })
-
     test('omits the provenance key when the run carried none', async () => {
       const written = await completeAndReadWrite({})
 

apps/sim/lib/logs/execution/logger.ts

@@ -1326,13 +1326,10 @@ export class ExecutionLogger implements IExecutionLoggerService {
           payerSubscription.plan,
           payerSubscription.seats
         )
-        const { readThresholdEmailUsageBefore } = await import(
-          '@/lib/billing/core/reporting-usage-cache'
-        )
-        const orgLedger = await readThresholdEmailUsageBefore(
+        const { getBillingPeriodUsageCost } = await import('@/lib/billing/core/usage-log')
+        const orgLedger = await getBillingPeriodUsageCost(
           billingAttribution.billingEntity,
-          exactBillingContext.billingPeriod,
-          orgLimit
+          exactBillingContext.billingPeriod
         )
         emailContext = {
           scope: 'organization',