@wopr-network/platform-core 1.13.3 → 1.14.0

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

@@ -1,40 +1,25 @@
-import { Credit, CreditLedger } from "@wopr-network/platform-core/credits";
+import { CREDIT_TYPE_ACCOUNT, Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { creditBalances, creditTransactions } from "../../db/schema/credits.js";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
-import { DrizzleCreditTransactionRepository } from "./credit-transaction-repository.js";
 import { runDividendCron } from "./dividend-cron.js";
-async function insertPurchase(db, tenantId, amountCents, createdAt) {
-    const id = `test-${tenantId}-${Date.now()}-${Math.random()}`;
+async function insertPurchase(ledger, tenantId, amountCents, postedAt) {
     const amount = Credit.fromCents(amountCents);
-    await db.insert(creditTransactions).values({
-        id,
+    await ledger.post({
+        entryType: "purchase",
         tenantId,
-        amount,
-        balanceAfter: amount,
-        type: "purchase",
-        createdAt,
+        description: `Test purchase ${amountCents}¢`,
+        referenceId: `test-purchase:${tenantId}:${postedAt}:${Math.random()}`,
+        postedAt,
+        lines: [
+            { accountCode: CREDIT_TYPE_ACCOUNT.purchase, amount, side: "debit" },
+            { accountCode: `2000:${tenantId}`, amount, side: "credit" },
+        ],
     });
-    // Upsert credit_balances
-    const existing = await db
-        .select()
-        .from(creditBalances)
-        .where((await import("drizzle-orm")).eq(creditBalances.tenantId, tenantId));
-    if (existing.length > 0) {
-        await db
-            .update(creditBalances)
-            .set({ balance: existing[0].balance.add(amount) })
-            .where((await import("drizzle-orm")).eq(creditBalances.tenantId, tenantId));
-    }
-    else {
-        await db.insert(creditBalances).values({ tenantId, balance: amount });
-    }
 }
 describe("runDividendCron", () => {
     let pool;
     let db;
     let ledger;
-    let creditTransactionRepo;
     beforeAll(async () => {
         ({ db, pool } = await createTestDb());
     });
@@ -43,12 +28,11 @@ describe("runDividendCron", () => {
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
-        creditTransactionRepo = new DrizzleCreditTransactionRepository(db);
+        ledger = new DrizzleLedger(db);
+        await ledger.seedSystemAccounts();
     });
     function makeConfig(overrides) {
         return {
-            creditTransactionRepo,
             ledger,
             matchRate: 1.0,
             targetDate: "2026-02-20",
@@ -56,7 +40,7 @@ describe("runDividendCron", () => {
         };
     }
     it("distributes dividend to eligible tenants", async () => {
-        await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t1", 1000, "2026-02-20 12:00:00");
         const result = await runDividendCron(makeConfig());
         expect(result.distributed).toBe(1);
         expect(result.pool.toCents()).toBe(1000);
@@ -64,7 +48,7 @@ describe("runDividendCron", () => {
         expect(result.activeCount).toBe(1);
     });
     it("is idempotent — skips if already ran for the date", async () => {
-        await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t1", 1000, "2026-02-20 12:00:00");
         const result1 = await runDividendCron(makeConfig());
         expect(result1.distributed).toBe(1);
         expect(result1.skippedAlreadyRun).toBe(false);
@@ -75,20 +59,19 @@ describe("runDividendCron", () => {
         expect((await ledger.balance("t1")).equals(balanceAfterFirst)).toBe(true);
     });
     it("handles floor rounding — remainder is not distributed", async () => {
-        await insertPurchase(db, "t1", 50, "2026-02-20 12:00:00");
-        await insertPurchase(db, "t2", 30, "2026-02-20 12:00:00");
-        await insertPurchase(db, "t3", 20, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t1", 50, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t2", 30, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t3", 20, "2026-02-20 12:00:00");
         const result = await runDividendCron(makeConfig());
         expect(result.pool.toCents()).toBe(100);
         expect(result.activeCount).toBe(3);
         // Nanodollar precision: floor(1_000_000_000 raw / 3) = 333_333_333 raw each
-        // Remainder = 1 nanodollar (not 1 cent — far less wasted with higher scale)
         expect(result.perUser.toRaw()).toBe(333_333_333);
         expect(result.distributed).toBe(3);
     });
     it("skips distribution when pool is zero", async () => {
         // Tenant purchased within 7 days but NOT on target date -> pool = 0
-        await insertPurchase(db, "t1", 500, "2026-02-18 12:00:00");
+        await insertPurchase(ledger, "t1", 500, "2026-02-18 12:00:00");
         const result = await runDividendCron(makeConfig());
         expect(result.pool.toCents()).toBe(0);
         expect(result.activeCount).toBe(1);
@@ -96,11 +79,9 @@ describe("runDividendCron", () => {
         expect(result.distributed).toBe(0);
     });
     it("distributes sub-cent amounts at nanodollar precision", async () => {
-        // 1 cent purchase, 3 active users: pool = 10_000_000 raw
-        // floor(10_000_000 / 3) = 3_333_333 raw each — non-zero, gets distributed
-        await insertPurchase(db, "t1", 1, "2026-02-20 12:00:00");
-        await insertPurchase(db, "t2", 500, "2026-02-18 12:00:00");
-        await insertPurchase(db, "t3", 500, "2026-02-17 12:00:00");
+        await insertPurchase(ledger, "t1", 1, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t2", 500, "2026-02-18 12:00:00");
+        await insertPurchase(ledger, "t3", 500, "2026-02-17 12:00:00");
         const result = await runDividendCron(makeConfig({ matchRate: 1.0 }));
         expect(result.pool.toCents()).toBe(1);
         expect(result.activeCount).toBe(3);
@@ -108,18 +89,17 @@ describe("runDividendCron", () => {
         expect(result.distributed).toBe(3);
     });
     it("records transactions with correct type and referenceId", async () => {
-        await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t1", 1000, "2026-02-20 12:00:00");
         await runDividendCron(makeConfig());
         const history = await ledger.history("t1", { type: "community_dividend" });
         expect(history).toHaveLength(1);
-        expect(history[0].type).toBe("community_dividend");
+        expect(history[0].entryType).toBe("community_dividend");
         expect(history[0].referenceId).toBe("dividend:2026-02-20:t1");
-        expect(history[0].amount.toCents()).toBe(1000);
         expect(history[0].description).toContain("Community dividend");
     });
     it("collects errors without stopping distribution to other tenants", async () => {
-        await insertPurchase(db, "t1", 500, "2026-02-20 12:00:00");
-        await insertPurchase(db, "t2", 500, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t1", 500, "2026-02-20 12:00:00");
+        await insertPurchase(ledger, "t2", 500, "2026-02-20 12:00:00");
         const result = await runDividendCron(makeConfig());
         expect(result.distributed).toBe(2);
         expect(result.errors).toEqual([]);

package/dist/monetization/credits/dividend-repository.js

@@ -1,32 +1,26 @@
 import { Credit } from "@wopr-network/platform-core/credits";
 import { and, desc, eq, gte, lt, sql } from "drizzle-orm";
 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";
 export class DrizzleDividendRepository {
     db;
     constructor(db) {
         this.db = db;
     }
     async getStats(tenantId) {
-        // 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 `COALESCE(SUM(${creditTransactions.amount}), 0)` })
-            .from(creditTransactions)
-            .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()))`)))[0];
-        const poolCents = poolRow?.total ?? 0;
-        const pool = Credit.fromCents(poolCents);
+            .select({ total: sql `COALESCE(SUM(${journalLines.amount}), 0)` })
+            .from(journalLines)
+            .innerJoin(journalEntries, eq(journalEntries.id, journalLines.journalEntryId))
+            .where(and(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 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 `COUNT(DISTINCT ${creditTransactions.tenantId})` })
-            .from(creditTransactions)
-            .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'`)))[0];
+            .select({ count: sql `COUNT(DISTINCT ${journalEntries.tenantId})` })
+            .from(journalEntries)
+            .where(and(eq(journalEntries.entryType, "purchase"), sql `${journalEntries.postedAt}::timestamp >= timezone('UTC', now()) - INTERVAL '7 days'`)))[0];
         const activeUsers = activeRow?.count ?? 0;
         // 3. Per-user projection (avoid division by zero)
         const perUser = activeUsers > 0 ? Credit.fromRaw(Math.floor(pool.toRaw() / activeUsers)) : Credit.ZERO;
@@ -36,19 +30,16 @@ export class DrizzleDividendRepository {
         const nextDistributionAt = nextMidnight.toISOString();
         // 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];
         let userEligible = false;
         let userLastPurchaseAt = null;
         let userWindowExpiresAt = 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);
             userWindowExpiresAt = windowExpiry.toISOString();

package/dist/monetization/credits/dividend-repository.test.js

@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-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 { adminUsers } from "../../db/schema/admin-users.js";
 import { dividendDistributions } from "../../db/schema/dividend-distributions.js";
@@ -39,6 +39,7 @@ describe("DrizzleDividendRepository", () => {
     let repo;
     beforeEach(async () => {
         await truncateAllTables(pool);
+        await new DrizzleLedger(db).seedSystemAccounts();
         repo = new DrizzleDividendRepository(db);
     });
     // --- getHistory() ---
@@ -152,8 +153,8 @@ describe("DrizzleDividendRepository", () => {
             expect(stats.nextDistributionAt).toEqual(expect.any(String));
         });
         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);
             expect(stats.userLastPurchaseAt).toEqual(expect.any(String));

package/dist/monetization/credits/index.d.ts

@@ -1,5 +1,5 @@
-export type { AutoTopupSettings, CreditExpiryCronConfig, CreditExpiryCronResult, CreditTransaction, CreditType, DebitType, HistoryOptions, IAutoTopupSettingsRepository, ICreditLedger, TransactionType, } from "@wopr-network/platform-core/credits";
-export { ALLOWED_SCHEDULE_INTERVALS, ALLOWED_THRESHOLDS, ALLOWED_TOPUP_AMOUNTS, CreditLedger, computeNextScheduleAt, DrizzleAutoTopupSettingsRepository, DrizzleCreditLedger, grantSignupCredits, InsufficientBalanceError, runCreditExpiryCron, SIGNUP_GRANT, } from "@wopr-network/platform-core/credits";
+export type { AutoTopupSettings, CreditExpiryCronConfig, CreditExpiryCronResult, CreditType, DebitType, HistoryOptions, IAutoTopupSettingsRepository, ILedger, JournalEntry, TransactionType, } from "@wopr-network/platform-core/credits";
+export { ALLOWED_SCHEDULE_INTERVALS, ALLOWED_THRESHOLDS, ALLOWED_TOPUP_AMOUNTS, computeNextScheduleAt, DrizzleAutoTopupSettingsRepository, DrizzleLedger, grantSignupCredits, InsufficientBalanceError, Ledger, runCreditExpiryCron, SIGNUP_GRANT, } from "@wopr-network/platform-core/credits";
 export type { BillingState, IBotBilling } from "./bot-billing.js";
 export { BotBilling, DrizzleBotBilling, SUSPENSION_GRACE_DAYS } from "./bot-billing.js";
 export type { DividendDigestConfig, DividendDigestResult } from "./dividend-digest-cron.js";

package/dist/monetization/credits/index.js

@@ -1,4 +1,4 @@
-export { ALLOWED_SCHEDULE_INTERVALS, ALLOWED_THRESHOLDS, ALLOWED_TOPUP_AMOUNTS, CreditLedger, computeNextScheduleAt, DrizzleAutoTopupSettingsRepository, DrizzleCreditLedger, grantSignupCredits, InsufficientBalanceError, runCreditExpiryCron, SIGNUP_GRANT, } from "@wopr-network/platform-core/credits";
+export { ALLOWED_SCHEDULE_INTERVALS, ALLOWED_THRESHOLDS, ALLOWED_TOPUP_AMOUNTS, computeNextScheduleAt, DrizzleAutoTopupSettingsRepository, DrizzleLedger, grantSignupCredits, InsufficientBalanceError, Ledger, runCreditExpiryCron, SIGNUP_GRANT, } from "@wopr-network/platform-core/credits";
 export { BotBilling, DrizzleBotBilling, SUSPENSION_GRACE_DAYS } from "./bot-billing.js";
 export { runDividendDigestCron } from "./dividend-digest-cron.js";
 export { buildResourceTierCosts, DAILY_BOT_COST, runRuntimeDeductions } from "./runtime-cron.js";

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

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

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

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

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

@@ -23,7 +23,11 @@ export async function runMonthlyPhoneBilling(phoneRepo, ledger, meter) {
         try {
             const costCredit = Credit.fromDollars(PHONE_NUMBER_MONTHLY_COST);
             const chargeCredit = withMargin(costCredit, PHONE_NUMBER_MARGIN);
-            await ledger.debit(number.tenantId, chargeCredit, "addon", "Monthly phone number fee", `phone-billing:${number.sid}:${now.toISOString().slice(0, 7)}`, true);
+            await ledger.debit(number.tenantId, chargeCredit, "addon", {
+                description: "Monthly phone number fee",
+                referenceId: `phone-billing:${number.sid}:${now.toISOString().slice(0, 7)}`,
+                allowNegative: true,
+            });
             meter.emit({
                 tenant: number.tenantId,
                 cost: costCredit,

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

@@ -1,19 +1,16 @@
-import { Credit, InsufficientBalanceError, } from "@wopr-network/platform-core/credits";
+import { Credit, InsufficientBalanceError } from "@wopr-network/platform-core/credits";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { PHONE_NUMBER_MONTHLY_COST, runMonthlyPhoneBilling } from "./phone-billing.js";
 function makeTx(tenantId) {
     return {
         id: "tx-1",
+        postedAt: new Date().toISOString(),
+        entryType: "addon",
         tenantId,
-        amount: Credit.fromDollars(1),
-        balanceAfter: Credit.fromDollars(100),
-        type: "addon",
         description: "Monthly phone number fee",
         referenceId: null,
-        fundingSource: null,
-        attributedUserId: null,
-        createdAt: new Date().toISOString(),
-        expiresAt: null,
+        metadata: null,
+        lines: [],
     };
 }
 function makeNumber(overrides = {}) {
@@ -85,16 +82,16 @@ describe("runMonthlyPhoneBilling", () => {
         expect(result.failed).toEqual([]);
         // Verify debit was called with the margined charge amount
         expect(ledger.debit).toHaveBeenCalledOnce();
-        const [tenantId, chargeAmount, type, description, referenceId, allowNegative] = ledger.debit.mock.calls[0];
+        const [tenantId, chargeAmount, type, opts] = ledger.debit.mock.calls[0];
         expect(tenantId).toBe("tenant-1");
         // chargeCredit = Credit.fromDollars(1.15).multiply(2.6)
         const expectedCharge = Credit.fromDollars(1.15).multiply(2.6);
         expect(chargeAmount.toRaw()).toBe(expectedCharge.toRaw());
         expect(type).toBe("addon");
-        expect(description).toBe("Monthly phone number fee");
+        expect(opts.description).toBe("Monthly phone number fee");
         const expectedMonth = `${NOW.getFullYear()}-${String(NOW.getMonth() + 1).padStart(2, "0")}`;
-        expect(referenceId).toMatch(new RegExp(`^phone-billing:PN-abc123:${expectedMonth}$`));
-        expect(allowNegative).toBe(true);
+        expect(opts.referenceId).toMatch(new RegExp(`^phone-billing:PN-abc123:${expectedMonth}$`));
+        expect(opts.allowNegative).toBe(true);
         // Verify meter emission
         expect(meter.emit).toHaveBeenCalledOnce();
         const event = meter.emit.mock.calls[0][0];

package/dist/monetization/credits/runtime-cron.d.ts

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

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

@@ -69,17 +69,26 @@ export async function runRuntimeDeductions(cfg) {
             const totalCost = DAILY_BOT_COST.multiply(botCount);
             if (!balance.lessThan(totalCost)) {
                 // Full deduction
-                await cfg.ledger.debit(tenantId, totalCost, "bot_runtime", `Daily runtime: ${botCount} bot(s) x $${DAILY_BOT_COST.toDollars().toFixed(2)}`, runtimeRef);
+                await cfg.ledger.debit(tenantId, totalCost, "bot_runtime", {
+                    description: `Daily runtime: ${botCount} bot(s) x $${DAILY_BOT_COST.toDollars().toFixed(2)}`,
+                    referenceId: runtimeRef,
+                });
                 // Debit resource tier surcharges (if any)
                 if (cfg.getResourceTierCosts) {
                     const tierCost = await cfg.getResourceTierCosts(tenantId);
                     if (!tierCost.isZero()) {
                         const balanceAfterRuntime = await cfg.ledger.balance(tenantId);
                         if (!balanceAfterRuntime.lessThan(tierCost)) {
-                            await cfg.ledger.debit(tenantId, tierCost, "resource_upgrade", "Daily resource tier surcharge", `runtime-tier:${cfg.date}:${tenantId}`);
+                            await cfg.ledger.debit(tenantId, tierCost, "resource_upgrade", {
+                                description: "Daily resource tier surcharge",
+                                referenceId: `runtime-tier:${cfg.date}:${tenantId}`,
+                            });
                         }
                         else if (balanceAfterRuntime.greaterThan(Credit.ZERO)) {
-                            await cfg.ledger.debit(tenantId, balanceAfterRuntime, "resource_upgrade", "Partial resource tier surcharge (balance exhausted)", `runtime-tier:${cfg.date}:${tenantId}`);
+                            await cfg.ledger.debit(tenantId, balanceAfterRuntime, "resource_upgrade", {
+                                description: "Partial resource tier surcharge (balance exhausted)",
+                                referenceId: `runtime-tier:${cfg.date}:${tenantId}`,
+                            });
                         }
                     }
                 }
@@ -110,12 +119,18 @@ export async function runRuntimeDeductions(cfg) {
                     if (!storageCost.isZero()) {
                         const currentBalance = await cfg.ledger.balance(tenantId);
                         if (!currentBalance.lessThan(storageCost)) {
-                            await cfg.ledger.debit(tenantId, storageCost, "storage_upgrade", "Daily storage tier surcharge", `runtime-storage:${cfg.date}:${tenantId}`);
+                            await cfg.ledger.debit(tenantId, storageCost, "storage_upgrade", {
+                                description: "Daily storage tier surcharge",
+                                referenceId: `runtime-storage:${cfg.date}:${tenantId}`,
+                            });
                         }
                         else {
                             // Partial debit — take what's left, then suspend
                             if (currentBalance.greaterThan(Credit.ZERO)) {
-                                await cfg.ledger.debit(tenantId, currentBalance, "storage_upgrade", "Partial storage tier surcharge (balance exhausted)", `runtime-storage:${cfg.date}:${tenantId}`);
+                                await cfg.ledger.debit(tenantId, currentBalance, "storage_upgrade", {
+                                    description: "Partial storage tier surcharge (balance exhausted)",
+                                    referenceId: `runtime-storage:${cfg.date}:${tenantId}`,
+                                });
                             }
                             if (!result.suspended.includes(tenantId)) {
                                 result.suspended.push(tenantId);
@@ -131,12 +146,18 @@ export async function runRuntimeDeductions(cfg) {
                     if (!addonCost.isZero()) {
                         const currentBalance = await cfg.ledger.balance(tenantId);
                         if (!currentBalance.lessThan(addonCost)) {
-                            await cfg.ledger.debit(tenantId, addonCost, "addon", "Daily infrastructure add-on charges", `runtime-addon:${cfg.date}:${tenantId}`);
+                            await cfg.ledger.debit(tenantId, addonCost, "addon", {
+                                description: "Daily infrastructure add-on charges",
+                                referenceId: `runtime-addon:${cfg.date}:${tenantId}`,
+                            });
                         }
                         else {
                             // Partial debit — take what's left, then suspend
                             if (currentBalance.greaterThan(Credit.ZERO)) {
-                                await cfg.ledger.debit(tenantId, currentBalance, "addon", "Partial add-on charges (balance exhausted)", `runtime-addon:${cfg.date}:${tenantId}`);
+                                await cfg.ledger.debit(tenantId, currentBalance, "addon", {
+                                    description: "Partial add-on charges (balance exhausted)",
+                                    referenceId: `runtime-addon:${cfg.date}:${tenantId}`,
+                                });
                             }
                             if (!result.suspended.includes(tenantId)) {
                                 result.suspended.push(tenantId);
@@ -150,7 +171,10 @@ export async function runRuntimeDeductions(cfg) {
             else {
                 // Partial deduction — debit remaining balance, then suspend
                 if (balance.greaterThan(Credit.ZERO)) {
-                    await cfg.ledger.debit(tenantId, balance, "bot_runtime", `Partial daily runtime (balance exhausted): ${botCount} bot(s)`, runtimeRef);
+                    await cfg.ledger.debit(tenantId, balance, "bot_runtime", {
+                        description: `Partial daily runtime (balance exhausted): ${botCount} bot(s)`,
+                        referenceId: runtimeRef,
+                    });
                 }
                 if (cfg.onCreditsExhausted) {
                     await cfg.onCreditsExhausted(tenantId);