@wopr-network/platform-core 1.13.3 → 1.14.0

package/src/monetization/credits/dividend-repository.test.ts

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
 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 { adminUsers } from "../../db/schema/admin-users.js";
@@ -54,6 +54,7 @@ describe("DrizzleDividendRepository", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
+    await new DrizzleLedger(db).seedSystemAccounts();
     repo = new DrizzleDividendRepository(db);
   });
 
@@ -194,8 +195,8 @@ describe("DrizzleDividendRepository", () => {
     });
 
     it("marks user as eligible when they have a recent purchase", async () => {
-      const ledger = new CreditLedger(db);
-      await ledger.credit("t1", Credit.fromCents(100), "purchase", "recent buy");
+      const ledger = new DrizzleLedger(db);
+      await ledger.credit("t1", Credit.fromCents(100), "purchase", { description: "recent buy" });
 
       const stats = await repo.getStats("t1");
       expect(stats.userEligible).toBe(true);

package/src/monetization/credits/dividend-repository.ts

@@ -2,8 +2,8 @@ import { Credit } from "@wopr-network/platform-core/credits";
 import { and, desc, eq, gte, lt, sql } from "drizzle-orm";
 import type { DrizzleDb } from "../../db/index.js";
 import { adminUsers } from "../../db/schema/admin-users.js";
-import { creditTransactions } from "../../db/schema/credits.js";
 import { dividendDistributions } from "../../db/schema/dividend-distributions.js";
+import { journalEntries, journalLines } from "../../db/schema/ledger.js";
 import type { DividendHistoryEntry, DividendStats } from "../repository-types.js";
 
 export type { DividendHistoryEntry, DividendStats };
@@ -30,35 +30,32 @@ export class DrizzleDividendRepository implements IDividendRepository {
   constructor(private readonly db: DrizzleDb) {}
 
   async getStats(tenantId: string): Promise<DividendStats> {
-    // 1. Pool = sum of purchase amounts from yesterday UTC
+    // 1. Pool = sum of purchase credit amounts from yesterday UTC
     const poolRow = (
       await this.db
-        // raw SQL: Drizzle cannot express COALESCE(SUM(...), 0) aggregate
-        .select({ total: sql<number>`COALESCE(SUM(${creditTransactions.amount}), 0)` })
-        .from(creditTransactions)
+        .select({ total: sql<string>`COALESCE(SUM(${journalLines.amount}), 0)` })
+        .from(journalLines)
+        .innerJoin(journalEntries, eq(journalEntries.id, journalLines.journalEntryId))
         .where(
           and(
-            eq(creditTransactions.type, "purchase"),
-            // raw SQL: Drizzle cannot express date_trunc with interval arithmetic
-            sql`${creditTransactions.createdAt}::timestamp >= date_trunc('day', timezone('UTC', now())) - INTERVAL '1 day'`,
-            sql`${creditTransactions.createdAt}::timestamp < date_trunc('day', timezone('UTC', now()))`,
+            eq(journalEntries.entryType, "purchase"),
+            eq(journalLines.side, "credit"),
+            sql`${journalEntries.postedAt}::timestamp >= date_trunc('day', timezone('UTC', now())) - INTERVAL '1 day'`,
+            sql`${journalEntries.postedAt}::timestamp < date_trunc('day', timezone('UTC', now()))`,
           ),
         )
     )[0];
-    const poolCents = poolRow?.total ?? 0;
-    const pool = Credit.fromCents(poolCents);
+    const pool = Credit.fromRaw(Number(poolRow?.total ?? 0));
 
     // 2. Active users = distinct tenants with a purchase in the last 7 days
     const activeRow = (
       await this.db
-        // raw SQL: Drizzle cannot express COUNT(DISTINCT col)
-        .select({ count: sql<number>`COUNT(DISTINCT ${creditTransactions.tenantId})` })
-        .from(creditTransactions)
+        .select({ count: sql<number>`COUNT(DISTINCT ${journalEntries.tenantId})` })
+        .from(journalEntries)
         .where(
           and(
-            eq(creditTransactions.type, "purchase"),
-            // raw SQL: Drizzle cannot express timestamp comparison with interval arithmetic
-            sql`${creditTransactions.createdAt}::timestamp >= timezone('UTC', now()) - INTERVAL '7 days'`,
+            eq(journalEntries.entryType, "purchase"),
+            sql`${journalEntries.postedAt}::timestamp >= timezone('UTC', now()) - INTERVAL '7 days'`,
           ),
         )
     )[0];
@@ -75,10 +72,10 @@ export class DrizzleDividendRepository implements IDividendRepository {
     // 5. User eligibility — last purchase within 7 days
     const userPurchaseRow = (
       await this.db
-        .select({ createdAt: creditTransactions.createdAt })
-        .from(creditTransactions)
-        .where(and(eq(creditTransactions.tenantId, tenantId), eq(creditTransactions.type, "purchase")))
-        .orderBy(desc(creditTransactions.createdAt))
+        .select({ postedAt: journalEntries.postedAt })
+        .from(journalEntries)
+        .where(and(eq(journalEntries.tenantId, tenantId), eq(journalEntries.entryType, "purchase")))
+        .orderBy(desc(journalEntries.postedAt))
         .limit(1)
     )[0];
 
@@ -87,10 +84,7 @@ export class DrizzleDividendRepository implements IDividendRepository {
     let userWindowExpiresAt: string | null = null;
 
     if (userPurchaseRow) {
-      const rawTs = userPurchaseRow.createdAt;
-      // Parse the timestamp directly. PGlite may return ISO strings with or without
-      // timezone suffix. JavaScript's Date constructor handles ISO 8601 strings natively.
-      const lastPurchase = new Date(rawTs);
+      const lastPurchase = new Date(userPurchaseRow.postedAt);
       userLastPurchaseAt = lastPurchase.toISOString();
 
       const windowExpiry = new Date(lastPurchase.getTime() + 7 * 24 * 60 * 60 * 1000);

package/src/monetization/credits/index.ts

@@ -2,24 +2,24 @@ export type {
   AutoTopupSettings,
   CreditExpiryCronConfig,
   CreditExpiryCronResult,
-  CreditTransaction,
   CreditType,
   DebitType,
   HistoryOptions,
   IAutoTopupSettingsRepository,
-  ICreditLedger,
+  ILedger,
+  JournalEntry,
   TransactionType,
 } from "@wopr-network/platform-core/credits";
 export {
   ALLOWED_SCHEDULE_INTERVALS,
   ALLOWED_THRESHOLDS,
   ALLOWED_TOPUP_AMOUNTS,
-  CreditLedger,
   computeNextScheduleAt,
   DrizzleAutoTopupSettingsRepository,
-  DrizzleCreditLedger,
+  DrizzleLedger,
   grantSignupCredits,
   InsufficientBalanceError,
+  Ledger,
   runCreditExpiryCron,
   SIGNUP_GRANT,
 } from "@wopr-network/platform-core/credits";

package/src/monetization/credits/member-usage.test.ts

@@ -1,13 +1,13 @@
 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";
 
-describe("DrizzleCreditLedger.memberUsage", () => {
+describe("DrizzleDrizzleLedger.memberUsage", () => {
   let pool: PGlite;
   let db: DrizzleDb;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
 
   beforeAll(async () => {
     ({ db, pool } = await createTestDb());
@@ -19,14 +19,25 @@ 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);
@@ -41,9 +52,12 @@ describe("DrizzleCreditLedger.memberUsage", () => {
   });
 
   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);

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,