@wopr-network/platform-core 0.1.0

package/src/metering/reconciliation-cron.test.ts

@@ -0,0 +1,202 @@
+import crypto from "node:crypto";
+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 { usageSummaries } from "../db/schema/meter-events.js";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "../credits/credit.js";
+import { CreditLedger } from "../credits/credit-ledger.js";
+import { runReconciliation } from "./reconciliation-cron.js";
+import { DrizzleAdapterUsageRepository, DrizzleUsageSummaryRepository } from "./reconciliation-repository.js";
+
+/** Today's date as YYYY-MM-DD (UTC). We use "today" as targetDate since the
+ *  credit ledger inserts use `now()` for createdAt, so debits land in today's window. */
+const TODAY = new Date().toISOString().slice(0, 10);
+const DAY_START = new Date(`${TODAY}T00:00:00Z`).getTime();
+const DAY_END = DAY_START + 24 * 60 * 60 * 1000;
+
+describe("runReconciliation", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let ledger: CreditLedger;
+  let usageSummaryRepo: DrizzleUsageSummaryRepository;
+  let adapterUsageRepo: DrizzleAdapterUsageRepository;
+
+  beforeAll(async () => {
+    const t = await createTestDb();
+    pool = t.pool;
+    db = t.db;
+    ledger = new CreditLedger(db);
+    usageSummaryRepo = new DrizzleUsageSummaryRepository(db);
+    adapterUsageRepo = new DrizzleAdapterUsageRepository(db);
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+  });
+
+  /** Insert a usage_summaries row directly. */
+  async function insertSummary(opts: {
+    tenant: string;
+    totalCharge: number;
+    windowStart?: number;
+    windowEnd?: number;
+    capability?: string;
+    provider?: string;
+  }) {
+    await db.insert(usageSummaries).values({
+      id: crypto.randomUUID(),
+      tenant: opts.tenant,
+      capability: opts.capability ?? "chat",
+      provider: opts.provider ?? "openai",
+      eventCount: 1,
+      totalCost: 0,
+      totalCharge: opts.totalCharge,
+      totalDuration: 0,
+      windowStart: opts.windowStart ?? DAY_START,
+      windowEnd: opts.windowEnd ?? DAY_END - 1,
+    });
+  }
+
+  it("returns empty result when no metering or ledger data", async () => {
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
+    expect(result.tenantsChecked).toBe(0);
+    expect(result.discrepancies).toEqual([]);
+    expect(result.flagged).toEqual([]);
+    expect(result.date).toBe(TODAY);
+  });
+
+  it("no discrepancy when metered charge matches ledger debit", async () => {
+    const charge = Credit.fromCents(50);
+    await insertSummary({ tenant: "t1", totalCharge: charge.toRaw() });
+
+    await ledger.credit("t1", Credit.fromCents(500), "purchase");
+    await ledger.debit("t1", charge, "adapter_usage", "chat usage");
+
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
+    expect(result.tenantsChecked).toBe(1);
+    expect(result.discrepancies).toEqual([]);
+  });
+
+  it("detects drift when metered charge exceeds ledger debit", async () => {
+    await insertSummary({ tenant: "t1", totalCharge: Credit.fromCents(100).toRaw() });
+
+    await ledger.credit("t1", Credit.fromCents(500), "purchase");
+    await ledger.debit("t1", Credit.fromCents(80), "adapter_usage", "chat usage");
+
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
+    expect(result.tenantsChecked).toBe(1);
+    expect(result.discrepancies).toHaveLength(1);
+    expect(result.discrepancies[0].tenantId).toBe("t1");
+    // drift = metered(100c) - ledger(80c) = 20c, in raw units
+    expect(result.discrepancies[0].driftRaw).toBe(Credit.fromCents(20).toRaw());
+  });
+
+  it("flags tenant when drift exceeds flag threshold", async () => {
+    await insertSummary({ tenant: "t1", totalCharge: Credit.fromCents(200).toRaw() });
+
+    // No ledger debit at all — simulating a missed deduction
+    const onFlagForReview = vi.fn();
+    const result = await runReconciliation({
+      usageSummaryRepo,
+      adapterUsageRepo,
+      targetDate: TODAY,
+      flagThresholdRaw: Credit.fromCents(100).toRaw(), // $1.00
+      onFlagForReview,
+    });
+
+    expect(result.flagged).toContain("t1");
+    expect(onFlagForReview).toHaveBeenCalledWith("t1", Credit.fromCents(200).toRaw());
+  });
+
+  it("ignores non-adapter_usage debits (bot_runtime, etc.)", async () => {
+    await insertSummary({ tenant: "t1", totalCharge: Credit.fromCents(20).toRaw() });
+
+    await ledger.credit("t1", Credit.fromCents(500), "purchase");
+    // Debit as bot_runtime — should NOT count toward reconciliation
+    await ledger.debit("t1", Credit.fromCents(20), "bot_runtime", "daily runtime");
+
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
+    // Metered 20c, ledger adapter_usage = 0 => drift = 20c
+    expect(result.discrepancies).toHaveLength(1);
+    expect(result.discrepancies[0].driftRaw).toBe(Credit.fromCents(20).toRaw());
+  });
+
+  it("ignores __sentinel__ rows from usage_summaries", async () => {
+    // Insert a sentinel row (should be ignored)
+    await db.insert(usageSummaries).values({
+      id: crypto.randomUUID(),
+      tenant: "__sentinel__",
+      capability: "__none__",
+      provider: "__none__",
+      eventCount: 0,
+      totalCost: 0,
+      totalCharge: 0,
+      totalDuration: 0,
+      windowStart: DAY_START,
+      windowEnd: DAY_END - 1,
+    });
+
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
+    expect(result.tenantsChecked).toBe(0);
+    expect(result.discrepancies).toEqual([]);
+  });
+
+  it("handles multiple tenants independently", async () => {
+    // t1: balanced
+    await insertSummary({ tenant: "t1", totalCharge: Credit.fromCents(50).toRaw() });
+    await ledger.credit("t1", Credit.fromCents(500), "purchase");
+    await ledger.debit("t1", Credit.fromCents(50), "adapter_usage", "chat");
+
+    // t2: drifted
+    await insertSummary({ tenant: "t2", totalCharge: Credit.fromCents(100).toRaw() });
+    await ledger.credit("t2", Credit.fromCents(500), "purchase");
+    await ledger.debit("t2", Credit.fromCents(60), "adapter_usage", "chat");
+
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
+    expect(result.tenantsChecked).toBe(2);
+    expect(result.discrepancies).toHaveLength(1);
+    expect(result.discrepancies[0].tenantId).toBe("t2");
+    expect(result.discrepancies[0].driftRaw).toBe(Credit.fromCents(40).toRaw());
+  });
+
+  it("uses yesterday as default targetDate", async () => {
+    const yesterday = new Date();
+    yesterday.setDate(yesterday.getDate() - 1);
+    const expectedDate = yesterday.toISOString().slice(0, 10);
+
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo });
+    expect(result.date).toBe(expectedDate);
+    expect(result.tenantsChecked).toBe(0);
+  });
+
+  it("ignores metering data outside the target date window", async () => {
+    // Summary from yesterday — should not appear in today's reconciliation
+    const yesterday = new Date(`${TODAY}T00:00:00Z`).getTime() - 24 * 60 * 60 * 1000;
+    await insertSummary({
+      tenant: "t1",
+      totalCharge: Credit.fromCents(100).toRaw(),
+      windowStart: yesterday,
+      windowEnd: yesterday + 24 * 60 * 60 * 1000 - 1,
+    });
+
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
+    expect(result.tenantsChecked).toBe(0);
+  });
+
+  it("handles over-billed drift (ledger > metered)", async () => {
+    // Metered 50c but debited 80c (over-billed)
+    await insertSummary({ tenant: "t1", totalCharge: Credit.fromCents(50).toRaw() });
+
+    await ledger.credit("t1", Credit.fromCents(500), "purchase");
+    await ledger.debit("t1", Credit.fromCents(80), "adapter_usage", "chat usage");
+
+    const result = await runReconciliation({ usageSummaryRepo, adapterUsageRepo, targetDate: TODAY });
+    expect(result.discrepancies).toHaveLength(1);
+    expect(result.discrepancies[0].driftRaw).toBe(Credit.fromCents(-30).toRaw());
+  });
+});

