fix(billing): seal cycle-close races and align refresh actors with billed usage

Threshold settlement revalidates the close marker and period under the
tracker lock via the same isSubscriptionCycleCloseCurrent predicate the
preflight uses, so a rollover between check and transaction aborts as a
concurrent-state retry instead of settling against the wrong cycle.
Terminal bookkeeping claims the close marker with its tracker reset, so a
deletion racing an in-flight sweep close serializes through the one marker
and the loser rolls back rather than re-billing settled overage; anchored
enterprise deletions only claim the marker since their windows derive from
the anchor, not Stripe bounds. A close with overage due but missing Stripe
identifiers now defers loudly instead of claiming the marker and silently
forgiving the money, the closed window's start derives from the ledger's
own period stamps so anchor-day drift cannot misalign the refresh window,
calculateSubscriptionOverage unions departed ledger actors into the org
refresh deduction like the close does, and blocked accounts report their
real ledger usage while staying blocked.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: icecrasher321

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

@@ -53,6 +53,7 @@ import {
   checkBillingBlocked,
   checkBillingEntityBlocked,
   checkOrganizationMemberUsageLimit,
+  checkServerSideUsageLimits,
   checkUsageStatus,
 } from '@/lib/billing/calculations/usage-monitor'
 
@@ -274,6 +275,39 @@ describe('checkUsageStatus', () => {
   })
 })
 
