@wopr-network/platform-core 1.39.3 → 1.39.5

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

@@ -81,6 +81,36 @@ describe("runCreditExpiryCron", () => {
         const balanceAfterSecond = await ledger.balance("tenant-1");
         expect(balanceAfterSecond.toCents()).toBe(balanceAfterFirst.toCents());
     });
+    it("skips expiry when balance has been fully consumed before cron runs", async () => {
+        // Simulate: grant expires but tenant spent everything before cron ran
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+            description: "Promo",
+            referenceId: "promo:fully-consumed",
+            expiresAt: "2026-01-10T00:00:00Z",
+        });
+        // Tenant spends entire balance before expiry cron runs
+        await ledger.debit("tenant-1", Credit.fromCents(500), "bot_runtime", { description: "Full spend" });
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        // Zero balance — nothing to expire
+        expect(result.processed).toBe(0);
+        const balance = await ledger.balance("tenant-1");
+        expect(balance.toCents()).toBe(0);
+    });
+    it("only expires remaining balance when usage reduced it between grant and expiry", async () => {
+        // Grant $5, spend $3 before cron, cron should only expire remaining $2
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+            description: "Promo",
+            referenceId: "promo:partial-concurrent",
+            expiresAt: "2026-01-10T00:00:00Z",
+        });
+        await ledger.debit("tenant-1", Credit.fromCents(300), "bot_runtime", { description: "Partial spend" });
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result.processed).toBe(1);
+        expect(result.expired).toContain("tenant-1");
+        // $5 granted - $3 used - $2 expired = $0
+        const balance = await ledger.balance("tenant-1");
+        expect(balance.toCents()).toBe(0);
+    });
     it("does not return unknown entry type even with expiresAt metadata", async () => {
         // Simulate a hypothetical new entry type that has expiresAt in metadata.
         // With the old denylist approach, this would be incorrectly returned.

package/dist/credits/ledger.js

@@ -169,19 +169,25 @@ export class DrizzleLedger {
             throw new Error("Journal entry must have at least 2 lines");
         }
         // Verify balance before hitting DB
-        let totalDebit = 0;
-        let totalCredit = 0;
+        let totalDebit = 0n;
+        let totalCredit = 0n;
         for (const line of input.lines) {
             if (line.amount.isZero() || line.amount.isNegative()) {
                 throw new Error("Journal line amounts must be positive");
             }
             if (line.side === "debit")
-                totalDebit += line.amount.toRaw();
+                totalDebit += BigInt(line.amount.toRaw());
             else
-                totalCredit += line.amount.toRaw();
+                totalCredit += BigInt(line.amount.toRaw());
         }
         if (totalDebit !== totalCredit) {
-            throw new Error(`Unbalanced entry: debits=${Credit.fromRaw(totalDebit).toDisplayString()}, credits=${Credit.fromRaw(totalCredit).toDisplayString()}`);
+            const fmtDebit = totalDebit <= BigInt(Number.MAX_SAFE_INTEGER)
+                ? Credit.fromRaw(Number(totalDebit)).toDisplayString()
+                : `${totalDebit} raw`;
+            const fmtCredit = totalCredit <= BigInt(Number.MAX_SAFE_INTEGER)
+                ? Credit.fromRaw(Number(totalCredit)).toDisplayString()
+                : `${totalCredit} raw`;
+            throw new Error(`Unbalanced entry: debits=${fmtDebit}, credits=${fmtCredit}`);
         }
         return this.db.transaction(async (tx) => {
             const entryId = crypto.randomUUID();

package/dist/credits/ledger.test.js

@@ -38,6 +38,21 @@ describe("DrizzleLedger", () => {
                 ],
             })).rejects.toThrow("Unbalanced");
         });
+        it("throws Unbalanced entry (not RangeError) when BigInt totals exceed MAX_SAFE_INTEGER", async () => {
+            // Two debit lines each at MAX_SAFE_INTEGER raw — their BigInt sum exceeds MAX_SAFE_INTEGER.
+            // Before the fix, Credit.fromRaw(Number(totalDebit)) would throw RangeError, masking the real error.
+            const big = Credit.fromRaw(Number.MAX_SAFE_INTEGER);
+            const small = Credit.fromRaw(1);
+            await expect(ledger.post({
+                entryType: "purchase",
+                tenantId: "t1",
+                lines: [
+                    { accountCode: "1000", amount: big, side: "debit" },
+                    { accountCode: "1000", amount: big, side: "debit" },
+                    { accountCode: "2000:t1", amount: small, side: "credit" },
+                ],
+            })).rejects.toThrow("Unbalanced entry");
+        });
         it("rejects zero-amount lines", async () => {
             await expect(ledger.post({
                 entryType: "purchase",
@@ -209,6 +224,22 @@ describe("DrizzleLedger", () => {
         it("rejects zero amount", async () => {
             await expect(ledger.debit("t1", Credit.ZERO, "bot_runtime")).rejects.toThrow("must be positive");
         });
+        it("concurrent debits do not overdraft", async () => {
+            // Balance is $10.00 from beforeEach credit.
+            // Two concurrent $8 debits — only one should succeed.
+            const results = await Promise.allSettled([
+                ledger.debit("t1", Credit.fromCents(800), "bot_runtime"),
+                ledger.debit("t1", Credit.fromCents(800), "bot_runtime"),
+            ]);
+            const successes = results.filter((r) => r.status === "fulfilled");
+            const failures = results.filter((r) => r.status === "rejected");
+            expect(successes).toHaveLength(1);
+            expect(failures).toHaveLength(1);
+            expect(failures[0].reason).toBeInstanceOf(InsufficientBalanceError);
+            // Balance should be $2.00, not -$6.00
+            const bal = await ledger.balance("t1");
+            expect(bal.toCentsRounded()).toBe(200);
+        });
     });
     // -----------------------------------------------------------------------
     // balance()
@@ -268,6 +299,20 @@ describe("DrizzleLedger", () => {
             expect(tb.balanced).toBe(true);
             expect(tb.totalDebits.equals(tb.totalCredits)).toBe(true);
         });
+        it("detects imbalance from direct DB corruption", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase");
+            // Corrupt the ledger: insert an unmatched debit line directly into journal_lines.
+            const entryRows = await pool.query("SELECT id FROM journal_entries LIMIT 1");
+            const accountRows = await pool.query("SELECT id FROM accounts WHERE code = '1000' LIMIT 1");
+            const entryId = entryRows.rows[0].id;
+            const accountId = accountRows.rows[0].id;
+            // Insert an unmatched debit line worth 999 raw units — no corresponding credit
+            await pool.query(`INSERT INTO journal_lines (id, journal_entry_id, account_id, amount, side)
+         VALUES ('corrupt-line-1', $1, $2, 999, 'debit')`, [entryId, accountId]);
+            const tb = await ledger.trialBalance();
+            expect(tb.balanced).toBe(false);
+            expect(tb.difference.toRaw()).toBe(999);
+        });
     });
     // -----------------------------------------------------------------------
     // history()
@@ -491,4 +536,46 @@ describe("DrizzleLedger", () => {
             expect(tb.balanced).toBe(true);
         });
     });
