test(billing): pin the Stripe-only rollover gate and the decision's subscription ID parsing

- A payer whose period is not a Stripe period is never rolled or share-locked.
- An account decision refuses a payer subscription ID that is not a non-empty string.
- Documents that a subscription replaced mid-run can only under-enforce the limit.

Author: waleedlatif1

apps/sim/app/api/billing/update-cost/route.test.ts

@@ -1112,6 +1112,29 @@ describe('POST /api/billing/update-cost — mid-run usage gate', () => {
       expect(res.status).toBe(200)
     })
 
+    it('keeps a payer whose period is not a Stripe period on its frozen period', async () => {
+      mockToBillingContext.mockReturnValue({
+        billingEntity: { type: 'organization', id: 'org-1' },
+        billingPeriod: {
+          start: new Date('2026-07-01T00:00:00.000Z'),
+          end: new Date('2026-08-01T00:00:00.000Z'),
+          source: 'default',
+        },
+      })
+      mockRecordCumulativeUsage.mockResolvedValue({
+        billed: true,
+        delta: 0.5,
+        total: 0.5,
+        billingPeriod: CURRENT_PERIOD,
+      })
+
+      await POST(attributedCallback())
+
+      expect(mockRecordCumulativeUsage).toHaveBeenCalledWith(
+        expect.not.objectContaining({ payerSubscriptionId: expect.anything() })
+      )
+    })
+
     it('keeps reporting-window payers on their frozen period', async () => {
       mockToBillingContext.mockReturnValue({
         billingEntity: { type: 'organization', id: 'org-1' },

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

@@ -20,6 +20,7 @@ import {
   checkAccountBillingBlocks,
   checkAttributedBillingBlocks,
   checkAttributedUsageLimits,
+  requireAccountBillingDecisionHeader,
   requireBillingAttributionHeader,
   requireBillingCallbackAttribution,
   requireBillingRequestIdHeader,
@@ -196,6 +197,38 @@ describe('resolveBillingAttribution', () => {
   })
 })
 
+describe('account billing decision header', () => {
+  const decision = {
+    userId: 'actor',
+    billingEntity: { type: 'user', id: 'actor' },
+    billingPeriod: {
+      start: '2026-07-01T00:00:00.000Z',
+      end: '2026-08-01T00:00:00.000Z',
+      source: 'stripe',
+    },
+  }
+  const header = (value: unknown) =>
+    new Headers({ 'x-sim-billing-account-decision': encodeURIComponent(JSON.stringify(value)) })
+
+  it('restores the admitted payer subscription', () => {
+    expect(
+      requireAccountBillingDecisionHeader(header({ ...decision, payerSubscriptionId: 'sub-1' }))
+    ).toMatchObject({ payerSubscriptionId: 'sub-1' })
+    expect(requireAccountBillingDecisionHeader(header(decision))).not.toHaveProperty(
+      'payerSubscriptionId'
+    )
+  })
+
+  it.each([42, '', ' ', null, { id: 'sub-1' }])(
+    'refuses a payer subscription of %j',
+    (payerSubscriptionId) => {
+      expect(() =>
+        requireAccountBillingDecisionHeader(header({ ...decision, payerSubscriptionId }))
+      ).toThrow('Account billing decision header is malformed')
+    }
+  )
+})
+
 describe('serialized attribution boundaries', () => {
   const attribution = {
     actorUserId: 'actor-a',

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

@@ -101,6 +101,8 @@ export interface AccountBillingDecision {
    * The payer's subscription at admission, so a run that outlives a Stripe period bills its
    * later spend to the period it was spent in, as an attributed run's `payerSubscription` does.
    * Absent for a payer without a subscription, and in decisions minted before it existed.
+   * If that subscription is replaced mid-run, spend stays in its period while the mid-run
+   * verdict judges the payer's current one, so the limit can only be under-enforced.
    */
   readonly payerSubscriptionId?: string
 }