fix(billing): include departed actors in close refresh and gate threshold billing on close currency

Cycle close now unions current members with every actor holding org-stamped
ledger rows in the closed period, so a departed member's daily-refresh
consumption offsets the final overage exactly like their billed usage.
Threshold billing defers with a pending-cycle-close no-op while a
subscription's close marker lags its current period, so the shared
billedOverageThisPeriod tracker can never mix an elapsed period's
settlements with the new period's.

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

Author: icecrasher321

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

@@ -79,7 +79,11 @@ vi.mock('@/lib/posthog/server', () => ({
   captureServerEvent: mockCaptureServerEvent,
 }))
 
-import { closeElapsedBillingPeriod, sweepBillingCycleCloses } from '@/lib/billing/cycle-close'
+import {
+  closeElapsedBillingPeriod,
+  isSubscriptionCycleCloseCurrent,
+  sweepBillingCycleCloses,
+} from '@/lib/billing/cycle-close'
 
 type SubInput = Parameters<typeof closeElapsedBillingPeriod>[0]
 
@@ -210,6 +214,27 @@ describe('closeElapsedBillingPeriod', () => {
     expect(mockCaptureServerEvent).toHaveBeenCalledTimes(1)
   })
 
+  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.
+    mockGetStampedPeriodRangeUsageCostByUser.mockResolvedValue(
+      new Map([
+        ['owner-1', 100],
+        ['departed-1', 50],
+      ])
+    )
+    queueOrgCloseReads()
+
+    await closeElapsedBillingPeriod(subRow())
+
+    expect(mockComputeOrgOverageAmount).toHaveBeenCalledWith(
+      expect.objectContaining({
+        pooledLedgerUsage: 150,
+        memberIds: ['owner-1', 'departed-1'],
+      })
+    )
+  })
+
   it('applies organization credits before invoicing and skips Stripe when covered', async () => {
     queueOrgCloseReads({ orgRow: { creditBalance: '100' } })
 
@@ -292,6 +317,37 @@ describe('closeElapsedBillingPeriod', () => {
   })
 })
 
