@wopr-network/platform-core 1.39.6 → 1.40.0

package/dist/billing/stripe/stripe-payment-processor.test.js

@@ -62,6 +62,7 @@ function createMocks() {
         existsByReferenceIdLike: vi.fn(),
         sumPurchasesForPeriod: vi.fn(),
         getActiveTenantIdsInWindow: vi.fn(),
+        debitCapped: vi.fn(),
     };
     const autoTopupEventLog = {
         writeEvent: vi.fn(),

package/dist/credits/credit-expiry-cron.js

@@ -1,5 +1,4 @@
 import { logger } from "../config/logger.js";
-import { InsufficientBalanceError } from "./ledger.js";
 /**
  * Sweep expired credit grants and debit the original grant amount
  * (or remaining balance if partially consumed).
@@ -16,31 +15,26 @@ export async function runCreditExpiryCron(cfg) {
     const expiredGrants = await cfg.ledger.expiredCredits(cfg.now);
     for (const grant of expiredGrants) {
         try {
-            const balance = await cfg.ledger.balance(grant.tenantId);
-            if (balance.isZero()) {
-                result.skippedZeroBalance++;
-                continue;
-            }
-            // Debit the lesser of the original grant amount or current balance
-            const debitAmount = balance.lessThan(grant.amount) ? balance : grant.amount;
-            await cfg.ledger.debit(grant.tenantId, debitAmount, "credit_expiry", {
+            // debitCapped never throws InsufficientBalanceError — it caps at the
+            // available balance and returns null when balance is zero. The catch
+            // below handles unexpected errors (DB failures, constraint violations).
+            const entry = await cfg.ledger.debitCapped(grant.tenantId, grant.amount, "credit_expiry", {
                 description: `Expired credit grant reclaimed: ${grant.entryId}`,
                 referenceId: `expiry:${grant.entryId}`,
             });
+            if (entry === null) {
+                result.skippedZeroBalance++;
+                continue;
+            }
             result.processed++;
             if (!result.expired.includes(grant.tenantId)) {
                 result.expired.push(grant.tenantId);
             }
         }
         catch (err) {
-            if (err instanceof InsufficientBalanceError) {
-                result.skippedZeroBalance++;
-            }
-            else {
-                const msg = err instanceof Error ? err.message : String(err);
-                logger.error("Credit expiry failed", { tenantId: grant.tenantId, entryId: grant.entryId, error: msg });
-                result.errors.push(`${grant.tenantId}:${grant.entryId}: ${msg}`);
-            }
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error("Credit expiry failed", { tenantId: grant.tenantId, entryId: grant.entryId, error: msg });
+            result.errors.push(`${grant.tenantId}:${grant.entryId}: ${msg}`);
         }
     }
     if (result.processed > 0) {

package/dist/credits/ledger.d.ts

@@ -154,6 +154,12 @@ export interface ILedger {
     sumPurchasesForPeriod(startTs: string, endTs: string): Promise<Credit>;
     /** Get distinct tenantIds with a purchase entry in [startTs, endTs). */
     getActiveTenantIdsInWindow(startTs: string, endTs: string): Promise<string[]>;
+    /**
+     * Debit up to maxAmount from a tenant, capped at their current balance.
+     * Reads balance inside the transaction (TOCTOU-safe). Returns null if
+     * balance is zero (nothing to debit).
+     */
+    debitCapped(tenantId: string, maxAmount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry | null>;
 }
 export declare class DrizzleLedger implements ILedger {
     private readonly db;
@@ -177,6 +183,7 @@ export declare class DrizzleLedger implements ILedger {
     post(input: PostEntryInput): Promise<JournalEntry>;
     credit(tenantId: string, amount: Credit, type: CreditType, opts?: CreditOpts): Promise<JournalEntry>;
     debit(tenantId: string, amount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry>;
+    debitCapped(tenantId: string, maxAmount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry | null>;
     balance(tenantId: string): Promise<Credit>;
     accountBalance(accountCode: string): Promise<Credit>;
     hasReferenceId(referenceId: string): Promise<boolean>;

package/dist/credits/ledger.js

@@ -327,6 +327,112 @@ export class DrizzleLedger {
             ],
         });
     }
+    async debitCapped(tenantId, maxAmount, type, opts) {
+        const creditAccountCode = DEBIT_TYPE_ACCOUNT[type];
+        const tenantAccountCode = `2000:${tenantId}`;
+        // Everything happens inside ONE transaction so the FOR UPDATE lock is held
+        // continuously from balance read through journal posting (TOCTOU-safe).
+        return this.db.transaction(async (tx) => {
+            // Step 1: Lock BOTH accounts in accountCode-sorted order to match post()'s
+            // lock ordering and prevent ABBA deadlocks. For type="refund" the credit
+            // account is "1000" which sorts before "2000:<tenant>", so we must lock it
+            // first — the same order post() would use.
+            const sortedCodes = [tenantAccountCode, creditAccountCode].sort();
+            const lockedIds = new Map();
+            for (const code of sortedCodes) {
+                if (code.startsWith("2000:")) {
+                    lockedIds.set(code, await this.ensureTenantAccountLocked(tx, code.slice(5)));
+                }
+                else {
+                    lockedIds.set(code, await this.resolveAccountLocked(tx, code));
+                }
+            }
+            const tenantAccountId = lockedIds.get(tenantAccountCode);
+            const creditAccountId = lockedIds.get(creditAccountCode);
+            if (!tenantAccountId || !creditAccountId) {
+                throw new Error("Failed to resolve account IDs during debitCapped");
+            }
+            // Step 2: Read balance while holding the lock.
+            const balRows = (await tx.execute(sql `SELECT ab.balance FROM account_balances ab
+            INNER JOIN accounts a ON a.id = ab.account_id
+            WHERE a.code = ${tenantAccountCode}`));
+            const currentBalance = Credit.fromRaw(Number(balRows.rows[0]?.balance ?? 0));
+            if (currentBalance.isZero()) {
+                return null;
+            }
+            // Step 3: Cap at lesser of maxAmount and currentBalance.
+            const debitAmount = currentBalance.lessThan(maxAmount) ? currentBalance : maxAmount;
+            // Step 4: Insert journal entry header.
+            const entryId = crypto.randomUUID();
+            const now = new Date().toISOString();
+            await tx.insert(journalEntries).values({
+                id: entryId,
+                postedAt: now,
+                entryType: type,
+                description: opts?.description ?? null,
+                referenceId: opts?.referenceId ?? null,
+                tenantId,
+                metadata: { attributedUserId: opts?.attributedUserId ?? null },
+                createdBy: opts?.createdBy ?? "system",
+            });
+            // Step 5: Both accounts already locked in step 1 — no additional locking needed.
+            // Step 6: Insert journal lines.
+            // Debit line (tenant liability account — reduces balance)
+            const debitLineId = crypto.randomUUID();
+            await tx.insert(journalLines).values({
+                id: debitLineId,
+                journalEntryId: entryId,
+                accountId: tenantAccountId,
+                amount: debitAmount.toRaw(),
+                side: "debit",
+            });
+            // Credit line (revenue/target account — increases balance)
+            const creditLineId = crypto.randomUUID();
+            await tx.insert(journalLines).values({
+                id: creditLineId,
+                journalEntryId: entryId,
+                accountId: creditAccountId,
+                amount: debitAmount.toRaw(),
+                side: "credit",
+            });
+            // Step 7: Update materialized balances.
+            // Tenant account is liability (normal_side=credit): debit decreases balance.
+            await tx
+                .update(accountBalances)
+                .set({
+                balance: sql `${accountBalances.balance} + ${-debitAmount.toRaw()}`,
+                lastUpdated: sql `(now())`,
+            })
+                .where(eq(accountBalances.accountId, tenantAccountId));
+            // Credit-side account: look up its normal_side to determine delta direction.
+            const acctRow = (await tx.execute(sql `SELECT normal_side FROM accounts WHERE id = ${creditAccountId}`));
+            const normalSide = acctRow.rows[0]?.normal_side;
+            if (!normalSide)
+                throw new Error(`Account ${creditAccountId} missing normal_side`);
+            const creditDelta = "credit" === normalSide ? debitAmount.toRaw() : -debitAmount.toRaw();
+            await tx
+                .update(accountBalances)
+                .set({
+                balance: sql `${accountBalances.balance} + ${creditDelta}`,
+                lastUpdated: sql `(now())`,
+            })
+                .where(eq(accountBalances.accountId, creditAccountId));
+            // Step 8: Return the journal entry.
+            return {
+                id: entryId,
+                postedAt: now,
+                entryType: type,
+                tenantId,
+                description: opts?.description ?? null,
+                referenceId: opts?.referenceId ?? null,
+                metadata: { attributedUserId: opts?.attributedUserId ?? null },
+                lines: [
+                    { accountCode: tenantAccountCode, amount: debitAmount, side: "debit" },
+                    { accountCode: creditAccountCode, amount: debitAmount, side: "credit" },
+                ],
+            };
+        });
+    }
     // -- Queries -------------------------------------------------------------
     async balance(tenantId) {
         const code = `2000:${tenantId}`;

package/dist/credits/ledger.test.js

@@ -578,4 +578,60 @@ describe("DrizzleLedger", () => {
             expect(tb.balanced).toBe(true);
         });
     });
+    // -----------------------------------------------------------------------
+    // debitCapped()
+    // -----------------------------------------------------------------------
+    describe("debitCapped()", () => {
+        it("caps debit at current balance when maxAmount exceeds balance", async () => {
+            await ledger.credit("tenant-cap", Credit.fromCents(300), "promo", {
+                description: "Test grant",
+            });
+            const entry = await ledger.debitCapped("tenant-cap", Credit.fromCents(500), // maxAmount > balance
+            "credit_expiry", { description: "Expiry test", referenceId: "expiry:test-cap" });
+            if (entry === null)
+                throw new Error("expected non-null entry");
+            // Should have debited 300 (the balance), not 500 (the maxAmount)
+            const debitLine = entry.lines.find((l) => l.accountCode === "2000:tenant-cap" && l.side === "debit");
+            if (!debitLine)
+                throw new Error("expected debit line");
+            expect(debitLine.amount.toCents()).toBe(300);
+            const balance = await ledger.balance("tenant-cap");
+            expect(balance.toCents()).toBe(0);
+        });
+        it("returns null when balance is zero", async () => {
+            const entry = await ledger.debitCapped("tenant-zero", Credit.fromCents(500), "credit_expiry", {
+                description: "Expiry test",
+                referenceId: "expiry:test-zero",
+            });
+            expect(entry).toBeNull();
+        });
+        it("debits exact maxAmount when balance exceeds it", async () => {
+            await ledger.credit("tenant-over", Credit.fromCents(1000), "purchase", {
+                description: "Big deposit",
+            });
+            const entry = await ledger.debitCapped("tenant-over", Credit.fromCents(300), "credit_expiry", {
+                description: "Partial expiry",
+                referenceId: "expiry:test-over",
+            });
+            if (entry === null)
+                throw new Error("expected non-null entry");
+            const debitLine = entry.lines.find((l) => l.accountCode === "2000:tenant-over" && l.side === "debit");
+            if (!debitLine)
+                throw new Error("expected debit line");
+            expect(debitLine.amount.toCents()).toBe(300);
+            const balance = await ledger.balance("tenant-over");
+            expect(balance.toCents()).toBe(700);
+        });
+        it("books balance correctly after capped debit (trial balance holds)", async () => {
+            await ledger.credit("tenant-tb", Credit.fromCents(200), "promo", {
+                description: "Small grant",
+            });
+            await ledger.debitCapped("tenant-tb", Credit.fromCents(500), "credit_expiry", {
+                description: "Expiry",
+                referenceId: "expiry:test-tb",
+            });
+            const tb = await ledger.trialBalance();
+            expect(tb.balanced).toBe(true);
+        });
+    });
 });

