@wopr-network/platform-core 1.13.2 → 1.14.0

package/src/backup/on-demand-snapshot-service.test.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 { describe, expect, it, vi } from "vitest";
 import {
@@ -48,8 +48,8 @@ function makeManager(overrides: Record<string, unknown> = {}): SnapshotManager {
   } as unknown as SnapshotManager;
 }
 
-function makeLedger(balanceCents = 100): CreditLedger {
-  return { balance: vi.fn().mockResolvedValue(Credit.fromCents(balanceCents)) } as unknown as CreditLedger;
+function makeLedger(balanceCents = 100): ILedger {
+  return { balance: vi.fn().mockResolvedValue(Credit.fromCents(balanceCents)) } as unknown as ILedger;
 }
 
 function makeService(managerOverrides: Record<string, unknown> = {}, balanceCents = 100) {

package/src/backup/on-demand-snapshot-service.ts

@@ -1,11 +1,11 @@
-import type { CreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import type { SnapshotManager } from "./snapshot-manager.js";
 import type { Snapshot, Tier } from "./types.js";
 import { SNAPSHOT_TIER_POLICIES, STORAGE_CHARGE_PER_GB_MONTH, STORAGE_COST_PER_GB_MONTH } from "./types.js";
 
 export interface OnDemandSnapshotServiceConfig {
   manager: SnapshotManager;
-  ledger: CreditLedger;
+  ledger: ILedger;
 }
 
 export interface CreateSnapshotParams {
@@ -25,7 +25,7 @@ export interface CreateSnapshotResult {
 
 export class OnDemandSnapshotService {
   private readonly manager: SnapshotManager;
-  private readonly ledger: CreditLedger;
+  private readonly ledger: ILedger;
 
   constructor(cfg: OnDemandSnapshotServiceConfig) {
     this.manager = cfg.manager;

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

@@ -7,7 +7,7 @@
 
 import type { PGlite } from "@electric-sql/pglite";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import { CreditLedger } from "../../credits/credit-ledger.js";
+import { DrizzleLedger } from "../../credits/ledger.js";
 import type { PlatformDb } from "../../db/index.js";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
 import { DrizzleWebhookSeenRepository } from "../drizzle-webhook-seen-repository.js";
@@ -41,13 +41,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
@@ -77,14 +79,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/billing/payram/webhook.ts

@@ -1,15 +1,15 @@
 import { Credit } from "../../credits/credit.js";
-import type { ICreditLedger } from "../../credits/credit-ledger.js";
+import type { ILedger } from "../../credits/ledger.js";
 import type { IWebhookSeenRepository } from "../webhook-seen-repository.js";
 import type { PayRamChargeRepository } from "./charge-store.js";
 import type { PayRamWebhookPayload, PayRamWebhookResult } from "./types.js";
 
 export interface PayRamWebhookDeps {
   chargeStore: PayRamChargeRepository;
-  creditLedger: ICreditLedger;
+  creditLedger: ILedger;
   replayGuard: IWebhookSeenRepository;
   /** Called after credits are purchased — consumer can reactivate suspended resources. Returns reactivated resource IDs. */
-  onCreditsPurchased?: (tenantId: string, ledger: ICreditLedger) => Promise<string[]>;
+  onCreditsPurchased?: (tenantId: string, ledger: ILedger) => Promise<string[]>;
 }
 
 /**
@@ -57,14 +57,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/billing/stripe/stripe-payment-processor.test.ts

@@ -2,7 +2,7 @@ import type Stripe from "stripe";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { IAutoTopupEventLogRepository } from "../../credits/auto-topup-event-log-repository.js";
 import { Credit } from "../../credits/credit.js";
-import type { CreditTransaction, ICreditLedger } from "../../credits/credit-ledger.js";
+import type { ILedger, JournalEntry } from "../../credits/ledger.js";
 import { PaymentMethodOwnershipError } from "../payment-processor.js";
 import type { CreditPriceMap } from "./credit-prices.js";
 import { StripePaymentProcessor } from "./stripe-payment-processor.js";
@@ -58,7 +58,8 @@ function createMocks() {
     buildCustomerIdMap: vi.fn(),
   };
 
-  const creditLedger: ICreditLedger = {
+  const creditLedger: ILedger = {
+    post: vi.fn(),
     credit: vi.fn(),
     debit: vi.fn(),
     balance: vi.fn(),
@@ -69,6 +70,12 @@ function createMocks() {
     expiredCredits: vi.fn(),
     lifetimeSpend: vi.fn(),
     lifetimeSpendBatch: vi.fn().mockResolvedValue(new Map()),
+    trialBalance: vi.fn(),
+    accountBalance: vi.fn(),
+    seedSystemAccounts: vi.fn(),
+    existsByReferenceIdLike: vi.fn(),
+    sumPurchasesForPeriod: vi.fn(),
+    getActiveTenantIdsInWindow: vi.fn(),
   };
 
   const autoTopupEventLog: IAutoTopupEventLogRepository = {
@@ -330,7 +337,7 @@ describe("StripePaymentProcessor", () => {
         status: "succeeded",
       } as unknown as Stripe.Response<Stripe.PaymentIntent>);
       vi.mocked(mocks.creditLedger.hasReferenceId).mockResolvedValue(false);
-      vi.mocked(mocks.creditLedger.credit).mockResolvedValue({} as unknown as CreditTransaction);
+      vi.mocked(mocks.creditLedger.credit).mockResolvedValue({} as unknown as JournalEntry);
       vi.mocked(mocks.autoTopupEventLog.writeEvent).mockResolvedValue(undefined);
 
       const result = await processor.charge({

package/src/billing/stripe/stripe-payment-processor.ts

@@ -2,7 +2,7 @@ import type Stripe from "stripe";
 import { chargeAutoTopup } from "../../credits/auto-topup-charge.js";
 import type { IAutoTopupEventLogRepository } from "../../credits/auto-topup-event-log-repository.js";
 import { Credit } from "../../credits/credit.js";
-import type { ICreditLedger } from "../../credits/credit-ledger.js";
+import type { ILedger } from "../../credits/ledger.js";
 import {
   type ChargeOpts,
   type ChargeResult,
@@ -37,7 +37,7 @@ export interface StripePaymentProcessorDeps {
   tenantRepo: ITenantCustomerRepository;
   webhookSecret: string;
   priceMap?: CreditPriceMap;
-  creditLedger: ICreditLedger;
+  creditLedger: ILedger;
   autoTopupEventLog?: IAutoTopupEventLogRepository;
   /** Consumer-supplied webhook handler (handles domain-specific event processing). */
   webhookHandler?: (event: Stripe.Event) => Promise<StripeWebhookHandlerResult>;
@@ -50,7 +50,7 @@ export class StripePaymentProcessor implements IPaymentProcessor {
   private readonly tenantRepo: ITenantCustomerRepository;
   private readonly webhookSecret: string;
   private readonly priceMap: CreditPriceMap;
-  private readonly creditLedger: ICreditLedger;
+  private readonly creditLedger: ILedger;
   private readonly autoTopupEventLog?: IAutoTopupEventLogRepository;
   private readonly webhookHandler?: (event: Stripe.Event) => Promise<StripeWebhookHandlerResult>;
 

package/src/billing/stripe/tenant-store.ts

@@ -23,7 +23,7 @@ export interface ITenantCustomerRepository {
  * All billing operations look up the processor customer via this store.
  *
  * Note: No subscription tracking — WOPR uses credits, not subscriptions.
- * Credit balances are managed by ICreditLedger / DrizzleCreditLedger.
+ * Credit balances are managed by ILedger / DrizzleCreditLedger.
  */
 export class DrizzleTenantCustomerRepository implements ITenantCustomerRepository {
   constructor(private readonly db: PlatformDb) {}

package/src/credits/auto-topup-charge.test.ts

@@ -8,7 +8,7 @@ import { createTestDb, truncateAllTables } from "../test/db.js";
 import { type AutoTopupChargeDeps, chargeAutoTopup, MAX_CONSECUTIVE_FAILURES } from "./auto-topup-charge.js";
 import { DrizzleAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
 import { Credit } from "./credit.js";
-import { CreditLedger } from "./credit-ledger.js";
+import { DrizzleLedger } from "./ledger.js";
 import type { ITenantCustomerRepository } from "./tenant-customer-repository.js";
 
 function mockStripe(overrides?: {
@@ -49,7 +49,7 @@ function mockTenantStore(stripeCustomerId = "cus_123") {
 describe("chargeAutoTopup", () => {
   let pool: PGlite;
   let db: PlatformDb;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
 
   beforeAll(async () => {
     ({ db, pool } = await createTestDb());
@@ -61,7 +61,9 @@ describe("chargeAutoTopup", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
-    ledger = new CreditLedger(db);
+    ledger = new DrizzleLedger(db);
+
+    await ledger.seedSystemAccounts();
   });
 
   it("charges Stripe and credits ledger on success", async () => {
@@ -80,8 +82,8 @@ describe("chargeAutoTopup", () => {
     expect(result.paymentReference).toEqual(expect.any(String));
     expect((await ledger.balance("t1")).toCents()).toBe(500);
     const history = await ledger.history("t1");
-    expect(history[0].type).toBe("purchase");
-    expect(history[0].fundingSource).toBe("stripe");
+    expect(history[0].entryType).toBe("purchase");
+    expect(history[0].metadata?.fundingSource).toBe("stripe");
   });
 
   it("writes success event to credit_auto_topup log", async () => {

package/src/credits/auto-topup-charge.ts

@@ -2,7 +2,7 @@ import Stripe from "stripe";
 import { logger } from "../config/logger.js";
 import type { IAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
 import type { Credit } from "./credit.js";
-import type { ICreditLedger } from "./credit-ledger.js";
+import type { ILedger } from "./ledger.js";
 import type { ITenantCustomerRepository } from "./tenant-customer-repository.js";
 
 /** After this many consecutive Stripe failures, the auto-topup mode is disabled. */
@@ -11,7 +11,7 @@ export const MAX_CONSECUTIVE_FAILURES = 3;
 export interface AutoTopupChargeDeps {
   stripe: Stripe;
   tenantRepo: ITenantCustomerRepository;
-  creditLedger: ICreditLedger;
+  creditLedger: ILedger;
   eventLogRepo: IAutoTopupEventLogRepository;
 }
 
@@ -137,14 +137,11 @@ export async function chargeAutoTopup(
   // 5. Credit the ledger (idempotent via referenceId = PI ID)
   try {
     if (!(await deps.creditLedger.hasReferenceId(paymentIntent.id))) {
-      await deps.creditLedger.credit(
-        tenantId,
-        amount,
-        "purchase",
-        `Auto-topup (${source})`,
-        paymentIntent.id,
-        "stripe",
-      );
+      await deps.creditLedger.credit(tenantId, amount, "purchase", {
+        description: `Auto-topup (${source})`,
+        referenceId: paymentIntent.id,
+        fundingSource: "stripe",
+      });
     }
   } catch (err) {
     const message = `Stripe charge ${paymentIntent.id} succeeded but credit grant failed: ${err instanceof Error ? err.message : String(err)}`;

package/src/credits/auto-topup-usage.test.ts

@@ -5,12 +5,12 @@ import { createTestDb, truncateAllTables } from "../test/db.js";
 import { DrizzleAutoTopupSettingsRepository } from "./auto-topup-settings-repository.js";
 import { maybeTriggerUsageTopup, type UsageTopupDeps } from "./auto-topup-usage.js";
 import { Credit } from "./credit.js";
-import { CreditLedger } from "./credit-ledger.js";
+import { DrizzleLedger } from "./ledger.js";
 
 describe("maybeTriggerUsageTopup", () => {
   let pool: PGlite;
   let db: PlatformDb;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
   let settingsRepo: DrizzleAutoTopupSettingsRepository;
 
   beforeAll(async () => {
@@ -23,7 +23,9 @@ describe("maybeTriggerUsageTopup", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
-    ledger = new CreditLedger(db);
+    ledger = new DrizzleLedger(db);
+
+    await ledger.seedSystemAccounts();
     settingsRepo = new DrizzleAutoTopupSettingsRepository(db);
   });
 
@@ -37,7 +39,11 @@ describe("maybeTriggerUsageTopup", () => {
 
   it("does nothing when usage_enabled is false", async () => {
     await settingsRepo.upsert("t1", { usageEnabled: false });
-    await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi.fn();
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
 
@@ -51,7 +57,11 @@ describe("maybeTriggerUsageTopup", () => {
       usageThreshold: Credit.fromCents(100),
       usageTopup: Credit.fromCents(500),
     });
-    await ledger.credit("t1", Credit.fromCents(200), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(200), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi.fn();
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
 
@@ -65,7 +75,11 @@ describe("maybeTriggerUsageTopup", () => {
       usageThreshold: Credit.fromCents(100),
       usageTopup: Credit.fromCents(500),
     });
-    await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_123" });
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
 
@@ -76,7 +90,11 @@ describe("maybeTriggerUsageTopup", () => {
   it("skips when charge is already in-flight", async () => {
     await settingsRepo.upsert("t1", { usageEnabled: true, usageThreshold: Credit.fromCents(100) });
     await settingsRepo.setUsageChargeInFlight("t1", true);
-    await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi.fn();
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
 
@@ -91,7 +109,11 @@ describe("maybeTriggerUsageTopup", () => {
       usageThreshold: Credit.fromCents(500),
       usageTopup: Credit.fromCents(2000),
     });
-    await ledger.credit("t1", Credit.fromCents(100), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
 
     const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_race" });
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
@@ -115,7 +137,11 @@ describe("maybeTriggerUsageTopup", () => {
       usageThreshold: Credit.fromCents(100),
       usageTopup: Credit.fromCents(500),
     });
-    await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_123" });
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
 
@@ -137,7 +163,11 @@ describe("maybeTriggerUsageTopup", () => {
       usageThreshold: Credit.fromCents(100),
       usageTopup: Credit.fromCents(500),
     });
-    await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi
       .fn()
       .mockRejectedValueOnce(new Error("Stripe network error"))
@@ -164,7 +194,11 @@ describe("maybeTriggerUsageTopup", () => {
     });
     await settingsRepo.incrementUsageFailures("t1");
     await settingsRepo.incrementUsageFailures("t1");
-    await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi.fn().mockResolvedValue({ success: true });
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
 
@@ -178,7 +212,11 @@ describe("maybeTriggerUsageTopup", () => {
       usageThreshold: Credit.fromCents(100),
       usageTopup: Credit.fromCents(500),
     });
-    await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi.fn().mockResolvedValue({ success: false, error: "declined" });
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
 
@@ -210,7 +248,11 @@ describe("maybeTriggerUsageTopup", () => {
     });
     await settingsRepo.incrementUsageFailures("t1");
     await settingsRepo.incrementUsageFailures("t1");
-    await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+    await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+      description: "buy",
+      referenceId: "ref-1",
+      fundingSource: "stripe",
+    });
     const mockCharge = vi.fn().mockResolvedValue({ success: false, error: "declined" });
     const deps: UsageTopupDeps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
 

package/src/credits/auto-topup-usage.ts

@@ -3,11 +3,11 @@ import type { AutoTopupChargeResult } from "./auto-topup-charge.js";
 import { MAX_CONSECUTIVE_FAILURES } from "./auto-topup-charge.js";
 import type { IAutoTopupSettingsRepository } from "./auto-topup-settings-repository.js";
 import type { Credit } from "./credit.js";
-import type { ICreditLedger } from "./credit-ledger.js";
+import type { ILedger } from "./ledger.js";
 
 export interface UsageTopupDeps {
   settingsRepo: IAutoTopupSettingsRepository;
-  creditLedger: ICreditLedger;
+  creditLedger: ILedger;
   /** Injected charge function (allows mocking in tests). */
   chargeAutoTopup: (tenantId: string, amount: Credit, source: string) => Promise<AutoTopupChargeResult>;
   /** Optional tenant status check. If provided and returns non-null, skip the charge. */

package/src/credits/credit-expiry-cron.test.ts

@@ -3,16 +3,16 @@ import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { createTestDb, truncateAllTables } from "../test/db.js";
 import { Credit } from "./credit.js";
 import { runCreditExpiryCron } from "./credit-expiry-cron.js";
-import { DrizzleCreditLedger } from "./credit-ledger.js";
+import { DrizzleLedger } from "./ledger.js";
 
 describe("runCreditExpiryCron", () => {
   let pool: PGlite;
-  let ledger: DrizzleCreditLedger;
+  let ledger: DrizzleLedger;
 
   beforeAll(async () => {
     const { db, pool: p } = await createTestDb();
     pool = p;
-    ledger = new DrizzleCreditLedger(db);
+    ledger = new DrizzleLedger(db);
   });
 
   afterAll(async () => {
@@ -21,6 +21,7 @@ describe("runCreditExpiryCron", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
+    await ledger.seedSystemAccounts();
   });
 
   // All tests pass an explicit `now` parameter — hardcoded dates are time-independent
@@ -33,16 +34,11 @@ describe("runCreditExpiryCron", () => {
   });
 
   it("debits expired promotional credit grant", async () => {
-    await ledger.credit(
-      "tenant-1",
-      Credit.fromCents(500),
-      "promo",
-      "New user bonus",
-      "promo:tenant-1",
-      undefined,
-      undefined,
-      "2026-01-10T00:00:00Z",
-    );
+    await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+      description: "New user bonus",
+      referenceId: "promo:tenant-1",
+      expiresAt: "2026-01-10T00:00:00Z",
+    });
 
     const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
     expect(result.processed).toBe(1);
@@ -53,16 +49,11 @@ describe("runCreditExpiryCron", () => {
   });
 
   it("does not debit non-expired credits", async () => {
-    await ledger.credit(
-      "tenant-1",
-      Credit.fromCents(500),
-      "promo",
-      "Future bonus",
-      "promo:tenant-1-future",
-      undefined,
-      undefined,
-      "2026-02-01T00:00:00Z",
-    );
+    await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+      description: "Future bonus",
+      referenceId: "promo:tenant-1-future",
+      expiresAt: "2026-02-01T00:00:00Z",
+    });
 
     const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
     expect(result.processed).toBe(0);
@@ -72,7 +63,7 @@ describe("runCreditExpiryCron", () => {
   });
 
   it("does not debit credits without expires_at", 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 runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
     expect(result.processed).toBe(0);
@@ -82,17 +73,12 @@ describe("runCreditExpiryCron", () => {
   });
 
   it("only debits up to available balance when partially consumed", async () => {
-    await ledger.credit(
-      "tenant-1",
-      Credit.fromCents(500),
-      "promo",
-      "Promo",
-      "promo:partial",
-      undefined,
-      undefined,
-      "2026-01-10T00:00:00Z",
-    );
-    await ledger.debit("tenant-1", Credit.fromCents(300), "bot_runtime", "Runtime");
+    await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+      description: "Promo",
+      referenceId: "promo:partial",
+      expiresAt: "2026-01-10T00:00:00Z",
+    });
+    await ledger.debit("tenant-1", Credit.fromCents(300), "bot_runtime", { description: "Runtime" });
 
     const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
     expect(result.processed).toBe(1);
@@ -102,16 +88,11 @@ describe("runCreditExpiryCron", () => {
   });
 
   it("is idempotent -- does not double-debit on second run", async () => {
-    await ledger.credit(
-      "tenant-1",
-      Credit.fromCents(500),
-      "promo",
-      "Promo",
-      "promo:idemp",
-      undefined,
-      undefined,
-      "2026-01-10T00:00:00Z",
-    );
+    await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+      description: "Promo",
+      referenceId: "promo:idemp",
+      expiresAt: "2026-01-10T00:00:00Z",
+    });
 
     await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
     const balanceAfterFirst = await ledger.balance("tenant-1");

package/src/credits/credit-expiry-cron.ts

@@ -1,9 +1,9 @@
 import { logger } from "../config/logger.js";
-import type { ICreditLedger } from "./credit-ledger.js";
-import { InsufficientBalanceError } from "./credit-ledger.js";
+import type { ILedger } from "./ledger.js";
+import { InsufficientBalanceError } from "./ledger.js";
 
 export interface CreditExpiryCronConfig {
-  ledger: ICreditLedger;
+  ledger: ILedger;
   /** Current time as ISO-8601 string. */
   now: string;
 }
@@ -42,13 +42,10 @@ export async function runCreditExpiryCron(cfg: CreditExpiryCronConfig): Promise<
       // Debit the lesser of the original grant amount or current balance
       const debitAmount = balance.lessThan(grant.amount) ? balance : grant.amount;
 
-      await cfg.ledger.debit(
-        grant.tenantId,
-        debitAmount,
-        "credit_expiry",
-        `Expired credit grant reclaimed: ${grant.id}`,
-        `expiry:${grant.id}`,
-      );
+      await cfg.ledger.debit(grant.tenantId, debitAmount, "credit_expiry", {
+        description: `Expired credit grant reclaimed: ${grant.entryId}`,
+        referenceId: `expiry:${grant.entryId}`,
+      });
 
       result.processed++;
       if (!result.expired.includes(grant.tenantId)) {
@@ -59,8 +56,8 @@ export async function runCreditExpiryCron(cfg: CreditExpiryCronConfig): Promise<
         result.skippedZeroBalance++;
       } else {
         const msg = err instanceof Error ? err.message : String(err);
-        logger.error("Credit expiry failed", { tenantId: grant.tenantId, txnId: grant.id, error: msg });
-        result.errors.push(`${grant.tenantId}:${grant.id}: ${msg}`);
+        logger.error("Credit expiry failed", { tenantId: grant.tenantId, entryId: grant.entryId, error: msg });
+        result.errors.push(`${grant.tenantId}:${grant.entryId}: ${msg}`);
       }
     }
   }

package/src/credits/credit-ledger.ts

@@ -95,7 +95,7 @@ export class InsufficientBalanceError extends Error {
   }
 }
 
-export interface ICreditLedger {
+export interface ILedger {
   credit(
     tenantId: string,
     amount: Credit,
@@ -135,7 +135,7 @@ export interface ICreditLedger {
  * creditBalances row is always consistent with the sum of creditTransactions.
  * Zero raw SQL in application code.
  */
-export class DrizzleCreditLedger implements ICreditLedger {
+export class DrizzleCreditLedger implements ILedger {
   constructor(private readonly db: PlatformDb) {}
 
   /**
@@ -446,5 +446,5 @@ export class DrizzleCreditLedger implements ICreditLedger {
   }
 }
 
-// Backward-compat alias — callers using 'new CreditLedger(db)' continue to work.
+// Backward-compat alias — callers using 'new DrizzleLedger(db)' continue to work.
 export { DrizzleCreditLedger as CreditLedger };