+describe('isSubscriptionCycleCloseCurrent', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+  })
+
+  it('is current when the marker has caught up to the period start', async () => {
+    queueTableRows(schemaMock.subscription, [
+      { periodStart: PERIOD_START, lastClosedPeriodStart: PERIOD_START },
+    ])
+    await expect(isSubscriptionCycleCloseCurrent('sub-1')).resolves.toBe(true)
+  })
+
+  it('is pending when the marker lags the period start or was never initialized', async () => {
+    queueTableRows(schemaMock.subscription, [
+      { periodStart: PERIOD_START, lastClosedPeriodStart: PREV_PERIOD_START },
+    ])
+    await expect(isSubscriptionCycleCloseCurrent('sub-1')).resolves.toBe(false)
+
+    queueTableRows(schemaMock.subscription, [
+      { periodStart: PERIOD_START, lastClosedPeriodStart: null },
+    ])
+    await expect(isSubscriptionCycleCloseCurrent('sub-1')).resolves.toBe(false)
+  })
+
+  it('is current when the subscription has no period to close', async () => {
+    queueTableRows(schemaMock.subscription, [{ periodStart: null, lastClosedPeriodStart: null }])
+    await expect(isSubscriptionCycleCloseCurrent('sub-1')).resolves.toBe(true)
+  })
+})
+
 describe('sweepBillingCycleCloses', () => {
   beforeEach(() => {
     vi.clearAllMocks()

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

@@ -63,6 +63,35 @@ function hasEnterpriseReportingAnchor(sub: SubscriptionRow): boolean {
   )
 }
 
+/**
+ * Whether a subscription's previous period has already been closed — i.e. the
+ * durable close marker has caught up to the current `periodStart`.
+ *
+ * Threshold billing gates on this so the shared `billedOverageThisPeriod`
+ * tracker never mixes periods: after a rollover but before the sweep closes
+ * the elapsed period, a new-period settlement would be subtracted from the
+ * elapsed period's final overage and then wiped by the close's tracker reset,
+ * under-billing one period and double-billing the other. Skipping settlement
+ * until the close lands (sweep cadence, ≤6h) removes the race; a null marker
+ * (pre-first-sweep) also gates, and a null `periodStart` cannot race at all.
+ */
+export async function isSubscriptionCycleCloseCurrent(subscriptionId: string): Promise<boolean> {
+  const [row] = await db
+    .select({
+      periodStart: subscriptionTable.periodStart,
+      lastClosedPeriodStart: subscriptionTable.lastClosedPeriodStart,
+    })
+    .from(subscriptionTable)
+    .where(eq(subscriptionTable.id, subscriptionId))
+    .limit(1)
+
+  if (!row?.periodStart) return true
+  return (
+    row.lastClosedPeriodStart !== null &&
+    row.lastClosedPeriodStart.getTime() >= row.periodStart.getTime()
+  )
+}
+
 /**
  * Advance the durable close marker to `periodStart`, guarded so concurrent
  * closers and replays collapse to one winner. Returns false when another
@@ -191,6 +220,14 @@ export async function closeElapsedBillingPeriod(sub: SubscriptionRow): Promise<C
   const trackerUserId = orgScoped
     ? (memberRows.find((row) => row.role === 'owner')?.userId ?? null)
     : sub.referenceId
+  // Every actor whose org-attributed usage is billed at this close, including
+  // members who departed mid-period: their ledger rows stay stamped to this
+  // organization's period, so their daily-refresh consumption must offset the
+  // overage exactly like a current member's. Current members with no rows stay
+  // in the set for their refresh bounds.
+  const overageActorIds = orgScoped
+    ? [...new Set([...memberIds, ...usageByUser.keys()])]
+    : memberIds
 
   // Final overage for the closed period (enterprise never bills overage).
   let totalOverage = 0
@@ -203,7 +240,7 @@ export async function closeElapsedBillingPeriod(sub: SubscriptionRow): Promise<C
         periodEnd: periodStart,
         organizationId: sub.referenceId,
         pooledLedgerUsage: closedLedgerUsage,
-        memberIds,
+        memberIds: overageActorIds,
       })
       totalOverage = computed
     } else {

apps/sim/lib/billing/threshold-billing.test.ts

@@ -17,6 +17,7 @@ const {
   mockIsFree,
   mockIsOrgScopedSubscription,
   mockIsOrganizationBillingBlocked,
+  mockIsSubscriptionCycleCloseCurrent,
   mockRecordAudit,
   mockCaptureServerEvent,
 } = vi.hoisted(() => ({
@@ -32,6 +33,7 @@ const {
   mockIsFree: vi.fn(),
   mockIsOrgScopedSubscription: vi.fn(),
   mockIsOrganizationBillingBlocked: vi.fn(),
+  mockIsSubscriptionCycleCloseCurrent: vi.fn(),
   mockRecordAudit: vi.fn(),
   mockCaptureServerEvent: vi.fn(),
 }))
@@ -61,6 +63,10 @@ vi.mock('@/lib/billing/core/usage-log', () => ({
   getBillingPeriodUsageCost: mockGetBillingPeriodUsageCost,
 }))
 
+vi.mock('@/lib/billing/cycle-close', () => ({
+  isSubscriptionCycleCloseCurrent: mockIsSubscriptionCycleCloseCurrent,
+}))
+
 vi.mock('@/lib/billing/plan-helpers', () => ({
   isEnterprise: mockIsEnterprise,
   isFree: mockIsFree,
@@ -157,6 +163,7 @@ function queueOrgReads({
 }
 
 const usableOrgSubscription = {
+  id: 'sub-db-team-1',
   plan: 'team',
   seats: 2,
   periodStart: new Date('2026-05-01T00:00:00.000Z'),
@@ -178,6 +185,7 @@ describe('checkAndBillOverageThreshold', () => {
     mockIsEnterprise.mockReturnValue(false)
     mockIsOrgScopedSubscription.mockReturnValue(false)
     mockGetBillingPeriodUsageCost.mockResolvedValue(0)
+    mockIsSubscriptionCycleCloseCurrent.mockResolvedValue(true)
   })
 
   afterAll(() => {
@@ -522,6 +530,42 @@ describe('checkAndBillOverageThreshold', () => {
     expect(mockEnqueueOutboxEvent).not.toHaveBeenCalled()
   })
 
+  it('defers personal settlement while the previous period cycle close is pending', async () => {
+    mockIsSubscriptionCycleCloseCurrent.mockResolvedValue(false)
+    mockCalculateSubscriptionOverage.mockResolvedValue(250)
+
+    await expect(
+      checkAndBillOverageThreshold('user-1', undefined, {
+        onError: 'throw',
+        expectedBillingPeriod,
+      })
+    ).resolves.toEqual({ status: 'no-op', reason: 'pending-cycle-close' })
+
+    expect(mockIsSubscriptionCycleCloseCurrent).toHaveBeenCalledWith(userSubscription.id)
+    expect(mockCalculateSubscriptionOverage).not.toHaveBeenCalled()
+    expect(dbChainMockFns.transaction).not.toHaveBeenCalled()
+    expect(mockEnqueueOutboxEvent).not.toHaveBeenCalled()
+  })
+
+  it('defers organization settlement while the previous period cycle close is pending', async () => {
+    mockIsOrgScopedSubscription.mockReturnValue(true)
+    mockIsOrganizationBillingBlocked.mockResolvedValue(false)
+    mockGetOrganizationSubscriptionUsable.mockResolvedValue(usableOrgSubscription)
+    mockIsSubscriptionCycleCloseCurrent.mockResolvedValue(false)
+
+    await expect(
+      checkAndBillOverageThreshold('user-1', undefined, {
+        onError: 'throw',
+        expectedBillingPeriod,
+      })
+    ).resolves.toEqual({ status: 'no-op', reason: 'pending-cycle-close' })
+
+    expect(mockIsSubscriptionCycleCloseCurrent).toHaveBeenCalledWith(usableOrgSubscription.id)
+    expect(mockComputeOrgOverageAmount).not.toHaveBeenCalled()
+    expect(dbChainMockFns.transaction).not.toHaveBeenCalled()
+    expect(mockEnqueueOutboxEvent).not.toHaveBeenCalled()
+  })
+
   it('wraps lock timeouts in markerless strict mode', async () => {
     queuePersonalReads()
     mockCalculateSubscriptionOverage.mockResolvedValue(250)

apps/sim/lib/billing/threshold-billing.ts

@@ -14,6 +14,7 @@ import {
   getOrganizationSubscriptionUsable,
 } from '@/lib/billing/core/subscription'
 import { type BillingEntity, getBillingPeriodUsageCost } from '@/lib/billing/core/usage-log'
+import { isSubscriptionCycleCloseCurrent } from '@/lib/billing/cycle-close'
 import { isEnterprise, isFree } from '@/lib/billing/plan-helpers'
 import {
   hasUsableSubscriptionAccess,
@@ -53,6 +54,7 @@ export type ThresholdSettlementNoOpReason =
   | 'billing-blocked'
   | 'billing-ineligible'
   | 'no-subscription'
+  | 'pending-cycle-close'
   | 'plan-ineligible'
 
 export type ThresholdSettlementOutcome =
@@ -279,6 +281,15 @@ export async function checkAndBillOverageThreshold(
       return checkAndBillOrganizationOverageThreshold(userSubscription.referenceId, options)
     }
 
+    // Defer settlement while the previous period's cycle close is pending so
+    // `billedOverageThisPeriod` never mixes periods (see
+    // `isSubscriptionCycleCloseCurrent`). The sweep closes it within hours and
+    // a later threshold attempt settles normally.
+    if (!(await isSubscriptionCycleCloseCurrent(userSubscription.id))) {
+      logger.debug('Previous period cycle close pending; deferring threshold billing', { userId })
+      return noOp(options, 'pending-cycle-close')
+    }
+
     const currentOverage = await calculateSubscriptionOverage({
       id: userSubscription.id,
       plan: userSubscription.plan,
@@ -530,6 +541,17 @@ async function checkAndBillOrganizationOverageThreshold(
       return noOp(options, 'billing-blocked')
     }
 
+    // Defer settlement while the previous period's cycle close is pending so
+    // `billedOverageThisPeriod` never mixes periods (see
+    // `isSubscriptionCycleCloseCurrent`). The sweep closes it within hours and
+    // a later threshold attempt settles normally.
+    if (!(await isSubscriptionCycleCloseCurrent(orgSubscription.id))) {
+      logger.debug('Previous period cycle close pending; deferring org threshold billing', {
+        organizationId,
+      })
+      return noOp(options, 'pending-cycle-close')
+    }
+
     logger.debug('Found organization subscription', {
       organizationId,
       plan: orgSubscription.plan,