@wopr-network/platform-core 1.13.2 → 1.14.0

package/src/monetization/credits/phone-billing.test.ts

@@ -1,28 +1,20 @@
-import {
-  Credit,
-  type CreditTransaction,
-  type ICreditLedger,
-  InsufficientBalanceError,
-} from "@wopr-network/platform-core/credits";
+import { Credit, type ILedger, InsufficientBalanceError, type JournalEntry } from "@wopr-network/platform-core/credits";
 import type { IMeterEmitter } from "@wopr-network/platform-core/metering";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { IPhoneNumberRepository } from "./drizzle-phone-number-repository.js";
 import { PHONE_NUMBER_MONTHLY_COST, runMonthlyPhoneBilling } from "./phone-billing.js";
 import type { ProvisionedPhoneNumber } from "./repository-types.js";
 
-function makeTx(tenantId: string): CreditTransaction {
+function makeTx(tenantId: string): JournalEntry {
   return {
     id: "tx-1",
+    postedAt: new Date().toISOString(),
+    entryType: "addon",
     tenantId,
-    amount: Credit.fromDollars(1),
-    balanceAfter: Credit.fromDollars(100),
-    type: "addon",
     description: "Monthly phone number fee",
     referenceId: null,
-    fundingSource: null,
-    attributedUserId: null,
-    createdAt: new Date().toISOString(),
-    expiresAt: null,
+    metadata: null,
+    lines: [],
   };
 }
 
@@ -108,7 +100,7 @@ describe("runMonthlyPhoneBilling", () => {
 
     const result = await runMonthlyPhoneBilling(
       phoneRepo as unknown as IPhoneNumberRepository,
-      ledger as unknown as ICreditLedger,
+      ledger as unknown as ILedger,
       meter as unknown as IMeterEmitter,
     );
 
@@ -128,7 +120,7 @@ describe("runMonthlyPhoneBilling", () => {
 
     const result = await runMonthlyPhoneBilling(
       phoneRepo as unknown as IPhoneNumberRepository,
-      ledger as unknown as ICreditLedger,
+      ledger as unknown as ILedger,
       meter as unknown as IMeterEmitter,
     );
 
@@ -138,16 +130,16 @@ describe("runMonthlyPhoneBilling", () => {
 
     // Verify debit was called with the margined charge amount
     expect(ledger.debit).toHaveBeenCalledOnce();
-    const [tenantId, chargeAmount, type, description, referenceId, allowNegative] = ledger.debit.mock.calls[0];
+    const [tenantId, chargeAmount, type, opts] = ledger.debit.mock.calls[0];
     expect(tenantId).toBe("tenant-1");
     // chargeCredit = Credit.fromDollars(1.15).multiply(2.6)
     const expectedCharge = Credit.fromDollars(1.15).multiply(2.6);
     expect(chargeAmount.toRaw()).toBe(expectedCharge.toRaw());
     expect(type).toBe("addon");
-    expect(description).toBe("Monthly phone number fee");
+    expect(opts.description).toBe("Monthly phone number fee");
     const expectedMonth = `${NOW.getFullYear()}-${String(NOW.getMonth() + 1).padStart(2, "0")}`;
-    expect(referenceId).toMatch(new RegExp(`^phone-billing:PN-abc123:${expectedMonth}$`));
-    expect(allowNegative).toBe(true);
+    expect(opts.referenceId).toMatch(new RegExp(`^phone-billing:PN-abc123:${expectedMonth}$`));
+    expect(opts.allowNegative).toBe(true);
 
     // Verify meter emission
     expect(meter.emit).toHaveBeenCalledOnce();
@@ -170,7 +162,7 @@ describe("runMonthlyPhoneBilling", () => {
 
     const result = await runMonthlyPhoneBilling(
       phoneRepo as unknown as IPhoneNumberRepository,
-      ledger as unknown as ICreditLedger,
+      ledger as unknown as ILedger,
       meter as unknown as IMeterEmitter,
     );
 
@@ -191,7 +183,7 @@ describe("runMonthlyPhoneBilling", () => {
 
     const result = await runMonthlyPhoneBilling(
       phoneRepo as unknown as IPhoneNumberRepository,
-      ledger as unknown as ICreditLedger,
+      ledger as unknown as ILedger,
       meter as unknown as IMeterEmitter,
     );
 
@@ -208,7 +200,7 @@ describe("runMonthlyPhoneBilling", () => {
 
     const result = await runMonthlyPhoneBilling(
       phoneRepo as unknown as IPhoneNumberRepository,
-      ledger as unknown as ICreditLedger,
+      ledger as unknown as ILedger,
       meter as unknown as IMeterEmitter,
     );
 
@@ -229,7 +221,7 @@ describe("runMonthlyPhoneBilling", () => {
 
     const result = await runMonthlyPhoneBilling(
       phoneRepo as unknown as IPhoneNumberRepository,
-      ledger as unknown as ICreditLedger,
+      ledger as unknown as ILedger,
       meter as unknown as IMeterEmitter,
     );
 
@@ -252,7 +244,7 @@ describe("runMonthlyPhoneBilling", () => {
 
     const result = await runMonthlyPhoneBilling(
       phoneRepo as unknown as IPhoneNumberRepository,
-      ledger as unknown as ICreditLedger,
+      ledger as unknown as ILedger,
       meter as unknown as IMeterEmitter,
     );
 
@@ -271,7 +263,7 @@ describe("runMonthlyPhoneBilling", () => {
 
     const result = await runMonthlyPhoneBilling(
       phoneRepo as unknown as IPhoneNumberRepository,
-      ledger as unknown as ICreditLedger,
+      ledger as unknown as ILedger,
       meter as unknown as IMeterEmitter,
     );
 

package/src/monetization/credits/phone-billing.ts

@@ -1,4 +1,4 @@
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit, InsufficientBalanceError } from "@wopr-network/platform-core/credits";
 import type { IMeterEmitter } from "@wopr-network/platform-core/metering";
 import { logger } from "../../config/logger.js";
@@ -15,7 +15,7 @@ const PHONE_NUMBER_MARGIN = 2.6;
 
 export async function runMonthlyPhoneBilling(
   phoneRepo: IPhoneNumberRepository,
-  ledger: ICreditLedger,
+  ledger: ILedger,
   meter: IMeterEmitter,
 ): Promise<{
   processed: number;
@@ -45,14 +45,11 @@ export async function runMonthlyPhoneBilling(
       const costCredit = Credit.fromDollars(PHONE_NUMBER_MONTHLY_COST);
       const chargeCredit = withMargin(costCredit, PHONE_NUMBER_MARGIN);
 
-      await ledger.debit(
-        number.tenantId,
-        chargeCredit,
-        "addon",
-        "Monthly phone number fee",
-        `phone-billing:${number.sid}:${now.toISOString().slice(0, 7)}`,
-        true,
-      );
+      await ledger.debit(number.tenantId, chargeCredit, "addon", {
+        description: "Monthly phone number fee",
+        referenceId: `phone-billing:${number.sid}:${now.toISOString().slice(0, 7)}`,
+        allowNegative: true,
+      });
 
       meter.emit({
         tenant: number.tenantId,

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

@@ -1,5 +1,5 @@
 import type { PGlite } from "@electric-sql/pglite";
-import { Credit, CreditLedger, InsufficientBalanceError } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger, InsufficientBalanceError } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { RESOURCE_TIERS } from "../../fleet/resource-tiers.js";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
@@ -8,12 +8,12 @@ import { buildResourceTierCosts, DAILY_BOT_COST, runRuntimeDeductions } from "./
 describe("runRuntimeDeductions", () => {
   const TODAY = "2025-01-01";
   let pool: PGlite;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
 
   beforeAll(async () => {
     const { db, pool: p } = await createTestDb();
     pool = p;
-    ledger = new CreditLedger(db);
+    ledger = new DrizzleLedger(db);
   });
 
   afterAll(async () => {
@@ -22,6 +22,7 @@ describe("runRuntimeDeductions", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
+    await ledger.seedSystemAccounts();
   });
 
   it("DAILY_BOT_COST equals 17 cents", () => {
@@ -40,7 +41,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("skips tenants with zero active bots", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
     const result = await runRuntimeDeductions({
       ledger,
       date: TODAY,
@@ -51,7 +52,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("deducts full amount when balance is sufficient", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
     const result = await runRuntimeDeductions({
       ledger,
       date: TODAY,
@@ -63,7 +64,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("partial deduction and suspension when balance is insufficient", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(10), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(10), "purchase", { description: "top-up" });
     const onSuspend = vi.fn();
     const result = await runRuntimeDeductions({
       ledger,
@@ -78,9 +79,9 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("suspends with zero partial when balance exactly zero", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(100), "purchase", "top-up");
-    await ledger.debit("tenant-1", Credit.fromCents(100), "bot_runtime", "drain");
-    await ledger.credit("tenant-1", Credit.fromCents(1), "purchase", "tiny");
+    await ledger.credit("tenant-1", Credit.fromCents(100), "purchase", { description: "top-up" });
+    await ledger.debit("tenant-1", Credit.fromCents(100), "bot_runtime", { description: "drain" });
+    await ledger.credit("tenant-1", Credit.fromCents(1), "purchase", { description: "tiny" });
 
     const onSuspend = vi.fn();
     const result = await runRuntimeDeductions({
@@ -95,7 +96,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("suspends without onSuspend callback", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(5), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(5), "purchase", { description: "top-up" });
     const result = await runRuntimeDeductions({
       ledger,
       date: TODAY,
@@ -106,7 +107,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("handles errors from getActiveBotCount gracefully", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
     const result = await runRuntimeDeductions({
       ledger,
       date: TODAY,
@@ -120,8 +121,8 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("handles InsufficientBalanceError from ledger.debit", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
-    await ledger.debit("tenant-1", Credit.fromCents(499), "bot_runtime", "drain");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
+    await ledger.debit("tenant-1", Credit.fromCents(499), "bot_runtime", { description: "drain" });
     const onSuspend = vi.fn();
     const result = await runRuntimeDeductions({
       ledger,
@@ -134,7 +135,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("catches InsufficientBalanceError from debit and suspends", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
     vi.spyOn(ledger, "debit").mockRejectedValue(
       new InsufficientBalanceError(Credit.fromCents(0), Credit.fromCents(17)),
     );
@@ -152,7 +153,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("catches InsufficientBalanceError without onSuspend callback", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
     vi.spyOn(ledger, "debit").mockRejectedValue(
       new InsufficientBalanceError(Credit.fromCents(0), Credit.fromCents(17)),
     );
@@ -167,8 +168,8 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("processes multiple tenants", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
-    await ledger.credit("tenant-2", Credit.fromCents(10), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
+    await ledger.credit("tenant-2", Credit.fromCents(10), "purchase", { description: "top-up" });
     const onSuspend = vi.fn();
     const result = await runRuntimeDeductions({
       ledger,
@@ -182,7 +183,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("fires onLowBalance when balance drops below 100 cents threshold", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(110), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(110), "purchase", { description: "top-up" });
     const onLowBalance = vi.fn();
     await runRuntimeDeductions({
       ledger,
@@ -197,7 +198,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("does NOT fire onLowBalance when balance was already below threshold before deduction", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(90), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(90), "purchase", { description: "top-up" });
     const onLowBalance = vi.fn();
     await runRuntimeDeductions({
       ledger,
@@ -209,7 +210,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("fires onCreditsExhausted when full deduction causes balance to drop to 0", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", { description: "top-up" });
     const onCreditsExhausted = vi.fn();
     await runRuntimeDeductions({
       ledger,
@@ -223,7 +224,7 @@ describe("runRuntimeDeductions", () => {
 
   it("suspends tenant when full deduction causes balance to drop to exactly 0", async () => {
     // Balance = exactly 1 bot * DAILY_BOT_COST = 17 cents → full deduction → 0
-    await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", { description: "top-up" });
     const onSuspend = vi.fn();
     const onCreditsExhausted = vi.fn();
     const result = await runRuntimeDeductions({
@@ -240,7 +241,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("fires onCreditsExhausted on partial deduction when balance hits 0", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(10), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(10), "purchase", { description: "top-up" });
     const onCreditsExhausted = vi.fn();
     await runRuntimeDeductions({
       ledger,
@@ -253,7 +254,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("partially debits resource tier surcharge when balance is positive but insufficient", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(30), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(30), "purchase", { description: "top-up" });
     const result = await runRuntimeDeductions({
       ledger,
       date: TODAY,
@@ -265,7 +266,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("skips resource tier partial debit when balance is exactly 0 after runtime", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", { description: "top-up" });
     const onCreditsExhausted = vi.fn();
     const result = await runRuntimeDeductions({
       ledger,
@@ -284,7 +285,7 @@ describe("runRuntimeDeductions", () => {
     // triggering the zero-crossing suspend in the runtime block.
     // Storage cost (5 cents) then tries to suspend again via its else-branch (balance 0 < 5).
     // The !result.suspended.includes(tenantId) guard must prevent onSuspend being called twice.
-    await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", { description: "top-up" });
     const onSuspend = vi.fn();
     const result = await runRuntimeDeductions({
       ledger,
@@ -301,7 +302,7 @@ describe("runRuntimeDeductions", () => {
   it("buildResourceTierCosts: deducts pro tier surcharge via getResourceTierCosts", async () => {
     const proTierCost = RESOURCE_TIERS.pro.dailyCost.toCents();
     const startBalance = 17 + proTierCost + 10;
-    await ledger.credit("tenant-1", Credit.fromCents(startBalance), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(startBalance), "purchase", { description: "top-up" });
 
     const mockRepo = {
       getResourceTier: async (_botId: string): Promise<string | null> => "pro",
@@ -324,7 +325,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("treats unique constraint violation from concurrent debit as already-billed (skip, not error)", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
     const uniqueErr = Object.assign(new Error("duplicate key value violates unique constraint"), { code: "23505" });
     vi.spyOn(ledger, "debit").mockRejectedValueOnce(uniqueErr);
     const result = await runRuntimeDeductions({
@@ -338,7 +339,7 @@ describe("runRuntimeDeductions", () => {
   });
 
   it("is idempotent — second run on same date does not double-deduct", async () => {
-    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "top-up");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
     const cfg = {
       ledger,
       getActiveBotCount: async () => 1,

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

@@ -1,4 +1,4 @@
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit, InsufficientBalanceError } from "@wopr-network/platform-core/credits";
 import { logger } from "../../config/logger.js";
 import type { IBotInstanceRepository } from "../../fleet/bot-instance-repository.js";
@@ -20,7 +20,7 @@ export type GetActiveBotCount = (tenantId: string) => number | Promise<number>;
 export const LOW_BALANCE_THRESHOLD = Credit.fromCents(100);
 
 export interface RuntimeCronConfig {
-  ledger: ICreditLedger;
+  ledger: ILedger;
   getActiveBotCount: GetActiveBotCount;
   /** The date being billed, as YYYY-MM-DD. Used for idempotency. */
   date: string;
@@ -122,13 +122,10 @@ export async function runRuntimeDeductions(cfg: RuntimeCronConfig): Promise<Runt
 
       if (!balance.lessThan(totalCost)) {
         // Full deduction
-        await cfg.ledger.debit(
-          tenantId,
-          totalCost,
-          "bot_runtime",
-          `Daily runtime: ${botCount} bot(s) x $${DAILY_BOT_COST.toDollars().toFixed(2)}`,
-          runtimeRef,
-        );
+        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) {
@@ -136,21 +133,15 @@ export async function runRuntimeDeductions(cfg: RuntimeCronConfig): Promise<Runt
           if (!tierCost.isZero()) {
             const balanceAfterRuntime = await cfg.ledger.balance(tenantId);
             if (!balanceAfterRuntime.lessThan(tierCost)) {
-              await cfg.ledger.debit(
-                tenantId,
-                tierCost,
-                "resource_upgrade",
-                "Daily resource tier surcharge",
-                `runtime-tier:${cfg.date}:${tenantId}`,
-              );
+              await cfg.ledger.debit(tenantId, tierCost, "resource_upgrade", {
+                description: "Daily resource tier surcharge",
+                referenceId: `runtime-tier:${cfg.date}:${tenantId}`,
+              });
             } else if (balanceAfterRuntime.greaterThan(Credit.ZERO)) {
-              await cfg.ledger.debit(
-                tenantId,
-                balanceAfterRuntime,
-                "resource_upgrade",
-                "Partial resource tier surcharge (balance exhausted)",
-                `runtime-tier:${cfg.date}:${tenantId}`,
-              );
+              await cfg.ledger.debit(tenantId, balanceAfterRuntime, "resource_upgrade", {
+                description: "Partial resource tier surcharge (balance exhausted)",
+                referenceId: `runtime-tier:${cfg.date}:${tenantId}`,
+              });
             }
           }
         }
@@ -190,23 +181,17 @@ export async function runRuntimeDeductions(cfg: RuntimeCronConfig): Promise<Runt
           if (!storageCost.isZero()) {
             const currentBalance = await cfg.ledger.balance(tenantId);
             if (!currentBalance.lessThan(storageCost)) {
-              await cfg.ledger.debit(
-                tenantId,
-                storageCost,
-                "storage_upgrade",
-                "Daily storage tier surcharge",
-                `runtime-storage:${cfg.date}:${tenantId}`,
-              );
+              await cfg.ledger.debit(tenantId, storageCost, "storage_upgrade", {
+                description: "Daily storage tier surcharge",
+                referenceId: `runtime-storage:${cfg.date}:${tenantId}`,
+              });
             } else {
               // Partial debit — take what's left, then suspend
               if (currentBalance.greaterThan(Credit.ZERO)) {
-                await cfg.ledger.debit(
-                  tenantId,
-                  currentBalance,
-                  "storage_upgrade",
-                  "Partial storage tier surcharge (balance exhausted)",
-                  `runtime-storage:${cfg.date}:${tenantId}`,
-                );
+                await cfg.ledger.debit(tenantId, currentBalance, "storage_upgrade", {
+                  description: "Partial storage tier surcharge (balance exhausted)",
+                  referenceId: `runtime-storage:${cfg.date}:${tenantId}`,
+                });
               }
               if (!result.suspended.includes(tenantId)) {
                 result.suspended.push(tenantId);
@@ -222,23 +207,17 @@ export async function runRuntimeDeductions(cfg: RuntimeCronConfig): Promise<Runt
           if (!addonCost.isZero()) {
             const currentBalance = await cfg.ledger.balance(tenantId);
             if (!currentBalance.lessThan(addonCost)) {
-              await cfg.ledger.debit(
-                tenantId,
-                addonCost,
-                "addon",
-                "Daily infrastructure add-on charges",
-                `runtime-addon:${cfg.date}:${tenantId}`,
-              );
+              await cfg.ledger.debit(tenantId, addonCost, "addon", {
+                description: "Daily infrastructure add-on charges",
+                referenceId: `runtime-addon:${cfg.date}:${tenantId}`,
+              });
             } else {
               // Partial debit — take what's left, then suspend
               if (currentBalance.greaterThan(Credit.ZERO)) {
-                await cfg.ledger.debit(
-                  tenantId,
-                  currentBalance,
-                  "addon",
-                  "Partial add-on charges (balance exhausted)",
-                  `runtime-addon:${cfg.date}:${tenantId}`,
-                );
+                await cfg.ledger.debit(tenantId, currentBalance, "addon", {
+                  description: "Partial add-on charges (balance exhausted)",
+                  referenceId: `runtime-addon:${cfg.date}:${tenantId}`,
+                });
               }
               if (!result.suspended.includes(tenantId)) {
                 result.suspended.push(tenantId);
@@ -250,13 +229,10 @@ export async function runRuntimeDeductions(cfg: RuntimeCronConfig): Promise<Runt
       } else {
         // Partial deduction — debit remaining balance, then suspend
         if (balance.greaterThan(Credit.ZERO)) {
-          await cfg.ledger.debit(
-            tenantId,
-            balance,
-            "bot_runtime",
-            `Partial daily runtime (balance exhausted): ${botCount} bot(s)`,
-            runtimeRef,
-          );
+          await cfg.ledger.debit(tenantId, balance, "bot_runtime", {
+            description: `Partial daily runtime (balance exhausted): ${botCount} bot(s)`,
+            referenceId: runtimeRef,
+          });
         }
 
         if (cfg.onCreditsExhausted) {

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

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { RUNTIME_INTERVAL_MS, startRuntimeScheduler } from "./runtime-scheduler.js";
 
-// Minimal ICreditLedger stub — only the methods runRuntimeDeductions calls.
+// Minimal ILedger stub — only the methods runRuntimeDeductions calls.
 function makeLedger() {
   return {
     tenantsWithBalance: vi.fn().mockResolvedValue([]),

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

@@ -1,4 +1,4 @@
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { logger } from "../../config/logger.js";
 import type { IBotInstanceRepository } from "../../fleet/bot-instance-repository.js";
 import { buildAddonCosts } from "../addons/addon-cron.js";
@@ -6,7 +6,7 @@ import type { ITenantAddonRepository } from "../addons/addon-repository.js";
 import { buildResourceTierCosts, runRuntimeDeductions } from "./runtime-cron.js";
 
 export interface RuntimeSchedulerDeps {
-  ledger: ICreditLedger;
+  ledger: ILedger;
   botInstanceRepo: IBotInstanceRepository;
   tenantAddonRepo: ITenantAddonRepository;
   onSuspend?: (tenantId: string) => void;

package/src/monetization/credits/signup-grant.test.ts

@@ -1,5 +1,5 @@
 import type { PGlite } from "@electric-sql/pglite";
-import { CreditLedger, grantSignupCredits, SIGNUP_GRANT } from "@wopr-network/platform-core/credits";
+import { DrizzleLedger, grantSignupCredits, SIGNUP_GRANT } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { DrizzleDb } from "../../db/index.js";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
@@ -7,7 +7,7 @@ import { createTestDb, truncateAllTables } from "../../test/db.js";
 describe("grantSignupCredits", () => {
   let pool: PGlite;
   let db: DrizzleDb;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
 
   beforeAll(async () => {
     ({ db, pool } = await createTestDb());
@@ -19,7 +19,9 @@ describe("grantSignupCredits", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
-    ledger = new CreditLedger(db);
+    ledger = new DrizzleLedger(db);
+
+    await ledger.seedSystemAccounts();
   });
 
   it("grants credits to a new tenant and returns true", async () => {
@@ -52,7 +54,8 @@ describe("grantSignupCredits", () => {
     const uniqueErr = Object.assign(new Error("duplicate key value violates unique constraint"), {
       code: "23505",
     });
-    const racingLedger = new CreditLedger(db);
+    const racingLedger = new DrizzleLedger(db);
+    await racingLedger.seedSystemAccounts();
     vi.spyOn(racingLedger, "hasReferenceId").mockResolvedValue(false);
     vi.spyOn(racingLedger, "credit").mockRejectedValue(uniqueErr);
 

package/src/monetization/credits/storage-tier-cron.test.ts

@@ -1,5 +1,5 @@
 import type { PGlite } from "@electric-sql/pglite";
-import { Credit, CreditLedger } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import type { DrizzleDb } from "../../db/index.js";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
@@ -9,7 +9,7 @@ describe("runtime cron with storage tiers", () => {
   const TODAY = "2025-01-01";
   let pool: PGlite;
   let db: DrizzleDb;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
 
   beforeAll(async () => {
     ({ db, pool } = await createTestDb());
@@ -21,7 +21,9 @@ describe("runtime cron with storage tiers", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
-    ledger = new CreditLedger(db);
+    ledger = new DrizzleLedger(db);
+
+    await ledger.seedSystemAccounts();
   });
 
   it("debits base cost plus storage surcharge for pro tier", async () => {