@wopr-network/platform-core 1.13.2 → 1.14.0

package/dist/monetization/promotions/engine.js

@@ -82,7 +82,10 @@ export class PromotionEngine {
         if (!granted)
             return null;
         // Grant credits
-        const tx = await ledger.credit(ctx.tenantId, grantAmount, "promo", `Promotion: ${promo.name}`, refId);
+        const tx = await ledger.credit(ctx.tenantId, grantAmount, "promo", {
+            description: `Promotion: ${promo.name}`,
+            referenceId: refId,
+        });
         // Record redemption
         await redemptionRepo.create({
             promotionId: promo.id,

package/dist/monetization/promotions/engine.test.js

@@ -96,7 +96,9 @@ describe("PromotionEngine", () => {
         });
         expect(results).toHaveLength(1);
         expect(ledger.credit).toHaveBeenCalledWith("tenant-1", expect.any(Object), // Credit instance
-        "promo", expect.any(String), "promo:promo-1:tenant-1:1");
+        "promo", expect.objectContaining({
+            referenceId: "promo:promo-1:tenant-1:1",
+        }));
     });
     it("skips if already redeemed (idempotency)", async () => {
         vi.mocked(ledger.hasReferenceId).mockResolvedValue(true);

package/dist/monetization/repository-types.d.ts

@@ -1,5 +1,5 @@
 export type { IPayRamChargeRepository, ITenantCustomerRepository, PayRamChargeRecord, } from "@wopr-network/platform-core/billing";
-export type { IAutoTopupSettingsRepository, ICreditLedger } from "@wopr-network/platform-core/credits";
+export type { IAutoTopupSettingsRepository, ILedger } from "@wopr-network/platform-core/credits";
 export type { IMeterAggregator, IMeterEmitter } from "@wopr-network/platform-core/metering";
 export type { FraudEvent, FraudEventInput, IAffiliateFraudRepository } from "./affiliate/affiliate-fraud-repository.js";
 export type { AffiliateCode, AffiliateReferral, AffiliateStats, IAffiliateRepository, } from "./affiliate/drizzle-affiliate-repository.js";

package/dist/monetization/socket/socket.d.ts

@@ -12,12 +12,12 @@
 import type { MeterEmitter } from "@wopr-network/platform-core/metering";
 import type { AdapterCapability, ProviderAdapter } from "../adapters/types.js";
 import type { ArbitrageRouter } from "../arbitrage/router.js";
-import type { BudgetChecker, SpendLimits } from "../budget/budget-checker.js";
+import type { IBudgetChecker, SpendLimits } from "../budget/budget-checker.js";
 export interface SocketConfig {
     /** MeterEmitter instance for usage tracking */
     meter: MeterEmitter;
-    /** BudgetChecker instance for pre-call budget validation */
-    budgetChecker?: BudgetChecker;
+    /** IBudgetChecker instance for pre-call budget validation */
+    budgetChecker?: IBudgetChecker;
     /** Default margin multiplier (default: 1.3) */
     defaultMargin?: number;
     /** ArbitrageRouter for cost-optimized routing (GPU-first, cheapest, 5xx failover) */

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

@@ -1,6 +1,6 @@
 import type { IWebhookSeenRepository } from "@wopr-network/platform-core/billing";
 import { type ChargeOpts, type ChargeResult, type CheckoutOpts, type CheckoutSession, type CreditPriceMap, type Invoice, type IPaymentProcessor, type ITenantCustomerRepository, type PortalOpts, type SavedPaymentMethod, type SetupResult, type WebhookResult } from "@wopr-network/platform-core/billing";
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import type Stripe from "stripe";
 import type { IAutoTopupEventLogRepository } from "../credits/auto-topup-event-log-repository.js";
 import type { BotBilling } from "../credits/bot-billing.js";
@@ -9,7 +9,7 @@ export interface StripePaymentProcessorDeps {
     tenantRepo: ITenantCustomerRepository;
     webhookSecret: string;
     priceMap?: CreditPriceMap;
-    creditLedger: ICreditLedger;
+    creditLedger: ILedger;
     botBilling?: BotBilling;
     replayGuard: IWebhookSeenRepository;
     autoTopupEventLog?: IAutoTopupEventLogRepository;

package/dist/monetization/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 replayGuard = {
         isDuplicate: vi.fn(),

package/dist/monetization/stripe/webhook.d.ts

@@ -1,5 +1,5 @@
 import type { CreditPriceMap, 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";
@@ -34,7 +34,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). */

package/dist/monetization/stripe/webhook.js

@@ -2,6 +2,43 @@ import { Credit } from "@wopr-network/platform-core/credits";
 import { logger } from "../../config/logger.js";
 import { processAffiliateCreditMatch } from "../affiliate/credit-match.js";
 import { grantNewUserBonus } from "../affiliate/new-user-bonus.js";
+/**
+ * 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) {
+    if (!obj || typeof obj !== "object")
+        return undefined;
+    const o = obj;
+    // PaymentIntent: pi.latest_charge expanded → Charge.payment_method_details.card.fingerprint
+    const latestCharge = o.latest_charge;
+    if (latestCharge && typeof latestCharge === "object") {
+        const pmd = latestCharge.payment_method_details;
+        const fp = pmd?.card?.fingerprint;
+        if (typeof fp === "string")
+            return fp;
+    }
+    // PaymentIntent (older API): pi.charges.data[0].payment_method_details.card.fingerprint
+    const charges = o.charges;
+    const charge0 = charges?.data?.[0];
+    if (charge0) {
+        const pmd = charge0.payment_method_details;
+        const fp = pmd?.card?.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.payment_method_details;
+        const fp = pmd?.card?.fingerprint;
+        if (typeof fp === "string")
+            return fp;
+    }
+    return undefined;
+}
 /**
  * Process a Stripe webhook event.
  *
@@ -64,7 +101,12 @@ export async function handleWebhookEvent(deps, event) {
                 creditCents = amountPaid;
             }
             // 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.
             let affiliateBonusCredit;
@@ -198,7 +240,12 @@ export async function handleWebhookEvent(deps, 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,
                 event_type: event.type,
@@ -261,7 +308,12 @@ export async function handleWebhookEvent(deps, event) {
                 result = { handled: true, event_type: event.type, tenant, creditedCents: 0 };
                 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;
             if (deps.botBilling) {
@@ -304,7 +356,11 @@ export async function handleWebhookEvent(deps, event) {
                 break;
             }
             // 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);
+            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 });
             result = { handled: true, event_type: event.type, tenant, debitedCents: refundedCents };
             break;
@@ -334,7 +390,11 @@ export async function handleWebhookEvent(deps, event) {
             await deps.tenantRepo.setBillingHold(tenant, true);
             // 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);
+                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).
             let suspendedBots;
@@ -388,7 +448,11 @@ export async function handleWebhookEvent(deps, 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).
                 let reactivatedBots;

package/dist/monetization/stripe/webhook.test.js

@@ -1,5 +1,5 @@
 import { CREDIT_PRICE_POINTS, DrizzleWebhookSeenRepository, 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 { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
 import { DrizzleAffiliateRepository } from "../affiliate/drizzle-affiliate-repository.js";
@@ -24,7 +24,8 @@ 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 };
     });
     // ---------------------------------------------------------------------------
@@ -170,7 +171,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");
         });
         it("grants affiliate match credits on first purchase for referred tenant (WOP-949)", async () => {
@@ -656,7 +657,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");
         });
         it("handles missing botBilling gracefully (no reactivation, still credits)", async () => {
@@ -690,7 +691,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());
             expect(result.handled).toBe(true);
             expect(result.event_type).toBe("charge.refunded");
@@ -707,7 +708,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" });
             const first = await handleWebhookEvent(deps, event);
             expect(first.debitedCents).toBe(2500);
@@ -727,19 +728,19 @@ 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, makeChargeRefundedEvent({ customer: { id: "cus_ref_obj" }, amount_refunded: 1500 }));
             expect(result.handled).toBe(true);
             expect(result.debitedCents).toBe(1500);
         });
         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");
         });
     });
@@ -810,7 +811,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",
                 type: "payment_intent.succeeded",
@@ -891,7 +896,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"]),
             };
@@ -912,7 +917,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");
             await handleWebhookEvent(deps, event);
             await handleWebhookEvent(deps, event);
@@ -921,7 +926,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 = {
                 notifyDisputeCreated: notifyFn,
@@ -957,14 +962,14 @@ 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" }));
             expect(result.handled).toBe(true);
             expect(result.tenant).toBe("tenant-dispute-obj");
         });
         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"));
             expect(result.handled).toBe(true);
             expect(result.suspendedBots).toBeUndefined();

package/dist/onboarding/onboarding-service.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 type { ISessionUsageRepository } from "../inference/session-usage-repository.js";
 import type { OnboardingConfig } from "./config.js";
 import type { IDaemonManager } from "./daemon-manager.js";
@@ -16,7 +16,7 @@ export declare class OnboardingService {
     private readonly resolveTenantId?;
     private static readonly DEFAULT_PROMPT;
     private static readonly DEFAULT_SCRIPT_REPO;
-    constructor(repo: IOnboardingSessionRepository, client: IWoprClient, config: OnboardingConfig, daemon: IDaemonManager, usageRepo?: ISessionUsageRepository | undefined, scriptRepo?: IOnboardingScriptRepository, creditLedger?: ICreditLedger | undefined, resolveTenantId?: ((userId: string) => Promise<string | null>) | undefined);
+    constructor(repo: IOnboardingSessionRepository, client: IWoprClient, config: OnboardingConfig, daemon: IDaemonManager, usageRepo?: ISessionUsageRepository | undefined, scriptRepo?: IOnboardingScriptRepository, creditLedger?: ILedger | undefined, resolveTenantId?: ((userId: string) => Promise<string | null>) | undefined);
     createSession(opts: {
         userId?: string;
         anonymousId?: string;

package/dist/onboarding/onboarding-service.js

@@ -120,8 +120,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/drizzle/migrations/0002_gateway_service_keys.sql

@@ -0,0 +1,14 @@
+CREATE TABLE "gateway_service_keys" (
+  "id" text PRIMARY KEY NOT NULL,
+  "key_hash" text NOT NULL,
+  "tenant_id" text NOT NULL,
+  "instance_id" text NOT NULL,
+  "created_at" bigint NOT NULL,
+  "revoked_at" bigint
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_gateway_service_keys_hash" ON "gateway_service_keys" USING btree ("key_hash");
+--> statement-breakpoint
+CREATE INDEX "idx_gateway_service_keys_tenant" ON "gateway_service_keys" USING btree ("tenant_id");
+--> statement-breakpoint
+CREATE INDEX "idx_gateway_service_keys_instance" ON "gateway_service_keys" USING btree ("instance_id");

package/drizzle/migrations/0003_double_entry_ledger.sql

@@ -0,0 +1,82 @@
+-- Double-entry ledger: accounts, journal_entries, journal_lines, account_balances
+-- Replaces single-entry credit_transactions + credit_balances
+
+DO $$ BEGIN
+  CREATE TYPE "public"."account_type" AS ENUM('asset','liability','equity','revenue','expense');
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+  CREATE TYPE "public"."entry_side" AS ENUM('debit','credit');
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+CREATE TABLE "accounts" (
+	"id" text PRIMARY KEY NOT NULL,
+	"code" text NOT NULL,
+	"name" text NOT NULL,
+	"type" "account_type" NOT NULL,
+	"normal_side" "entry_side" NOT NULL,
+	"tenant_id" text,
+	"created_at" text DEFAULT (now()) NOT NULL
+);--> statement-breakpoint
+CREATE TABLE "journal_entries" (
+	"id" text PRIMARY KEY NOT NULL,
+	"posted_at" text DEFAULT (now()) NOT NULL,
+	"entry_type" text NOT NULL,
+	"description" text,
+	"reference_id" text,
+	"tenant_id" text NOT NULL,
+	"metadata" jsonb,
+	"created_by" text
+);--> statement-breakpoint
+CREATE TABLE "journal_lines" (
+	"id" text PRIMARY KEY NOT NULL,
+	"journal_entry_id" text NOT NULL REFERENCES "journal_entries"("id"),
+	"account_id" text NOT NULL REFERENCES "accounts"("id"),
+	"amount" bigint NOT NULL,
+	"side" "entry_side" NOT NULL
+);--> statement-breakpoint
+CREATE TABLE "account_balances" (
+	"account_id" text PRIMARY KEY NOT NULL REFERENCES "accounts"("id"),
+	"balance" bigint DEFAULT 0 NOT NULL,
+	"last_updated" text DEFAULT (now()) NOT NULL
+);--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_accounts_code" ON "accounts" USING btree ("code");--> statement-breakpoint
+CREATE INDEX "idx_accounts_tenant" ON "accounts" USING btree ("tenant_id") WHERE "tenant_id" IS NOT NULL;--> statement-breakpoint
+CREATE INDEX "idx_accounts_type" ON "accounts" USING btree ("type");--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_je_reference" ON "journal_entries" USING btree ("reference_id") WHERE "reference_id" IS NOT NULL;--> statement-breakpoint
+CREATE INDEX "idx_je_tenant" ON "journal_entries" USING btree ("tenant_id");--> statement-breakpoint
+CREATE INDEX "idx_je_type" ON "journal_entries" USING btree ("entry_type");--> statement-breakpoint
+CREATE INDEX "idx_je_posted" ON "journal_entries" USING btree ("posted_at");--> statement-breakpoint
+CREATE INDEX "idx_je_tenant_posted" ON "journal_entries" USING btree ("tenant_id","posted_at");--> statement-breakpoint
+CREATE INDEX "idx_jl_entry" ON "journal_lines" USING btree ("journal_entry_id");--> statement-breakpoint
+CREATE INDEX "idx_jl_account" ON "journal_lines" USING btree ("account_id");--> statement-breakpoint
+CREATE INDEX "idx_jl_account_side" ON "journal_lines" USING btree ("account_id","side");--> statement-breakpoint
+
+-- Seed system accounts
+INSERT INTO "accounts" ("id", "code", "name", "type", "normal_side") VALUES
+  (gen_random_uuid(), '1000', 'Cash', 'asset', 'debit'),
+  (gen_random_uuid(), '1100', 'Stripe Receivable', 'asset', 'debit'),
+  (gen_random_uuid(), '3000', 'Retained Earnings', 'equity', 'credit'),
+  (gen_random_uuid(), '4000', 'Revenue: Bot Runtime', 'revenue', 'credit'),
+  (gen_random_uuid(), '4010', 'Revenue: Adapter Usage', 'revenue', 'credit'),
+  (gen_random_uuid(), '4020', 'Revenue: Addon', 'revenue', 'credit'),
+  (gen_random_uuid(), '4030', 'Revenue: Storage Upgrade', 'revenue', 'credit'),
+  (gen_random_uuid(), '4040', 'Revenue: Resource Upgrade', 'revenue', 'credit'),
+  (gen_random_uuid(), '4050', 'Revenue: Onboarding LLM', 'revenue', 'credit'),
+  (gen_random_uuid(), '4060', 'Revenue: Expired Credits', 'revenue', 'credit'),
+  (gen_random_uuid(), '5000', 'Expense: Signup Grant', 'expense', 'debit'),
+  (gen_random_uuid(), '5010', 'Expense: Admin Grant', 'expense', 'debit'),
+  (gen_random_uuid(), '5020', 'Expense: Promo', 'expense', 'debit'),
+  (gen_random_uuid(), '5030', 'Expense: Referral', 'expense', 'debit'),
+  (gen_random_uuid(), '5040', 'Expense: Affiliate', 'expense', 'debit'),
+  (gen_random_uuid(), '5050', 'Expense: Bounty', 'expense', 'debit'),
+  (gen_random_uuid(), '5060', 'Expense: Dividend', 'expense', 'debit'),
+  (gen_random_uuid(), '5070', 'Expense: Correction', 'expense', 'debit');--> statement-breakpoint
+
+-- Initialize balance rows for all seeded system accounts
+INSERT INTO "account_balances" ("account_id", "balance")
+  SELECT "id", 0 FROM "accounts";--> statement-breakpoint
+
+-- Drop old single-entry tables
+DROP TABLE IF EXISTS "credit_transactions" CASCADE;--> statement-breakpoint
+DROP TABLE IF EXISTS "credit_balances" CASCADE;

package/drizzle/migrations/meta/_journal.json

@@ -15,6 +15,20 @@
       "when": 1773279600000,
       "tag": "0001_infrastructure_extraction",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1741795200000,
+      "tag": "0002_gateway_service_keys",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1741881600000,
+      "tag": "0003_double_entry_ledger",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.13.2",
+  "version": "1.14.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/api/routes/admin-credits.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { z } from "zod";
 import type { AuthEnv } from "../../auth/index.js";
-import type { ICreditLedger } from "../../credits/index.js";
+import type { ILedger } from "../../credits/index.js";
 import { Credit, InsufficientBalanceError } from "../../credits/index.js";
 import type { AdminAuditLogger } from "./admin-audit-helper.js";
 import { safeAuditLog } from "./admin-audit-helper.js";
@@ -31,7 +31,7 @@ function parseIntParam(value: string | undefined): number | undefined {
  * Pass a ledger directly or a factory for lazy init.
  */
 export function createAdminCreditApiRoutes(
-  ledgerOrFactory: ICreditLedger | (() => ICreditLedger),
+  ledgerOrFactory: ILedger | (() => ILedger),
   auditLogger?: () => AdminAuditLogger,
 ): Hono<AuthEnv> {
   const ledgerFactory = typeof ledgerOrFactory === "function" ? ledgerOrFactory : () => ledgerOrFactory;
@@ -66,15 +66,10 @@ export function createAdminCreditApiRoutes(
       const adminUser = user?.id ?? "unknown";
       let result: Awaited<ReturnType<typeof ledger.credit>>;
       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, {
           adminUser,
@@ -129,7 +124,7 @@ export function createAdminCreditApiRoutes(
       const adminUser = user?.id ?? "unknown";
       let result: Awaited<ReturnType<typeof ledger.credit>>;
       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, {
           adminUser,
@@ -188,9 +183,11 @@ export function createAdminCreditApiRoutes(
       let result: Awaited<ReturnType<typeof ledger.credit>>;
       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) {
         safeAuditLog(auditLogger, {

package/src/api/routes/quota.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import type { ICreditLedger } from "../../credits/credit-ledger.js";
+import type { ILedger } from "../../credits/ledger.js";
 import { checkInstanceQuota, DEFAULT_INSTANCE_LIMITS } from "../../monetization/quotas/quota-check.js";
 import { buildResourceLimits, DEFAULT_RESOURCE_CONFIG } from "../../monetization/quotas/resource-limits.js";
 
@@ -8,7 +8,7 @@ import { buildResourceLimits, DEFAULT_RESOURCE_CONFIG } from "../../monetization
  *
  * @param ledgerFactory - Factory returning the credit ledger
  */
-export function createQuotaRoutes(ledgerFactory: () => ICreditLedger): Hono {
+export function createQuotaRoutes(ledgerFactory: () => ILedger): Hono {
   const routes = new Hono();
 
   /**

package/src/api/routes/verify-email.ts

@@ -1,14 +1,14 @@
 import { Hono } from "hono";
 import type { Pool } from "pg";
 import { logger } from "../../config/logger.js";
-import type { ICreditLedger } from "../../credits/index.js";
+import type { ILedger } from "../../credits/index.js";
 import { grantSignupCredits } from "../../credits/index.js";
 import { getEmailClient } from "../../email/client.js";
 import { verifyToken, welcomeTemplate } from "../../email/index.js";
 
 export interface VerifyEmailRouteDeps {
   pool: Pool;
-  creditLedger: ICreditLedger;
+  creditLedger: ILedger;
 }
 
 export interface VerifyEmailRouteConfig {
@@ -32,7 +32,7 @@ export function createVerifyEmailRoutes(deps: VerifyEmailRouteDeps, config?: Ver
  */
 export function createVerifyEmailRoutesLazy(
   poolFactory: () => Pool,
-  creditLedgerFactory: () => ICreditLedger,
+  creditLedgerFactory: () => ILedger,
   config?: VerifyEmailRouteConfig,
 ): Hono {
   return buildRoutes(poolFactory, creditLedgerFactory, config);
@@ -40,7 +40,7 @@ export function createVerifyEmailRoutesLazy(
 
 function buildRoutes(
   poolFactory: () => Pool,
-  creditLedgerFactory: () => ICreditLedger,
+  creditLedgerFactory: () => ILedger,
   config?: VerifyEmailRouteConfig,
 ): Hono {
   const uiOrigin = config?.uiOrigin ?? process.env.UI_ORIGIN ?? "http://localhost:3001";