+describe('checkServerSideUsageLimits', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+    setEnvFlags({ isHosted: true, isBillingEnabled: true })
+    mockGetBillingPeriodUsageCost.mockResolvedValue(125)
+  })
+
+  it('keeps blocked accounts blocked while reporting their real ledger usage', async () => {
+    dbChainMockFns.limit.mockResolvedValueOnce([{ blocked: true, blockedReason: 'payment_failed' }])
+    const subscription = {
+      referenceId: 'user-1',
+      plan: 'pro',
+      status: 'active',
+      seats: 1,
+      periodStart: new Date('2026-06-01T00:00:00.000Z'),
+      periodEnd: new Date('2026-07-01T00:00:00.000Z'),
+    }
+
+    const result = await checkServerSideUsageLimits('user-1', subscription)
+
+    expect(result).toMatchObject({ isExceeded: true, currentUsage: 125, limit: 0 })
+    expect(result.message).toBeTruthy()
+    expect(mockGetBillingPeriodUsageCost).toHaveBeenCalledWith(
+      { type: 'user', id: 'user-1' },
+      expect.objectContaining({
+        start: subscription.periodStart,
+        end: subscription.periodEnd,
+      })
+    )
+  })
+})
+
 describe('checkBillingBlocked', () => {
   beforeEach(() => {
     vi.clearAllMocks()

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

@@ -332,7 +332,21 @@ export async function checkServerSideUsageLimits(
 
     const blocked = await checkBillingBlocked(userId)
     if (blocked.blocked) {
-      return { isExceeded: true, currentUsage: 0, limit: 0, message: blocked.message }
+      // Enforcement stays blocked, but surfaced usage must be the real ledger
+      // value — `/api/users/me/usage-limits` exposes it as `currentPeriodCost`.
+      const sub =
+        preloadedSubscription !== undefined
+          ? preloadedSubscription
+          : await getHighestPrioritySubscription(userId)
+      const subIsOrgScoped = isOrgScopedSubscription(sub, userId)
+      const billingEntity: BillingEntity =
+        subIsOrgScoped && sub
+          ? { type: 'organization', id: sub.referenceId }
+          : { type: 'user', id: userId }
+      const billingPeriod = preloadedBillingContext?.billingPeriod ??
+        resolveSubscriptionUsagePeriod(sub) ?? { ...defaultBillingPeriod(), source: 'default' }
+      const currentUsage = await getBillingPeriodUsageCost(billingEntity, billingPeriod)
+      return { isExceeded: true, currentUsage, limit: 0, message: blocked.message }
     }
 
     const usageData = await checkUsageStatus(userId, preloadedSubscription, preloadedBillingContext)

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

@@ -1,24 +1,28 @@
 /**
  * @vitest-environment node
  */
-import { dbChainMock, dbChainMockFns } from '@sim/testing'
+import { dbChainMock, dbChainMockFns, queueTableRows, schemaMock } from '@sim/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const {
   mockComputeDailyRefreshConsumed,
   mockEnsureUserStatsExists,
   mockGetBillingPeriodUsageCost,
+  mockGetBillingPeriodUsageCostByUser,
   mockGetBillingPeriodUsageCostWithSourceSubset,
   mockGetHighestPriorityPersonalSubscription,
   mockGetHighestPrioritySubscription,
+  mockGetOrgMemberRefreshBounds,
   mockResolveBillingInterval,
 } = vi.hoisted(() => ({
   mockComputeDailyRefreshConsumed: vi.fn(),
   mockEnsureUserStatsExists: vi.fn(),
   mockGetBillingPeriodUsageCost: vi.fn(),
+  mockGetBillingPeriodUsageCostByUser: vi.fn(),
   mockGetBillingPeriodUsageCostWithSourceSubset: vi.fn(),
   mockGetHighestPriorityPersonalSubscription: vi.fn(),
   mockGetHighestPrioritySubscription: vi.fn(),
+  mockGetOrgMemberRefreshBounds: vi.fn(),
   mockResolveBillingInterval: vi.fn(),
 }))
 
@@ -37,15 +41,16 @@ vi.mock('@/lib/billing/core/usage', () => ({
 vi.mock('@/lib/billing/core/usage-log', () => ({
   COPILOT_USAGE_SOURCES: ['copilot'],
   getBillingPeriodUsageCost: mockGetBillingPeriodUsageCost,
+  getBillingPeriodUsageCostByUser: mockGetBillingPeriodUsageCostByUser,
   getBillingPeriodUsageCostWithSourceSubset: mockGetBillingPeriodUsageCostWithSourceSubset,
 }))
 
 vi.mock('@/lib/billing/credits/daily-refresh', () => ({
   computeDailyRefreshConsumed: mockComputeDailyRefreshConsumed,
-  getOrgMemberRefreshBounds: vi.fn(),
+  getOrgMemberRefreshBounds: mockGetOrgMemberRefreshBounds,
 }))
 
-import { getPersonalBillingSummary } from '@/lib/billing/core/billing'
+import { calculateSubscriptionOverage, getPersonalBillingSummary } from '@/lib/billing/core/billing'
 
 describe('getPersonalBillingSummary', () => {
   beforeEach(() => {
@@ -120,3 +125,37 @@ describe('getPersonalBillingSummary', () => {
     )
   })
 })
+
+describe('calculateSubscriptionOverage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetOrgMemberRefreshBounds.mockResolvedValue({})
+    mockComputeDailyRefreshConsumed.mockResolvedValue(0)
+  })
+
+  it('includes departed ledger actors in the org refresh deduction', async () => {
+    queueTableRows(schemaMock.organization, [{ id: 'org-1' }]) // isSubscriptionOrgScoped
+    queueTableRows(schemaMock.member, [{ userId: 'owner-1' }]) // current members
+    mockGetBillingPeriodUsageCostByUser.mockResolvedValue(
+      new Map([
+        ['owner-1', 100],
+        ['departed-1', 60],
+      ])
+    )
+
+    await calculateSubscriptionOverage({
+      id: 'sub-1',
+      plan: 'team',
+      referenceId: 'org-1',
+      seats: 2,
+      periodStart: new Date('2026-07-01T00:00:00.000Z'),
+      periodEnd: new Date('2026-08-01T00:00:00.000Z'),
+    })
+
+    expect(mockComputeDailyRefreshConsumed).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userIds: expect.arrayContaining(['owner-1', 'departed-1']),
+      })
+    )
+  })
+})

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

@@ -10,6 +10,7 @@ import { ensureUserStatsExists } from '@/lib/billing/core/usage'
 import {
   COPILOT_USAGE_SOURCES,
   getBillingPeriodUsageCost,
+  getBillingPeriodUsageCostByUser,
   getBillingPeriodUsageCostWithSourceSubset,
 } from '@/lib/billing/core/usage-log'
 import {
@@ -188,14 +189,19 @@ export async function calculateSubscriptionOverage(sub: {
       .select({ userId: member.userId })
       .from(member)
       .where(eq(member.organizationId, sub.referenceId))
-    const memberIds = memberRows.map((row) => row.userId)
-    const ledgerUsage =
+    const usageByUser =
       sub.periodStart && sub.periodEnd
-        ? await getBillingPeriodUsageCost(
+        ? await getBillingPeriodUsageCostByUser(
             { type: 'organization', id: sub.referenceId },
             { start: sub.periodStart, end: sub.periodEnd }
           )
-        : 0
+        : new Map<string, number>()
+    let ledgerUsage = 0
+    for (const cost of usageByUser.values()) ledgerUsage += cost
+    // Union current members with every actor holding org-attributed rows this
+    // period: a member who departed mid-period still bills here, so their
+    // daily-refresh consumption must offset the overage too.
+    const memberIds = [...new Set([...memberRows.map((row) => row.userId), ...usageByUser.keys()])]
 
     const { totalOverage, effectiveUsage, baseSubscriptionAmount } = await computeOrgOverageAmount({
       plan: sub.plan,

apps/sim/lib/billing/cycle-close.test.ts

@@ -83,6 +83,7 @@ import {
   closeElapsedBillingPeriod,
   isSubscriptionCycleCloseCurrent,
   sweepBillingCycleCloses,
+  writeFinalPeriodBookkeeping,
 } from '@/lib/billing/cycle-close'
 
 type SubInput = Parameters<typeof closeElapsedBillingPeriod>[0]
@@ -214,6 +215,31 @@ describe('closeElapsedBillingPeriod', () => {
     expect(mockCaptureServerEvent).toHaveBeenCalledTimes(1)
   })
 
+  it('defers the close when overage is due but Stripe identifiers are missing', async () => {
+    const result = await closeElapsedBillingPeriod(subRow({ stripeCustomerId: null }))
+
+    expect(result.status).toBe('skipped')
+    // No marker claim, no money, no bookkeeping — the sweep retries next run.
+    expect(dbChainMockFns.transaction).not.toHaveBeenCalled()
+    expect(dbChainMockFns.update).not.toHaveBeenCalled()
+    expect(mockEnqueueOutboxEvent).not.toHaveBeenCalled()
+  })
+
+  it('derives the closed window from the ledger period stamps when they drift from calendar math', async () => {
+    // Rows for the elapsed period are stamped starting Jul 3 (anchor drift);
+    // the stamped boundary — not periodStart minus one interval — must bound
+    // the refresh window.
+    const stampedPrevStart = new Date('2026-07-03T00:00:00.000Z')
+    queueTableRows(schemaMock.usageLog, [{ start: stampedPrevStart }])
+    queueOrgCloseReads()
+
+    await closeElapsedBillingPeriod(subRow({ lastClosedPeriodStart: stampedPrevStart }))
+
+    expect(mockComputeOrgOverageAmount).toHaveBeenCalledWith(
+      expect.objectContaining({ periodStart: stampedPrevStart, periodEnd: PERIOD_START })
+    )
+  })
+
   it('includes departed members with billed ledger usage in the refresh actor set', async () => {
     // 'departed-1' has org-attributed rows in the closed period but no member
     // row anymore; their refresh consumption must still offset the overage.
@@ -317,6 +343,62 @@ describe('closeElapsedBillingPeriod', () => {
   })
 })
 
+describe('writeFinalPeriodBookkeeping', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+    mockIsSubscriptionOrgScoped.mockResolvedValue(true)
+    mockIsEnterprise.mockReturnValue(false)
+    mockGetStampedPeriodRangeUsageCostByUser.mockResolvedValue(new Map([['owner-1', 25]]))
+    dbChainMockFns.returning.mockResolvedValue([{ id: 'sub-1' }])
+  })
+
+  it('resets trackers, writes last-period sums, and claims the terminal marker in one transaction', async () => {
+    queueTableRows(schemaMock.member, [{ userId: 'owner-1' }])
+
+    await writeFinalPeriodBookkeeping({
+      id: 'sub-1',
+      plan: 'team',
+      referenceId: 'org-1',
+      periodStart: PERIOD_START,
+      periodEnd: new Date('2026-09-01T00:00:00.000Z'),
+    })
+
+    expect(dbChainMockFns.transaction).toHaveBeenCalledTimes(1)
+    const bookkeepingSet = dbChainMockFns.set.mock.calls.find(
+      (call) => (call[0] as Record<string, unknown>).billedOverageThisPeriod === '0'
+    )
+    expect(bookkeepingSet).toBeDefined()
+    const markerSet = dbChainMockFns.set.mock.calls.find(
+      (call) => (call[0] as Record<string, unknown>).lastClosedPeriodStart instanceof Date
+    )
+    expect(markerSet).toBeDefined()
+  })
+
+  it('only claims the marker for reporting-anchor enterprise subscriptions', async () => {
+    mockIsEnterprise.mockReturnValue(true)
+
+    await writeFinalPeriodBookkeeping({
+      id: 'sub-1',
+      plan: 'enterprise',
+      referenceId: 'org-1',
+      periodStart: PERIOD_START,
+      periodEnd: new Date('2026-09-01T00:00:00.000Z'),
+      metadata: { reportingPeriodAnchorDate: '2026-05-01' },
+    })
+
+    expect(mockGetStampedPeriodRangeUsageCostByUser).not.toHaveBeenCalled()
+    const markerSet = dbChainMockFns.set.mock.calls.find(
+      (call) => (call[0] as Record<string, unknown>).lastClosedPeriodStart instanceof Date
+    )
+    expect(markerSet).toBeDefined()
+    const bookkeepingSet = dbChainMockFns.set.mock.calls.find(
+      (call) => (call[0] as Record<string, unknown>).billedOverageThisPeriod === '0'
+    )
+    expect(bookkeepingSet).toBeUndefined()
+  })
+})
+
 describe('isSubscriptionCycleCloseCurrent', () => {
   beforeEach(() => {
     vi.clearAllMocks()