package/dist/db/schema/tenants.js

@@ -4,7 +4,7 @@ export const tenants = pgTable("tenants", {
     id: text("id").primaryKey(), // nanoid or crypto.randomUUID()
     name: text("name").notNull(),
     slug: text("slug").unique(),
-    type: text("type").notNull(), // "personal" | "org"
+    type: text("type").notNull(), // "personal" | "org" | "platform_service"
     ownerId: text("owner_id").notNull(), // user who created it
     billingEmail: text("billing_email"),
     createdAt: bigint("created_at", { mode: "number" })
@@ -14,5 +14,5 @@ export const tenants = pgTable("tenants", {
     index("idx_tenants_slug").on(table.slug),
     index("idx_tenants_owner").on(table.ownerId),
     index("idx_tenants_type").on(table.type),
-    check("chk_tenants_type", sql `${table.type} IN ('personal', 'org')`),
+    check("chk_tenants_type", sql `${table.type} IN ('personal', 'org', 'platform_service')`),
 ]);

package/dist/db/seed-platform-service-tenant.d.ts

@@ -0,0 +1,6 @@
+import type { DrizzleDb } from "./index.js";
+export interface PlatformServiceSeedResult {
+    tenantId: string;
+    serviceKey: string | null;
+}
+export declare function seedPlatformServiceTenant(db: DrizzleDb): Promise<PlatformServiceSeedResult>;

package/dist/db/seed-platform-service-tenant.js

@@ -0,0 +1,42 @@
+/**
+ * Idempotent seed: creates the holyship-platform internal billing tenant
+ * with a stable service key for platform-to-gateway LLM billing.
+ *
+ * Safe to call on every boot — skips if the tenant already exists.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { eq } from "drizzle-orm";
+import { gatewayServiceKeys } from "./schema/gateway-service-keys.js";
+import { tenants } from "./schema/tenants.js";
+const PLATFORM_TENANT_ID = "holyship-platform";
+const PLATFORM_TENANT_SLUG = "holyship-platform";
+const PLATFORM_INSTANCE_ID = "holyship-platform-internal";
+export async function seedPlatformServiceTenant(db) {
+    // Check if tenant already exists
+    const existing = await db.select({ id: tenants.id }).from(tenants).where(eq(tenants.id, PLATFORM_TENANT_ID)).limit(1);
+    if (existing.length > 0) {
+        return { tenantId: PLATFORM_TENANT_ID, serviceKey: null };
+    }
+    // Create the platform_service tenant
+    await db.insert(tenants).values({
+        id: PLATFORM_TENANT_ID,
+        name: "Holy Ship Platform",
+        slug: PLATFORM_TENANT_SLUG,
+        type: "platform_service",
+        ownerId: "system",
+        billingEmail: null,
+        createdAt: Date.now(),
+    });
+    // Generate a service key and store its hash
+    const rawKey = `sk-hs-${randomBytes(24).toString("hex")}`;
+    const keyHash = createHash("sha256").update(rawKey).digest("hex");
+    await db.insert(gatewayServiceKeys).values({
+        id: crypto.randomUUID(),
+        keyHash,
+        tenantId: PLATFORM_TENANT_ID,
+        instanceId: PLATFORM_INSTANCE_ID,
+        createdAt: Date.now(),
+        revokedAt: null,
+    });
+    return { tenantId: PLATFORM_TENANT_ID, serviceKey: rawKey };
+}

package/dist/monetization/stripe/stripe-payment-processor.test.js

@@ -62,6 +62,7 @@ function createMocks() {
         existsByReferenceIdLike: vi.fn(),
         sumPurchasesForPeriod: vi.fn(),
         getActiveTenantIdsInWindow: vi.fn(),
+        debitCapped: vi.fn(),
     };
     const replayGuard = {
         isDuplicate: vi.fn(),

package/drizzle/migrations/0013_platform_service_tenant_type.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "tenants" DROP CONSTRAINT "chk_tenants_type";
+--> statement-breakpoint
+ALTER TABLE "tenants" ADD CONSTRAINT "chk_tenants_type" CHECK ("tenants"."type" IN ('personal', 'org', 'platform_service'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.39.6",
+  "version": "1.40.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/billing/stripe/stripe-payment-processor.test.ts

@@ -76,6 +76,7 @@ function createMocks() {
     existsByReferenceIdLike: vi.fn(),
     sumPurchasesForPeriod: vi.fn(),
     getActiveTenantIdsInWindow: vi.fn(),
+    debitCapped: vi.fn(),
   };
 
   const autoTopupEventLog: IAutoTopupEventLogRepository = {

package/src/credits/credit-expiry-cron.ts

@@ -1,6 +1,5 @@
 import { logger } from "../config/logger.js";
 import type { ILedger } from "./ledger.js";
-import { InsufficientBalanceError } from "./ledger.js";
 
 export interface CreditExpiryCronConfig {
   ledger: ILedger;
@@ -33,32 +32,27 @@ export async function runCreditExpiryCron(cfg: CreditExpiryCronConfig): Promise<
 
   for (const grant of expiredGrants) {
     try {
-      const balance = await cfg.ledger.balance(grant.tenantId);
-      if (balance.isZero()) {
-        result.skippedZeroBalance++;
-        continue;
-      }
-
-      // Debit the lesser of the original grant amount or current balance
-      const debitAmount = balance.lessThan(grant.amount) ? balance : grant.amount;
-
-      await cfg.ledger.debit(grant.tenantId, debitAmount, "credit_expiry", {
+      // debitCapped never throws InsufficientBalanceError — it caps at the
+      // available balance and returns null when balance is zero. The catch
+      // below handles unexpected errors (DB failures, constraint violations).
+      const entry = await cfg.ledger.debitCapped(grant.tenantId, grant.amount, "credit_expiry", {
         description: `Expired credit grant reclaimed: ${grant.entryId}`,
         referenceId: `expiry:${grant.entryId}`,
       });
 
+      if (entry === null) {
+        result.skippedZeroBalance++;
+        continue;
+      }
+
       result.processed++;
       if (!result.expired.includes(grant.tenantId)) {
         result.expired.push(grant.tenantId);
       }
     } catch (err) {
-      if (err instanceof InsufficientBalanceError) {
-        result.skippedZeroBalance++;
-      } else {
-        const msg = err instanceof Error ? err.message : String(err);
-        logger.error("Credit expiry failed", { tenantId: grant.tenantId, entryId: grant.entryId, error: msg });
-        result.errors.push(`${grant.tenantId}:${grant.entryId}: ${msg}`);
-      }
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.error("Credit expiry failed", { tenantId: grant.tenantId, entryId: grant.entryId, error: msg });
+      result.errors.push(`${grant.tenantId}:${grant.entryId}: ${msg}`);
     }
   }
 

package/src/credits/ledger.test.ts

@@ -714,4 +714,74 @@ describe("DrizzleLedger", () => {
       expect(tb.balanced).toBe(true);
     });
   });
+
+  // -----------------------------------------------------------------------
+  // debitCapped()
+  // -----------------------------------------------------------------------
+
+  describe("debitCapped()", () => {
+    it("caps debit at current balance when maxAmount exceeds balance", async () => {
+      await ledger.credit("tenant-cap", Credit.fromCents(300), "promo", {
+        description: "Test grant",
+      });
+
+      const entry = await ledger.debitCapped(
+        "tenant-cap",
+        Credit.fromCents(500), // maxAmount > balance
+        "credit_expiry",
+        { description: "Expiry test", referenceId: "expiry:test-cap" },
+      );
+
+      if (entry === null) throw new Error("expected non-null entry");
+      // Should have debited 300 (the balance), not 500 (the maxAmount)
+      const debitLine = entry.lines.find((l) => l.accountCode === "2000:tenant-cap" && l.side === "debit");
+      if (!debitLine) throw new Error("expected debit line");
+      expect(debitLine.amount.toCents()).toBe(300);
+
+      const balance = await ledger.balance("tenant-cap");
+      expect(balance.toCents()).toBe(0);
+    });
+
+    it("returns null when balance is zero", async () => {
+      const entry = await ledger.debitCapped("tenant-zero", Credit.fromCents(500), "credit_expiry", {
+        description: "Expiry test",
+        referenceId: "expiry:test-zero",
+      });
+
+      expect(entry).toBeNull();
+    });
+
+    it("debits exact maxAmount when balance exceeds it", async () => {
+      await ledger.credit("tenant-over", Credit.fromCents(1000), "purchase", {
+        description: "Big deposit",
+      });
+
+      const entry = await ledger.debitCapped("tenant-over", Credit.fromCents(300), "credit_expiry", {
+        description: "Partial expiry",
+        referenceId: "expiry:test-over",
+      });
+
+      if (entry === null) throw new Error("expected non-null entry");
+      const debitLine = entry.lines.find((l) => l.accountCode === "2000:tenant-over" && l.side === "debit");
+      if (!debitLine) throw new Error("expected debit line");
+      expect(debitLine.amount.toCents()).toBe(300);
+
+      const balance = await ledger.balance("tenant-over");
+      expect(balance.toCents()).toBe(700);
+    });
+
+    it("books balance correctly after capped debit (trial balance holds)", async () => {
+      await ledger.credit("tenant-tb", Credit.fromCents(200), "promo", {
+        description: "Small grant",
+      });
+
+      await ledger.debitCapped("tenant-tb", Credit.fromCents(500), "credit_expiry", {
+        description: "Expiry",
+        referenceId: "expiry:test-tb",
+      });
+
+      const tb = await ledger.trialBalance();
+      expect(tb.balanced).toBe(true);
+    });
+  });
 });

package/src/credits/ledger.ts

@@ -281,6 +281,13 @@ export interface ILedger {
 
   /** Get distinct tenantIds with a purchase entry in [startTs, endTs). */
   getActiveTenantIdsInWindow(startTs: string, endTs: string): Promise<string[]>;
+
+  /**
+   * Debit up to maxAmount from a tenant, capped at their current balance.
+   * Reads balance inside the transaction (TOCTOU-safe). Returns null if
+   * balance is zero (nothing to debit).
+   */
+  debitCapped(tenantId: string, maxAmount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry | null>;
 }
 
 // ---------------------------------------------------------------------------
@@ -463,7 +470,9 @@ export class DrizzleLedger implements ILedger {
         // We store balance in "normal" direction, so:
         const acctRow = (await tx.execute(
           sql`SELECT normal_side FROM accounts WHERE id = ${accountId}`,
-        )) as unknown as { rows: Array<{ normal_side: Side }> };
+        )) as unknown as {
+          rows: Array<{ normal_side: Side }>;
+        };
         const normalSide = acctRow.rows[0]?.normal_side;
         if (!normalSide) throw new Error(`Account ${accountId} missing normal_side`);
 
@@ -553,6 +562,136 @@ export class DrizzleLedger implements ILedger {
     });
   }
 
