@wopr-network/platform-core 1.13.3 → 1.14.1

package/dist/credits/dividend-cron.js

@@ -4,8 +4,8 @@ import { Credit } from "./credit.js";
  * 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.
  */
@@ -18,28 +18,21 @@ export async function runDividendCron(cfg) {
         skippedAlreadyRun: false,
         errors: [],
     };
-    // Idempotency: check if any per-tenant dividend was already distributed for this date.
-    // We look for any referenceId matching "dividend:YYYY-MM-DD:*".
     const sentinelPrefix = `dividend:${cfg.targetDate}:`;
-    const alreadyRan = await cfg.creditTransactionRepo.existsByReferenceIdLike(`${sentinelPrefix}%`);
+    const alreadyRan = await cfg.ledger.existsByReferenceIdLike(`${sentinelPrefix}%`);
     if (alreadyRan) {
         result.skippedAlreadyRun = true;
         logger.info("Dividend cron already ran for this date", { targetDate: cfg.targetDate });
         return result;
     }
-    // Step 1: Sum all purchase amounts for the target date.
     const dayStart = `${cfg.targetDate} 00:00:00`;
     const dayEnd = `${cfg.targetDate} 24:00:00`;
-    const dailyPurchaseTotalCredit = await cfg.creditTransactionRepo.sumPurchasesForPeriod(dayStart, dayEnd);
-    result.pool = dailyPurchaseTotalCredit.multiply(cfg.matchRate);
-    // Step 2: Find all active tenants (purchased in last 7 days from target date).
-    // The 7-day window is: [targetDate - 6 days 00:00:00, targetDate 24:00:00)
-    // This gives a full 7-day range ending at the end of targetDate.
+    const dailyPurchaseTotal = await cfg.ledger.sumPurchasesForPeriod(dayStart, dayEnd);
+    result.pool = dailyPurchaseTotal.multiply(cfg.matchRate);
     const windowStart = subtractDays(cfg.targetDate, 6);
     const windowStartTs = `${windowStart} 00:00:00`;
-    const activeTenantIds = await cfg.creditTransactionRepo.getActiveTenantIdsInWindow(windowStartTs, dayEnd);
+    const activeTenantIds = await cfg.ledger.getActiveTenantIdsInWindow(windowStartTs, dayEnd);
     result.activeCount = activeTenantIds.length;
