@wopr-network/platform-core 1.13.3 → 1.14.1

package/src/credits/signup-grant.test.ts

@@ -2,13 +2,13 @@ import type { PGlite } from "@electric-sql/pglite";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { PlatformDb } from "../db/index.js";
 import { createTestDb, truncateAllTables } from "../test/db.js";
-import { CreditLedger } from "./credit-ledger.js";
+import { DrizzleLedger } from "./ledger.js";
 import { grantSignupCredits, SIGNUP_GRANT } from "./signup-grant.js";
 
 describe("grantSignupCredits", () => {
   let pool: PGlite;
   let db: PlatformDb;
-  let ledger: CreditLedger;
+  let ledger: DrizzleLedger;
 
   beforeAll(async () => {
     ({ db, pool } = await createTestDb());
@@ -20,7 +20,9 @@ describe("grantSignupCredits", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
-    ledger = new CreditLedger(db);
+    ledger = new DrizzleLedger(db);
+
+    await ledger.seedSystemAccounts();
   });
 
   it("grants credits to a new tenant and returns true", async () => {
@@ -53,7 +55,8 @@ describe("grantSignupCredits", () => {
     const uniqueErr = Object.assign(new Error("duplicate key value violates unique constraint"), {
       code: "23505",
     });
-    const racingLedger = new CreditLedger(db);
+    const racingLedger = new DrizzleLedger(db);
+    await racingLedger.seedSystemAccounts();
     vi.spyOn(racingLedger, "hasReferenceId").mockResolvedValue(false);
     vi.spyOn(racingLedger, "credit").mockRejectedValue(uniqueErr);
 

package/src/credits/signup-grant.ts

@@ -1,5 +1,5 @@
 import { Credit } from "./credit.js";
-import type { ICreditLedger } from "./credit-ledger.js";
+import type { ILedger } from "./ledger.js";
 
 /** Signup grant amount: $5.00 */
 export const SIGNUP_GRANT = Credit.fromDollars(5);
@@ -11,25 +11,19 @@ export const SIGNUP_GRANT = Credit.fromDollars(5);
  *
  * @returns true if the grant was applied, false if already granted.
  */
-export async function grantSignupCredits(ledger: ICreditLedger, tenantId: string): Promise<boolean> {
+export async function grantSignupCredits(ledger: ILedger, tenantId: string): Promise<boolean> {
   const refId = `signup:${tenantId}`;
 
-  // Idempotency check
   if (await ledger.hasReferenceId(refId)) {
     return false;
   }
 
   try {
-    await ledger.credit(
-      tenantId,
-      SIGNUP_GRANT,
-      "signup_grant",
-      "Welcome bonus — $5.00 credit on email verification",
-      refId,
-    );
+    await ledger.credit(tenantId, SIGNUP_GRANT, "signup_grant", {
+      description: "Welcome bonus — $5.00 credit on email verification",
+      referenceId: refId,
+    });
   } catch (err) {
-    // Concurrent verify-email request won the race and already inserted the same referenceId.
-    // Treat unique constraint violation as a no-op (idempotent).
     if (isUniqueConstraintViolation(err)) return false;
     throw err;
   }

package/src/credits/trial-balance-cron.test.ts

@@ -0,0 +1,68 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { DrizzleLedger } from "./ledger.js";
+import { runTrialBalanceCron } from "./trial-balance-cron.js";
+
+describe("runTrialBalanceCron", () => {
+  let pool: PGlite;
+  let ledger: DrizzleLedger;
+
+  beforeAll(async () => {
+    const { db, pool: p } = await createTestDb();
+    pool = p;
+    ledger = new DrizzleLedger(db);
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    await ledger.seedSystemAccounts();
+  });
+
+  it("returns balanced when no entries exist", async () => {
+    const result = await runTrialBalanceCron({ ledger });
+    expect(result.balanced).toBe(true);
+    expect(result.differenceRaw).toBe(0);
+  });
+
+  it("returns balanced after normal credit and debit", async () => {
+    await ledger.credit("t1", Credit.fromCents(500), "purchase");
+    await ledger.debit("t1", Credit.fromCents(200), "bot_runtime");
+
+    const result = await runTrialBalanceCron({ ledger });
+    expect(result.balanced).toBe(true);
+    expect(result.differenceRaw).toBe(0);
+  });
+
+  it("logs an error on imbalance", async () => {
+    // Inject an imbalance by mocking trialBalance to return unbalanced data
+    const errorSpy = vi.spyOn(ledger, "trialBalance").mockResolvedValueOnce({
+      totalDebits: Credit.fromCents(1000),
+      totalCredits: Credit.fromCents(900),
+      balanced: false,
+      difference: Credit.fromCents(100),
+    });
+
+    const result = await runTrialBalanceCron({ ledger });
+    expect(result.balanced).toBe(false);
+    expect(result.differenceRaw).toBe(Credit.fromCents(100).toRaw());
+
+    errorSpy.mockRestore();
+  });
+
+  it("does not throw on imbalance", async () => {
+    vi.spyOn(ledger, "trialBalance").mockResolvedValueOnce({
+      totalDebits: Credit.fromCents(500),
+      totalCredits: Credit.fromCents(400),
+      balanced: false,
+      difference: Credit.fromCents(100),
+    });
+
+    await expect(runTrialBalanceCron({ ledger })).resolves.not.toThrow();
+  });
+});

package/src/credits/trial-balance-cron.ts

@@ -0,0 +1,46 @@
+import { logger } from "../config/logger.js";
+import type { ILedger } from "./ledger.js";
+
+export interface TrialBalanceCronConfig {
+  ledger: ILedger;
+}
+
+export interface TrialBalanceCronResult {
+  balanced: boolean;
+  totalDebits: number;
+  totalCredits: number;
+  /** Absolute difference in raw units (nanodollars). Zero when balanced. */
+  differenceRaw: number;
+}
+
+/**
+ * Run a trial balance check: assert that sum(debit lines) === sum(credit lines)
+ * across all journal entries.
+ *
+ * Designed to run hourly. Logs an error on imbalance but never throws —
+ * an imbalance is historical and requires human investigation, not automated action.
+ */
+export async function runTrialBalanceCron(cfg: TrialBalanceCronConfig): Promise<TrialBalanceCronResult> {
+  const tb = await cfg.ledger.trialBalance();
+
+  const result: TrialBalanceCronResult = {
+    balanced: tb.balanced,
+    totalDebits: tb.totalDebits.toRaw(),
+    totalCredits: tb.totalCredits.toRaw(),
+    differenceRaw: tb.difference.toRaw(),
+  };
+
+  if (!tb.balanced) {
+    logger.error("LEDGER IMBALANCE DETECTED — books do not balance", {
+      totalDebits: tb.totalDebits.toDisplayString(),
+      totalCredits: tb.totalCredits.toDisplayString(),
+      difference: tb.difference.toDisplayString(),
+    });
+  } else {
+    logger.info("Trial balance check passed", {
+      totalDebits: tb.totalDebits.toDisplayString(),
+    });
+  }
+
+  return result;
+}

package/src/db/schema/index.ts

@@ -25,6 +25,7 @@ export * from "./gateway-service-keys.js";
 export * from "./gpu-allocations.js";
 export * from "./gpu-configurations.js";
 export * from "./gpu-nodes.js";
+export * from "./ledger.js";
 export * from "./marketplace-plugins.js";
 export * from "./meter-events.js";
 export * from "./node-registration-tokens.js";

package/src/db/schema/ledger.ts

@@ -0,0 +1,94 @@
+import { sql } from "drizzle-orm";
+import { bigint, index, jsonb, pgEnum, pgTable, text, uniqueIndex } from "drizzle-orm/pg-core";
+
+export const accountTypeEnum = pgEnum("account_type", ["asset", "liability", "equity", "revenue", "expense"]);
+
+export const entrySideEnum = pgEnum("entry_side", ["debit", "credit"]);
+
+/**
+ * Chart of accounts — every account that can appear in a journal line.
+ *
+ * System accounts (tenant_id IS NULL) are seeded at migration time.
+ * Per-tenant liability accounts are created lazily on first transaction.
+ */
+export const accounts = pgTable(
+  "accounts",
+  {
+    id: text("id").primaryKey(),
+    code: text("code").notNull(),
+    name: text("name").notNull(),
+    type: accountTypeEnum("type").notNull(),
+    normalSide: entrySideEnum("normal_side").notNull(),
+    tenantId: text("tenant_id"), // NULL = system account
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+  },
+  (table) => [
+    uniqueIndex("idx_accounts_code").on(table.code),
+    index("idx_accounts_tenant").on(table.tenantId).where(sql`${table.tenantId} IS NOT NULL`),
+    index("idx_accounts_type").on(table.type),
+  ],
+);
+
+/**
+ * Journal entries — the header for each balanced transaction.
+ * One business event = one journal entry = two or more journal lines that sum to zero.
+ */
+export const journalEntries = pgTable(
+  "journal_entries",
+  {
+    id: text("id").primaryKey(),
+    postedAt: text("posted_at").notNull().default(sql`(now())`),
+    entryType: text("entry_type").notNull(), // purchase, usage, grant, refund, dividend, expiry, correction
+    description: text("description"),
+    referenceId: text("reference_id"),
+    tenantId: text("tenant_id").notNull(),
+    metadata: jsonb("metadata"), // funding_source, attributed_user_id, stripe_fingerprint, etc.
+    createdBy: text("created_by"), // system, admin:<id>, cron:expiry, etc.
+  },
+  (table) => [
+    uniqueIndex("idx_je_reference").on(table.referenceId).where(sql`${table.referenceId} IS NOT NULL`),
+    index("idx_je_tenant").on(table.tenantId),
+    index("idx_je_type").on(table.entryType),
+    index("idx_je_posted").on(table.postedAt),
+    index("idx_je_tenant_posted").on(table.tenantId, table.postedAt),
+  ],
+);
+
+/**
+ * Journal lines — the individual debits and credits within a journal entry.
+ * Invariant: for every journal_entry, SUM(debit amounts) = SUM(credit amounts).
+ * Amount is always positive; `side` determines the direction.
+ * Stored in nanodollars (Credit.toRaw()).
+ */
+export const journalLines = pgTable(
+  "journal_lines",
+  {
+    id: text("id").primaryKey(),
+    journalEntryId: text("journal_entry_id")
+      .notNull()
+      .references(() => journalEntries.id),
+    accountId: text("account_id")
+      .notNull()
+      .references(() => accounts.id),
+    amount: bigint("amount", { mode: "number" }).notNull(), // nanodollars, always positive
+    side: entrySideEnum("side").notNull(),
+  },
+  (table) => [
+    index("idx_jl_entry").on(table.journalEntryId),
+    index("idx_jl_account").on(table.accountId),
+    index("idx_jl_account_side").on(table.accountId, table.side),
+  ],
+);
+
+/**
+ * Materialized account balances — cache derived from journal_lines.
+ * Updated atomically within the same transaction as the journal line insert.
+ * Can always be reconstructed from journal_lines if corrupted.
+ */
+export const accountBalances = pgTable("account_balances", {
+  accountId: text("account_id")
+    .primaryKey()
+    .references(() => accounts.id),
+  balance: bigint("balance", { mode: "number" }).notNull().default(0), // net balance in nanodollars
+  lastUpdated: text("last_updated").notNull().default(sql`(now())`),
+});

package/src/gateway/credit-gate-wiring.test.ts

@@ -1,4 +1,4 @@
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit } from "@wopr-network/platform-core/credits";
 import { describe, expect, it, vi } from "vitest";
 import { type CreditGateDeps, debitCredits } from "./credit-gate.js";
@@ -9,7 +9,7 @@ describe("onDebitComplete wiring", () => {
     const balance = vi.fn().mockResolvedValue(Credit.fromCents(500));
     const debit = vi.fn().mockResolvedValue(undefined);
     const deps: CreditGateDeps = {
-      creditLedger: { balance, debit } as unknown as ICreditLedger,
+      creditLedger: { balance, debit } as unknown as ILedger,
       topUpUrl: "/billing",
       onDebitComplete,
     };
@@ -25,7 +25,7 @@ describe("onDebitComplete wiring", () => {
     const { InsufficientBalanceError } = await import("@wopr-network/platform-core/credits");
     const debit = vi.fn().mockRejectedValue(new InsufficientBalanceError(Credit.fromCents(0), Credit.fromCents(100)));
     const deps: CreditGateDeps = {
-      creditLedger: { debit } as unknown as ICreditLedger,
+      creditLedger: { debit } as unknown as ILedger,
       topUpUrl: "/billing",
       onDebitComplete,
     };

package/src/gateway/credit-gate.test.ts

@@ -3,7 +3,7 @@
  */
 
 import type { PGlite } from "@electric-sql/pglite";
-import { Credit, CreditLedger } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import { Hono } from "hono";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { DrizzleDb } from "../db/index.js";
@@ -51,11 +51,12 @@ afterAll(async () => {
 describe("creditBalanceCheck grace buffer", () => {
   beforeEach(async () => {
     await truncateAllTables(pool);
+    await new DrizzleLedger(db).seedSystemAccounts();
   });
 
   it("returns null when balance is above estimated cost (passes)", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(500), "purchase", "setup");
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(500), "purchase", { description: "setup" });
     const c = await buildHonoContext("t1");
     const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing" };
     expect(await creditBalanceCheck(c, deps, 1)).toBeNull();
@@ -63,27 +64,27 @@ describe("creditBalanceCheck grace buffer", () => {
 
   it("returns null when balance is zero but within default grace buffer (passes)", async () => {
     // Balance at exactly 0 — within the -50 grace buffer
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(10), "purchase", "setup");
-    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "drain");
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(10), "purchase", { description: "setup" });
+    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", { description: "drain" });
     const c = await buildHonoContext("t1");
     const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing" };
     expect(await creditBalanceCheck(c, deps, 0)).toBeNull();
   });
 
   it("returns null when balance is -49 (within 50-cent grace buffer)", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(1), "purchase", "setup");
-    await ledger.debit("t1", Credit.fromCents(50), "adapter_usage", "drain", undefined, true); // balance = -49
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(1), "purchase", { description: "setup" });
+    await ledger.debit("t1", Credit.fromCents(50), "adapter_usage", { description: "drain", allowNegative: true }); // balance = -49
     const c = await buildHonoContext("t1");
     const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing" };
     expect(await creditBalanceCheck(c, deps, 0)).toBeNull();
   });
 
   it("returns credits_exhausted when balance is at -50 (at grace buffer limit)", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(1), "purchase", "setup");
-    await ledger.debit("t1", Credit.fromCents(51), "adapter_usage", "drain", undefined, true); // balance = -50
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(1), "purchase", { description: "setup" });
+    await ledger.debit("t1", Credit.fromCents(51), "adapter_usage", { description: "drain", allowNegative: true }); // balance = -50
     const c = await buildHonoContext("t1");
     const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing" };
     const result = await creditBalanceCheck(c, deps, 0);
@@ -92,9 +93,9 @@ describe("creditBalanceCheck grace buffer", () => {
   });
 
   it("returns credits_exhausted when balance is at -51 (beyond grace buffer)", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(1), "purchase", "setup");
-    await ledger.debit("t1", Credit.fromCents(52), "adapter_usage", "drain", undefined, true); // balance = -51
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(1), "purchase", { description: "setup" });
+    await ledger.debit("t1", Credit.fromCents(52), "adapter_usage", { description: "drain", allowNegative: true }); // balance = -51
     const c = await buildHonoContext("t1");
     const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing" };
     const result = await creditBalanceCheck(c, deps, 0);
@@ -103,9 +104,9 @@ describe("creditBalanceCheck grace buffer", () => {
   });
 
   it("returns credits_exhausted when custom graceBufferCents=0 and balance is 0", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(10), "purchase", "setup");
-    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "drain"); // balance = 0
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(10), "purchase", { description: "setup" });
+    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", { description: "drain" }); // balance = 0
     const c = await buildHonoContext("t1");
     const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing", graceBufferCents: 0 };
     const result = await creditBalanceCheck(c, deps, 0);
@@ -114,8 +115,8 @@ describe("creditBalanceCheck grace buffer", () => {
   });
 
   it("returns insufficient_credits when balance positive but below estimated cost", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup");
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(5), "purchase", { description: "setup" });
     const c = await buildHonoContext("t1");
     const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing" };
     const result = await creditBalanceCheck(c, deps, 10);
@@ -131,11 +132,12 @@ describe("creditBalanceCheck grace buffer", () => {
 describe("debitCredits with allowNegative and onBalanceExhausted", () => {
   beforeEach(async () => {
     await truncateAllTables(pool);
+    await new DrizzleLedger(db).seedSystemAccounts();
   });
 
   it("debit with cost that would exceed balance succeeds (allowNegative=true)", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup"); // balance = 5 cents
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(5), "purchase", { description: "setup" }); // balance = 5 cents
 
     // costUsd = $0.10 = 10 cents, margin = 1.0
     // This should push balance negative without throwing
@@ -147,8 +149,8 @@ describe("debitCredits with allowNegative and onBalanceExhausted", () => {
   });
 
   it("fires onBalanceExhausted when debit causes balance to cross zero", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup"); // balance = 5 cents
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(5), "purchase", { description: "setup" }); // balance = 5 cents
 
     const onBalanceExhausted = vi.fn();
     // costUsd = $0.10 = 10 cents with margin 1.0 → chargeCents = 10, pushes balance to -5
@@ -165,8 +167,8 @@ describe("debitCredits with allowNegative and onBalanceExhausted", () => {
   });
 
   it("does NOT fire onBalanceExhausted when balance stays positive after debit", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(500), "purchase", "setup"); // balance = 500 cents
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(500), "purchase", { description: "setup" }); // balance = 500 cents
 
     const onBalanceExhausted = vi.fn();
     // costUsd = $0.01 = 1 cent → balance stays at 499
@@ -184,8 +186,8 @@ describe("debitCredits with allowNegative and onBalanceExhausted", () => {
   });
 
   it("onBalanceExhausted callback receives correct tenantId and negative balance", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(3), "purchase", "setup"); // balance = 3 cents
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(3), "purchase", { description: "setup" }); // balance = 3 cents
 
     const onBalanceExhausted = vi.fn();
     // costUsd = $0.05 = 5 cents with margin 1.0 → pushes balance to -2
@@ -203,8 +205,8 @@ describe("debitCredits with allowNegative and onBalanceExhausted", () => {
   });
 
   it("calls onSpendAlertCrossed after successful debit", async () => {
-    const ledger = new CreditLedger(db);
-    await ledger.credit("t1", Credit.fromCents(500), "purchase", "setup");
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("t1", Credit.fromCents(500), "purchase", { description: "setup" });
 
     const onSpendAlertCrossed = vi.fn();
     await debitCredits(
@@ -219,10 +221,10 @@ describe("debitCredits with allowNegative and onBalanceExhausted", () => {
   });
 
   it("does NOT fire onBalanceExhausted when balance was already negative before debit", async () => {
-    const ledger = new CreditLedger(db);
+    const ledger = new DrizzleLedger(db);
     // Start with negative balance: credit 5, debit 10 → balance = -5
-    await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup");
-    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "drain", undefined, true);
+    await ledger.credit("t1", Credit.fromCents(5), "purchase", { description: "setup" });
+    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", { description: "drain", allowNegative: true });
 
     const onBalanceExhausted = vi.fn();
     // Another debit of 1 cent — balance goes from -5 to -6, but was already negative

package/src/gateway/credit-gate.ts

@@ -6,7 +6,7 @@
  * gateway endpoints.
  */
 
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit, InsufficientBalanceError } from "@wopr-network/platform-core/credits";
 import type { Context } from "hono";
 import { logger } from "../config/logger.js";
@@ -14,7 +14,7 @@ import { withMargin } from "../monetization/adapters/types.js";
 import type { GatewayAuthEnv } from "./service-key-auth.js";
 
 export interface CreditGateDeps {
-  creditLedger?: ICreditLedger;
+  creditLedger?: ILedger;
   topUpUrl: string;
   /** Maximum negative balance allowed before hard-stop, in cents. Default: 50 (-$0.50). */
   graceBufferCents?: number;
@@ -118,15 +118,11 @@ export async function debitCredits(
   }
 
   try {
-    await deps.creditLedger.debit(
-      tenantId,
-      chargeCredit,
-      "adapter_usage",
-      `Gateway ${capability} via ${provider}`,
-      undefined,
-      true,
+    await deps.creditLedger.debit(tenantId, chargeCredit, "adapter_usage", {
+      description: `Gateway ${capability} via ${provider}`,
+      allowNegative: true,
       attributedUserId,
-    );
+    });
 
     // Only fire on first zero-crossing (balance was positive before, now ≤ 0)
     if (deps.onBalanceExhausted) {

package/src/gateway/gateway-routes.test.ts

@@ -7,7 +7,7 @@
  * Uses mocked deps — no PGlite required.
  */
 
-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 { Hono } from "hono";
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -51,7 +51,7 @@ function buildTestConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig
     debit: vi.fn().mockResolvedValue(undefined),
     credit: vi.fn(),
     history: vi.fn(),
-  } as unknown as ICreditLedger;
+  } as unknown as ILedger;
   const fetchFn = vi.fn().mockResolvedValue(
     new Response(
       JSON.stringify({
@@ -163,7 +163,7 @@ describe("gateway routes — credit check", () => {
         debit: vi.fn(),
         credit: vi.fn(),
         history: vi.fn(),
-      } as unknown as ICreditLedger,
+      } as unknown as ILedger,
     });
     const app = buildApp(config);
     const res = await chatRequest(app, VALID_KEY);
@@ -183,7 +183,7 @@ describe("gateway routes — credit check", () => {
         debit: vi.fn(),
         credit: vi.fn(),
         history: vi.fn(),
-      } as unknown as ICreditLedger,
+      } as unknown as ILedger,
     });
     const app = buildApp(config);
     const res = await chatRequest(app, VALID_KEY);
@@ -200,7 +200,7 @@ describe("gateway routes — credit check", () => {
         debit: vi.fn(),
         credit: vi.fn(),
         history: vi.fn(),
-      } as unknown as ICreditLedger,
+      } as unknown as ILedger,
       fetchFn,
     });
     const app = buildApp(config);

package/src/gateway/protocol/deps.ts

@@ -5,7 +5,7 @@
  * budget checking, metering, provider configs, fetch, and service key resolution.
  */
 
-import type { Credit, ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { Credit, ILedger } from "@wopr-network/platform-core/credits";
 import type { MeterEmitter } from "@wopr-network/platform-core/metering";
 import type { IRateLimitRepository } from "../../api/rate-limit-repository.js";
 import type { IBudgetChecker } from "../../monetization/budget/budget-checker.js";
@@ -18,7 +18,7 @@ import type { FetchFn, GatewayTenant, ProviderConfig } from "../types.js";
 export interface ProtocolDeps {
   meter: MeterEmitter;
   budgetChecker: IBudgetChecker;
-  creditLedger?: ICreditLedger;
+  creditLedger?: ILedger;
   topUpUrl: string;
   graceBufferCents?: number;
   providers: ProviderConfig;