@wopr-network/platform-core 1.13.3 → 1.14.0

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 () => {

package/src/monetization/credits/trial-balance-cron.test.ts

@@ -0,0 +1,52 @@
+import type { PGlite } from "@electric-sql/pglite";
+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: PGlite;
+  let ledger: DrizzleLedger;
+
+  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/src/monetization/feature-gate.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";
 import { DAILY_BOT_COST } from "./credits/runtime-cron.js";
@@ -74,7 +74,7 @@ export function createFeatureGate(cfg: FeatureGateConfig) {
 /**
  * Convenience factory that creates a requireBalance middleware from a CreditLedger instance.
  */
-export function createBalanceGate(ledger: CreditLedger, userKey?: string, userIdField?: string) {
+export function createBalanceGate(ledger: ILedger, userKey?: string, userIdField?: string) {
   return createFeatureGate({
     getUserBalance: (tenantId) => ledger.balance(tenantId),
     userKey,
@@ -94,7 +94,7 @@ export type ResolveTenantId = (c: Context) => string | undefined | Promise<strin
 
 export interface CreditGateConfig {
   /** CreditLedger instance used to check balance. */
-  ledger: CreditLedger;
+  ledger: ILedger;
   /** Resolve the tenant ID from the request context. */
   resolveTenantId: ResolveTenantId;
 }

package/src/monetization/index.ts

@@ -134,11 +134,12 @@ export { BudgetChecker, DrizzleBudgetChecker } from "./budget/index.js";
 // Credit ledger (WOP-384)
 export type {
   BillingState,
-  CreditTransaction,
   CreditType,
   DebitType,
   GetActiveBotCount,
   HistoryOptions,
+  ILedger,
+  JournalEntry,
   OnSuspend,
   RuntimeCronConfig,
   RuntimeCronResult,
@@ -147,12 +148,12 @@ export type {
 export {
   BotBilling,
   buildResourceTierCosts,
-  CreditLedger,
   DAILY_BOT_COST,
   DrizzleBotBilling,
-  DrizzleCreditLedger,
+  DrizzleLedger,
   grantSignupCredits,
   InsufficientBalanceError,
+  Ledger,
   runRuntimeDeductions,
   SIGNUP_GRANT,
   SUSPENSION_GRACE_DAYS,
@@ -215,7 +216,6 @@ export {
 export type {
   IBotBilling,
   IBudgetChecker,
-  ICreditLedger,
   IMeterAggregator,
   IMeterEmitter,
   IPayRamChargeRepository,

package/src/monetization/metering/reconciliation-cron.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 { runReconciliation } from "@wopr-network/platform-core/metering";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { DrizzleDb } from "../../db/index.js";
@@ -17,7 +17,7 @@ const DAY_END = DAY_START + 24 * 60 * 60 * 1000;
 describe("runReconciliation", () => {
   let pool: PGlite;
   let db: DrizzleDb;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
   let usageSummaryRepo: DrizzleUsageSummaryRepository;
   let adapterUsageRepo: DrizzleAdapterUsageRepository;
 
@@ -25,7 +25,7 @@ describe("runReconciliation", () => {
     const t = await createTestDb();
     pool = t.pool;
     db = t.db;
-    ledger = new CreditLedger(db);
+    ledger = new DrizzleLedger(db);
     usageSummaryRepo = new DrizzleUsageSummaryRepository(db);
     adapterUsageRepo = new DrizzleAdapterUsageRepository(db);
   });
@@ -36,6 +36,7 @@ describe("runReconciliation", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
+    await ledger.seedSystemAccounts();
   });
 
   /** Insert a usage_summaries row directly. */
@@ -74,7 +75,7 @@ describe("runReconciliation", () => {
     await insertSummary({ tenant: "t1", totalCharge: charge.toRaw() });
 
     await ledger.credit("t1", Credit.fromCents(500), "purchase");
-    await ledger.debit("t1", charge, "adapter_usage", "chat usage");
+    await ledger.debit("t1", charge, "adapter_usage", { description: "chat usage" });
 
     const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
     expect(result.tenantsChecked).toBe(1);
@@ -85,7 +86,7 @@ describe("runReconciliation", () => {
     await insertSummary({ tenant: "t1", totalCharge: Credit.fromCents(100).toRaw() });
 
     await ledger.credit("t1", Credit.fromCents(500), "purchase");
-    await ledger.debit("t1", Credit.fromCents(80), "adapter_usage", "chat usage");
+    await ledger.debit("t1", Credit.fromCents(80), "adapter_usage", { description: "chat usage" });
 
     const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
     expect(result.tenantsChecked).toBe(1);
@@ -117,7 +118,7 @@ describe("runReconciliation", () => {
 
     await ledger.credit("t1", Credit.fromCents(500), "purchase");
     // Debit as bot_runtime — should NOT count toward reconciliation
-    await ledger.debit("t1", Credit.fromCents(20), "bot_runtime", "daily runtime");
+    await ledger.debit("t1", Credit.fromCents(20), "bot_runtime", { description: "daily runtime" });
 
     const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
     // Metered 20c, ledger adapter_usage = 0 => drift = 20c
@@ -149,12 +150,12 @@ describe("runReconciliation", () => {
     // t1: balanced
     await insertSummary({ tenant: "t1", totalCharge: Credit.fromCents(50).toRaw() });
     await ledger.credit("t1", Credit.fromCents(500), "purchase");
-    await ledger.debit("t1", Credit.fromCents(50), "adapter_usage", "chat");
+    await ledger.debit("t1", Credit.fromCents(50), "adapter_usage", { description: "chat" });
 
     // t2: drifted
     await insertSummary({ tenant: "t2", totalCharge: Credit.fromCents(100).toRaw() });
     await ledger.credit("t2", Credit.fromCents(500), "purchase");
-    await ledger.debit("t2", Credit.fromCents(60), "adapter_usage", "chat");
+    await ledger.debit("t2", Credit.fromCents(60), "adapter_usage", { description: "chat" });
 
     const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
     expect(result.tenantsChecked).toBe(2);
@@ -192,7 +193,7 @@ describe("runReconciliation", () => {
     await insertSummary({ tenant: "t1", totalCharge: Credit.fromCents(50).toRaw() });
 
     await ledger.credit("t1", Credit.fromCents(500), "purchase");
-    await ledger.debit("t1", Credit.fromCents(80), "adapter_usage", "chat usage");
+    await ledger.debit("t1", Credit.fromCents(80), "adapter_usage", { description: "chat usage" });
 
     const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
     expect(result.discrepancies).toHaveLength(1);

package/src/monetization/metering/reconciliation-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 { createTestDb, seedUsageSummary, truncateAllTables } from "../../test/db.js";
@@ -125,12 +125,14 @@ describe("DrizzleUsageSummaryRepository", () => {
 
 describe("DrizzleAdapterUsageRepository", () => {
   let repo: DrizzleAdapterUsageRepository;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
 
   beforeEach(async () => {
     await truncateAllTables(pool);
     repo = new DrizzleAdapterUsageRepository(db);
-    ledger = new CreditLedger(db);
+    ledger = new DrizzleLedger(db);
+
+    await ledger.seedSystemAccounts();
   });
 
   it("returns empty array when no adapter_usage debits exist", async () => {
@@ -146,9 +148,9 @@ describe("DrizzleAdapterUsageRepository", () => {
     await ledger.credit("t1", Credit.fromCents(1000), "purchase");
     await ledger.credit("t2", Credit.fromCents(1000), "purchase");
 
-    await ledger.debit("t1", Credit.fromCents(30), "adapter_usage", "t1-debit-1");
-    await ledger.debit("t1", Credit.fromCents(20), "adapter_usage", "t1-debit-2");
-    await ledger.debit("t2", Credit.fromCents(50), "adapter_usage", "t2-debit-1");
+    await ledger.debit("t1", Credit.fromCents(30), "adapter_usage", { description: "t1-debit-1" });
+    await ledger.debit("t1", Credit.fromCents(20), "adapter_usage", { description: "t1-debit-2" });
+    await ledger.debit("t2", Credit.fromCents(50), "adapter_usage", { description: "t2-debit-1" });
 
     // Query window covering today
     const today = new Date().toISOString().slice(0, 10);
@@ -167,8 +169,8 @@ describe("DrizzleAdapterUsageRepository", () => {
 
   it("excludes non-adapter_usage debit types", async () => {
     await ledger.credit("t1", Credit.fromCents(1000), "purchase");
-    await ledger.debit("t1", Credit.fromCents(30), "adapter_usage", "adapter debit");
-    await ledger.debit("t1", Credit.fromCents(20), "bot_runtime", "runtime debit");
+    await ledger.debit("t1", Credit.fromCents(30), "adapter_usage", { description: "adapter debit" });
+    await ledger.debit("t1", Credit.fromCents(20), "bot_runtime", { description: "runtime debit" });
 
     const today = new Date().toISOString().slice(0, 10);
     const startIso = `${today}T00:00:00Z`;
@@ -181,7 +183,7 @@ describe("DrizzleAdapterUsageRepository", () => {
 
   it("excludes credit transactions (positive amounts are not debits)", async () => {
     await ledger.credit("t1", Credit.fromCents(1000), "purchase");
-    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "real debit");
+    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", { description: "real debit" });
 
     const today = new Date().toISOString().slice(0, 10);
     const startIso = `${today}T00:00:00Z`;

package/src/monetization/metering/reconciliation-repository.ts

@@ -1,6 +1,6 @@
 import { and, eq, gte, lt, ne, sql } from "drizzle-orm";
 import type { DrizzleDb } from "../../db/index.js";
-import { creditTransactions } from "../../db/schema/credits.js";
+import { journalEntries, journalLines } from "../../db/schema/ledger.js";
 import { usageSummaries } from "../../db/schema/meter-events.js";
 
 // ---------------------------------------------------------------------------
@@ -59,24 +59,26 @@ export class DrizzleAdapterUsageRepository implements IAdapterUsageRepository {
   constructor(private readonly db: DrizzleDb) {}
 
   async getAggregatedAdapterUsageDebits(startIso: string, endIso: string): Promise<AggregatedDebit[]> {
+    // Sum the debit-side journal line amounts for adapter_usage entries.
+    // In double-entry: DR tenant liability (2000:<tenantId>), CR revenue:adapter_usage (4010).
     const rows = await this.db
       .select({
-        tenantId: creditTransactions.tenantId,
-        // amount_credits stores negative values for debits; ABS gives the raw positive debit amount.
-        // Use the raw column name in sql to bypass the custom creditColumn type serializer.
-        // raw SQL: Drizzle cannot express ABS with COALESCE and SUM
-        totalDebitRaw: sql<number>`COALESCE(SUM(ABS(amount_credits)), 0)`,
+        tenantId: journalEntries.tenantId,
+        // raw SQL: Drizzle cannot express COALESCE with SUM aggregation
+        totalDebitRaw: sql<number>`COALESCE(SUM(${journalLines.amount}), 0)`,
       })
-      .from(creditTransactions)
+      .from(journalLines)
+      .innerJoin(journalEntries, eq(journalEntries.id, journalLines.journalEntryId))
       .where(
         and(
-          eq(creditTransactions.type, "adapter_usage"),
+          eq(journalEntries.entryType, "adapter_usage"),
+          eq(journalLines.side, "debit"),
           // raw SQL: Drizzle cannot express timestamptz cast for text column date comparison
-          sql`${creditTransactions.createdAt}::timestamptz >= ${startIso}::timestamptz`,
-          sql`${creditTransactions.createdAt}::timestamptz < ${endIso}::timestamptz`,
+          sql`${journalEntries.postedAt}::timestamptz >= ${startIso}::timestamptz`,
+          sql`${journalEntries.postedAt}::timestamptz < ${endIso}::timestamptz`,
         ),
       )
-      .groupBy(creditTransactions.tenantId);
+      .groupBy(journalEntries.tenantId);
 
     return rows.map((r) => ({ tenantId: r.tenantId, totalDebitRaw: Number(r.totalDebitRaw) }));
   }

package/src/monetization/payram/webhook.test.ts

@@ -12,7 +12,7 @@ import {
   noOpReplayGuard,
   PayRamChargeRepository,
 } from "@wopr-network/platform-core/billing";
-import { CreditLedger } from "@wopr-network/platform-core/credits";
+import { DrizzleLedger } 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";
@@ -44,13 +44,15 @@ afterAll(async () => {
 
 describe("handlePayRamWebhook", () => {
   let chargeStore: PayRamChargeRepository;
-  let creditLedger: CreditLedger;
+  let creditLedger: DrizzleLedger;
   let deps: PayRamWebhookDeps;
 
   beforeEach(async () => {
     await truncateAllTables(pool);
     chargeStore = new PayRamChargeRepository(db);
-    creditLedger = new CreditLedger(db);
+    creditLedger = new DrizzleLedger(db);
+
+    await creditLedger.seedSystemAccounts();
     deps = { chargeStore, creditLedger, replayGuard: noOpReplayGuard };
 
     // Create a default test charge
@@ -80,14 +82,14 @@ describe("handlePayRamWebhook", () => {
       const history = await creditLedger.history("tenant-a");
       expect(history).toHaveLength(1);
       expect(history[0].referenceId).toBe("payram:ref-test-001");
-      expect(history[0].type).toBe("purchase");
+      expect(history[0].entryType).toBe("purchase");
     });
 
     it("records fundingSource as payram", async () => {
       await handlePayRamWebhook(deps, makePayload({ status: "FILLED" }));
 
       const history = await creditLedger.history("tenant-a");
-      expect(history[0].fundingSource).toBe("payram");
+      expect(history[0].metadata?.fundingSource).toBe("payram");
     });
 
     it("marks the charge as credited after FILLED", async () => {

package/src/monetization/payram/webhook.ts

@@ -4,13 +4,13 @@ import type {
   PayRamWebhookPayload,
   PayRamWebhookResult,
 } from "@wopr-network/platform-core/billing";
-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 { BotBilling } from "../credits/bot-billing.js";
 
 export interface PayRamWebhookDeps {
   chargeStore: PayRamChargeRepository;
-  creditLedger: ICreditLedger;
+  creditLedger: ILedger;
   botBilling?: BotBilling;
   replayGuard: IWebhookSeenRepository;
 }
@@ -60,14 +60,11 @@ export async function handlePayRamWebhook(
       // overpayment stays in the PayRam wallet as a buffer.
       const creditCents = charge.amountUsdCents;
 
-      await creditLedger.credit(
-        charge.tenantId,
-        Credit.fromCents(creditCents),
-        "purchase",
-        `Crypto credit purchase via PayRam (ref: ${payload.reference_id}, ${payload.currency ?? "crypto"})`,
-        `payram:${payload.reference_id}`,
-        "payram",
-      );
+      await creditLedger.credit(charge.tenantId, Credit.fromCents(creditCents), "purchase", {
+        description: `Crypto credit purchase via PayRam (ref: ${payload.reference_id}, ${payload.currency ?? "crypto"})`,
+        referenceId: `payram:${payload.reference_id}`,
+        fundingSource: "payram",
+      });
 
       await chargeStore.markCredited(payload.reference_id);
 

package/src/monetization/promotions/engine.test.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 { beforeEach, describe, expect, it, vi } from "vitest";
 import type { ICouponRepository } from "./coupon-repository.js";
@@ -40,7 +40,7 @@ describe("PromotionEngine", () => {
   let promotionRepo: IPromotionRepository;
   let couponRepo: ICouponRepository;
   let redemptionRepo: IRedemptionRepository;
-  let ledger: ICreditLedger;
+  let ledger: ILedger;
   let engine: PromotionEngine;
 
   beforeEach(() => {
@@ -95,7 +95,7 @@ describe("PromotionEngine", () => {
         createdAt: new Date().toISOString(),
       }),
       hasReferenceId: vi.fn().mockResolvedValue(false),
-    } as unknown as ICreditLedger;
+    } as unknown as ILedger;
 
     engine = new PromotionEngine({ promotionRepo, couponRepo, redemptionRepo, ledger });
   });
@@ -111,8 +111,9 @@ describe("PromotionEngine", () => {
       "tenant-1",
       expect.any(Object), // Credit instance
       "promo",
-      expect.any(String),
-      "promo:promo-1:tenant-1:1",
+      expect.objectContaining({
+        referenceId: "promo:promo-1:tenant-1:1",
+      }),
     );
   });