package/src/metering/reconciliation-cron.ts

@@ -0,0 +1,134 @@
+import { logger } from "../config/logger.js";
+import { Credit } from "../credits/credit.js";
+import type { IAdapterUsageRepository, IUsageSummaryRepository } from "./reconciliation-repository.js";
+
+export interface ReconciliationConfig {
+  usageSummaryRepo: IUsageSummaryRepository;
+  adapterUsageRepo: IAdapterUsageRepository;
+  /** The date to reconcile, as YYYY-MM-DD. Defaults to yesterday. */
+  targetDate?: string;
+  /** Raw nano-dollar threshold below which drift is ignored. Default: 1 cent in raw units. */
+  driftThresholdRaw?: number;
+  /** If drift exceeds this raw amount, flag the account for review. Default: $1.00 in raw units. */
+  flagThresholdRaw?: number;
+  /** Callback invoked for each tenant exceeding the flag threshold. */
+  onFlagForReview?: (tenantId: string, driftRaw: number) => void | Promise<void>;
+}
+
+export interface ReconciliationResult {
+  /** Date reconciled (YYYY-MM-DD). */
+  date: string;
+  /** Number of tenants checked. */
+  tenantsChecked: number;
+  /** Tenants with drift exceeding driftThresholdRaw. */
+  discrepancies: Array<{
+    tenantId: string;
+    /** Total charge from metering (raw nano-dollars). */
+    meteredChargeRaw: number;
+    /** Total debits from ledger for adapter_usage (raw nano-dollars, absolute value). */
+    ledgerDebitRaw: number;
+    /** meteredChargeRaw - ledgerDebitRaw (positive = under-billed, negative = over-billed). */
+    driftRaw: number;
+  }>;
+  /** Tenants flagged for review (drift > flagThresholdRaw). */
+  flagged: string[];
+}
+
+/**
+ * Reconcile metered usage charges against ledger adapter_usage debits
+ * for a single day. Logs warnings for any per-tenant drift exceeding the
+ * threshold and optionally flags accounts for review.
+ */
+export async function runReconciliation(cfg: ReconciliationConfig): Promise<ReconciliationResult> {
+  const yesterday = new Date();
+  yesterday.setDate(yesterday.getDate() - 1);
+  const targetDate = cfg.targetDate ?? yesterday.toISOString().slice(0, 10);
+
+  const driftThresholdRaw = cfg.driftThresholdRaw ?? Credit.fromCents(1).toRaw();
+  const flagThresholdRaw = cfg.flagThresholdRaw ?? Credit.fromCents(100).toRaw();
+
+  // Convert YYYY-MM-DD to epoch ms range [dayStart, dayEnd)
+  const dayStart = new Date(`${targetDate}T00:00:00Z`).getTime();
+  const dayEnd = dayStart + 24 * 60 * 60 * 1000;
+
+  const result: ReconciliationResult = {
+    date: targetDate,
+    tenantsChecked: 0,
+    discrepancies: [],
+    flagged: [],
+  };
+
+  // 1. Sum metered charges per tenant from usage_summaries for the day window.
+  //    Filter out __sentinel__ rows.
+  const meteredRows = await cfg.usageSummaryRepo.getAggregatedChargesByWindow(dayStart, dayEnd);
+
+  // 2. Sum ledger adapter_usage debits per tenant for the same day.
+  //    credit_transactions.created_at is a text column storing Postgres now() values
+  //    (e.g. "2026-02-28 17:00:00+00"). Cast to timestamptz for reliable range comparison.
+  const dayStartIso = new Date(dayStart).toISOString();
+  const dayEndIso = new Date(dayEnd).toISOString();
+
+  const ledgerRows = await cfg.adapterUsageRepo.getAggregatedAdapterUsageDebits(dayStartIso, dayEndIso);
+
+  // 3. Build union of tenant IDs from both sources so ledger-only tenants
+  //    (e.g. debits with no metering summary — negative drift / over-billed) are also checked.
+  const meteredMap = new Map<string, number>();
+  for (const row of meteredRows) {
+    meteredMap.set(row.tenant, row.totalChargeRaw);
+  }
+
+  const ledgerMap = new Map<string, number>();
+  for (const row of ledgerRows) {
+    ledgerMap.set(row.tenantId, row.totalDebitRaw);
+  }
+
+  const allTenants = new Set([...meteredMap.keys(), ...ledgerMap.keys()]);
+
+  if (allTenants.size === 0) {
+    return result;
+  }
+
+  // 4. Compare per-tenant across the union
+  result.tenantsChecked = allTenants.size;
+
+  for (const tenantId of allTenants) {
+    const meteredChargeRaw = meteredMap.get(tenantId) ?? 0;
+    const ledgerDebitRaw = ledgerMap.get(tenantId) ?? 0;
+    const driftRaw = meteredChargeRaw - ledgerDebitRaw;
+    const absDrift = Math.abs(driftRaw);
+
+    if (absDrift > driftThresholdRaw) {
+      result.discrepancies.push({
+        tenantId,
+        meteredChargeRaw,
+        ledgerDebitRaw,
+        driftRaw,
+      });
+
+      logger.warn("Metering/ledger drift detected", {
+        tenantId,
+        meteredCharge: Credit.fromRaw(meteredChargeRaw).toDisplayString(),
+        ledgerDebit: Credit.fromRaw(ledgerDebitRaw).toDisplayString(),
+        drift: Credit.fromRaw(absDrift).toDisplayString(),
+        direction: driftRaw > 0 ? "under-billed" : "over-billed",
+        date: targetDate,
+      });
+
+      if (absDrift > flagThresholdRaw) {
+        result.flagged.push(tenantId);
+        if (cfg.onFlagForReview) {
+          try {
+            await cfg.onFlagForReview(tenantId, driftRaw);
+          } catch (err) {
+            logger.error("onFlagForReview callback failed for tenant", {
+              tenantId,
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return result;
+}

package/src/metering/reconciliation-repository.test.ts

@@ -0,0 +1,196 @@
+import crypto from "node:crypto";
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { createTestDb, seedUsageSummary, truncateAllTables } from "../test/db.js";
+import { Credit } from "../credits/credit.js";
+import { CreditLedger } from "../credits/credit-ledger.js";
+import { DrizzleAdapterUsageRepository, DrizzleUsageSummaryRepository } from "./reconciliation-repository.js";
+
+let pool: PGlite;
+let db: PlatformDb;
+
+beforeAll(async () => {
+  ({ db, pool } = await createTestDb());
+});
+
+afterAll(async () => {
+  await pool.close();
+});
+
+/** Epoch ms for a given date string. */
+function epochMs(dateStr: string): number {
+  return new Date(dateStr).getTime();
+}
+
+describe("DrizzleUsageSummaryRepository", () => {
+  let repo: DrizzleUsageSummaryRepository;
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    repo = new DrizzleUsageSummaryRepository(db);
+  });
+
+  it("returns empty array when no usage summaries exist", async () => {
+    const result = await repo.getAggregatedChargesByWindow(0, Date.now());
+    expect(result).toEqual([]);
+  });
+
+  it("aggregates charges per tenant within [windowStart, windowEnd)", async () => {
+    const dayStart = epochMs("2026-02-15T00:00:00Z");
+    const dayEnd = epochMs("2026-02-16T00:00:00Z");
+
+    // Two summaries for t1 within window
+    await seedUsageSummary(db, {
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      totalCharge: 5000,
+      windowStart: dayStart,
+      windowEnd: dayStart + 3600000,
+    });
+    await seedUsageSummary(db, {
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      totalCharge: 3000,
+      windowStart: dayStart + 3600000,
+      windowEnd: dayStart + 7200000,
+    });
+
+    // One summary for t2 within window
+    await seedUsageSummary(db, {
+      id: crypto.randomUUID(),
+      tenant: "t2",
+      totalCharge: 1000,
+      windowStart: dayStart,
+      windowEnd: dayStart + 3600000,
+    });
+
+    const result = await repo.getAggregatedChargesByWindow(dayStart, dayEnd);
+
+    expect(result).toHaveLength(2);
+    const t1 = result.find((r) => r.tenant === "t1");
+    const t2 = result.find((r) => r.tenant === "t2");
+    expect(t1?.totalChargeRaw).toBe(8000); // 5000 + 3000
+    expect(t2?.totalChargeRaw).toBe(1000);
+  });
+
+  it("excludes __sentinel__ rows", async () => {
+    const dayStart = epochMs("2026-02-15T00:00:00Z");
+
+    await seedUsageSummary(db, {
+      id: crypto.randomUUID(),
+      tenant: "__sentinel__",
+      totalCharge: 999999,
+      windowStart: dayStart,
+      windowEnd: dayStart + 3600000,
+    });
+    await seedUsageSummary(db, {
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      totalCharge: 100,
+      windowStart: dayStart,
+      windowEnd: dayStart + 3600000,
+    });
+
+    const result = await repo.getAggregatedChargesByWindow(dayStart, dayStart + 86400000);
+    expect(result).toHaveLength(1);
+    expect(result[0].tenant).toBe("t1");
+  });
+
+  it("excludes summaries outside the window", async () => {
+    const dayStart = epochMs("2026-02-15T00:00:00Z");
+    const dayEnd = epochMs("2026-02-16T00:00:00Z");
+
+    // Before window
+    await seedUsageSummary(db, {
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      totalCharge: 100,
+      windowStart: epochMs("2026-02-14T00:00:00Z"),
+      windowEnd: epochMs("2026-02-14T01:00:00Z"),
+    });
+
+    // After window
+    await seedUsageSummary(db, {
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      totalCharge: 200,
+      windowStart: dayEnd,
+      windowEnd: dayEnd + 3600000,
+    });
+
+    const result = await repo.getAggregatedChargesByWindow(dayStart, dayEnd);
+    expect(result).toEqual([]);
+  });
+});
+
+describe("DrizzleAdapterUsageRepository", () => {
+  let repo: DrizzleAdapterUsageRepository;
+  let ledger: CreditLedger;
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    repo = new DrizzleAdapterUsageRepository(db);
+    ledger = new CreditLedger(db);
+  });
+
+  it("returns empty array when no adapter_usage debits exist", async () => {
+    const today = new Date().toISOString().slice(0, 10);
+    const startIso = `${today}T00:00:00Z`;
+    const endIso = new Date(new Date(startIso).getTime() + 86400000).toISOString();
+    const result = await repo.getAggregatedAdapterUsageDebits(startIso, endIso);
+    expect(result).toEqual([]);
+  });
+
+  it("aggregates adapter_usage debits per tenant within [startIso, endIso)", async () => {
+    // Fund tenants
+    await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+    await ledger.credit("t2", Credit.fromCents(1000), "purchase");
+
+    await ledger.debit("t1", Credit.fromCents(30), "adapter_usage", "t1-debit-1");
+    await ledger.debit("t1", Credit.fromCents(20), "adapter_usage", "t1-debit-2");
+    await ledger.debit("t2", Credit.fromCents(50), "adapter_usage", "t2-debit-1");
+
+    // Query window covering today
+    const today = new Date().toISOString().slice(0, 10);
+    const startIso = `${today}T00:00:00Z`;
+    const endIso = new Date(new Date(startIso).getTime() + 86400000).toISOString();
+
+    const result = await repo.getAggregatedAdapterUsageDebits(startIso, endIso);
+    expect(result).toHaveLength(2);
+
+    const t1 = result.find((r) => r.tenantId === "t1");
+    const t2 = result.find((r) => r.tenantId === "t2");
+
+    expect(t1?.totalDebitRaw).toBe(Credit.fromCents(50).toRaw()); // 30 + 20
+    expect(t2?.totalDebitRaw).toBe(Credit.fromCents(50).toRaw());
+  });
+
+  it("excludes non-adapter_usage debit types", async () => {
+    await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+    await ledger.debit("t1", Credit.fromCents(30), "adapter_usage", "adapter debit");
+    await ledger.debit("t1", Credit.fromCents(20), "bot_runtime", "runtime debit");
+
+    const today = new Date().toISOString().slice(0, 10);
+    const startIso = `${today}T00:00:00Z`;
+    const endIso = new Date(new Date(startIso).getTime() + 86400000).toISOString();
+
+    const result = await repo.getAggregatedAdapterUsageDebits(startIso, endIso);
+    expect(result).toHaveLength(1);
+    expect(result[0].totalDebitRaw).toBe(Credit.fromCents(30).toRaw());
+  });
+
+  it("excludes credit transactions (positive amounts are not debits)", async () => {
+    await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+    await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "real debit");
+
+    const today = new Date().toISOString().slice(0, 10);
+    const startIso = `${today}T00:00:00Z`;
+    const endIso = new Date(new Date(startIso).getTime() + 86400000).toISOString();
+
+    const result = await repo.getAggregatedAdapterUsageDebits(startIso, endIso);
+    expect(result).toHaveLength(1);
+    // Only the 10-cent adapter_usage debit
+    expect(result[0].totalDebitRaw).toBe(Credit.fromCents(10).toRaw());
+  });
+});

package/src/metering/reconciliation-repository.ts

@@ -0,0 +1,83 @@
+import { and, eq, gte, lt, ne, sql } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { creditTransactions } from "../db/schema/credits.js";
+import { usageSummaries } from "../db/schema/meter-events.js";
+
+// ---------------------------------------------------------------------------
+// IUsageSummaryRepository
+// ---------------------------------------------------------------------------
+
+export interface AggregatedCharge {
+  tenant: string;
+  totalChargeRaw: number;
+}
+
+export interface IUsageSummaryRepository {
+  /** Sum metered charges per tenant for windows overlapping [windowStart, windowEnd). */
+  getAggregatedChargesByWindow(windowStart: number, windowEnd: number): Promise<AggregatedCharge[]>;
+}
+
+export class DrizzleUsageSummaryRepository implements IUsageSummaryRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async getAggregatedChargesByWindow(windowStart: number, windowEnd: number): Promise<AggregatedCharge[]> {
+    const rows = await this.db
+      .select({
+        tenant: usageSummaries.tenant,
+        // raw SQL: Drizzle cannot express COALESCE with SUM aggregation
+        totalCharge: sql<number>`COALESCE(SUM(${usageSummaries.totalCharge}), 0)`,
+      })
+      .from(usageSummaries)
+      .where(
+        and(
+          gte(usageSummaries.windowStart, windowStart),
+          lt(usageSummaries.windowEnd, windowEnd),
+          ne(usageSummaries.tenant, "__sentinel__"),
+        ),
+      )
+      .groupBy(usageSummaries.tenant);
+
+    return rows.map((r) => ({ tenant: r.tenant, totalChargeRaw: Number(r.totalCharge) }));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// IAdapterUsageRepository
+// ---------------------------------------------------------------------------
+
+export interface AggregatedDebit {
+  tenantId: string;
+  totalDebitRaw: number;
+}
+
+export interface IAdapterUsageRepository {
+  /** Sum adapter_usage debits per tenant within [startIso, endIso). */
+  getAggregatedAdapterUsageDebits(startIso: string, endIso: string): Promise<AggregatedDebit[]>;
+}
+
+export class DrizzleAdapterUsageRepository implements IAdapterUsageRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async getAggregatedAdapterUsageDebits(startIso: string, endIso: string): Promise<AggregatedDebit[]> {
+    const rows = await this.db
+      .select({
+        tenantId: creditTransactions.tenantId,
+        // amount_credits stores negative values for debits; ABS gives the raw positive debit amount.
+        // Use the raw column name in sql to bypass the custom creditColumn type serializer.
+        // raw SQL: Drizzle cannot express ABS with COALESCE and SUM
+        totalDebitRaw: sql<number>`COALESCE(SUM(ABS(amount_credits)), 0)`,
+      })
+      .from(creditTransactions)
+      .where(
+        and(
+          eq(creditTransactions.type, "adapter_usage"),
+          // raw SQL: Drizzle cannot express timestamptz cast for text column date comparison
+          sql`${creditTransactions.createdAt}::timestamptz >= ${startIso}::timestamptz`,
+          sql`${creditTransactions.createdAt}::timestamptz < ${endIso}::timestamptz`,
+        ),
+      )
+      .groupBy(creditTransactions.tenantId);
+
+    return rows.map((r) => ({ tenantId: r.tenantId, totalDebitRaw: Number(r.totalDebitRaw) }));
+  }
+}