@wopr-network/platform-core 1.39.4 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.39.4",
+  "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())`),
 });