+    // -----------------------------------------------------------------------
+    // deadlock prevention — concurrent multi-line entries
+    // -----------------------------------------------------------------------
+    describe("deadlock prevention", () => {
+        it("concurrent multi-line entries with overlapping accounts succeed", async () => {
+            // Fund two tenants
+            await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+            await ledger.credit("t2", Credit.fromCents(1000), "purchase");
+            // Two entries that touch accounts in potentially reverse order.
+            // Both touch account 4000 (revenue), creating a potential lock conflict.
+            const results = await Promise.allSettled([
+                ledger.debit("t1", Credit.fromCents(50), "bot_runtime"),
+                ledger.debit("t2", Credit.fromCents(30), "bot_runtime"),
+            ]);
+            // Both should succeed — lock ordering prevents deadlock
+            expect(results.every((r) => r.status === "fulfilled")).toBe(true);
+            // Verify balances are correct
+            expect((await ledger.balance("t1")).toCentsRounded()).toBe(950);
+            expect((await ledger.balance("t2")).toCentsRounded()).toBe(970);
+            // Revenue account should reflect both debits
+            expect((await ledger.accountBalance("4000")).toCentsRounded()).toBe(80);
+            // Trial balance must still be balanced
+            const tb = await ledger.trialBalance();
+            expect(tb.balanced).toBe(true);
+        });
+        it("concurrent multi-line entries on same tenant serialize correctly", async () => {
+            await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+            // Two debits on the same tenant, touching overlapping accounts.
+            const results = await Promise.allSettled([
+                ledger.debit("t1", Credit.fromCents(100), "bot_runtime"),
+                ledger.debit("t1", Credit.fromCents(200), "adapter_usage"),
+            ]);
+            expect(results.every((r) => r.status === "fulfilled")).toBe(true);
+            // Balance: $10 - $1 - $2 = $7
+            expect((await ledger.balance("t1")).toCentsRounded()).toBe(700);
+            // Revenue accounts
+            expect((await ledger.accountBalance("4000")).toCentsRounded()).toBe(100); // bot_runtime
+            expect((await ledger.accountBalance("4010")).toCentsRounded()).toBe(200); // adapter_usage
+            const tb = await ledger.trialBalance();
+            expect(tb.balanced).toBe(true);
+        });
+    });
 });

package/dist/db/schema/ledger.js

