Fix free-tier credit overdraw and consumeFromOrderedGrants debt accounting

Root-cause fix in consumeFromOrderedGrants (packages/billing/src/balance-calculator.ts):
- Removed buggy "repay debt" first pass that treated consumption as credit addition
  (grant.balance + repayAmount), shrinking debt during spending. This caused every
  other post-exhaustion message to get free compute.
- Mutate grant.balance in-memory in the consume loop so the overflow check sees
  post-consumption state (previously stale, dropped overflow credits silently).
- Unconditionally create/extend debt on the last grant when remainingToConsume > 0
  (previously guarded by lastGrant.balance <= 0 using stale in-memory value).

Hard gate (defense-in-depth): added shouldBlockFreeUserOverdraw() and wired it into
consumeCreditsAndAddAgentStep. Free-tier users (no purchase/subscription grant) with
netBalance < credits are refused before consume/message-insert. Throws typed
InsufficientCreditsError (netBalance, chargeAmount fields) inside the advisory-lock
tx so it rolls back cleanly and the outer catch returns failure(error).

These two layers are complementary, not redundant:
- Root-cause fix = correct accounting (debt deepens monotonically)
- Hard gate = policy enforcement (free tier can't go negative; only paying users
  can accumulate debt via the fixed consume path)

Debt-settlement model is split: consume path only deepens debt; grant path
(executeGrantCreditOperation in grant-credits.ts:134-154) is the ONLY place debt is
cleared, via the existing negativeGrants-zeroing logic that runs on every credit
addition (Stripe purchases, monthly resets, referrals, admin grants). Added
cross-reference comments in both files documenting this invariant.

Tests:
- 9 unit tests for shouldBlockFreeUserOverdraw (exhausted, insufficient, sufficient,
  subscription/purchase bypass, zero-charge, referral-only, debt, multi-grant)
- 6 regression tests for consumeFromOrderedGrants using write-capture mock tx:
  debt deepening, drain-and-overflow, no debt forgiveness, happy path, multi-grant
  priority, consumed tracks overflow
- 2 tests for InsufficientCreditsError class (instance + barrel export)
- Fixed createMockGrant type (added org_id, stripe_subscription_id, extended union)
- Updated local copy of consumeFromOrderedGrants in the real-DB integration test
  and renamed/rewrote the 'should repay debt...' test to 'should not forgive
  debt...' — the old test was codifying the bug as correct behavior.

Validation: typecheck clean on packages/billing; 28/28 balance-calculator unit
tests pass; 14/14 integration tests pass against real Postgres; 128/128 full
billing test suite green.

Impact: Apr-16 credit-farming cohort of 10 freshly-created accounts consumed
~\$18.4k of API compute (74% of daily burn) off 500-credit free grants. With this
fix, those accounts would have been refused after message ~6.

Author: jahooma

packages/billing/src/__tests__/balance-calculator.integration.test.ts

