@wopr-network/platform-core 1.13.3 → 1.14.1

package/dist/monetization/credits/member-usage.test.js

@@ -1,7 +1,7 @@
-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 { createTestDb, truncateAllTables } from "../../test/db.js";
-describe("DrizzleCreditLedger.memberUsage", () => {
+describe("DrizzleDrizzleLedger.memberUsage", () => {
     let pool;
     let db;
     let ledger;
@@ -13,13 +13,23 @@ describe("DrizzleCreditLedger.memberUsage", () => {
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
+        ledger = new DrizzleLedger(db);
+        await ledger.seedSystemAccounts();
     });
     it("should aggregate debit totals per attributed user", async () => {
-        await ledger.credit("org-1", Credit.fromCents(10000), "purchase", "Seed");
-        await ledger.debit("org-1", Credit.fromCents(100), "adapter_usage", "Chat", undefined, false, "user-a");
-        await ledger.debit("org-1", Credit.fromCents(200), "adapter_usage", "Chat", undefined, false, "user-a");
-        await ledger.debit("org-1", Credit.fromCents(300), "adapter_usage", "Chat", undefined, false, "user-b");
+        await ledger.credit("org-1", Credit.fromCents(10000), "purchase", { description: "Seed" });
+        await ledger.debit("org-1", Credit.fromCents(100), "adapter_usage", {
+            description: "Chat",
+            attributedUserId: "user-a",
+        });
+        await ledger.debit("org-1", Credit.fromCents(200), "adapter_usage", {
+            description: "Chat",
+            attributedUserId: "user-a",
+        });
+        await ledger.debit("org-1", Credit.fromCents(300), "adapter_usage", {
+            description: "Chat",
+            attributedUserId: "user-b",
+        });
         const result = await ledger.memberUsage("org-1");
         expect(result).toHaveLength(2);
         const userA = result.find((r) => r.userId === "user-a");
@@ -30,9 +40,12 @@ describe("DrizzleCreditLedger.memberUsage", () => {
         expect(userB?.transactionCount).toBe(1);
     });
     it("should exclude transactions with null attributedUserId", async () => {
-        await ledger.credit("org-1", Credit.fromCents(10000), "purchase", "Seed");
-        await ledger.debit("org-1", Credit.fromCents(100), "bot_runtime", "Cron"); // no attributedUserId
-        await ledger.debit("org-1", Credit.fromCents(200), "adapter_usage", "Chat", undefined, false, "user-a");
+        await ledger.credit("org-1", Credit.fromCents(10000), "purchase", { description: "Seed" });
+        await ledger.debit("org-1", Credit.fromCents(100), "bot_runtime", { description: "Cron" }); // no attributedUserId
+        await ledger.debit("org-1", Credit.fromCents(200), "adapter_usage", {
+            description: "Chat",
+            attributedUserId: "user-a",
+        });
         const result = await ledger.memberUsage("org-1");
         expect(result).toHaveLength(1);
         expect(result[0]?.userId).toBe("user-a");

package/dist/monetization/credits/phone-billing.d.ts

@@ -1,10 +1,10 @@
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import type { IMeterEmitter } from "@wopr-network/platform-core/metering";
 import type { IPhoneNumberRepository } from "./drizzle-phone-number-repository.js";
 export type { IPhoneNumberRepository } from "./drizzle-phone-number-repository.js";
 /** Phone number monthly wholesale cost in USD. Exported for proxy.ts to import. */
 export declare const PHONE_NUMBER_MONTHLY_COST = 1.15;
-export declare function runMonthlyPhoneBilling(phoneRepo: IPhoneNumberRepository, ledger: ICreditLedger, meter: IMeterEmitter): Promise<{
+export declare function runMonthlyPhoneBilling(phoneRepo: IPhoneNumberRepository, ledger: ILedger, meter: IMeterEmitter): Promise<{
     processed: number;
     billed: {
         tenantId: string;

package/dist/monetization/credits/phone-billing.js

@@ -23,7 +23,11 @@ export async function runMonthlyPhoneBilling(phoneRepo, ledger, meter) {
         try {
             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,
                 cost: costCredit,

package/dist/monetization/credits/phone-billing.test.js

@@ -1,19 +1,16 @@
-import { Credit, InsufficientBalanceError, } from "@wopr-network/platform-core/credits";
+import { Credit, InsufficientBalanceError } from "@wopr-network/platform-core/credits";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { PHONE_NUMBER_MONTHLY_COST, runMonthlyPhoneBilling } from "./phone-billing.js";
 function makeTx(tenantId) {
     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: [],
     };
 }
 function makeNumber(overrides = {}) {
@@ -85,16 +82,16 @@ describe("runMonthlyPhoneBilling", () => {
         expect(result.failed).toEqual([]);
         // 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();
         const event = meter.emit.mock.calls[0][0];

package/dist/monetization/credits/runtime-cron.d.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 } from "@wopr-network/platform-core/credits";
 import type { IBotInstanceRepository } from "../../fleet/bot-instance-repository.js";
 /**
@@ -13,7 +13,7 @@ export type GetActiveBotCount = (tenantId: string) => number | Promise<number>;
 /** Low balance threshold ($1.00 = 20% of signup grant). */
 export declare const LOW_BALANCE_THRESHOLD: Credit;
 export interface RuntimeCronConfig {
-    ledger: ICreditLedger;
+    ledger: ILedger;
     getActiveBotCount: GetActiveBotCount;
     /** The date being billed, as YYYY-MM-DD. Used for idempotency. */
     date: string;

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

@@ -69,17 +69,26 @@ export async function runRuntimeDeductions(cfg) {
             const totalCost = DAILY_BOT_COST.multiply(botCount);
             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) {
                     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", "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}`,
+                            });
                         }
                     }
                 }
@@ -110,12 +119,18 @@ export async function runRuntimeDeductions(cfg) {
                     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);
@@ -131,12 +146,18 @@ export async function runRuntimeDeductions(cfg) {
                     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);
@@ -150,7 +171,10 @@ export async function runRuntimeDeductions(cfg) {
             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) {
                     await cfg.onCreditsExhausted(tenantId);

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

@@ -1,4 +1,4 @@
-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";
@@ -10,13 +10,14 @@ describe("runRuntimeDeductions", () => {
     beforeAll(async () => {
         const { db, pool: p } = await createTestDb();
         pool = p;
-        ledger = new CreditLedger(db);
+        ledger = new DrizzleLedger(db);
     });
     afterAll(async () => {
         await pool.close();
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
+        await ledger.seedSystemAccounts();
     });
     it("DAILY_BOT_COST equals 17 cents", () => {
         expect(DAILY_BOT_COST.toCents()).toBe(17);
@@ -32,7 +33,7 @@ describe("runRuntimeDeductions", () => {
         expect(result.errors).toEqual([]);
     });
     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,
@@ -42,7 +43,7 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(500);
     });
     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,
@@ -53,7 +54,7 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(500 - 2 * 17);
     });
     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,
@@ -67,9 +68,9 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
     });
     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({
             ledger,
@@ -82,7 +83,7 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
     });
     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,
@@ -92,7 +93,7 @@ describe("runRuntimeDeductions", () => {
         expect(result.processed).toBe(1);
     });
     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,
@@ -105,8 +106,8 @@ describe("runRuntimeDeductions", () => {
         expect(result.errors[0]).toContain("db connection failed");
     });
     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,
@@ -118,7 +119,7 @@ describe("runRuntimeDeductions", () => {
         expect(onSuspend).toHaveBeenCalledWith("tenant-1");
     });
     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)));
         const onSuspend = vi.fn();
         const result = await runRuntimeDeductions({
@@ -133,7 +134,7 @@ describe("runRuntimeDeductions", () => {
         vi.restoreAllMocks();
     });
     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)));
         const result = await runRuntimeDeductions({
             ledger,
@@ -145,8 +146,8 @@ describe("runRuntimeDeductions", () => {
         vi.restoreAllMocks();
     });
     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,
@@ -159,7 +160,7 @@ describe("runRuntimeDeductions", () => {
         expect(result.suspended).not.toContain("tenant-1");
     });
     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,
@@ -173,7 +174,7 @@ describe("runRuntimeDeductions", () => {
         expect(calledBalance.toCents()).toBe(93);
     });
     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,
@@ -184,7 +185,7 @@ describe("runRuntimeDeductions", () => {
         expect(onLowBalance).not.toHaveBeenCalled();
     });
     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,
@@ -197,7 +198,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({
@@ -213,7 +214,7 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
     });
     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,
@@ -225,7 +226,7 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
     });
     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,
@@ -236,7 +237,7 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
     });
     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,
@@ -254,7 +255,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,
@@ -270,7 +271,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) => "pro",
         };
@@ -285,7 +286,7 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(expected);
     });
     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({
@@ -298,7 +299,7 @@ describe("runRuntimeDeductions", () => {
         vi.restoreAllMocks();
     });
     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/dist/monetization/credits/runtime-scheduler.d.ts

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

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

@@ -1,6 +1,6 @@
 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/dist/monetization/credits/signup-grant.test.js

@@ -1,4 +1,4 @@
-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 { createTestDb, truncateAllTables } from "../../test/db.js";
 describe("grantSignupCredits", () => {
@@ -13,7 +13,8 @@ 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 () => {
         const result = await grantSignupCredits(ledger, "tenant-1");
@@ -41,7 +42,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);
         const result = await grantSignupCredits(racingLedger, "tenant-race");

package/dist/monetization/credits/storage-tier-cron.test.js

@@ -1,4 +1,4 @@
-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 { createTestDb, truncateAllTables } from "../../test/db.js";
 import { runRuntimeDeductions } from "./runtime-cron.js";
@@ -15,7 +15,8 @@ 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 () => {
         await ledger.credit("t1", Credit.fromCents(1000), "purchase");

package/dist/monetization/credits/trial-balance-cron.test.js

@@ -0,0 +1,42 @@
+import { Credit, DrizzleLedger, runTrialBalanceCron } from "@wopr-network/platform-core/credits";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+describe("runTrialBalanceCron", () => {
+    let pool;
+    let ledger;
+    beforeAll(async () => {
+        const { db, pool: p } = await createTestDb();
+        pool = p;
+        ledger = new DrizzleLedger(db);
+    });
+    afterAll(async () => {
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+        await ledger.seedSystemAccounts();
+    });
+    it("returns balanced when no entries exist", async () => {
+        const result = await runTrialBalanceCron({ ledger });
+        expect(result.balanced).toBe(true);
+        expect(result.differenceRaw).toBe(0);
+    });
+    it("returns balanced after normal credit and debit", async () => {
+        await ledger.credit("t1", Credit.fromCents(500), "purchase");
+        await ledger.debit("t1", Credit.fromCents(200), "bot_runtime");
+        const result = await runTrialBalanceCron({ ledger });
+        expect(result.balanced).toBe(true);
+        expect(result.differenceRaw).toBe(0);
+    });
+    it("logs an error on imbalance without throwing", async () => {
+        vi.spyOn(ledger, "trialBalance").mockResolvedValueOnce({
+            totalDebits: Credit.fromCents(1000),
+            totalCredits: Credit.fromCents(900),
+            balanced: false,
+            difference: Credit.fromCents(100),
+        });
+        const result = await runTrialBalanceCron({ ledger });
+        expect(result.balanced).toBe(false);
+        expect(result.differenceRaw).toBe(Credit.fromCents(100).toRaw());
+    });
+});

package/dist/monetization/feature-gate.d.ts

@@ -1,4 +1,4 @@
-import type { CreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit } from "@wopr-network/platform-core/credits";
 import type { Context, Next } from "hono";
 /**
@@ -37,7 +37,7 @@ export declare function createFeatureGate(cfg: FeatureGateConfig): {
 /**
  * Convenience factory that creates a requireBalance middleware from a CreditLedger instance.
  */
-export declare function createBalanceGate(ledger: CreditLedger, userKey?: string, userIdField?: string): {
+export declare function createBalanceGate(ledger: ILedger, userKey?: string, userIdField?: string): {
     requireBalance: (minBalance?: Credit) => (c: Context, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
         error: string;
     }, 401, "json">) | (Response & import("hono").TypedResponse<{
@@ -54,7 +54,7 @@ export declare function createBalanceGate(ledger: CreditLedger, userKey?: string
 export type ResolveTenantId = (c: Context) => string | undefined | Promise<string | undefined>;
 export interface CreditGateConfig {
     /** CreditLedger instance used to check balance. */
-    ledger: CreditLedger;
+    ledger: ILedger;
     /** Resolve the tenant ID from the request context. */
     resolveTenantId: ResolveTenantId;
 }

package/dist/monetization/index.d.ts

@@ -39,8 +39,8 @@ export { type AdapterCapability, type AdapterResult, type EmbeddingsInput, type
 export { type ArbitrageRequest, ArbitrageRouter, type ArbitrageRouterConfig, type MarginRecord, type ModelProviderEntry, NoProviderAvailableError, ProviderRegistry, type ProviderRegistryConfig, type RoutingDecision, } from "./arbitrage/index.js";
 export type { BudgetCheckerConfig, BudgetCheckResult, SpendLimits } from "./budget/index.js";
 export { BudgetChecker, DrizzleBudgetChecker } from "./budget/index.js";
-export type { BillingState, CreditTransaction, CreditType, DebitType, GetActiveBotCount, HistoryOptions, OnSuspend, RuntimeCronConfig, RuntimeCronResult, TransactionType, } from "./credits/index.js";
-export { BotBilling, buildResourceTierCosts, CreditLedger, DAILY_BOT_COST, DrizzleBotBilling, DrizzleCreditLedger, grantSignupCredits, InsufficientBalanceError, runRuntimeDeductions, SIGNUP_GRANT, SUSPENSION_GRACE_DAYS, } from "./credits/index.js";
+export type { BillingState, CreditType, DebitType, GetActiveBotCount, HistoryOptions, ILedger, JournalEntry, OnSuspend, RuntimeCronConfig, RuntimeCronResult, TransactionType, } from "./credits/index.js";
+export { BotBilling, buildResourceTierCosts, DAILY_BOT_COST, DrizzleBotBilling, DrizzleLedger, grantSignupCredits, InsufficientBalanceError, Ledger, runRuntimeDeductions, SIGNUP_GRANT, SUSPENSION_GRACE_DAYS, } from "./credits/index.js";
 export { type CreditGateConfig, createBalanceGate, createCreditGate, createFeatureGate, type FeatureGateConfig, type GetUserBalance, type ResolveTenantId, } from "./feature-gate.js";
 export type { BillingPeriod, BillingPeriodSummary, MeterEventRow, UsageSummary, } from "./metering/index.js";
 export { DrizzleMeterAggregator, DrizzleMeterEmitter, MeterAggregator, MeterEmitter, } from "./metering/index.js";
@@ -48,7 +48,7 @@ export type { PayRamBillingConfig, PayRamCheckoutOpts, PayRamConfig, PayRamPayme
 export { createPayRamCheckout, createPayRamClient, DrizzlePayRamChargeRepository, handlePayRamWebhook, loadPayRamConfig, MIN_PAYMENT_USD, PayRamChargeRepository, } from "./payram/index.js";
 export { checkInstanceQuota, DEFAULT_INSTANCE_LIMITS, type InstanceLimits, type QuotaCheckResult, } from "./quotas/quota-check.js";
 export { buildResourceLimits, type ContainerResourceLimits, DEFAULT_RESOURCE_CONFIG, type ResourceConfig, } from "./quotas/resource-limits.js";
-export type { IBotBilling, IBudgetChecker, ICreditLedger, IMeterAggregator, IMeterEmitter, IPayRamChargeRepository, ITenantCustomerRepository, PayRamChargeRecord, } from "./repository-types.js";
+export type { IBotBilling, IBudgetChecker, IMeterAggregator, IMeterEmitter, IPayRamChargeRepository, ITenantCustomerRepository, PayRamChargeRecord, } from "./repository-types.js";
 export { AdapterSocket, type SocketConfig, type SocketRequest } from "./socket/socket.js";
 export type { CreditCheckoutOpts, CreditPriceMap, CreditPricePoint, PortalSessionOpts, StripeBillingConfig, TenantCustomerRow, WebhookDeps, WebhookResult, } from "./stripe/index.js";
 export { CREDIT_PRICE_POINTS, createCreditCheckoutSession, createPortalSession, createStripeClient, DrizzleTenantCustomerRepository, getConfiguredPriceIds, getCreditAmountForPurchase, handleWebhookEvent, loadCreditPriceMap, loadStripeConfig, lookupCreditPrice, TenantCustomerRepository, } from "./stripe/index.js";

package/dist/monetization/index.js

@@ -49,7 +49,7 @@ export { withMargin, } from "./adapters/types.js";
 // Arbitrage router — multi-provider routing for maximum margin (WOP-463)
 export { ArbitrageRouter, NoProviderAvailableError, ProviderRegistry, } from "./arbitrage/index.js";
 export { BudgetChecker, DrizzleBudgetChecker } from "./budget/index.js";
-export { BotBilling, buildResourceTierCosts, CreditLedger, DAILY_BOT_COST, DrizzleBotBilling, DrizzleCreditLedger, grantSignupCredits, InsufficientBalanceError, runRuntimeDeductions, SIGNUP_GRANT, SUSPENSION_GRACE_DAYS, } from "./credits/index.js";
+export { BotBilling, buildResourceTierCosts, DAILY_BOT_COST, DrizzleBotBilling, DrizzleLedger, grantSignupCredits, InsufficientBalanceError, Ledger, runRuntimeDeductions, SIGNUP_GRANT, SUSPENSION_GRACE_DAYS, } from "./credits/index.js";
 // Feature gating middleware (WOP-384 — replaced tier gates with balance gates)
 export { createBalanceGate, createCreditGate, createFeatureGate, } from "./feature-gate.js";
 export { DrizzleMeterAggregator, DrizzleMeterEmitter, MeterAggregator, MeterEmitter, } from "./metering/index.js";