fix(billing): pair the overage tracker with the marker's period and pin test clocks

billedOverageThisPeriod only ever holds collections for the period that
began at the close marker — the threshold gate blocks settlement whenever
the marker lags. Both consumers now honor that pairing: a close that
skipped forgiven periods counts nothing from the tracker against the
period it bills, and the deletion settlement ignores the tracker when the
marker was still lagging at claim time. Ignoring is provably safe in both
cases because a lagging marker means no current-period collections exist.

The cycle-close and daily-refresh suites pin the system clock: their grace
and window checks compare fixed period fixtures against Date.now(), which
made them dependent on the host date.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: icecrasher321

apps/sim/lib/billing/credits/daily-refresh.test.ts

@@ -2,7 +2,7 @@
  * @vitest-environment node
  */
 import { dbChainMockFns, drizzleOrmMock, schemaMock } from '@sim/testing'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('drizzle-orm', () => {
   const sqlTag = () => {
@@ -25,6 +25,21 @@ import {
   computeDailyRefreshConsumed,
 } from '@/lib/billing/credits/daily-refresh'
 
+/**
+ * Refresh caps windows at `Date.now()`, so the suite pins the clock after
+ * every fixture period to stay hermetic on any host date.
+ */
+const FROZEN_NOW = new Date('2026-08-15T00:00:00.000Z')
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(FROZEN_NOW)
+})
+
+afterAll(() => {
+  vi.useRealTimers()
+})
+
 describe('computeBillingPeriodUsageWithDailyRefresh', () => {
   const periodStart = new Date('2026-03-01T00:00:00.000Z')
   const periodEnd = new Date('2026-04-01T00:00:00.000Z')

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

@@ -95,6 +95,21 @@ type SubInput = Parameters<typeof closeElapsedBillingPeriod>[0]
 const PERIOD_START = new Date('2026-08-01T00:00:00.000Z')
 const PREV_PERIOD_START = new Date('2026-07-01T00:00:00.000Z')
 
+/**
+ * The grace gate and lagging checks compare fixed period boundaries against
+ * `Date.now()`, so the suite pins the clock to stay hermetic on any host date.
+ */
+const FROZEN_NOW = new Date('2026-08-15T00:00:00.000Z')
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(FROZEN_NOW)
+})
+
+afterAll(() => {
+  vi.useRealTimers()
+})
+
 function subRow(overrides: Partial<Record<string, unknown>> = {}): SubInput {
   return {
     id: 'sub-1',
@@ -305,6 +320,35 @@ describe('closeElapsedBillingPeriod', () => {
     })
   })
 
+  it('subtracts the current period tracker from the final overage', async () => {
+    queueOrgCloseReads({ trackerRow: { billedOverageThisPeriod: '30', creditBalance: '0' } })
+
+    const result = await closeElapsedBillingPeriod(subRow())
+
+    expect(result.status).toBe('closed')
+    expect(result.overageBilled).toBe(40)
+    const [, , payload] = mockEnqueueOutboxEvent.mock.calls[0]
+    expect(payload).toMatchObject({ amountCents: 4000 })
+  })
+
+  it('ignores the stale tracker when the close skipped forgiven periods', async () => {
+    // Marker two intervals back: the close forgives the older period and
+    // bills [Jul 1, Aug 1) only. The tracker's collections belong to the
+    // period that began at the marker, so none of them offset this close.
+    const staleMarker = new Date('2026-05-01T00:00:00.000Z')
+    queueOrgCloseReads({
+      markerRow: { lastClosedPeriodStart: staleMarker },
+      trackerRow: { billedOverageThisPeriod: '30', creditBalance: '0' },
+    })
+
+    const result = await closeElapsedBillingPeriod(subRow({ lastClosedPeriodStart: staleMarker }))
+
+    expect(result.status).toBe('closed')
+    expect(result.overageBilled).toBe(70)
+    const [, , payload] = mockEnqueueOutboxEvent.mock.calls[0]
+    expect(payload).toMatchObject({ amountCents: 7000 })
+  })
+
   it('applies organization credits before invoicing and skips Stripe when covered', async () => {
     queueOrgCloseReads({ orgRow: { creditBalance: '100' } })
 
@@ -508,24 +552,43 @@ describe('claimTerminalPeriod', () => {
 
   it('claims the marker from the fresh row period and returns it for settlement', async () => {
     queueTableRows(schemaMock.subscription, [
-      { periodStart: PERIOD_START, periodEnd: new Date('2026-09-01T00:00:00.000Z') },
+      {
+        periodStart: PERIOD_START,
+        periodEnd: new Date('2026-09-01T00:00:00.000Z'),
+        lastClosedPeriodStart: PERIOD_START,
+      },
     ])
 
     const terminal = await claimTerminalPeriod('sub-1')
 
     expect(terminal.periodStart).toEqual(PERIOD_START)
+    expect(terminal.markerWasCurrent).toBe(true)
     const markerSet = dbChainMockFns.set.mock.calls.find(
       (call) => (call[0] as Record<string, unknown>).lastClosedPeriodStart instanceof Date
     )
     expect(markerSet).toBeDefined()
   })
 
+  it('reports a lagging marker so the terminal settlement ignores the stale tracker', async () => {
+    queueTableRows(schemaMock.subscription, [
+      {
+        periodStart: PERIOD_START,
+        periodEnd: new Date('2026-09-01T00:00:00.000Z'),
+        lastClosedPeriodStart: PREV_PERIOD_START,
+      },
+    ])
+
+    const terminal = await claimTerminalPeriod('sub-1')
+
+    expect(terminal.markerWasCurrent).toBe(false)
+  })
+
   it('returns nulls without claiming when the subscription has no period', async () => {
     queueTableRows(schemaMock.subscription, [{ periodStart: null, periodEnd: null }])
 
     const terminal = await claimTerminalPeriod('sub-1')
 
-    expect(terminal).toEqual({ periodStart: null, periodEnd: null })
+    expect(terminal).toEqual({ periodStart: null, periodEnd: null, markerWasCurrent: true })
     expect(dbChainMockFns.set).not.toHaveBeenCalled()
   })
 })

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

@@ -196,25 +196,41 @@ export async function closeElapsedPeriodBeforeDeletion(subscriptionId: string):
  * including its outbox invoice — so deletion and sweep can never both bill
  * the same period. Call `closeElapsedPeriodBeforeDeletion` first so a lagging
  * elapsed period is settled rather than jumped. Returns the fresh period
- * bounds for the deletion flow to settle against.
+ * bounds for the deletion flow to settle against, plus `markerWasCurrent`:
+ * whether the close marker had already caught up to the terminal period
+ * before this claim. The `billedOverageThisPeriod` tracker only ever holds
+ * collections for the period that began at the marker (the threshold gate
+ * blocks settlement whenever the marker lags), so the terminal settlement
+ * must ignore the tracker when the marker was still lagging — its contents
+ * belong to a forgiven elapsed period, never to the terminal window.
  */
-export async function claimTerminalPeriod(
-  subscriptionId: string
-): Promise<{ periodStart: Date | null; periodEnd: Date | null }> {
+export async function claimTerminalPeriod(subscriptionId: string): Promise<{
+  periodStart: Date | null
+  periodEnd: Date | null
+  markerWasCurrent: boolean
+}> {
   return db.transaction(async (tx) => {
     const [row] = await tx
       .select({
         periodStart: subscriptionTable.periodStart,
         periodEnd: subscriptionTable.periodEnd,
+        lastClosedPeriodStart: subscriptionTable.lastClosedPeriodStart,
       })
       .from(subscriptionTable)
       .where(eq(subscriptionTable.id, subscriptionId))
       .for('update')
       .limit(1)
 
-    if (!row?.periodStart) return { periodStart: null, periodEnd: null }
+    if (!row?.periodStart) {
+      // Mirrors the threshold gate: a null `periodStart` cannot race a
+      // rollover, so any tracked collections are legitimately current.
+      return { periodStart: null, periodEnd: null, markerWasCurrent: true }
+    }
+    const markerWasCurrent =
+      !!row.lastClosedPeriodStart &&
+      row.lastClosedPeriodStart.getTime() >= row.periodStart.getTime()
     await claimCloseMarker(tx, subscriptionId, row.periodStart)
-    return { periodStart: row.periodStart, periodEnd: row.periodEnd }
+    return { periodStart: row.periodStart, periodEnd: row.periodEnd, markerWasCurrent }
   })
 }
 
@@ -514,7 +530,16 @@ export async function closeElapsedBillingPeriod(
           .where(eq(userStats.userId, trackerUserId))
           .limit(1)
 
-        const alreadyBilled = toNumber(toDecimal(tracker?.billedOverageThisPeriod))
+        // The tracker's collections belong to the period that began at the
+        // marker — the threshold gate blocks settlement whenever the marker
+        // lags, so nothing newer can be in it. When this close skipped
+        // forgiven periods (`closeFrom` advanced past the marker), those
+        // collections offset a forgiven period's overage, not this one's:
+        // count nothing against this close. The reset below still clears them.
+        const alreadyBilled =
+          closeFrom.getTime() === marker.getTime()
+            ? toNumber(toDecimal(tracker?.billedOverageThisPeriod))
+            : 0
         let remaining = Math.max(0, totalOverage - alreadyBilled)
 
         if (remaining > 0) {

apps/sim/lib/billing/webhooks/subscription.ts

@@ -350,7 +350,15 @@ export async function handleSubscriptionDeleted(
           return { totalOverage: 0, kind: 'enterprise' as const }
         }
 
-        const billedOverage = await getBilledOverageForSubscription(subscription)
+        // The tracker only ever holds collections for the period that began
+        // at the close marker — the threshold gate blocks settlement while
+        // the marker lags. If the marker was still lagging at claim time
+        // (the elapsed close above deferred), the tracked amount belongs to
+        // that forgiven elapsed period, not the terminal window: subtracting
+        // it would under-bill the final invoice, so count nothing.
+        const billedOverage = terminal.markerWasCurrent
+          ? await getBilledOverageForSubscription(subscription)
+          : 0
         const remainingOverage = Math.max(0, totalOverage - billedOverage)
 
         logger.info('Subscription deleted overage calculation', {