@@ -65,32 +65,7 @@ async function consumeFromOrderedGrants(params: {
   let consumed = 0
   let fromPurchased = 0
 
-  // First pass: try to repay any debt
-  for (const grant of grants) {
-    if (grant.balance < 0 && remainingToConsume > 0) {
-      const debtAmount = Math.abs(grant.balance)
-      const repayAmount = Math.min(debtAmount, remainingToConsume)
-      const newBalance = grant.balance + repayAmount
-      remainingToConsume -= repayAmount
-      consumed += repayAmount
-
-      await updateGrantBalance({
-        userId,
-        grant,
-        consumed: -repayAmount,
-        newBalance,
-        tx,
-        logger,
-      })
-
-      logger.debug(
-        { userId, grantId: grant.operation_id, repayAmount, newBalance },
-        'Repaid debt in grant',
-      )
-    }
-  }
-
-  // Second pass: consume from positive balances
+  // Consume from positive balances in priority order
   for (const grant of grants) {
     if (remainingToConsume <= 0) break
     if (grant.balance <= 0) continue
@@ -113,35 +88,41 @@ async function consumeFromOrderedGrants(params: {
       tx,
       logger,
     })
+
+    // Mutate in-memory balance so the overflow check below sees
+    // post-consumption state (not the stale original value).
+    grant.balance = newBalance
   }
 
-  // If we still have remaining to consume and no grants left, create debt in the last grant
+  // If we still have remaining to consume, create or extend debt on the
+  // last grant. After the loop above all positive-balance grants are drained.
+  // The "last grant" (lowest consumption priority, typically a subscription
+  // grant that renews monthly) absorbs the overflow as debt.
   if (remainingToConsume > 0 && grants.length > 0) {
     const lastGrant = grants[grants.length - 1]
+    const newBalance = lastGrant.balance - remainingToConsume
+
+    await updateGrantBalance({
+      userId,
+      grant: lastGrant,
+      consumed: remainingToConsume,
+      newBalance,
+      tx,
+      logger,
+    })
+    consumed += remainingToConsume
+    lastGrant.balance = newBalance
 
-    if (lastGrant.balance <= 0) {
-      const newBalance = lastGrant.balance - remainingToConsume
-      await updateGrantBalance({
+    logger.warn(
+      {
         userId,
-        grant: lastGrant,
+        grantId: lastGrant.operation_id,
+        requested: remainingToConsume,
         consumed: remainingToConsume,
-        newBalance,
-        tx,
-        logger,
-      })
-      consumed += remainingToConsume
-
-      logger.warn(
-        {
-          userId,
-          grantId: lastGrant.operation_id,
-          requested: remainingToConsume,
-          consumed: remainingToConsume,
-          newDebt: Math.abs(newBalance),
-        },
-        'Created new debt in grant',
-      )
-    }
+        newDebt: Math.abs(newBalance),
+      },
+      'Created/extended debt in grant',
+    )
   }
 
   return { consumed, fromPurchased }
@@ -789,7 +770,7 @@ describe('Balance Calculator - Integration Tests (Real DB)', () => {
       expect(grant3Balance).toBe(100) // Untouched
     })
 
-    it('should repay debt when consuming from grants with negative balance', async () => {
+    it('should not forgive debt when consuming from a positive grant (debt stays untouched)', async () => {
       const db = getTestDb()
       const now = new Date()
 
@@ -820,14 +801,10 @@ describe('Balance Calculator - Integration Tests (Real DB)', () => {
         conn: db,
       })
 
-      // Consume 80 credits
-      // The consumption algorithm works as follows:
-      // 1. First pass (debt repayment): Uses creditsToConsume to repay debt
-      //    - debt-grant has -50, repay 50 from the 80 requested, debt becomes 0
-      //    - remainingToConsume = 30, consumed = 50
-      // 2. Second pass (consumption): Consumes from positive balances
-      //    - positive-grant has 100, consume 30, becomes 70
-      //    - remainingToConsume = 0, consumed = 80
+      // Consume 80 credits.
+      // Consumption only drains positive balances. Debt grants are untouched.
+      // positive-grant (priority 10, consumed first): 100 - 80 = 20
+      // debt-grant (priority 60): stays at -50 (debt is NOT "repaid" by consumption)
       const result = await consumeFromOrderedGrants({
         userId: TEST_USER_ID,
         creditsToConsume: 80,
@@ -842,10 +819,10 @@ describe('Balance Calculator - Integration Tests (Real DB)', () => {
       const debtGrantBalance = await getGrantBalance('e2e-debt-grant')
       const positiveGrantBalance = await getGrantBalance('e2e-positive-grant')
 
-      // Debt should be repaid: -50 + 50 = 0
-      expect(debtGrantBalance).toBe(0)
-      // Positive grant: 100 - 30 (consume after debt repayment) = 70
-      expect(positiveGrantBalance).toBe(70)
+      // Debt must be untouched — consumption does not repay debt
+      expect(debtGrantBalance).toBe(-50)
+      // Positive grant: 100 - 80 = 20
+      expect(positiveGrantBalance).toBe(20)
     })
 
     it('should track purchased credits consumption correctly', async () => {