fix(billing): reject lagging terminal claims and thread billingInterval into deletion bookkeeping

claimTerminalPeriod no longer advances the marker over an unclosed elapsed
period: a lagging marker is reported without a write so the deletion handler
can run the elapsed close once more (healing a rollover that committed
between close and claim) and only then seal the marker explicitly, with an
error log, when the period is genuinely unclosable. Sealing preserves the
in-flight-sweep abort guarantee.

Deletion bookkeeping now passes the subscription's billingInterval through,
so an enterprise reporting subscription whose interval lives on the row
column (not metadata) still resolves as reporting-anchored and keeps its
bookkeeping no-op, matching every other resolver call site.

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

Author: icecrasher321

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

@@ -550,7 +550,7 @@ describe('claimTerminalPeriod', () => {
     dbChainMockFns.returning.mockResolvedValue([{ id: 'sub-1' }])
   })
 
-  it('claims the marker from the fresh row period and returns it for settlement', async () => {
+  it('returns the fresh period without rewriting a current marker', async () => {
     queueTableRows(schemaMock.subscription, [
       {
         periodStart: PERIOD_START,
@@ -563,13 +563,10 @@ describe('claimTerminalPeriod', () => {
 
     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()
+    expect(dbChainMockFns.set).not.toHaveBeenCalled()
   })
 
-  it('reports a lagging marker so the terminal settlement ignores the stale tracker', async () => {
+  it('reports a lagging marker without jumping it, so the caller can close and re-claim', async () => {
     queueTableRows(schemaMock.subscription, [
       {
         periodStart: PERIOD_START,
@@ -581,6 +578,25 @@ describe('claimTerminalPeriod', () => {
     const terminal = await claimTerminalPeriod('sub-1')
 
     expect(terminal.markerWasCurrent).toBe(false)
+    expect(dbChainMockFns.set).not.toHaveBeenCalled()
+  })
+
+  it('seals a lagging marker on request, forgiving the unclosed period loudly', 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', { sealLagging: true })
+
+    expect(terminal.markerWasCurrent).toBe(false)
+    const markerSet = dbChainMockFns.set.mock.calls.find(
+      (call) => (call[0] as Record<string, unknown>).lastClosedPeriodStart instanceof Date
+    )
+    expect(markerSet).toBeDefined()
   })
 
   it('returns nulls without claiming when the subscription has no period', async () => {

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

@@ -197,14 +197,25 @@ export async function closeElapsedPeriodBeforeDeletion(subscriptionId: string):
  * 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, 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.
+ * whether the close marker had already caught up to the terminal period.
+ * 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.
+ *
+ * A lagging marker means an elapsed period is still unclosed — either the
+ * preceding close deferred, or a rollover committed between that close and
+ * this claim. By default the claim then leaves the marker untouched so the
+ * caller can run the close again and re-claim; `sealLagging` advances the
+ * marker over the unclosed period anyway (logging the forgiveness), which
+ * also guarantees an in-flight sweep that selected this subscription before
+ * its status changed aborts its own conflicting close.
  */
-export async function claimTerminalPeriod(subscriptionId: string): Promise<{
+export async function claimTerminalPeriod(
+  subscriptionId: string,
+  options: { sealLagging?: boolean } = {}
+): Promise<{
   periodStart: Date | null
   periodEnd: Date | null
   markerWasCurrent: boolean
@@ -229,7 +240,17 @@ export async function claimTerminalPeriod(subscriptionId: string): Promise<{
     const markerWasCurrent =
       !!row.lastClosedPeriodStart &&
       row.lastClosedPeriodStart.getTime() >= row.periodStart.getTime()
-    await claimCloseMarker(tx, subscriptionId, row.periodStart)
+    if (!markerWasCurrent && options.sealLagging) {
+      logger.error(
+        'Sealing an unclosed elapsed period at terminal claim; residual overage forgiven',
+        {
+          subscriptionId,
+          marker: row.lastClosedPeriodStart?.toISOString() ?? null,
+          periodStart: row.periodStart.toISOString(),
+        }
+      )
+      await claimCloseMarker(tx, subscriptionId, row.periodStart)
+    }
     return { periodStart: row.periodStart, periodEnd: row.periodEnd, markerWasCurrent }
   })
 }
@@ -713,6 +734,7 @@ export async function writeFinalPeriodBookkeeping(sub: {
   id: string
   plan: string | null
   referenceId: string
+  billingInterval?: string | null
   periodStart?: Date | null
   periodEnd?: Date | null
   metadata?: unknown

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

@@ -260,6 +260,7 @@ export async function handleSubscriptionDeleted(
     referenceId: string
     stripeSubscriptionId: string | null
     seats?: number | null
+    billingInterval?: string | null
     periodStart?: Date | null
     periodEnd?: Date | null
     metadata?: unknown
@@ -293,10 +294,17 @@ export async function handleSubscriptionDeleted(
 
         // Then claim the terminal period BEFORE computing or charging: this
         // reads the row's fresh period (webhook payloads can be stale across
-        // a rollover) and serializes with the cycle-close sweep — an
-        // in-flight close fails its guarded marker claim and rolls back, so
-        // both paths can never bill the same period.
-        const terminal = await claimTerminalPeriod(subscription.id)
+        // a rollover) and serializes with the cycle-close sweep. A lagging
+        // marker here means the close above deferred OR a rollover committed
+        // in between — run the close once more (it settles a freshly elapsed
+        // period; a deferred close defers again, loudly), then seal so the
+        // marker cannot be raced indefinitely and an in-flight sweep aborts
+        // its conflicting close.
+        let terminal = await claimTerminalPeriod(subscription.id)
+        if (!terminal.markerWasCurrent) {
+          await closeElapsedPeriodBeforeDeletion(subscription.id)
+          terminal = await claimTerminalPeriod(subscription.id, { sealLagging: true })
+        }
         const settlementPeriod = {
           periodStart: terminal.periodStart ?? subscription.periodStart ?? null,
           periodEnd: terminal.periodEnd ?? subscription.periodEnd ?? null,
@@ -313,6 +321,7 @@ export async function handleSubscriptionDeleted(
             id: subscription.id,
             plan: subscription.plan,
             referenceId: subscription.referenceId,
+            billingInterval: subscription.billingInterval ?? null,
             ...settlementPeriod,
             metadata: subscription.metadata,
           })
@@ -442,6 +451,7 @@ export async function handleSubscriptionDeleted(
           id: subscription.id,
           plan: subscription.plan,
           referenceId: subscription.referenceId,
+          billingInterval: subscription.billingInterval ?? null,
           ...settlementPeriod,
           metadata: subscription.metadata,
         })