@wopr-network/platform-core 1.13.2 → 1.14.0

package/dist/api/routes/admin-credits.d.ts

@@ -1,9 +1,9 @@
 import { Hono } from "hono";
 import type { AuthEnv } from "../../auth/index.js";
-import type { ICreditLedger } from "../../credits/index.js";
+import type { ILedger } from "../../credits/index.js";
 import type { AdminAuditLogger } from "./admin-audit-helper.js";
 /**
  * Create admin credit API routes.
  * Pass a ledger directly or a factory for lazy init.
  */
-export declare function createAdminCreditApiRoutes(ledgerOrFactory: ICreditLedger | (() => ICreditLedger), auditLogger?: () => AdminAuditLogger): Hono<AuthEnv>;
+export declare function createAdminCreditApiRoutes(ledgerOrFactory: ILedger | (() => ILedger), auditLogger?: () => AdminAuditLogger): Hono<AuthEnv>;

package/dist/api/routes/admin-credits.js

@@ -53,7 +53,10 @@ export function createAdminCreditApiRoutes(ledgerOrFactory, auditLogger) {
             const adminUser = user?.id ?? "unknown";
             let result;
             try {
-                result = await ledger.credit(tenant, Credit.fromCents(amountCents), "admin_grant", reason, undefined, undefined, adminUser);
+                result = await ledger.credit(tenant, Credit.fromCents(amountCents), "admin_grant", {
+                    description: reason,
+                    createdBy: adminUser,
+                });
             }
             catch (err) {
                 safeAuditLog(auditLogger, {
@@ -106,7 +109,7 @@ export function createAdminCreditApiRoutes(ledgerOrFactory, auditLogger) {
             const adminUser = user?.id ?? "unknown";
             let result;
             try {
-                result = await ledger.credit(tenant, Credit.fromCents(amountCents), "admin_grant", reason);
+                result = await ledger.credit(tenant, Credit.fromCents(amountCents), "admin_grant", { description: reason });
             }
             catch (err) {
                 safeAuditLog(auditLogger, {
@@ -163,10 +166,12 @@ export function createAdminCreditApiRoutes(ledgerOrFactory, auditLogger) {
             let result;
             try {
                 if (amountCents >= 0) {
-                    result = await ledger.credit(tenant, Credit.fromCents(amountCents), "promo", reason);
+                    result = await ledger.credit(tenant, Credit.fromCents(amountCents), "correction", { description: reason });
                 }
                 else {
-                    result = await ledger.debit(tenant, Credit.fromCents(Math.abs(amountCents)), "correction", reason);
+                    result = await ledger.debit(tenant, Credit.fromCents(Math.abs(amountCents)), "correction", {
+                        description: reason,
+                    });
                 }
             }
             catch (err) {

package/dist/api/routes/quota.d.ts

@@ -1,8 +1,8 @@
 import { Hono } from "hono";
-import type { ICreditLedger } from "../../credits/credit-ledger.js";
+import type { ILedger } from "../../credits/ledger.js";
 /**
  * Create quota routes.
  *
  * @param ledgerFactory - Factory returning the credit ledger
  */
-export declare function createQuotaRoutes(ledgerFactory: () => ICreditLedger): Hono;
+export declare function createQuotaRoutes(ledgerFactory: () => ILedger): Hono;

package/dist/api/routes/verify-email.d.ts

@@ -1,9 +1,9 @@
 import { Hono } from "hono";
 import type { Pool } from "pg";
-import type { ICreditLedger } from "../../credits/index.js";
+import type { ILedger } from "../../credits/index.js";
 export interface VerifyEmailRouteDeps {
     pool: Pool;
-    creditLedger: ICreditLedger;
+    creditLedger: ILedger;
 }
 export interface VerifyEmailRouteConfig {
     /** UI origin for redirect URLs (default: http://localhost:3001) */
@@ -16,4 +16,4 @@ export declare function createVerifyEmailRoutes(deps: VerifyEmailRouteDeps, conf
 /**
  * Create verify-email routes with factory functions (for lazy init).
  */
-export declare function createVerifyEmailRoutesLazy(poolFactory: () => Pool, creditLedgerFactory: () => ICreditLedger, config?: VerifyEmailRouteConfig): Hono;
+export declare function createVerifyEmailRoutesLazy(poolFactory: () => Pool, creditLedgerFactory: () => ILedger, config?: VerifyEmailRouteConfig): Hono;

package/dist/backup/on-demand-snapshot-service.d.ts

@@ -1,9 +1,9 @@
-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";
 export interface OnDemandSnapshotServiceConfig {
     manager: SnapshotManager;
-    ledger: CreditLedger;
+    ledger: ILedger;
 }
 export interface CreateSnapshotParams {
     tenant: string;

package/dist/billing/payram/webhook.d.ts

@@ -1,13 +1,13 @@
-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[]>;
 }
 /**
  * Process a PayRam webhook event.

package/dist/billing/payram/webhook.js

@@ -36,7 +36,11 @@ export async function handlePayRamWebhook(deps, payload) {
             // For OVER_FILLED, we still credit the requested amount — the
             // 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);
             // Reactivate suspended resources after credit purchase.
             let reactivatedBots;

package/dist/billing/payram/webhook.test.js

@@ -5,7 +5,7 @@
  * no-op status, idempotency, replay guard, and bot reactivation.
  */
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import { CreditLedger } from "../../credits/credit-ledger.js";
+import { DrizzleLedger } from "../../credits/ledger.js";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
 import { DrizzleWebhookSeenRepository } from "../drizzle-webhook-seen-repository.js";
 import { noOpReplayGuard } from "../webhook-seen-repository.js";
@@ -37,7 +37,8 @@ describe("handlePayRamWebhook", () => {
     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
         await chargeStore.create("ref-test-001", "tenant-a", 2500);
@@ -60,12 +61,12 @@ 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 () => {
             await handlePayRamWebhook(deps, makePayload({ status: "FILLED" }));

package/dist/billing/stripe/stripe-payment-processor.d.ts

@@ -1,6 +1,6 @@
 import type Stripe from "stripe";
 import type { IAutoTopupEventLogRepository } from "../../credits/auto-topup-event-log-repository.js";
-import type { ICreditLedger } from "../../credits/credit-ledger.js";
+import type { ILedger } from "../../credits/ledger.js";
 import { type ChargeOpts, type ChargeResult, type CheckoutOpts, type CheckoutSession, type Invoice, type IPaymentProcessor, type PortalOpts, type SavedPaymentMethod, type SetupResult, type WebhookResult } from "../payment-processor.js";
 import type { CreditPriceMap } from "./credit-prices.js";
 import type { ITenantCustomerRepository } from "./tenant-store.js";
@@ -18,7 +18,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>;

package/dist/billing/stripe/stripe-payment-processor.test.js

@@ -45,6 +45,7 @@ function createMocks() {
         buildCustomerIdMap: vi.fn(),
     };
     const creditLedger = {
+        post: vi.fn(),
         credit: vi.fn(),
         debit: vi.fn(),
         balance: vi.fn(),
@@ -55,6 +56,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 = {
         writeEvent: vi.fn(),

package/dist/billing/stripe/tenant-store.d.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 declare class DrizzleTenantCustomerRepository implements ITenantCustomerRepository {
     private readonly db;

package/dist/billing/stripe/tenant-store.js

@@ -7,7 +7,7 @@ import { tenantCustomers } from "../../db/schema/tenant-customers.js";
  * 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 {
     db;

package/dist/credits/auto-topup-charge.d.ts

@@ -1,14 +1,14 @@
 import Stripe from "stripe";
 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. */
 export declare const MAX_CONSECUTIVE_FAILURES = 3;
 export interface AutoTopupChargeDeps {
     stripe: Stripe;
     tenantRepo: ITenantCustomerRepository;
-    creditLedger: ICreditLedger;
+    creditLedger: ILedger;
     eventLogRepo: IAutoTopupEventLogRepository;
 }
 export interface AutoTopupChargeResult {

package/dist/credits/auto-topup-charge.js

@@ -113,7 +113,11 @@ export async function chargeAutoTopup(deps, tenantId, amount, source) {
     // 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) {

package/dist/credits/auto-topup-charge.test.js

@@ -6,7 +6,7 @@ import { createTestDb, truncateAllTables } from "../test/db.js";
 import { 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";
 function mockStripe(overrides) {
     const piId = overrides?.paymentIntentId ?? `pi_${crypto.randomUUID()}`;
     return {
@@ -47,7 +47,8 @@ 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 () => {
         const stripe = mockStripe();
@@ -63,8 +64,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 () => {
         const stripe = mockStripe();

package/dist/credits/auto-topup-usage.d.ts

@@ -1,10 +1,10 @@
 import type { AutoTopupChargeResult } 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/dist/credits/auto-topup-usage.test.js

@@ -3,7 +3,7 @@ import { createTestDb, truncateAllTables } from "../test/db.js";
 import { DrizzleAutoTopupSettingsRepository } from "./auto-topup-settings-repository.js";
 import { maybeTriggerUsageTopup } 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;
     let db;
@@ -17,7 +17,8 @@ describe("maybeTriggerUsageTopup", () => {
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
+        ledger = new DrizzleLedger(db);
+        await ledger.seedSystemAccounts();
         settingsRepo = new DrizzleAutoTopupSettingsRepository(db);
     });
     it("does nothing when tenant has no auto-topup settings", async () => {
@@ -28,7 +29,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -40,7 +45,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -52,7 +61,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -61,7 +74,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -74,7 +91,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         // Fire two concurrent calls — both see balance < threshold,
@@ -93,7 +114,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         // First call — triggers charge, flag set then cleared
@@ -111,7 +136,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"))
@@ -134,7 +163,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -146,7 +179,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -172,7 +209,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 = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");

package/dist/credits/credit-expiry-cron.d.ts

@@ -1,6 +1,6 @@
-import type { ICreditLedger } from "./credit-ledger.js";
+import type { ILedger } from "./ledger.js";
 export interface CreditExpiryCronConfig {
-    ledger: ICreditLedger;
+    ledger: ILedger;
     /** Current time as ISO-8601 string. */
     now: string;
 }

package/dist/credits/credit-expiry-cron.js

@@ -1,5 +1,5 @@
 import { logger } from "../config/logger.js";
-import { InsufficientBalanceError } from "./credit-ledger.js";
+import { InsufficientBalanceError } from "./ledger.js";
 /**
  * Sweep expired credit grants and debit the original grant amount
  * (or remaining balance if partially consumed).
@@ -23,7 +23,10 @@ export async function runCreditExpiryCron(cfg) {
             }
             // 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)) {
                 result.expired.push(grant.tenantId);
@@ -35,8 +38,8 @@ export async function runCreditExpiryCron(cfg) {
             }
             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/dist/credits/credit-expiry-cron.test.js

@@ -2,20 +2,21 @@ 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;
     let ledger;
     beforeAll(async () => {
         const { db, pool: p } = await createTestDb();
         pool = p;
-        ledger = new DrizzleCreditLedger(db);
+        ledger = new DrizzleLedger(db);
     });
     afterAll(async () => {
         await pool.close();
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
+        await ledger.seedSystemAccounts();
     });
     // All tests pass an explicit `now` parameter — hardcoded dates are time-independent
     // because runCreditExpiryCron never reads the system clock.
@@ -26,7 +27,11 @@ describe("runCreditExpiryCron", () => {
         expect(result.errors).toEqual([]);
     });
     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);
         expect(result.expired).toContain("tenant-1");
@@ -34,29 +39,41 @@ describe("runCreditExpiryCron", () => {
         expect(balance.toCents()).toBe(0);
     });
     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);
         const balance = await ledger.balance("tenant-1");
         expect(balance.toCents()).toBe(500);
     });
     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);
         const balance = await ledger.balance("tenant-1");
         expect(balance.toCents()).toBe(500);
     });
     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);
         const balance = await ledger.balance("tenant-1");
         expect(balance.toCents()).toBe(0);
     });
     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");
         const result2 = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });

package/dist/credits/credit-ledger.d.ts

@@ -56,7 +56,7 @@ export declare class InsufficientBalanceError extends Error {
     requestedAmount: Credit;
     constructor(currentBalance: Credit, requestedAmount: Credit);
 }
-export interface ICreditLedger {
+export interface ILedger {
     credit(tenantId: string, amount: Credit, type: CreditType, description?: string, referenceId?: string, fundingSource?: string, attributedUserId?: string, expiresAt?: string): Promise<CreditTransaction>;
     expiredCredits(now: string): Promise<Array<{
         id: string;
@@ -82,7 +82,7 @@ export interface ICreditLedger {
  * creditBalances row is always consistent with the sum of creditTransactions.
  * Zero raw SQL in application code.
  */
-export declare class DrizzleCreditLedger implements ICreditLedger {
+export declare class DrizzleCreditLedger implements ILedger {
     private readonly db;
     constructor(db: PlatformDb);
     /**

package/dist/credits/credit-ledger.js

@@ -289,5 +289,5 @@ export class DrizzleCreditLedger {
             .where(sql `${creditBalances.balance} > 0`);
     }
 }
-// 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 };

package/dist/credits/dividend-cron.d.ts

@@ -1,9 +1,7 @@
 import { Credit } from "./credit.js";
-import type { ICreditLedger } from "./credit-ledger.js";
-import type { ICreditTransactionRepository } from "./credit-transaction-repository.js";
+import type { ILedger } from "./ledger.js";
 export interface DividendCronConfig {
-    creditTransactionRepo: ICreditTransactionRepository;
-    ledger: ICreditLedger;
+    ledger: ILedger;
     /** Fraction of daily purchases matched as dividend pool. Default 1.0 (100%). */
     matchRate: number;
     /** The date to compute dividend for, as YYYY-MM-DD string. Typically yesterday. */
@@ -21,8 +19,8 @@ export interface DividendCronResult {
  * Compute and distribute the community dividend for a given day.
  *
  * 1. Check idempotency — skip if already run for this date.
- * 2. Sum all 'purchase' transactions for the target date.
- * 3. Find all tenants with a 'purchase' transaction in the last 7 days.
+ * 2. Sum all 'purchase' entries for the target date.
+ * 3. Find all tenants with a 'purchase' entry in the last 7 days.
  * 4. Compute pool = sum × matchRate, per-user share = floor(pool / activeCount).
  * 5. Credit each active tenant with their share.
  */