fix(billing): hold cycle close for a settlement grace after rollover

Billing attribution is frozen at run start, so a run straddling a
rollover can insert elapsed-period-stamped rows after the period ends.
Closing only once the rollover is older than any possible in-flight run
guarantees the close's ledger sums are final; the sweep picks the period
up on a later run.

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

Author: icecrasher321

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

@@ -223,6 +223,21 @@ describe('closeElapsedBillingPeriod', () => {
     expect(mockCaptureServerEvent).toHaveBeenCalledTimes(1)
   })
 
+  it('defers the close inside the settlement grace after a rollover', async () => {
+    // A run whose frozen attribution predates the rollover could still insert
+    // elapsed-period rows; the close waits until sums are final.
+    const result = await closeElapsedBillingPeriod(
+      subRow({
+        periodStart: new Date(Date.now() - 60_000),
+        lastClosedPeriodStart: new Date(Date.now() - 60_000 - 31 * 24 * 60 * 60 * 1000),
+      })
+    )
+
+    expect(result.status).toBe('skipped')
+    expect(dbChainMockFns.transaction).not.toHaveBeenCalled()
+    expect(mockGetStampedPeriodRangeUsageCostByUser).not.toHaveBeenCalled()
+  })
+
   it('defers the close when overage is due but Stripe identifiers are missing', async () => {
     const result = await closeElapsedBillingPeriod(subRow({ stripeCustomerId: null }))
 

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

@@ -35,6 +35,18 @@ const logger = createLogger('BillingCycleClose')
  */
 const MIN_CLOSE_INVOICE_DOLLARS = 0.5
 
+/**
+ * Settlement grace after a rollover before its elapsed period may close.
+ * Billing attribution is frozen at run start (the payer is immutable for the
+ * run), so a run that started just before the rollover can insert rows
+ * stamped with the elapsed period after it ends. Closing only once the
+ * rollover is older than any possible in-flight run guarantees the close's
+ * ledger sums are final — no straggler row is orphaned from the final
+ * overage or bookkeeping. Non-enterprise execution timeouts are far below
+ * this bound; the sweep simply picks the period up on a later run.
+ */
+const CLOSE_SETTLEMENT_GRACE_MS = 60 * 60 * 1000
+
 type SubscriptionRow = typeof subscriptionTable.$inferSelect
 
 export type CycleCloseStatus = 'initialized' | 'current' | 'closed' | 'already-closed' | 'skipped'
@@ -199,6 +211,12 @@ export async function closeElapsedBillingPeriod(sub: SubscriptionRow): Promise<C
     return { ...base, status: 'initialized' }
   }
 
+  if (Date.now() - periodStart.getTime() < CLOSE_SETTLEMENT_GRACE_MS) {
+    // Rollover too recent — a run started before it could still insert rows
+    // stamped with the elapsed period. A later sweep closes it with final sums.
+    return base
+  }
+
   const marker = sub.lastClosedPeriodStart
   const orgScoped = await isSubscriptionOrgScoped(sub)
   const billingEntity = orgScoped