+  async debitCapped(
+    tenantId: string,
+    maxAmount: Credit,
+    type: DebitType,
+    opts?: DebitOpts,
+  ): Promise<JournalEntry | null> {
+    const creditAccountCode = DEBIT_TYPE_ACCOUNT[type];
+    const tenantAccountCode = `2000:${tenantId}`;
+
+    // Everything happens inside ONE transaction so the FOR UPDATE lock is held
+    // continuously from balance read through journal posting (TOCTOU-safe).
+    return this.db.transaction(async (tx) => {
+      // Step 1: Lock BOTH accounts in accountCode-sorted order to match post()'s
+      // lock ordering and prevent ABBA deadlocks. For type="refund" the credit
+      // account is "1000" which sorts before "2000:<tenant>", so we must lock it
+      // first — the same order post() would use.
+      const sortedCodes = [tenantAccountCode, creditAccountCode].sort();
+      const lockedIds = new Map<string, string>();
+      for (const code of sortedCodes) {
+        if (code.startsWith("2000:")) {
+          lockedIds.set(code, await this.ensureTenantAccountLocked(tx, code.slice(5)));
+        } else {
+          lockedIds.set(code, await this.resolveAccountLocked(tx, code));
+        }
+      }
+      const tenantAccountId = lockedIds.get(tenantAccountCode);
+      const creditAccountId = lockedIds.get(creditAccountCode);
+      if (!tenantAccountId || !creditAccountId) {
+        throw new Error("Failed to resolve account IDs during debitCapped");
+      }
+
+      // Step 2: Read balance while holding the lock.
+      const balRows = (await tx.execute(
+        sql`SELECT ab.balance FROM account_balances ab
+            INNER JOIN accounts a ON a.id = ab.account_id
+            WHERE a.code = ${tenantAccountCode}`,
+      )) as unknown as { rows: Array<{ balance: number }> };
+      const currentBalance = Credit.fromRaw(Number(balRows.rows[0]?.balance ?? 0));
+
+      if (currentBalance.isZero()) {
+        return null;
+      }
+
+      // Step 3: Cap at lesser of maxAmount and currentBalance.
+      const debitAmount = currentBalance.lessThan(maxAmount) ? currentBalance : maxAmount;
+
+      // Step 4: Insert journal entry header.
+      const entryId = crypto.randomUUID();
+      const now = new Date().toISOString();
+
+      await tx.insert(journalEntries).values({
+        id: entryId,
+        postedAt: now,
+        entryType: type,
+        description: opts?.description ?? null,
+        referenceId: opts?.referenceId ?? null,
+        tenantId,
+        metadata: { attributedUserId: opts?.attributedUserId ?? null },
+        createdBy: opts?.createdBy ?? "system",
+      });
+
+      // Step 5: Both accounts already locked in step 1 — no additional locking needed.
+
+      // Step 6: Insert journal lines.
+      // Debit line (tenant liability account — reduces balance)
+      const debitLineId = crypto.randomUUID();
+      await tx.insert(journalLines).values({
+        id: debitLineId,
+        journalEntryId: entryId,
+        accountId: tenantAccountId,
+        amount: debitAmount.toRaw(),
+        side: "debit",
+      });
+
+      // Credit line (revenue/target account — increases balance)
+      const creditLineId = crypto.randomUUID();
+      await tx.insert(journalLines).values({
+        id: creditLineId,
+        journalEntryId: entryId,
+        accountId: creditAccountId,
+        amount: debitAmount.toRaw(),
+        side: "credit",
+      });
+
+      // Step 7: Update materialized balances.
+      // Tenant account is liability (normal_side=credit): debit decreases balance.
+      await tx
+        .update(accountBalances)
+        .set({
+          balance: sql`${accountBalances.balance} + ${-debitAmount.toRaw()}`,
+          lastUpdated: sql`(now())`,
+        })
+        .where(eq(accountBalances.accountId, tenantAccountId));
+
+      // Credit-side account: look up its normal_side to determine delta direction.
+      const acctRow = (await tx.execute(
+        sql`SELECT normal_side FROM accounts WHERE id = ${creditAccountId}`,
+      )) as unknown as {
+        rows: Array<{ normal_side: Side }>;
+      };
+      const normalSide = acctRow.rows[0]?.normal_side;
+      if (!normalSide) throw new Error(`Account ${creditAccountId} missing normal_side`);
+
+      const creditDelta = "credit" === normalSide ? debitAmount.toRaw() : -debitAmount.toRaw();
+
+      await tx
+        .update(accountBalances)
+        .set({
+          balance: sql`${accountBalances.balance} + ${creditDelta}`,
+          lastUpdated: sql`(now())`,
+        })
+        .where(eq(accountBalances.accountId, creditAccountId));
+
+      // Step 8: Return the journal entry.
+      return {
+        id: entryId,
+        postedAt: now,
+        entryType: type,
+        tenantId,
+        description: opts?.description ?? null,
+        referenceId: opts?.referenceId ?? null,
+        metadata: { attributedUserId: opts?.attributedUserId ?? null } as Record<string, unknown>,
+        lines: [
+          { accountCode: tenantAccountCode, amount: debitAmount, side: "debit" as Side },
+          { accountCode: creditAccountCode, amount: debitAmount, side: "credit" as Side },
+        ],
+      };
+    });
+  }
+
   // -- Queries -------------------------------------------------------------
 
   async balance(tenantId: string): Promise<Credit> {

package/src/db/schema/tenants.ts

@@ -7,7 +7,7 @@ export const tenants = pgTable(
     id: text("id").primaryKey(), // nanoid or crypto.randomUUID()
     name: text("name").notNull(),
     slug: text("slug").unique(),
-    type: text("type").notNull(), // "personal" | "org"
+    type: text("type").notNull(), // "personal" | "org" | "platform_service"
     ownerId: text("owner_id").notNull(), // user who created it
     billingEmail: text("billing_email"),
     createdAt: bigint("created_at", { mode: "number" })
@@ -18,6 +18,6 @@ export const tenants = pgTable(
     index("idx_tenants_slug").on(table.slug),
     index("idx_tenants_owner").on(table.ownerId),
     index("idx_tenants_type").on(table.type),
-    check("chk_tenants_type", sql`${table.type} IN ('personal', 'org')`),
+    check("chk_tenants_type", sql`${table.type} IN ('personal', 'org', 'platform_service')`),
   ],
 );

package/src/db/seed-platform-service-tenant.ts

@@ -0,0 +1,55 @@
+/**
+ * Idempotent seed: creates the holyship-platform internal billing tenant
+ * with a stable service key for platform-to-gateway LLM billing.
+ *
+ * Safe to call on every boot — skips if the tenant already exists.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { eq } from "drizzle-orm";
+import type { DrizzleDb } from "./index.js";
+import { gatewayServiceKeys } from "./schema/gateway-service-keys.js";
+import { tenants } from "./schema/tenants.js";
+
+const PLATFORM_TENANT_ID = "holyship-platform";
+const PLATFORM_TENANT_SLUG = "holyship-platform";
+const PLATFORM_INSTANCE_ID = "holyship-platform-internal";
+
+export interface PlatformServiceSeedResult {
+  tenantId: string;
+  serviceKey: string | null; // null if tenant + key already existed
+}
+
+export async function seedPlatformServiceTenant(db: DrizzleDb): Promise<PlatformServiceSeedResult> {
+  // Check if tenant already exists
+  const existing = await db.select({ id: tenants.id }).from(tenants).where(eq(tenants.id, PLATFORM_TENANT_ID)).limit(1);
+
+  if (existing.length > 0) {
+    return { tenantId: PLATFORM_TENANT_ID, serviceKey: null };
+  }
+
+  // Create the platform_service tenant
+  await db.insert(tenants).values({
+    id: PLATFORM_TENANT_ID,
+    name: "Holy Ship Platform",
+    slug: PLATFORM_TENANT_SLUG,
+    type: "platform_service",
+    ownerId: "system",
+    billingEmail: null,
+    createdAt: Date.now(),
+  });
+
+  // Generate a service key and store its hash
+  const rawKey = `sk-hs-${randomBytes(24).toString("hex")}`;
+  const keyHash = createHash("sha256").update(rawKey).digest("hex");
+
+  await db.insert(gatewayServiceKeys).values({
+    id: crypto.randomUUID(),
+    keyHash,
+    tenantId: PLATFORM_TENANT_ID,
+    instanceId: PLATFORM_INSTANCE_ID,
+    createdAt: Date.now(),
+    revokedAt: null,
+  });
+
+  return { tenantId: PLATFORM_TENANT_ID, serviceKey: rawKey };
+}

package/src/monetization/stripe/stripe-payment-processor.test.ts

@@ -79,6 +79,7 @@ function createMocks() {
     existsByReferenceIdLike: vi.fn(),
     sumPurchasesForPeriod: vi.fn(),
     getActiveTenantIdsInWindow: vi.fn(),
+    debitCapped: vi.fn(),
   };
 
   const replayGuard: IWebhookSeenRepository = {