-    // Step 3: Compute per-user share.
     if (result.pool.isZero() || result.activeCount <= 0) {
         logger.info("Dividend cron: no pool or no active tenants", {
             targetDate: cfg.targetDate,
@@ -57,11 +50,13 @@ export async function runDividendCron(cfg) {
         });
         return result;
     }
-    // Step 4: Distribute to each active tenant.
     for (const tenantId of activeTenantIds) {
         const perUserRef = `dividend:${cfg.targetDate}:${tenantId}`;
         try {
-            await cfg.ledger.credit(tenantId, result.perUser, "community_dividend", `Community dividend for ${cfg.targetDate}: pool ${result.pool.toCents()}c / ${result.activeCount} users`, perUserRef);
+            await cfg.ledger.credit(tenantId, result.perUser, "community_dividend", {
+                description: `Community dividend for ${cfg.targetDate}: pool ${result.pool.toCents()}c / ${result.activeCount} users`,
+                referenceId: perUserRef,
+            });
             result.distributed++;
         }
         catch (err) {
@@ -80,7 +75,6 @@ export async function runDividendCron(cfg) {
     });
     return result;
 }
-/** Subtract N days from a YYYY-MM-DD date string, returning YYYY-MM-DD. */
 function subtractDays(dateStr, days) {
     const d = new Date(`${dateStr}T00:00:00Z`);
     d.setUTCDate(d.getUTCDate() - days);

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

@@ -1,41 +1,31 @@
 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 { Credit } from "./credit.js";
-import { CreditLedger } from "./credit-ledger.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()}`;
+import { CREDIT_TYPE_ACCOUNT, DrizzleLedger } from "./ledger.js";
+/**
+ * Insert a backdated purchase entry into the double-entry ledger.
+ * Uses post() with postedAt override to simulate historical purchases.
+ */
+async function insertPurchase(ledger, tenantId, amountCents, postedAt) {
     const amount = Credit.fromCents(amountCents);
-    await db.insert(creditTransactions).values({
-        id,
+    // Purchase: DR cash (1000), CR unearned_revenue (2000:<tenantId>)
+    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());
     });
@@ -44,12 +34,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",
@@ -57,7 +46,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);
@@ -65,7 +54,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);
@@ -76,20 +65,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);
@@ -99,9 +87,9 @@ describe("runDividendCron", () => {
     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);
@@ -109,18 +97,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/credits/dividend-repository.js

@@ -1,7 +1,7 @@
 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";
 import { Credit } from "./credit.js";
 export class DrizzleDividendRepository {
     db;
@@ -9,24 +9,24 @@ export class DrizzleDividendRepository {
         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
+        // In double-entry: purchase entries have a credit line on the tenant liability account.
+        // Sum those credit line amounts for entries posted yesterday.
         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"), 
+            .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"), 
         // 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);
+        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"), 
+            .select({ count: sql `COUNT(DISTINCT ${journalEntries.tenantId})` })
+            .from(journalEntries)
+            .where(and(eq(journalEntries.entryType, "purchase"), 
         // raw SQL: Drizzle cannot express timestamp comparison with interval arithmetic
-        sql `${creditTransactions.createdAt}::timestamp >= timezone('UTC', now()) - INTERVAL '7 days'`)))[0];
+        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 +36,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/credits/dividend-repository.test.js

@@ -4,8 +4,8 @@ import { adminUsers } from "../db/schema/admin-users.js";
 import { dividendDistributions } from "../db/schema/dividend-distributions.js";
 import { createTestDb, truncateAllTables } from "../test/db.js";
 import { Credit } from "./credit.js";
-import { CreditLedger } from "./credit-ledger.js";
 import { DrizzleDividendRepository } from "./dividend-repository.js";
+import { DrizzleLedger } from "./ledger.js";
 let pool;
 let db;
 beforeAll(async () => {
@@ -40,6 +40,7 @@ describe("DrizzleDividendRepository", () => {
     let repo;
     beforeEach(async () => {
         await truncateAllTables(pool);
+        await new DrizzleLedger(db).seedSystemAccounts();
         repo = new DrizzleDividendRepository(db);
     });
     // --- getHistory() ---
@@ -153,8 +154,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/credits/index.d.ts

@@ -3,7 +3,9 @@ export { ALLOWED_SCHEDULE_INTERVALS, ALLOWED_THRESHOLDS, ALLOWED_TOPUP_AMOUNTS,
 export { Credit } from "./credit.js";
 export type { CreditExpiryCronConfig, CreditExpiryCronResult } from "./credit-expiry-cron.js";
 export { runCreditExpiryCron } from "./credit-expiry-cron.js";
-export type { CreditTransaction, CreditType, DebitType, HistoryOptions, ICreditLedger, TransactionType, } from "./credit-ledger.js";
-export { CreditLedger, DrizzleCreditLedger, InsufficientBalanceError } from "./credit-ledger.js";
+export type { AccountType, CreditOpts, CreditType, DebitOpts, DebitType, HistoryOptions, ILedger, JournalEntry, JournalLine, MemberUsageSummary, PostEntryInput, Side, SystemAccount, TransactionType, TrialBalance, } from "./ledger.js";
+export { CREDIT_TYPE_ACCOUNT, DEBIT_TYPE_ACCOUNT, DrizzleLedger, InsufficientBalanceError, Ledger, SYSTEM_ACCOUNTS, } from "./ledger.js";
 export { grantSignupCredits, SIGNUP_GRANT } from "./signup-grant.js";
 export type { ITenantCustomerRepository, TenantCustomerRow } from "./tenant-customer-repository.js";
+export type { TrialBalanceCronConfig, TrialBalanceCronResult } from "./trial-balance-cron.js";
+export { runTrialBalanceCron } from "./trial-balance-cron.js";

package/dist/credits/index.js

@@ -1,5 +1,6 @@
 export { ALLOWED_SCHEDULE_INTERVALS, ALLOWED_THRESHOLDS, ALLOWED_TOPUP_AMOUNTS, computeNextScheduleAt, DrizzleAutoTopupSettingsRepository, } from "./auto-topup-settings-repository.js";
 export { Credit } from "./credit.js";
 export { runCreditExpiryCron } from "./credit-expiry-cron.js";
-export { CreditLedger, DrizzleCreditLedger, InsufficientBalanceError } from "./credit-ledger.js";
+export { CREDIT_TYPE_ACCOUNT, DEBIT_TYPE_ACCOUNT, DrizzleLedger, InsufficientBalanceError, Ledger, SYSTEM_ACCOUNTS, } from "./ledger.js";
 export { grantSignupCredits, SIGNUP_GRANT } from "./signup-grant.js";
+export { runTrialBalanceCron } from "./trial-balance-cron.js";

package/dist/credits/ledger.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Double-entry credit ledger.
+ *
+ * Every mutation posts a balanced journal entry: sum(debits) === sum(credits).
+ * A tenant's "credit balance" is the balance of their unearned_revenue liability account.
+ *
+ * Account model:
+ *   ASSETS      — cash, stripe_receivable
+ *   LIABILITIES — unearned_revenue:<tenant_id> (the "credit balance")
+ *   REVENUE     — revenue:bot_runtime, revenue:adapter_usage, etc.
+ *   EXPENSES    — expense:signup_grant, expense:admin_grant, expense:promo, etc.
+ *   EQUITY      — retained_earnings
+ */
+import type { PlatformDb } from "../db/index.js";
+import { Credit } from "./credit.js";
+export type CreditType = "signup_grant" | "admin_grant" | "purchase" | "bounty" | "referral" | "promo" | "community_dividend" | "affiliate_bonus" | "affiliate_match" | "correction";
+export type DebitType = "bot_runtime" | "adapter_usage" | "addon" | "refund" | "correction" | "resource_upgrade" | "storage_upgrade" | "onboarding_llm" | "credit_expiry";
+export type TransactionType = CreditType | DebitType;
+export type AccountType = "asset" | "liability" | "equity" | "revenue" | "expense";
+export type Side = "debit" | "credit";
+export interface JournalLine {
+    accountCode: string;
+    amount: Credit;
+    side: Side;
+}
+export interface PostEntryInput {
+    entryType: string;
+    tenantId: string;
+    description?: string;
+    referenceId?: string;
+    metadata?: Record<string, unknown>;
+    createdBy?: string;
+    /** Override the posted_at timestamp (useful in tests to backdate entries). */
+    postedAt?: string;
+    lines: JournalLine[];
+    /**
+     * When set, verifies inside the transaction (after acquiring row locks) that
+     * the tenant's balance >= amount. Throws InsufficientBalanceError otherwise.
+     * Use this instead of a pre-check outside the transaction (TOCTOU-safe).
+     */
+    balanceCheck?: {
+        tenantId: string;
+        amount: Credit;
+    };
+}
+export interface JournalEntry {
+    id: string;
+    postedAt: string;
+    entryType: string;
+    tenantId: string;
+    description: string | null;
+    referenceId: string | null;
+    metadata: Record<string, unknown> | null;
+    lines: Array<{
+        accountCode: string;
+        amount: Credit;
+        side: Side;
+    }>;
+}
+/** Thrown when a debit would exceed a tenant's credit balance. */
+export declare class InsufficientBalanceError extends Error {
+    currentBalance: Credit;
+    requestedAmount: Credit;
+    constructor(currentBalance: Credit, requestedAmount: Credit);
+}
+export interface HistoryOptions {
+    limit?: number;
+    offset?: number;
+    type?: string;
+}
+export interface MemberUsageSummary {
+    userId: string;
+    totalDebit: Credit;
+    transactionCount: number;
+}
+export interface TrialBalance {
+    totalDebits: Credit;
+    totalCredits: Credit;
+    balanced: boolean;
+    difference: Credit;
+}
+export interface CreditOpts {
+    description?: string;
+    referenceId?: string;
+    fundingSource?: string;
+    stripeFingerprint?: string;
+    attributedUserId?: string;
+    expiresAt?: string;
+    createdBy?: string;
+}
+export interface DebitOpts {
+    description?: string;
+    referenceId?: string;
+    allowNegative?: boolean;
+    attributedUserId?: string;
+    createdBy?: string;
+}
+/** Maps credit (money-in) types to the debit-side account code. */
+export declare const CREDIT_TYPE_ACCOUNT: Record<CreditType, string>;
+/** Maps debit (money-out) types to the credit-side account code. */
+export declare const DEBIT_TYPE_ACCOUNT: Record<DebitType, string>;
+export interface SystemAccount {
+    code: string;
+    name: string;
+    type: AccountType;
+    normalSide: Side;
+}
+export declare const SYSTEM_ACCOUNTS: SystemAccount[];
+export interface ILedger {
+    /** Post a balanced journal entry. The primitive. Everything else calls this. */
+    post(input: PostEntryInput): Promise<JournalEntry>;
+    /** Add credits to a tenant (posts balanced entry: DR source, CR unearned_revenue). */
+    credit(tenantId: string, amount: Credit, type: CreditType, opts?: CreditOpts): Promise<JournalEntry>;
+    /** Deduct credits from a tenant (posts balanced entry: DR unearned_revenue, CR revenue). */
+    debit(tenantId: string, amount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry>;
+    /** Tenant's credit balance (= their unearned_revenue liability account balance). */
+    balance(tenantId: string): Promise<Credit>;
+    /** Check if a reference ID has already been posted (idempotency). */
+    hasReferenceId(referenceId: string): Promise<boolean>;
+    /** Journal entries for a tenant, newest first. */
+    history(tenantId: string, opts?: HistoryOptions): Promise<JournalEntry[]>;
+    /** All tenants with positive credit balance. */
+    tenantsWithBalance(): Promise<Array<{
+        tenantId: string;
+        balance: Credit;
+    }>>;
+    /** Per-member debit totals for a tenant. */
+    memberUsage(tenantId: string): Promise<MemberUsageSummary[]>;
+    /** Sum of all debits for a tenant (absolute value). */
+    lifetimeSpend(tenantId: string): Promise<Credit>;
+    /** Batch lifetimeSpend for multiple tenants. */
+    lifetimeSpendBatch(tenantIds: string[]): Promise<Map<string, Credit>>;
+    /** Expired credit grants not yet clawed back. */
+    expiredCredits(now: string): Promise<Array<{
+        entryId: string;
+        tenantId: string;
+        amount: Credit;
+    }>>;
+    /** Verify the books balance: total debits === total credits across all lines. */
+    trialBalance(): Promise<TrialBalance>;
+    /** Balance of any account by code. */
+    accountBalance(accountCode: string): Promise<Credit>;
+    /** Ensure system accounts exist (idempotent, called at startup). */
+    seedSystemAccounts(): Promise<void>;
+    /** Check if any journal entry has a referenceId matching a LIKE pattern (for dividend idempotency). */
+    existsByReferenceIdLike(pattern: string): Promise<boolean>;
+    /** Sum all purchase-type entry amounts credited to tenant accounts in [startTs, endTs). */
+    sumPurchasesForPeriod(startTs: string, endTs: string): Promise<Credit>;
+    /** Get distinct tenantIds with a purchase entry in [startTs, endTs). */
+    getActiveTenantIdsInWindow(startTs: string, endTs: string): Promise<string[]>;
+}
+export declare class DrizzleLedger implements ILedger {
+    private readonly db;
+    constructor(db: PlatformDb);
+    seedSystemAccounts(): Promise<void>;
+    /**
+     * Get or create the per-tenant unearned_revenue liability account, then lock
+     * it for the duration of the surrounding transaction.
+     * Code format: `2000:<tenantId>`
+     *
+     * Uses INSERT ON CONFLICT DO NOTHING so concurrent first-time calls for the
+     * same tenant are idempotent (no unique-constraint crash on the second writer).
+     */
+    private ensureTenantAccountLocked;
+    /**
+     * Resolve account code → account id.
+     * Acquires FOR UPDATE locks on both the accounts row and the account_balances
+     * row so concurrent transactions are fully serialized on balance reads/writes.
+     */
+    private resolveAccountLocked;
+    post(input: PostEntryInput): Promise<JournalEntry>;
+    credit(tenantId: string, amount: Credit, type: CreditType, opts?: CreditOpts): Promise<JournalEntry>;
+    debit(tenantId: string, amount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry>;
+    balance(tenantId: string): Promise<Credit>;
+    accountBalance(accountCode: string): Promise<Credit>;
+    hasReferenceId(referenceId: string): Promise<boolean>;
+    history(tenantId: string, opts?: HistoryOptions): Promise<JournalEntry[]>;
+    tenantsWithBalance(): Promise<Array<{
+        tenantId: string;
+        balance: Credit;
+    }>>;
+    memberUsage(tenantId: string): Promise<MemberUsageSummary[]>;
+    lifetimeSpend(tenantId: string): Promise<Credit>;
+    lifetimeSpendBatch(tenantIds: string[]): Promise<Map<string, Credit>>;
+    expiredCredits(now: string): Promise<Array<{
+        entryId: string;
+        tenantId: string;
+        amount: Credit;
+    }>>;
+    existsByReferenceIdLike(pattern: string): Promise<boolean>;
+    sumPurchasesForPeriod(startTs: string, endTs: string): Promise<Credit>;
+    getActiveTenantIdsInWindow(startTs: string, endTs: string): Promise<string[]>;
+    trialBalance(): Promise<TrialBalance>;
+}
+export { DrizzleLedger as Ledger };