@@ -55,6 +55,9 @@ export const journalLines = pgTable("journal_lines", {
     accountId: text("account_id")
         .notNull()
         .references(() => accounts.id),
+    // mode: "number" truncates values > Number.MAX_SAFE_INTEGER (≈$9.007M in nanodollars).
+    // Credit.fromRaw() guards against this with a RangeError.
+    // If balances approach $9M, migrate to mode: "bigint" (returns string from Drizzle).
     amount: bigint("amount", { mode: "number" }).notNull(), // nanodollars, always positive
     side: entrySideEnum("side").notNull(),
 }, (table) => [
@@ -71,6 +74,9 @@ export const accountBalances = pgTable("account_balances", {
     accountId: text("account_id")
         .primaryKey()
         .references(() => accounts.id),
+    // mode: "number" truncates values > Number.MAX_SAFE_INTEGER (≈$9.007M in nanodollars).
+    // Credit.fromRaw() guards against this with a RangeError.
+    // If balances approach $9M, migrate to mode: "bigint" (returns string from Drizzle).
     balance: bigint("balance", { mode: "number" }).notNull().default(0), // net balance in nanodollars
     lastUpdated: text("last_updated").notNull().default(sql `(now())`),
 });

package/dist/monetization/credits/runtime-cron.js

@@ -59,69 +59,95 @@ export async function runRuntimeDeductions(cfg) {
     for (const { tenantId, balance } of tenants) {
         try {
             const runtimeRef = `runtime:${cfg.date}:${tenantId}`;
-            if (await cfg.ledger.hasReferenceId(runtimeRef)) {
-                result.skipped.push(tenantId);
-                continue;
-            }
+            const runtimeAlreadyBilled = await cfg.ledger.hasReferenceId(runtimeRef);
             const botCount = await cfg.getActiveBotCount(tenantId);
-            if (botCount <= 0)
+            if (botCount <= 0) {
+                if (runtimeAlreadyBilled)
+                    result.skipped.push(tenantId);
                 continue;
+            }
             const totalCost = DAILY_BOT_COST.multiply(botCount);
-            if (!balance.lessThan(totalCost)) {
-                // Full deduction
-                await cfg.ledger.debit(tenantId, totalCost, "bot_runtime", {
-                    description: `Daily runtime: ${botCount} bot(s) x $${DAILY_BOT_COST.toDollars().toFixed(2)}`,
-                    referenceId: runtimeRef,
-                });
-                // Debit resource tier surcharges (if any)
-                if (cfg.getResourceTierCosts) {
+            let didBillAnything = false;
+            // Bill runtime debit (skipped if already billed on a previous run)
+            if (!runtimeAlreadyBilled) {
+                if (!balance.lessThan(totalCost)) {
+                    // Full deduction
+                    await cfg.ledger.debit(tenantId, totalCost, "bot_runtime", {
+                        description: `Daily runtime: ${botCount} bot(s) x $${DAILY_BOT_COST.toDollars().toFixed(2)}`,
+                        referenceId: runtimeRef,
+                    });
+                }
+                else {
+                    // Partial deduction — balance insufficient to cover full cost; debit what's available and suspend
+                    if (balance.greaterThan(Credit.ZERO)) {
+                        await cfg.ledger.debit(tenantId, balance, "bot_runtime", {
+                            description: `Partial daily runtime (balance exhausted): ${botCount} bot(s)`,
+                            referenceId: runtimeRef,
+                        });
+                    }
+                    if (!result.suspended.includes(tenantId)) {
+                        result.suspended.push(tenantId);
+                        if (cfg.onSuspend)
+                            await cfg.onSuspend(tenantId);
+                    }
+                }
+                didBillAnything = true;
+            }
+            // Debit resource tier surcharges (if any) — independent idempotency
+            if (cfg.getResourceTierCosts) {
+                const tierRef = `runtime-tier:${cfg.date}:${tenantId}`;
+                if (!(await cfg.ledger.hasReferenceId(tierRef))) {
                     const tierCost = await cfg.getResourceTierCosts(tenantId);
                     if (!tierCost.isZero()) {
                         const balanceAfterRuntime = await cfg.ledger.balance(tenantId);
                         if (!balanceAfterRuntime.lessThan(tierCost)) {
                             await cfg.ledger.debit(tenantId, tierCost, "resource_upgrade", {
                                 description: "Daily resource tier surcharge",
-                                referenceId: `runtime-tier:${cfg.date}:${tenantId}`,
+                                referenceId: tierRef,
                             });
                         }
                         else if (balanceAfterRuntime.greaterThan(Credit.ZERO)) {
                             await cfg.ledger.debit(tenantId, balanceAfterRuntime, "resource_upgrade", {
                                 description: "Partial resource tier surcharge (balance exhausted)",
-                                referenceId: `runtime-tier:${cfg.date}:${tenantId}`,
+                                referenceId: tierRef,
                             });
                         }
+                        didBillAnything = true;
                     }
                 }
-                const newBalance = await cfg.ledger.balance(tenantId);
-                // Fire onLowBalance if balance crossed below threshold from above
-                if (newBalance.greaterThan(Credit.ZERO) &&
-                    !newBalance.greaterThan(LOW_BALANCE_THRESHOLD) &&
-                    balance.greaterThan(LOW_BALANCE_THRESHOLD) &&
-                    cfg.onLowBalance) {
-                    await cfg.onLowBalance(tenantId, newBalance);
-                }
-                // Fire onCreditsExhausted if balance just hit 0
-                if (!newBalance.greaterThan(Credit.ZERO) && balance.greaterThan(Credit.ZERO) && cfg.onCreditsExhausted) {
-                    await cfg.onCreditsExhausted(tenantId);
-                }
-                // Suspend tenant when balance hits zero after full deduction (zero-crossing guard)
-                if (!newBalance.greaterThan(Credit.ZERO) &&
-                    balance.greaterThan(Credit.ZERO) &&
-                    !result.suspended.includes(tenantId)) {
-                    result.suspended.push(tenantId);
-                    if (cfg.onSuspend) {
-                        await cfg.onSuspend(tenantId);
-                    }
+            }
+            const newBalance = await cfg.ledger.balance(tenantId);
+            // Fire onLowBalance if balance crossed below threshold from above
+            if (newBalance.greaterThan(Credit.ZERO) &&
+                !newBalance.greaterThan(LOW_BALANCE_THRESHOLD) &&
+                balance.greaterThan(LOW_BALANCE_THRESHOLD) &&
+                cfg.onLowBalance) {
+                await cfg.onLowBalance(tenantId, newBalance);
+            }
+            // Fire onCreditsExhausted if balance just hit 0
+            if (!newBalance.greaterThan(Credit.ZERO) && balance.greaterThan(Credit.ZERO) && cfg.onCreditsExhausted) {
+                await cfg.onCreditsExhausted(tenantId);
+            }
+            // Suspend tenant when balance hits zero (zero-crossing guard)
+            if (!newBalance.greaterThan(Credit.ZERO) &&
+                balance.greaterThan(Credit.ZERO) &&
+                !result.suspended.includes(tenantId)) {
+                result.suspended.push(tenantId);
+                if (cfg.onSuspend) {
+                    await cfg.onSuspend(tenantId);
                 }
-                // Debit storage tier surcharges (if any)
-                if (cfg.getStorageTierCosts) {
+            }
+            // Debit storage tier surcharges (if any) — independent idempotency
+            if (cfg.getStorageTierCosts) {
+                const storageRef = `runtime-storage:${cfg.date}:${tenantId}`;
+                if (!(await cfg.ledger.hasReferenceId(storageRef))) {
                     const storageCost = await cfg.getStorageTierCosts(tenantId);
                     if (!storageCost.isZero()) {
                         const currentBalance = await cfg.ledger.balance(tenantId);
                         if (!currentBalance.lessThan(storageCost)) {
                             await cfg.ledger.debit(tenantId, storageCost, "storage_upgrade", {
                                 description: "Daily storage tier surcharge",
-                                referenceId: `runtime-storage:${cfg.date}:${tenantId}`,
+                                referenceId: storageRef,
                             });
                         }
                         else {
@@ -129,7 +155,7 @@ export async function runRuntimeDeductions(cfg) {
                             if (currentBalance.greaterThan(Credit.ZERO)) {
                                 await cfg.ledger.debit(tenantId, currentBalance, "storage_upgrade", {
                                     description: "Partial storage tier surcharge (balance exhausted)",
-                                    referenceId: `runtime-storage:${cfg.date}:${tenantId}`,
+                                    referenceId: storageRef,
                                 });
                             }
                             if (!result.suspended.includes(tenantId)) {
@@ -138,17 +164,21 @@ export async function runRuntimeDeductions(cfg) {
                                     await cfg.onSuspend(tenantId);
                             }
                         }
+                        didBillAnything = true;
                     }
                 }
-                // Debit infrastructure add-on costs (if any)
-                if (cfg.getAddonCosts) {
+            }
+            // Debit infrastructure add-on costs (if any) — independent idempotency
+            if (cfg.getAddonCosts) {
+                const addonRef = `runtime-addon:${cfg.date}:${tenantId}`;
+                if (!(await cfg.ledger.hasReferenceId(addonRef))) {
                     const addonCost = await cfg.getAddonCosts(tenantId);
                     if (!addonCost.isZero()) {
                         const currentBalance = await cfg.ledger.balance(tenantId);
                         if (!currentBalance.lessThan(addonCost)) {
                             await cfg.ledger.debit(tenantId, addonCost, "addon", {
                                 description: "Daily infrastructure add-on charges",
-                                referenceId: `runtime-addon:${cfg.date}:${tenantId}`,
+                                referenceId: addonRef,
                             });
                         }
                         else {
@@ -156,7 +186,7 @@ export async function runRuntimeDeductions(cfg) {
                             if (currentBalance.greaterThan(Credit.ZERO)) {
                                 await cfg.ledger.debit(tenantId, currentBalance, "addon", {
                                     description: "Partial add-on charges (balance exhausted)",
-                                    referenceId: `runtime-addon:${cfg.date}:${tenantId}`,
+                                    referenceId: addonRef,
                                 });
                             }
                             if (!result.suspended.includes(tenantId)) {
@@ -165,26 +195,16 @@ export async function runRuntimeDeductions(cfg) {
                                     await cfg.onSuspend(tenantId);
                             }
                         }
+                        didBillAnything = true;
                     }
                 }
             }
+            if (didBillAnything) {
+                result.processed++;
+            }
             else {
-                // Partial deduction — debit remaining balance, then suspend
-                if (balance.greaterThan(Credit.ZERO)) {
-                    await cfg.ledger.debit(tenantId, balance, "bot_runtime", {
-                        description: `Partial daily runtime (balance exhausted): ${botCount} bot(s)`,
-                        referenceId: runtimeRef,
-                    });
-                }
-                if (cfg.onCreditsExhausted) {
-                    await cfg.onCreditsExhausted(tenantId);
-                }
-                result.suspended.push(tenantId);
-                if (cfg.onSuspend) {
-                    await cfg.onSuspend(tenantId);
-                }
+                result.skipped.push(tenantId);
             }
-            result.processed++;
         }
         catch (err) {
             if (err instanceof InsufficientBalanceError) {

package/dist/monetization/credits/runtime-cron.test.js

@@ -314,4 +314,110 @@ describe("runRuntimeDeductions", () => {
         // Balance unchanged after second run
         expect((await ledger.balance("tenant-1")).toCents()).toBe(500 - 17);
     });
+    it("bills surcharges on retry when runtime was already billed (crash recovery)", async () => {
+        // Setup: tenant with enough balance for runtime + tier + storage + addon
+        await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+        const cfg = {
+            ledger,
+            date: "2025-07-01",
+            getActiveBotCount: async () => 1,
+            getResourceTierCosts: async () => Credit.fromCents(10),
+            getStorageTierCosts: async () => Credit.fromCents(8),
+            getAddonCosts: async () => Credit.fromCents(5),
+        };
+        // First run — bills everything
+        const first = await runRuntimeDeductions(cfg);
+        expect(first.processed).toBe(1);
+        // 1000 - 17 (runtime) - 10 (tier) - 8 (storage) - 5 (addon) = 960
+        expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+        // Second run — all already billed, should skip
+        const second = await runRuntimeDeductions(cfg);
+        expect(second.skipped).toContain("tenant-1");
+        expect(second.processed).toBe(0);
+        expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+    });
+    it("bills remaining surcharges when runtime was billed but surcharges were not (simulated crash)", async () => {
+        // Setup: tenant with enough balance
+        await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+        // Simulate crash: manually debit only the runtime charge (as if the cron crashed after this)
+        await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
+            description: "Daily runtime: 1 bot(s) x $0.17",
+            referenceId: `runtime:2025-07-02:tenant-1`,
+        });
+        expect((await ledger.balance("tenant-1")).toCents()).toBe(983); // 1000 - 17
+        // Retry run — runtime already billed, but surcharges should still be billed
+        const result = await runRuntimeDeductions({
+            ledger,
+            date: "2025-07-02",
+            getActiveBotCount: async () => 1,
+            getResourceTierCosts: async () => Credit.fromCents(10),
+            getStorageTierCosts: async () => Credit.fromCents(8),
+            getAddonCosts: async () => Credit.fromCents(5),
+        });
+        expect(result.processed).toBe(1);
+        expect(result.skipped).not.toContain("tenant-1");
+        // 983 - 10 (tier) - 8 (storage) - 5 (addon) = 960
+        expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+    });
+    it("bills only missing surcharges when some were already committed (simulated partial crash)", async () => {
+        await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+        // Simulate: runtime + tier already billed, storage + addon not yet
+        await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
+            description: "Daily runtime: 1 bot(s) x $0.17",
+            referenceId: `runtime:2025-07-03:tenant-1`,
+        });
+        await ledger.debit("tenant-1", Credit.fromCents(10), "resource_upgrade", {
+            description: "Daily resource tier surcharge",
+            referenceId: `runtime-tier:2025-07-03:tenant-1`,
+        });
+        expect((await ledger.balance("tenant-1")).toCents()).toBe(973); // 1000 - 17 - 10
+        const result = await runRuntimeDeductions({
+            ledger,
+            date: "2025-07-03",
+            getActiveBotCount: async () => 1,
+            getResourceTierCosts: async () => Credit.fromCents(10),
+            getStorageTierCosts: async () => Credit.fromCents(8),
+            getAddonCosts: async () => Credit.fromCents(5),
+        });
+        expect(result.processed).toBe(1);
+        // 973 - 8 (storage) - 5 (addon) = 960
+        expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+    });
+    it("does not double-debit runtime on retry after partial deduction + crash", async () => {
+        await ledger.credit("tenant-1", Credit.fromCents(10), "purchase", { description: "top-up" });
+        // Simulate: partial runtime debit already committed (balance was 10, cost was 17)
+        await ledger.debit("tenant-1", Credit.fromCents(10), "bot_runtime", {
+            description: "Partial daily runtime (balance exhausted): 1 bot(s)",
+            referenceId: `runtime:2025-07-04:tenant-1`,
+            allowNegative: true,
+        });
+        expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
+        // Retry — runtime already billed, balance is 0, nothing should happen
+        const result = await runRuntimeDeductions({
+            ledger,
+            date: "2025-07-04",
+            getActiveBotCount: async () => 1,
+        });
+        // Tenant still has 0 balance (tenantsWithBalance returns only positive), so won't be processed
+        expect(result.processed).toBe(0);
+        expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
+    });
+    it("trial balance remains balanced after crash-recovery billing", async () => {
+        await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+        // Simulate crash: only runtime billed
+        await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
+            description: "Daily runtime: 1 bot(s) x $0.17",
+            referenceId: `runtime:2025-07-05:tenant-1`,
+        });
+        // Retry — surcharges billed
+        await runRuntimeDeductions({
+            ledger,
+            date: "2025-07-05",
+            getActiveBotCount: async () => 1,
+            getResourceTierCosts: async () => Credit.fromCents(10),
+            getStorageTierCosts: async () => Credit.fromCents(8),
+        });
+        const tb = await ledger.trialBalance();
+        expect(tb.balanced).toBe(true);
+    });
 });

package/package.json

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

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

@@ -104,6 +104,42 @@ describe("runCreditExpiryCron", () => {
     expect(balanceAfterSecond.toCents()).toBe(balanceAfterFirst.toCents());
   });
 
+  it("skips expiry when balance has been fully consumed before cron runs", async () => {
+    // Simulate: grant expires but tenant spent everything before cron ran
+    await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+      description: "Promo",
+      referenceId: "promo:fully-consumed",
+      expiresAt: "2026-01-10T00:00:00Z",
+    });
+    // Tenant spends entire balance before expiry cron runs
+    await ledger.debit("tenant-1", Credit.fromCents(500), "bot_runtime", { description: "Full spend" });
+
+    const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+    // Zero balance — nothing to expire
+    expect(result.processed).toBe(0);
+
+    const balance = await ledger.balance("tenant-1");
+    expect(balance.toCents()).toBe(0);
+  });
+
+  it("only expires remaining balance when usage reduced it between grant and expiry", async () => {
+    // Grant $5, spend $3 before cron, cron should only expire remaining $2
+    await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+      description: "Promo",
+      referenceId: "promo:partial-concurrent",
+      expiresAt: "2026-01-10T00:00:00Z",
+    });
+    await ledger.debit("tenant-1", Credit.fromCents(300), "bot_runtime", { description: "Partial spend" });
+
+    const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+    expect(result.processed).toBe(1);
+    expect(result.expired).toContain("tenant-1");
+
+    // $5 granted - $3 used - $2 expired = $0
+    const balance = await ledger.balance("tenant-1");
+    expect(balance.toCents()).toBe(0);
+  });
+
   it("does not return unknown entry type even with expiresAt metadata", async () => {
     // Simulate a hypothetical new entry type that has expiresAt in metadata.
     // With the old denylist approach, this would be incorrectly returned.

package/src/credits/ledger.test.ts

@@ -53,6 +53,24 @@ describe("DrizzleLedger", () => {
       ).rejects.toThrow("Unbalanced");
     });
 
+    it("throws Unbalanced entry (not RangeError) when BigInt totals exceed MAX_SAFE_INTEGER", async () => {
+      // Two debit lines each at MAX_SAFE_INTEGER raw — their BigInt sum exceeds MAX_SAFE_INTEGER.
+      // Before the fix, Credit.fromRaw(Number(totalDebit)) would throw RangeError, masking the real error.
+      const big = Credit.fromRaw(Number.MAX_SAFE_INTEGER);
+      const small = Credit.fromRaw(1);
+      await expect(
+        ledger.post({
+          entryType: "purchase",
+          tenantId: "t1",
+          lines: [
+            { accountCode: "1000", amount: big, side: "debit" },
+            { accountCode: "1000", amount: big, side: "debit" },
+            { accountCode: "2000:t1", amount: small, side: "credit" },
+          ],
+        }),
+      ).rejects.toThrow("Unbalanced entry");
+    });
+
     it("rejects zero-amount lines", async () => {
       await expect(
         ledger.post({
@@ -260,6 +278,25 @@ describe("DrizzleLedger", () => {
     it("rejects zero amount", async () => {
       await expect(ledger.debit("t1", Credit.ZERO, "bot_runtime")).rejects.toThrow("must be positive");
     });
+
+    it("concurrent debits do not overdraft", async () => {
+      // Balance is $10.00 from beforeEach credit.
+      // Two concurrent $8 debits — only one should succeed.
+      const results = await Promise.allSettled([
+        ledger.debit("t1", Credit.fromCents(800), "bot_runtime"),
+        ledger.debit("t1", Credit.fromCents(800), "bot_runtime"),
+      ]);
+
+      const successes = results.filter((r) => r.status === "fulfilled");
+      const failures = results.filter((r) => r.status === "rejected");
+      expect(successes).toHaveLength(1);
+      expect(failures).toHaveLength(1);
+      expect((failures[0] as PromiseRejectedResult).reason).toBeInstanceOf(InsufficientBalanceError);
+
+      // Balance should be $2.00, not -$6.00
+      const bal = await ledger.balance("t1");
+      expect(bal.toCentsRounded()).toBe(200);
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -334,6 +371,27 @@ describe("DrizzleLedger", () => {
       expect(tb.balanced).toBe(true);
       expect(tb.totalDebits.equals(tb.totalCredits)).toBe(true);
     });
+
+    it("detects imbalance from direct DB corruption", async () => {
+      await ledger.credit("t1", Credit.fromCents(100), "purchase");
+
+      // Corrupt the ledger: insert an unmatched debit line directly into journal_lines.
+      const entryRows = await pool.query<{ id: string }>("SELECT id FROM journal_entries LIMIT 1");
+      const accountRows = await pool.query<{ id: string }>("SELECT id FROM accounts WHERE code = '1000' LIMIT 1");
+      const entryId = entryRows.rows[0].id;
+      const accountId = accountRows.rows[0].id;
+
+      // Insert an unmatched debit line worth 999 raw units — no corresponding credit
+      await pool.query(
+        `INSERT INTO journal_lines (id, journal_entry_id, account_id, amount, side)
+         VALUES ('corrupt-line-1', $1, $2, 999, 'debit')`,
+        [entryId, accountId],
+      );
+
+      const tb = await ledger.trialBalance();
+      expect(tb.balanced).toBe(false);
+      expect(tb.difference.toRaw()).toBe(999);
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -601,4 +659,59 @@ describe("DrizzleLedger", () => {
       expect(tb.balanced).toBe(true);
     });
   });
+
+  // -----------------------------------------------------------------------
+  // deadlock prevention — concurrent multi-line entries
+  // -----------------------------------------------------------------------
+
+  describe("deadlock prevention", () => {
+    it("concurrent multi-line entries with overlapping accounts succeed", async () => {
+      // Fund two tenants
+      await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+      await ledger.credit("t2", Credit.fromCents(1000), "purchase");
+
+      // Two entries that touch accounts in potentially reverse order.
+      // Both touch account 4000 (revenue), creating a potential lock conflict.
+      const results = await Promise.allSettled([
+        ledger.debit("t1", Credit.fromCents(50), "bot_runtime"),
+        ledger.debit("t2", Credit.fromCents(30), "bot_runtime"),
+      ]);
+
+      // Both should succeed — lock ordering prevents deadlock
+      expect(results.every((r) => r.status === "fulfilled")).toBe(true);
+
+      // Verify balances are correct
+      expect((await ledger.balance("t1")).toCentsRounded()).toBe(950);
+      expect((await ledger.balance("t2")).toCentsRounded()).toBe(970);
+
+      // Revenue account should reflect both debits
+      expect((await ledger.accountBalance("4000")).toCentsRounded()).toBe(80);
+
+      // Trial balance must still be balanced
+      const tb = await ledger.trialBalance();
+      expect(tb.balanced).toBe(true);
+    });
+
+    it("concurrent multi-line entries on same tenant serialize correctly", async () => {
+      await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+
+      // Two debits on the same tenant, touching overlapping accounts.
+      const results = await Promise.allSettled([
+        ledger.debit("t1", Credit.fromCents(100), "bot_runtime"),
+        ledger.debit("t1", Credit.fromCents(200), "adapter_usage"),
+      ]);
+
+      expect(results.every((r) => r.status === "fulfilled")).toBe(true);
+
+      // Balance: $10 - $1 - $2 = $7
+      expect((await ledger.balance("t1")).toCentsRounded()).toBe(700);
+
+      // Revenue accounts
+      expect((await ledger.accountBalance("4000")).toCentsRounded()).toBe(100); // bot_runtime
+      expect((await ledger.accountBalance("4010")).toCentsRounded()).toBe(200); // adapter_usage
+
+      const tb = await ledger.trialBalance();
+      expect(tb.balanced).toBe(true);
+    });
+  });
 });

package/src/credits/ledger.ts

@@ -372,19 +372,25 @@ export class DrizzleLedger implements ILedger {
     }
 
     // Verify balance before hitting DB
-    let totalDebit = 0;
-    let totalCredit = 0;
+    let totalDebit = 0n;
+    let totalCredit = 0n;
     for (const line of input.lines) {
       if (line.amount.isZero() || line.amount.isNegative()) {
         throw new Error("Journal line amounts must be positive");
       }
-      if (line.side === "debit") totalDebit += line.amount.toRaw();
-      else totalCredit += line.amount.toRaw();
+      if (line.side === "debit") totalDebit += BigInt(line.amount.toRaw());
+      else totalCredit += BigInt(line.amount.toRaw());
     }
     if (totalDebit !== totalCredit) {
-      throw new Error(
-        `Unbalanced entry: debits=${Credit.fromRaw(totalDebit).toDisplayString()}, credits=${Credit.fromRaw(totalCredit).toDisplayString()}`,
-      );
+      const fmtDebit =
+        totalDebit <= BigInt(Number.MAX_SAFE_INTEGER)
+          ? Credit.fromRaw(Number(totalDebit)).toDisplayString()
+          : `${totalDebit} raw`;
+      const fmtCredit =
+        totalCredit <= BigInt(Number.MAX_SAFE_INTEGER)
+          ? Credit.fromRaw(Number(totalCredit)).toDisplayString()
+          : `${totalCredit} raw`;
+      throw new Error(`Unbalanced entry: debits=${fmtDebit}, credits=${fmtCredit}`);
     }
 
     return this.db.transaction(async (tx) => {

package/src/db/schema/ledger.ts

@@ -70,6 +70,9 @@ export const journalLines = pgTable(
     accountId: text("account_id")
       .notNull()
       .references(() => accounts.id),
+    // mode: "number" truncates values > Number.MAX_SAFE_INTEGER (≈$9.007M in nanodollars).
+    // Credit.fromRaw() guards against this with a RangeError.
+    // If balances approach $9M, migrate to mode: "bigint" (returns string from Drizzle).
     amount: bigint("amount", { mode: "number" }).notNull(), // nanodollars, always positive
     side: entrySideEnum("side").notNull(),
   },
@@ -89,6 +92,9 @@ export const accountBalances = pgTable("account_balances", {
   accountId: text("account_id")
     .primaryKey()
     .references(() => accounts.id),
+  // mode: "number" truncates values > Number.MAX_SAFE_INTEGER (≈$9.007M in nanodollars).
+  // Credit.fromRaw() guards against this with a RangeError.
+  // If balances approach $9M, migrate to mode: "bigint" (returns string from Drizzle).
   balance: bigint("balance", { mode: "number" }).notNull().default(0), // net balance in nanodollars
   lastUpdated: text("last_updated").notNull().default(sql`(now())`),
 });

package/src/monetization/credits/runtime-cron.test.ts

@@ -356,4 +356,130 @@ describe("runRuntimeDeductions", () => {
     // Balance unchanged after second run
     expect((await ledger.balance("tenant-1")).toCents()).toBe(500 - 17);
   });
+
+  it("bills surcharges on retry when runtime was already billed (crash recovery)", async () => {
+    // Setup: tenant with enough balance for runtime + tier + storage + addon
+    await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+
+    const cfg = {
+      ledger,
+      date: "2025-07-01",
+      getActiveBotCount: async () => 1,
+      getResourceTierCosts: async () => Credit.fromCents(10),
+      getStorageTierCosts: async () => Credit.fromCents(8),
+      getAddonCosts: async () => Credit.fromCents(5),
+    };
+
+    // First run — bills everything
+    const first = await runRuntimeDeductions(cfg);
+    expect(first.processed).toBe(1);
+    // 1000 - 17 (runtime) - 10 (tier) - 8 (storage) - 5 (addon) = 960
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+
+    // Second run — all already billed, should skip
+    const second = await runRuntimeDeductions(cfg);
+    expect(second.skipped).toContain("tenant-1");
+    expect(second.processed).toBe(0);
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+  });
+
+  it("bills remaining surcharges when runtime was billed but surcharges were not (simulated crash)", async () => {
+    // Setup: tenant with enough balance
+    await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+
+    // Simulate crash: manually debit only the runtime charge (as if the cron crashed after this)
+    await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
+      description: "Daily runtime: 1 bot(s) x $0.17",
+      referenceId: `runtime:2025-07-02:tenant-1`,
+    });
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(983); // 1000 - 17
+
+    // Retry run — runtime already billed, but surcharges should still be billed
+    const result = await runRuntimeDeductions({
+      ledger,
+      date: "2025-07-02",
+      getActiveBotCount: async () => 1,
+      getResourceTierCosts: async () => Credit.fromCents(10),
+      getStorageTierCosts: async () => Credit.fromCents(8),
+      getAddonCosts: async () => Credit.fromCents(5),
+    });
+
+    expect(result.processed).toBe(1);
+    expect(result.skipped).not.toContain("tenant-1");
+    // 983 - 10 (tier) - 8 (storage) - 5 (addon) = 960
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+  });
+
+  it("bills only missing surcharges when some were already committed (simulated partial crash)", async () => {
+    await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+
+    // Simulate: runtime + tier already billed, storage + addon not yet
+    await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
+      description: "Daily runtime: 1 bot(s) x $0.17",
+      referenceId: `runtime:2025-07-03:tenant-1`,
+    });
+    await ledger.debit("tenant-1", Credit.fromCents(10), "resource_upgrade", {
+      description: "Daily resource tier surcharge",
+      referenceId: `runtime-tier:2025-07-03:tenant-1`,
+    });
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(973); // 1000 - 17 - 10
+
+    const result = await runRuntimeDeductions({
+      ledger,
+      date: "2025-07-03",
+      getActiveBotCount: async () => 1,
+      getResourceTierCosts: async () => Credit.fromCents(10),
+      getStorageTierCosts: async () => Credit.fromCents(8),
+      getAddonCosts: async () => Credit.fromCents(5),
+    });
+
+    expect(result.processed).toBe(1);
+    // 973 - 8 (storage) - 5 (addon) = 960
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+  });
+
+  it("does not double-debit runtime on retry after partial deduction + crash", async () => {
+    await ledger.credit("tenant-1", Credit.fromCents(10), "purchase", { description: "top-up" });
+
+    // Simulate: partial runtime debit already committed (balance was 10, cost was 17)
+    await ledger.debit("tenant-1", Credit.fromCents(10), "bot_runtime", {
+      description: "Partial daily runtime (balance exhausted): 1 bot(s)",
+      referenceId: `runtime:2025-07-04:tenant-1`,
+      allowNegative: true,
+    });
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
+
+    // Retry — runtime already billed, balance is 0, nothing should happen
+    const result = await runRuntimeDeductions({
+      ledger,
+      date: "2025-07-04",
+      getActiveBotCount: async () => 1,
+    });
+
+    // Tenant still has 0 balance (tenantsWithBalance returns only positive), so won't be processed
+    expect(result.processed).toBe(0);
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
+  });
+
+  it("trial balance remains balanced after crash-recovery billing", async () => {
+    await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+
+    // Simulate crash: only runtime billed
+    await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
+      description: "Daily runtime: 1 bot(s) x $0.17",
+      referenceId: `runtime:2025-07-05:tenant-1`,
+    });
+
+    // Retry — surcharges billed
+    await runRuntimeDeductions({
+      ledger,
+      date: "2025-07-05",
+      getActiveBotCount: async () => 1,
+      getResourceTierCosts: async () => Credit.fromCents(10),
+      getStorageTierCosts: async () => Credit.fromCents(8),
+    });
+
+    const tb = await ledger.trialBalance();
+    expect(tb.balanced).toBe(true);
+  });
 });

package/src/monetization/credits/runtime-cron.ts

@@ -110,87 +110,111 @@ export async function runRuntimeDeductions(cfg: RuntimeCronConfig): Promise<Runt
   for (const { tenantId, balance } of tenants) {
     try {
       const runtimeRef = `runtime:${cfg.date}:${tenantId}`;
-      if (await cfg.ledger.hasReferenceId(runtimeRef)) {
-        result.skipped.push(tenantId);
-        continue;
-      }
+      const runtimeAlreadyBilled = await cfg.ledger.hasReferenceId(runtimeRef);
 
       const botCount = await cfg.getActiveBotCount(tenantId);
-      if (botCount <= 0) continue;
+      if (botCount <= 0) {
+        if (runtimeAlreadyBilled) result.skipped.push(tenantId);
+        continue;
+      }
 
       const totalCost = DAILY_BOT_COST.multiply(botCount);
+      let didBillAnything = false;
 
-      if (!balance.lessThan(totalCost)) {
-        // Full deduction
-        await cfg.ledger.debit(tenantId, totalCost, "bot_runtime", {
-          description: `Daily runtime: ${botCount} bot(s) x $${DAILY_BOT_COST.toDollars().toFixed(2)}`,
-          referenceId: runtimeRef,
-        });
+      // Bill runtime debit (skipped if already billed on a previous run)
+      if (!runtimeAlreadyBilled) {
+        if (!balance.lessThan(totalCost)) {
+          // Full deduction
+          await cfg.ledger.debit(tenantId, totalCost, "bot_runtime", {
+            description: `Daily runtime: ${botCount} bot(s) x $${DAILY_BOT_COST.toDollars().toFixed(2)}`,
+            referenceId: runtimeRef,
+          });
+        } else {
+          // Partial deduction — balance insufficient to cover full cost; debit what's available and suspend
+          if (balance.greaterThan(Credit.ZERO)) {
+            await cfg.ledger.debit(tenantId, balance, "bot_runtime", {
+              description: `Partial daily runtime (balance exhausted): ${botCount} bot(s)`,
+              referenceId: runtimeRef,
+            });
+          }
+          if (!result.suspended.includes(tenantId)) {
+            result.suspended.push(tenantId);
+            if (cfg.onSuspend) await cfg.onSuspend(tenantId);
+          }
+        }
+        didBillAnything = true;
+      }
 
-        // Debit resource tier surcharges (if any)
-        if (cfg.getResourceTierCosts) {
+      // Debit resource tier surcharges (if any) — independent idempotency
+      if (cfg.getResourceTierCosts) {
+        const tierRef = `runtime-tier:${cfg.date}:${tenantId}`;
+        if (!(await cfg.ledger.hasReferenceId(tierRef))) {
           const tierCost = await cfg.getResourceTierCosts(tenantId);
           if (!tierCost.isZero()) {
             const balanceAfterRuntime = await cfg.ledger.balance(tenantId);
             if (!balanceAfterRuntime.lessThan(tierCost)) {
               await cfg.ledger.debit(tenantId, tierCost, "resource_upgrade", {
                 description: "Daily resource tier surcharge",
-                referenceId: `runtime-tier:${cfg.date}:${tenantId}`,
+                referenceId: tierRef,
               });
             } else if (balanceAfterRuntime.greaterThan(Credit.ZERO)) {
               await cfg.ledger.debit(tenantId, balanceAfterRuntime, "resource_upgrade", {
                 description: "Partial resource tier surcharge (balance exhausted)",
-                referenceId: `runtime-tier:${cfg.date}:${tenantId}`,
+                referenceId: tierRef,
               });
             }
+            didBillAnything = true;
           }
         }
+      }
 
-        const newBalance = await cfg.ledger.balance(tenantId);
+      const newBalance = await cfg.ledger.balance(tenantId);
 
-        // Fire onLowBalance if balance crossed below threshold from above
-        if (
-          newBalance.greaterThan(Credit.ZERO) &&
-          !newBalance.greaterThan(LOW_BALANCE_THRESHOLD) &&
-          balance.greaterThan(LOW_BALANCE_THRESHOLD) &&
-          cfg.onLowBalance
-        ) {
-          await cfg.onLowBalance(tenantId, newBalance);
-        }
+      // Fire onLowBalance if balance crossed below threshold from above
+      if (
+        newBalance.greaterThan(Credit.ZERO) &&
+        !newBalance.greaterThan(LOW_BALANCE_THRESHOLD) &&
+        balance.greaterThan(LOW_BALANCE_THRESHOLD) &&
+        cfg.onLowBalance
+      ) {
+        await cfg.onLowBalance(tenantId, newBalance);
+      }
 
-        // Fire onCreditsExhausted if balance just hit 0
-        if (!newBalance.greaterThan(Credit.ZERO) && balance.greaterThan(Credit.ZERO) && cfg.onCreditsExhausted) {
-          await cfg.onCreditsExhausted(tenantId);
-        }
+      // Fire onCreditsExhausted if balance just hit 0
+      if (!newBalance.greaterThan(Credit.ZERO) && balance.greaterThan(Credit.ZERO) && cfg.onCreditsExhausted) {
+        await cfg.onCreditsExhausted(tenantId);
+      }
 
-        // Suspend tenant when balance hits zero after full deduction (zero-crossing guard)
-        if (
-          !newBalance.greaterThan(Credit.ZERO) &&
-          balance.greaterThan(Credit.ZERO) &&
-          !result.suspended.includes(tenantId)
-        ) {
-          result.suspended.push(tenantId);
-          if (cfg.onSuspend) {
-            await cfg.onSuspend(tenantId);
-          }
+      // Suspend tenant when balance hits zero (zero-crossing guard)
+      if (
+        !newBalance.greaterThan(Credit.ZERO) &&
+        balance.greaterThan(Credit.ZERO) &&
+        !result.suspended.includes(tenantId)
+      ) {
+        result.suspended.push(tenantId);
+        if (cfg.onSuspend) {
+          await cfg.onSuspend(tenantId);
         }
+      }
 
-        // Debit storage tier surcharges (if any)
-        if (cfg.getStorageTierCosts) {
+      // Debit storage tier surcharges (if any) — independent idempotency
+      if (cfg.getStorageTierCosts) {
+        const storageRef = `runtime-storage:${cfg.date}:${tenantId}`;
+        if (!(await cfg.ledger.hasReferenceId(storageRef))) {
           const storageCost = await cfg.getStorageTierCosts(tenantId);
           if (!storageCost.isZero()) {
             const currentBalance = await cfg.ledger.balance(tenantId);
             if (!currentBalance.lessThan(storageCost)) {
               await cfg.ledger.debit(tenantId, storageCost, "storage_upgrade", {
                 description: "Daily storage tier surcharge",
-                referenceId: `runtime-storage:${cfg.date}:${tenantId}`,
+                referenceId: storageRef,
               });
             } else {
               // Partial debit — take what's left, then suspend
               if (currentBalance.greaterThan(Credit.ZERO)) {
                 await cfg.ledger.debit(tenantId, currentBalance, "storage_upgrade", {
                   description: "Partial storage tier surcharge (balance exhausted)",
-                  referenceId: `runtime-storage:${cfg.date}:${tenantId}`,
+                  referenceId: storageRef,
                 });
               }
               if (!result.suspended.includes(tenantId)) {
@@ -198,25 +222,29 @@ export async function runRuntimeDeductions(cfg: RuntimeCronConfig): Promise<Runt
                 if (cfg.onSuspend) await cfg.onSuspend(tenantId);
               }
             }
+            didBillAnything = true;
           }
         }
+      }
 
-        // Debit infrastructure add-on costs (if any)
-        if (cfg.getAddonCosts) {
+      // Debit infrastructure add-on costs (if any) — independent idempotency
+      if (cfg.getAddonCosts) {
+        const addonRef = `runtime-addon:${cfg.date}:${tenantId}`;
+        if (!(await cfg.ledger.hasReferenceId(addonRef))) {
           const addonCost = await cfg.getAddonCosts(tenantId);
           if (!addonCost.isZero()) {
             const currentBalance = await cfg.ledger.balance(tenantId);
             if (!currentBalance.lessThan(addonCost)) {
               await cfg.ledger.debit(tenantId, addonCost, "addon", {
                 description: "Daily infrastructure add-on charges",
-                referenceId: `runtime-addon:${cfg.date}:${tenantId}`,
+                referenceId: addonRef,
               });
             } else {
               // Partial debit — take what's left, then suspend
               if (currentBalance.greaterThan(Credit.ZERO)) {
                 await cfg.ledger.debit(tenantId, currentBalance, "addon", {
                   description: "Partial add-on charges (balance exhausted)",
-                  referenceId: `runtime-addon:${cfg.date}:${tenantId}`,
+                  referenceId: addonRef,
                 });
               }
               if (!result.suspended.includes(tenantId)) {
@@ -224,28 +252,16 @@ export async function runRuntimeDeductions(cfg: RuntimeCronConfig): Promise<Runt
                 if (cfg.onSuspend) await cfg.onSuspend(tenantId);
               }
             }
+            didBillAnything = true;
           }
         }
-      } else {
-        // Partial deduction — debit remaining balance, then suspend
-        if (balance.greaterThan(Credit.ZERO)) {
-          await cfg.ledger.debit(tenantId, balance, "bot_runtime", {
-            description: `Partial daily runtime (balance exhausted): ${botCount} bot(s)`,
-            referenceId: runtimeRef,
-          });
-        }
-
-        if (cfg.onCreditsExhausted) {
-          await cfg.onCreditsExhausted(tenantId);
-        }
-
-        result.suspended.push(tenantId);
-        if (cfg.onSuspend) {
-          await cfg.onSuspend(tenantId);
-        }
       }
 
-      result.processed++;
+      if (didBillAnything) {
+        result.processed++;
+      } else {
+        result.skipped.push(tenantId);
+      }
     } catch (err) {
       if (err instanceof InsufficientBalanceError) {
         result.suspended.push(tenantId);

package/vitest.config.ts

@@ -1,6 +1,15 @@
+import { resolve } from "node:path";
 import { defineConfig } from "vitest/config";
 
 export default defineConfig({
+  resolve: {
+    alias: {
+      "@wopr-network/platform-core/billing": resolve(__dirname, "src/billing/index.ts"),
+      "@wopr-network/platform-core/credits": resolve(__dirname, "src/credits/index.ts"),
+      "@wopr-network/platform-core/email": resolve(__dirname, "src/email/index.ts"),
+      "@wopr-network/platform-core/metering": resolve(__dirname, "src/metering/index.ts"),
+    },
+  },
   test: {
     testTimeout: 30000,
     hookTimeout: 30000,