@wopr-network/platform-core 1.13.2 → 1.14.0

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

@@ -11,7 +11,7 @@ import {
   noOpReplayGuard,
   TenantCustomerRepository,
 } from "@wopr-network/platform-core/billing";
-import { Credit, CreditLedger } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import type Stripe from "stripe";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
@@ -28,7 +28,7 @@ function makeReplayGuard() {
 
 describe("handleWebhookEvent (credit model)", () => {
   let tenantRepo: TenantCustomerRepository;
-  let creditLedger: CreditLedger;
+  let creditLedger: DrizzleLedger;
   let deps: WebhookDeps;
 
   beforeAll(async () => {
@@ -44,7 +44,9 @@ describe("handleWebhookEvent (credit model)", () => {
   beforeEach(async () => {
     await truncateAllTables(pool);
     tenantRepo = new TenantCustomerRepository(db);
-    creditLedger = new CreditLedger(db);
+    creditLedger = new DrizzleLedger(db);
+
+    await creditLedger.seedSystemAccounts();
     deps = { tenantRepo, creditLedger, replayGuard: noOpReplayGuard };
   });
 
@@ -227,7 +229,7 @@ describe("handleWebhookEvent (credit model)", () => {
       const txns = await creditLedger.history("tenant-123");
       expect(txns).toHaveLength(1);
       expect(txns[0].description).toContain("cs_test_abc");
-      expect(txns[0].type).toBe("purchase");
+      expect(txns[0].entryType).toBe("purchase");
       expect(txns[0].referenceId).toBe("cs_test_abc");
     });
 
@@ -870,7 +872,7 @@ describe("handleWebhookEvent (credit model)", () => {
       const txns = await creditLedger.history("tenant-renew-ref");
       expect(txns).toHaveLength(1);
       expect(txns[0].referenceId).toBe("in_renewal_abc");
-      expect(txns[0].type).toBe("purchase");
+      expect(txns[0].entryType).toBe("purchase");
       expect(txns[0].description).toContain("in_renewal_abc");
     });
 
@@ -913,7 +915,7 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("debits the credit ledger for the refunded amount", async () => {
       await tenantRepo.upsert({ tenant: "tenant-ref-1", processorCustomerId: "cus_ref_abc" });
-      await creditLedger.credit("tenant-ref-1", Credit.fromCents(5000), "purchase", "seed");
+      await creditLedger.credit("tenant-ref-1", Credit.fromCents(5000), "purchase", { description: "seed" });
 
       const result = await handleWebhookEvent(deps, makeChargeRefundedEvent());
 
@@ -940,7 +942,7 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("is idempotent — skips duplicate refund for same charge ID", async () => {
       await tenantRepo.upsert({ tenant: "tenant-ref-idem", processorCustomerId: "cus_ref_idem" });
-      await creditLedger.credit("tenant-ref-idem", Credit.fromCents(5000), "purchase", "seed");
+      await creditLedger.credit("tenant-ref-idem", Credit.fromCents(5000), "purchase", { description: "seed" });
 
       const event = makeChargeRefundedEvent({ customer: "cus_ref_idem" });
 
@@ -973,7 +975,7 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("handles customer object instead of string", async () => {
       await tenantRepo.upsert({ tenant: "tenant-ref-obj", processorCustomerId: "cus_ref_obj" });
-      await creditLedger.credit("tenant-ref-obj", Credit.fromCents(3000), "purchase", "seed");
+      await creditLedger.credit("tenant-ref-obj", Credit.fromCents(3000), "purchase", { description: "seed" });
 
       const result = await handleWebhookEvent(
         deps,
@@ -986,14 +988,14 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("records event ID as referenceId in the ledger transaction", async () => {
       await tenantRepo.upsert({ tenant: "tenant-ref-txn", processorCustomerId: "cus_ref_txn" });
-      await creditLedger.credit("tenant-ref-txn", Credit.fromCents(5000), "purchase", "seed");
+      await creditLedger.credit("tenant-ref-txn", Credit.fromCents(5000), "purchase", { description: "seed" });
 
       await handleWebhookEvent(deps, makeChargeRefundedEvent({ customer: "cus_ref_txn", id: "ch_ref_txn_123" }));
 
       const txns = await creditLedger.history("tenant-ref-txn", { type: "refund" });
       expect(txns).toHaveLength(1);
       expect(txns[0].referenceId).toBe("evt_charge_ref_1");
-      expect(txns[0].type).toBe("refund");
+      expect(txns[0].entryType).toBe("refund");
       expect(txns[0].description).toContain("ch_ref_txn_123");
     });
   });
@@ -1076,7 +1078,11 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("skips credit when referenceId already exists (inline grant ran first)", async () => {
       // Simulate inline grant already happened
-      await creditLedger.credit("t1", Credit.fromCents(500), "purchase", "Auto-topup", "pi_already_granted", "stripe");
+      await creditLedger.credit("t1", Credit.fromCents(500), "purchase", {
+        description: "Auto-topup",
+        referenceId: "pi_already_granted",
+        fundingSource: "stripe",
+      });
 
       const event = {
         id: "evt_pi_success_2",
@@ -1172,7 +1178,7 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("freezes tenant credits and suspends bots on dispute", async () => {
       await tenantRepo.upsert({ tenant: "tenant-dispute-1", processorCustomerId: "cus_dispute_abc" });
-      await creditLedger.credit("tenant-dispute-1", Credit.fromCents(5000), "purchase", "seed");
+      await creditLedger.credit("tenant-dispute-1", Credit.fromCents(5000), "purchase", { description: "seed" });
 
       const botBilling = {
         suspendAllForTenant: vi.fn(async () => ["bot-d1"]),
@@ -1201,7 +1207,7 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("is idempotent — skips duplicate debit for same dispute ID", async () => {
       await tenantRepo.upsert({ tenant: "tenant-dispute-idem", processorCustomerId: "cus_dispute_idem" });
-      await creditLedger.credit("tenant-dispute-idem", Credit.fromCents(5000), "purchase", "seed");
+      await creditLedger.credit("tenant-dispute-idem", Credit.fromCents(5000), "purchase", { description: "seed" });
 
       const event = makeDisputeCreatedEvent("cus_dispute_idem");
 
@@ -1214,7 +1220,7 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("sends admin notification when notificationService is available", async () => {
       await tenantRepo.upsert({ tenant: "tenant-dispute-notify", processorCustomerId: "cus_dispute_notify" });
-      await creditLedger.credit("tenant-dispute-notify", Credit.fromCents(5000), "purchase", "seed");
+      await creditLedger.credit("tenant-dispute-notify", Credit.fromCents(5000), "purchase", { description: "seed" });
 
       const notifyFn = vi.fn();
       const notificationService = {
@@ -1267,7 +1273,7 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("handles customer object (expanded) inside charge", async () => {
       await tenantRepo.upsert({ tenant: "tenant-dispute-obj", processorCustomerId: "cus_dispute_obj" });
-      await creditLedger.credit("tenant-dispute-obj", Credit.fromCents(3000), "purchase", "seed");
+      await creditLedger.credit("tenant-dispute-obj", Credit.fromCents(3000), "purchase", { description: "seed" });
 
       const result = await handleWebhookEvent(deps, makeDisputeCreatedEvent({ id: "cus_dispute_obj" }));
 
@@ -1277,7 +1283,7 @@ describe("handleWebhookEvent (credit model)", () => {
 
     it("works without botBilling (no suspension, still handled)", async () => {
       await tenantRepo.upsert({ tenant: "tenant-dispute-no-bb", processorCustomerId: "cus_dispute_no_bb" });
-      await creditLedger.credit("tenant-dispute-no-bb", Credit.fromCents(5000), "purchase", "seed");
+      await creditLedger.credit("tenant-dispute-no-bb", Credit.fromCents(5000), "purchase", { description: "seed" });
 
       const result = await handleWebhookEvent(deps, makeDisputeCreatedEvent("cus_dispute_no_bb"));
 

package/src/monetization/stripe/webhook.ts

@@ -3,7 +3,7 @@ import type {
   IWebhookSeenRepository,
   TenantCustomerRepository,
 } from "@wopr-network/platform-core/billing";
-import type { CreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit } from "@wopr-network/platform-core/credits";
 import type { NotificationService } from "@wopr-network/platform-core/email";
 import type Stripe from "stripe";
@@ -43,7 +43,7 @@ export interface WebhookResult {
  */
 export interface WebhookDeps {
   tenantRepo: TenantCustomerRepository;
-  creditLedger: CreditLedger;
+  creditLedger: ILedger;
   /** Map of Stripe Price ID -> CreditPricePoint for bonus calculation. */
   priceMap?: CreditPriceMap;
   /** Bot billing manager for reactivation after credit purchase (WOP-447). */
@@ -62,6 +62,46 @@ export interface WebhookDeps {
   promotionEngine?: PromotionEngine;
 }
 
+/**
+ * Extract the card fingerprint from a Stripe webhook payload object.
+ * Works for PaymentIntent (via latest_charge or charges.data[0]) and
+ * Invoice (via charge) objects where the Charge is expanded.
+ * Returns undefined when the nested object is only a string ID (not expanded).
+ */
+function extractStripeFingerprint(obj: unknown): string | undefined {
+  if (!obj || typeof obj !== "object") return undefined;
+  const o = obj as Record<string, unknown>;
+
+  // PaymentIntent: pi.latest_charge expanded → Charge.payment_method_details.card.fingerprint
+  const latestCharge = o.latest_charge;
+  if (latestCharge && typeof latestCharge === "object") {
+    const pmd = (latestCharge as Record<string, unknown>).payment_method_details as Record<string, unknown> | undefined;
+    const fp = (pmd?.card as Record<string, unknown> | undefined)?.fingerprint;
+    if (typeof fp === "string") return fp;
+  }
+
+  // PaymentIntent (older API): pi.charges.data[0].payment_method_details.card.fingerprint
+  const charges = o.charges as { data?: Array<Record<string, unknown>> } | undefined;
+  const charge0 = charges?.data?.[0];
+  if (charge0) {
+    const pmd = charge0.payment_method_details as Record<string, unknown> | undefined;
+    const fp = (pmd?.card as Record<string, unknown> | undefined)?.fingerprint;
+    if (typeof fp === "string") return fp;
+  }
+
+  // Invoice: invoice.charge expanded → Charge.payment_method_details.card.fingerprint
+  const invoiceCharge = o.charge;
+  if (invoiceCharge && typeof invoiceCharge === "object") {
+    const pmd = (invoiceCharge as Record<string, unknown>).payment_method_details as
+      | Record<string, unknown>
+      | undefined;
+    const fp = (pmd?.card as Record<string, unknown> | undefined)?.fingerprint;
+    if (typeof fp === "string") return fp;
+  }
+
+  return undefined;
+}
+
 /**
  * Process a Stripe webhook event.
  *
@@ -133,14 +173,12 @@ export async function handleWebhookEvent(deps: WebhookDeps, event: Stripe.Event)
       }
 
       // Credit the ledger with session ID as reference for idempotency.
-      await deps.creditLedger.credit(
-        tenant,
-        Credit.fromCents(creditCents),
-        "purchase",
-        `Stripe credit purchase (session: ${stripeSessionId})`,
-        stripeSessionId,
-        "stripe",
-      );
+      await deps.creditLedger.credit(tenant, Credit.fromCents(creditCents), "purchase", {
+        description: `Stripe credit purchase (session: ${stripeSessionId})`,
+        referenceId: stripeSessionId,
+        fundingSource: "stripe",
+        stripeFingerprint: extractStripeFingerprint(session),
+      });
 
       // New-user first-purchase bonus for referred users (WOP-950).
       // Must run before credit match so markFirstPurchase hasn't been called yet.
@@ -292,14 +330,12 @@ export async function handleWebhookEvent(deps: WebhookDeps, event: Stripe.Event)
 
       // Fallback grant — inline path failed or process crashed before granting.
       const source = pi.metadata?.wopr_source ?? "auto_topup_webhook_fallback";
-      await deps.creditLedger.credit(
-        tenant,
-        Credit.fromCents(pi.amount),
-        "purchase",
-        `Auto-topup webhook fallback (${source})`,
-        pi.id,
-        "stripe",
-      );
+      await deps.creditLedger.credit(tenant, Credit.fromCents(pi.amount), "purchase", {
+        description: `Auto-topup webhook fallback (${source})`,
+        referenceId: pi.id,
+        fundingSource: "stripe",
+        stripeFingerprint: extractStripeFingerprint(pi),
+      });
 
       result = {
         handled: true,
@@ -379,14 +415,12 @@ export async function handleWebhookEvent(deps: WebhookDeps, event: Stripe.Event)
         break;
       }
 
-      await deps.creditLedger.credit(
-        tenant,
-        Credit.fromCents(amountPaid),
-        "purchase",
-        `Stripe subscription renewal (invoice: ${invoice.id})`,
-        invoice.id,
-        "stripe",
-      );
+      await deps.creditLedger.credit(tenant, Credit.fromCents(amountPaid), "purchase", {
+        description: `Stripe subscription renewal (invoice: ${invoice.id})`,
+        referenceId: invoice.id,
+        fundingSource: "stripe",
+        stripeFingerprint: extractStripeFingerprint(invoice),
+      });
 
       // Reactivate suspended bots now that balance is positive (WOP-447).
       let reactivatedBots: string[] | undefined;
@@ -437,14 +471,11 @@ export async function handleWebhookEvent(deps: WebhookDeps, event: Stripe.Event)
       }
 
       // Debit the ledger. Allow negative balance — refund must always succeed.
-      await deps.creditLedger.debit(
-        tenant,
-        Credit.fromCents(refundedCents),
-        "refund",
-        `Stripe refund (charge: ${charge.id})`,
-        event.id,
-        true, // allowNegative
-      );
+      await deps.creditLedger.debit(tenant, Credit.fromCents(refundedCents), "refund", {
+        description: `Stripe refund (charge: ${charge.id})`,
+        referenceId: event.id,
+        allowNegative: true,
+      });
 
       logger.warn("Charge refunded — credits debited", { tenant, customerId, chargeId: charge.id, refundedCents });
 
@@ -483,14 +514,11 @@ export async function handleWebhookEvent(deps: WebhookDeps, event: Stripe.Event)
 
       // Debit disputed amount (allow negative). Idempotent via disputeId.
       if (disputedCents > 0 && !(await deps.creditLedger.hasReferenceId(disputeId))) {
-        await deps.creditLedger.debit(
-          tenant,
-          Credit.fromCents(disputedCents),
-          "correction",
-          `Stripe dispute (dispute: ${disputeId}, reason: ${dispute.reason})`,
-          disputeId,
-          true, // allowNegative
-        );
+        await deps.creditLedger.debit(tenant, Credit.fromCents(disputedCents), "correction", {
+          description: `Stripe dispute (dispute: ${disputeId}, reason: ${dispute.reason})`,
+          referenceId: disputeId,
+          allowNegative: true,
+        });
       }
 
       // Suspend all bots (non-fatal if botBilling not provided).
@@ -554,14 +582,11 @@ export async function handleWebhookEvent(deps: WebhookDeps, event: Stripe.Event)
         // Re-credit the disputed amount. Idempotent via reversal referenceId.
         const reversalRef = `${disputeId}:reversal`;
         if (disputedCents > 0 && !(await deps.creditLedger.hasReferenceId(reversalRef))) {
-          await deps.creditLedger.credit(
-            tenant,
-            Credit.fromCents(disputedCents),
-            "correction",
-            `Stripe dispute won — credits restored (dispute: ${disputeId})`,
-            reversalRef,
-            "stripe",
-          );
+          await deps.creditLedger.credit(tenant, Credit.fromCents(disputedCents), "correction", {
+            description: `Stripe dispute won — credits restored (dispute: ${disputeId})`,
+            referenceId: reversalRef,
+            fundingSource: "stripe",
+          });
         }
 
         // Reactivate bots (non-fatal).

package/src/onboarding/onboarding-service.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-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 { BudgetTier } from "../inference/budget-guard.js";
 import { checkSessionBudget } from "../inference/budget-guard.js";
@@ -30,7 +30,7 @@ export class OnboardingService {
     private readonly daemon: IDaemonManager,
     private readonly usageRepo?: ISessionUsageRepository,
     private readonly scriptRepo: IOnboardingScriptRepository = OnboardingService.DEFAULT_SCRIPT_REPO,
-    private readonly creditLedger?: ICreditLedger,
+    private readonly creditLedger?: ILedger,
     private readonly resolveTenantId?: (userId: string) => Promise<string | null>,
   ) {}
 
@@ -137,15 +137,12 @@ export class OnboardingService {
         if (costCents > 0) {
           const tenantId = await this.resolveTenantId(session.userId);
           if (tenantId) {
-            await this.creditLedger.debit(
-              tenantId,
-              Credit.fromCents(costCents),
-              "onboarding_llm",
-              `Onboarding session ${sessionId}`,
-              `onboarding-${sessionId}-${Date.now()}`,
-              true, // allowNegative — don't block onboarding mid-conversation
-              session.userId,
-            );
+            await this.creditLedger.debit(tenantId, Credit.fromCents(costCents), "onboarding_llm", {
+              description: `Onboarding session ${sessionId}`,
+              referenceId: `onboarding-${sessionId}-${Date.now()}`,
+              allowNegative: true,
+              attributedUserId: session.userId,
+            });
           }
         }
       }

package/dist/credits/credit-ledger-extra.test.js

@@ -1,40 +0,0 @@
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
-import { Credit } from "./credit.js";
-import { CreditLedger, InsufficientBalanceError } from "./credit-ledger.js";
-let pool;
-let db;
-beforeAll(async () => {
-    ({ db, pool } = await createTestDb());
-    await beginTestTransaction(pool);
-});
-afterAll(async () => {
-    await endTestTransaction(pool);
-    await pool.close();
-});
-describe("CreditLedger concurrent debit safety", () => {
-    let ledger;
-    beforeEach(async () => {
-        await rollbackTestTransaction(pool);
-        ledger = new CreditLedger(db);
-    });
-    it("concurrent debits do not overdraw — at least one should fail with InsufficientBalanceError", async () => {
-        // Fund with exactly 100 cents
-        await ledger.credit("t1", Credit.fromCents(100), "purchase");
-        // Fire two 100-cent debits concurrently — only one can succeed
-        const results = await Promise.allSettled([
-            ledger.debit("t1", Credit.fromCents(100), "bot_runtime", "debit-1"),
-            ledger.debit("t1", Credit.fromCents(100), "bot_runtime", "debit-2"),
-        ]);
-        const fulfilled = results.filter((r) => r.status === "fulfilled");
-        const rejected = results.filter((r) => r.status === "rejected");
-        // Exactly one succeeds, one fails (PGlite serializes transactions so this is deterministic)
-        expect(fulfilled).toHaveLength(1);
-        expect(rejected).toHaveLength(1);
-        const err = rejected[0].reason;
-        expect(err).toBeInstanceOf(InsufficientBalanceError);
-        // Final balance must be exactly 0, not negative
-        const bal = await ledger.balance("t1");
-        expect(bal.toCents()).toBe(0);
-    });
-});

package/dist/credits/credit-ledger.bench.js

@@ -1,33 +0,0 @@
-import { afterAll, beforeAll, beforeEach, bench, describe } from "vitest";
-import { createTestDb, truncateAllTables } from "../test/db.js";
-import { Credit } from "./credit.js";
-import { CreditLedger } from "./credit-ledger.js";
-let db;
-let pool;
-beforeAll(async () => {
-    ({ db, pool } = await createTestDb());
-});
-afterAll(async () => {
-    await pool.close();
-});
-describe("CreditLedger throughput", () => {
-    let ledger;
-    beforeEach(async () => {
-        await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
-    });
-    let creditIdx = 0;
-    let debitIdx = 0;
-    bench("credit operation", async () => {
-        const tenant = `tenant-${creditIdx++ % 100}`;
-        await ledger.credit(tenant, Credit.fromCents(100), "purchase", "bench");
-    }, { iterations: 1_000 });
-    bench("debit operation", async () => {
-        const tenant = `tenant-${debitIdx++ % 100}`;
-        await ledger.debit(tenant, Credit.fromCents(1), "adapter_usage", "bench");
-    }, { iterations: 1_000 });
-    bench("balance query", async () => {
-        const tenant = `tenant-${debitIdx++ % 100}`;
-        await ledger.balance(tenant);
-    }, { iterations: 5_000 });
-});

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

@@ -1,4 +0,0 @@
-/**
- * Tests for CreditLedger — including the allowNegative debit parameter (WOP-821).
- */
-export {};

package/dist/credits/credit-ledger.test.js

@@ -1,203 +0,0 @@
-/**
- * Tests for CreditLedger — including the allowNegative debit parameter (WOP-821).
- */
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { createTestDb, truncateAllTables } from "../test/db.js";
-import { Credit } from "./credit.js";
-import { CreditLedger, InsufficientBalanceError } from "./credit-ledger.js";
-// TOP OF FILE - shared across ALL describes
-let pool;
-let db;
-beforeAll(async () => {
-    ({ db, pool } = await createTestDb());
-});
-afterAll(async () => {
-    await pool.close();
-});
-describe("CreditLedger core methods", () => {
-    let ledger;
-    beforeEach(async () => {
-        await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
-    });
-    // --- credit() ---
-    describe("credit()", () => {
-        it("happy path: credits a tenant and returns correct transaction fields", async () => {
-            const txn = await ledger.credit("t1", Credit.fromCents(100), "purchase", "Initial deposit", "ref-001", "stripe", "user-abc");
-            expect(txn.tenantId).toBe("t1");
-            expect(txn.amount.toCents()).toBe(100);
-            expect(txn.balanceAfter.toCents()).toBe(100);
-            expect(txn.type).toBe("purchase");
-            expect(txn.description).toBe("Initial deposit");
-            expect(txn.referenceId).toBe("ref-001");
-            expect(txn.fundingSource).toBe("stripe");
-            expect(txn.attributedUserId).toBe("user-abc");
-            expect(txn.id).toEqual(expect.any(String));
-            expect(txn.createdAt).toEqual(expect.any(String));
-        });
-        it("multiple credits accumulate balance correctly", async () => {
-            await ledger.credit("t1", Credit.fromCents(100), "purchase");
-            await ledger.credit("t1", Credit.fromCents(50), "promo");
-            const bal = await ledger.balance("t1");
-            expect(bal.toCents()).toBe(150);
-        });
-        it("rejects zero amount", async () => {
-            await expect(ledger.credit("t1", Credit.fromCents(0), "purchase")).rejects.toThrow("amount must be positive for credits");
-        });
-        it("rejects negative amount", async () => {
-            await expect(ledger.credit("t1", Credit.fromRaw(-1), "purchase")).rejects.toThrow("amount must be positive for credits");
-        });
-        it("optional fields default to null", async () => {
-            const txn = await ledger.credit("t1", Credit.fromCents(10), "signup_grant");
-            expect(txn.description).toBeNull();
-            expect(txn.referenceId).toBeNull();
-            expect(txn.fundingSource).toBeNull();
-            expect(txn.attributedUserId).toBeNull();
-        });
-    });
-    // --- balance() ---
-    describe("balance()", () => {
-        it("returns Credit.ZERO for a tenant with no transactions", async () => {
-            const bal = await ledger.balance("nonexistent");
-            expect(bal.toCents()).toBe(0);
-            expect(bal.isZero()).toBe(true);
-        });
-        it("reflects credits and debits accurately", async () => {
-            await ledger.credit("t1", Credit.fromCents(200), "purchase");
-            await ledger.debit("t1", Credit.fromCents(50), "bot_runtime");
-            const bal = await ledger.balance("t1");
-            expect(bal.toCents()).toBe(150);
-        });
-    });
-    // --- history() ---
-    describe("history()", () => {
-        it("returns transactions in reverse chronological order (newest first)", async () => {
-            await ledger.credit("t1", Credit.fromCents(100), "purchase", "first");
-            await ledger.credit("t1", Credit.fromCents(200), "promo", "second");
-            await ledger.debit("t1", Credit.fromCents(50), "bot_runtime", "third");
-            const hist = await ledger.history("t1");
-            expect(hist).toHaveLength(3);
-            // newest first
-            expect(hist[0].description).toBe("third");
-            expect(hist[1].description).toBe("second");
-            expect(hist[2].description).toBe("first");
-        });
-        it("all CreditTransaction fields are populated", async () => {
-            await ledger.credit("t1", Credit.fromCents(100), "purchase", "desc", "ref-1", "stripe", "user-1");
-            const hist = await ledger.history("t1");
-            expect(hist).toHaveLength(1);
-            const txn = hist[0];
-            expect(txn.id).toEqual(expect.any(String));
-            expect(txn.tenantId).toBe("t1");
-            expect(txn.amount.toCents()).toBe(100);
-            expect(txn.balanceAfter.toCents()).toBe(100);
-            expect(txn.type).toBe("purchase");
-            expect(txn.description).toBe("desc");
-            expect(txn.referenceId).toBe("ref-1");
-            expect(txn.fundingSource).toBe("stripe");
-            expect(txn.attributedUserId).toBe("user-1");
-            expect(txn.createdAt).toEqual(expect.any(String));
-        });
-        it("respects limit and offset for pagination", async () => {
-            // Insert 5 transactions
-            for (let i = 1; i <= 5; i++) {
-                await ledger.credit("t1", Credit.fromCents(10 * i), "purchase", `txn-${i}`);
-            }
-            const page1 = await ledger.history("t1", { limit: 2, offset: 0 });
-            expect(page1).toHaveLength(2);
-            expect(page1[0].description).toBe("txn-5"); // newest first
-            expect(page1[1].description).toBe("txn-4");
-            const page2 = await ledger.history("t1", { limit: 2, offset: 2 });
-            expect(page2).toHaveLength(2);
-            expect(page2[0].description).toBe("txn-3");
-            expect(page2[1].description).toBe("txn-2");
-        });
-        it("filters by type when provided", async () => {
-            await ledger.credit("t1", Credit.fromCents(100), "purchase", "buy");
-            await ledger.credit("t1", Credit.fromCents(50), "promo", "free");
-            await ledger.debit("t1", Credit.fromCents(10), "bot_runtime", "usage");
-            const purchases = await ledger.history("t1", { type: "purchase" });
-            expect(purchases).toHaveLength(1);
-            expect(purchases[0].description).toBe("buy");
-        });
-        it("returns empty array for tenant with no transactions", async () => {
-            const hist = await ledger.history("nonexistent");
-            expect(hist).toEqual([]);
-        });
-    });
-    // --- hasReferenceId() ---
-    describe("hasReferenceId()", () => {
-        it("returns false for a reference ID that does not exist", async () => {
-            expect(await ledger.hasReferenceId("nonexistent-ref")).toBe(false);
-        });
-        it("returns true for a reference ID used in a credit", async () => {
-            await ledger.credit("t1", Credit.fromCents(100), "purchase", "desc", "ref-unique");
-            expect(await ledger.hasReferenceId("ref-unique")).toBe(true);
-        });
-        it("returns true for a reference ID used in a debit", async () => {
-            await ledger.credit("t1", Credit.fromCents(100), "purchase");
-            await ledger.debit("t1", Credit.fromCents(10), "bot_runtime", "desc", "debit-ref");
-            expect(await ledger.hasReferenceId("debit-ref")).toBe(true);
-        });
-        it("detects reference IDs across different tenants", async () => {
-            await ledger.credit("t1", Credit.fromCents(100), "purchase", "desc", "cross-tenant-ref");
-            // hasReferenceId is global, not tenant-scoped
-            expect(await ledger.hasReferenceId("cross-tenant-ref")).toBe(true);
-        });
-    });
-    // --- tenantsWithBalance() ---
-    describe("tenantsWithBalance()", () => {
-        it("returns empty array when no tenants exist", async () => {
-            const result = await ledger.tenantsWithBalance();
-            expect(result).toEqual([]);
-        });
-        it("returns only tenants with positive balance", async () => {
-            // t1: positive balance (100 cents)
-            await ledger.credit("t1", Credit.fromCents(100), "purchase");
-            // t2: zero balance (credit then debit same amount)
-            await ledger.credit("t2", Credit.fromCents(50), "purchase");
-            await ledger.debit("t2", Credit.fromCents(50), "bot_runtime");
-            // t3: negative balance (via allowNegative)
-            await ledger.credit("t3", Credit.fromCents(10), "purchase");
-            await ledger.debit("t3", Credit.fromCents(20), "bot_runtime", undefined, undefined, true);
-            // t4: positive balance (200 cents)
-            await ledger.credit("t4", Credit.fromCents(200), "signup_grant");
-            const result = await ledger.tenantsWithBalance();
-            const tenantIds = result.map((r) => r.tenantId).sort();
-            expect(tenantIds).toEqual(["t1", "t4"]);
-            const t1 = result.find((r) => r.tenantId === "t1");
-            expect(t1?.balance.toCents()).toBe(100);
-            const t4 = result.find((r) => r.tenantId === "t4");
-            expect(t4?.balance.toCents()).toBe(200);
-        });
-        it("excludes tenants with exactly zero balance", async () => {
-            await ledger.credit("t1", Credit.fromCents(100), "purchase");
-            await ledger.debit("t1", Credit.fromCents(100), "bot_runtime");
-            const result = await ledger.tenantsWithBalance();
-            expect(result).toEqual([]);
-        });
-    });
-});
-describe("CreditLedger.debit with allowNegative", () => {
-    let ledger;
-    beforeEach(async () => {
-        await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
-    });
-    it("debit with allowNegative=false (default) throws InsufficientBalanceError when balance insufficient", async () => {
-        await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup");
-        await expect(ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "test")).rejects.toThrow(InsufficientBalanceError);
-    });
-    it("debit with allowNegative=true allows negative balance", async () => {
-        await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup");
-        const txn = await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "test", undefined, true);
-        expect(txn).not.toBeNull();
-        expect((await ledger.balance("t1")).toCents()).toBe(-5);
-    });
-    it("debit with allowNegative=true records correct transaction with negative amount and negative balanceAfter", async () => {
-        await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup");
-        const txn = await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "test", undefined, true);
-        expect(txn.amount.toCents()).toBe(-10);
-        expect(txn.balanceAfter.toCents()).toBe(-5);
-    });
-});