@wopr-network/platform-core 0.1.0

package/dist/metering/reconciliation-cron.d.ts

@@ -0,0 +1,37 @@
+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 declare function runReconciliation(cfg: ReconciliationConfig): Promise<ReconciliationResult>;

package/dist/metering/reconciliation-cron.js

@@ -0,0 +1,85 @@
+import { logger } from "../config/logger.js";
+import { Credit } from "../credits/credit.js";
+/**
+ * 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) {
+    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 = {
+        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();
+    for (const row of meteredRows) {
+        meteredMap.set(row.tenant, row.totalChargeRaw);
+    }
+    const ledgerMap = new Map();
+    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/dist/metering/reconciliation-cron.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/metering/reconciliation-cron.test.js

@@ -0,0 +1,162 @@
+import crypto from "node:crypto";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+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;
+    let db;
+    let ledger;
+    let usageSummaryRepo;
+    let adapterUsageRepo;
+    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) {
+        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/dist/metering/reconciliation-repository.d.ts

@@ -0,0 +1,27 @@
+import type { PlatformDb } from "../db/index.js";
+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 declare class DrizzleUsageSummaryRepository implements IUsageSummaryRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    getAggregatedChargesByWindow(windowStart: number, windowEnd: number): Promise<AggregatedCharge[]>;
+}
+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 declare class DrizzleAdapterUsageRepository implements IAdapterUsageRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    getAggregatedAdapterUsageDebits(startIso: string, endIso: string): Promise<AggregatedDebit[]>;
+}

package/dist/metering/reconciliation-repository.js

@@ -0,0 +1,43 @@
+import { and, eq, gte, lt, ne, sql } from "drizzle-orm";
+import { creditTransactions } from "../db/schema/credits.js";
+import { usageSummaries } from "../db/schema/meter-events.js";
+export class DrizzleUsageSummaryRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getAggregatedChargesByWindow(windowStart, windowEnd) {
+        const rows = await this.db
+            .select({
+            tenant: usageSummaries.tenant,
+            // raw SQL: Drizzle cannot express COALESCE with SUM aggregation
+            totalCharge: sql `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) }));
+    }
+}
+export class DrizzleAdapterUsageRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getAggregatedAdapterUsageDebits(startIso, endIso) {
+        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 `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) }));
+    }
+}

package/dist/metering/reconciliation-repository.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/metering/reconciliation-repository.test.js

@@ -0,0 +1,160 @@
+import crypto from "node:crypto";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+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;
+let db;
+beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+});
+afterAll(async () => {
+    await pool.close();
+});
+/** Epoch ms for a given date string. */
+function epochMs(dateStr) {
+    return new Date(dateStr).getTime();
+}
+describe("DrizzleUsageSummaryRepository", () => {
+    let repo;
+    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;
+    let ledger;
+    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/dist/metering/types.d.ts

@@ -0,0 +1,88 @@
+import type { Credit } from "../credits/credit.js";
+/** A single metering event emitted by the socket after observing an adapter call. */
+export interface MeterEvent {
+    /** Tenant identifier (who). */
+    tenant: string;
+    /** Upstream cost from the provider (as Credit value object). */
+    cost: Credit;
+    /** What we charge the tenant (cost x multiplier, as Credit value object). */
+    charge: Credit;
+    /** Capability used (embeddings, voice, search, chat, etc.). */
+    capability: string;
+    /** Which adapter fulfilled the request (replicate, deepgram, elevenlabs, etc.). */
+    provider: string;
+    /** Unix epoch ms when the event occurred. */
+    timestamp: number;
+    /** Groups events from one continuous session (voice calls, etc.). */
+    sessionId?: string;
+    /** Session duration in ms (for usage dashboard display). */
+    duration?: number;
+    /** Generic usage measurement — units + unitType (WOP-512). */
+    usage?: {
+        /** Quantity consumed (tokens, seconds, characters, pixels, requests, etc.). */
+        units: number;
+        /** What the units represent. */
+        unitType: string;
+    };
+    /** Pricing tier for billing multiplier lookup (WOP-512). */
+    tier?: "wopr" | "branded" | "byok";
+    /** Provider-specific details (model name, voice ID, resolution, etc.) (WOP-512). */
+    metadata?: Record<string, unknown>;
+}
+/** A meter event row as stored in SQLite. */
+export interface MeterEventRow {
+    id: string;
+    tenant: string;
+    cost: number;
+    charge: number;
+    capability: string;
+    provider: string;
+    timestamp: number;
+    session_id: string | null;
+    duration: number | null;
+    /** WOP-512: Generic usage fields */
+    usage_units: number | null;
+    usage_unit_type: string | null;
+    tier: string | null;
+    metadata: string | null;
+}
+/** Per-tenant usage summary for a given time window. */
+export interface UsageSummary {
+    tenant: string;
+    capability: string;
+    provider: string;
+    /** Number of events aggregated. */
+    event_count: number;
+    /** Sum of upstream costs. */
+    total_cost: number;
+    /** Sum of charges to tenant. */
+    total_charge: number;
+    /** Sum of durations in ms (for session-based capabilities). */
+    total_duration: number;
+    /** Start of the aggregation window (unix epoch ms). */
+    window_start: number;
+    /** End of the aggregation window (unix epoch ms). */
+    window_end: number;
+}
+/** A billing period boundary (e.g., hourly). */
+export interface BillingPeriod {
+    /** Start of the billing period (unix epoch ms, inclusive). */
+    start: number;
+    /** End of the billing period (unix epoch ms, exclusive). */
+    end: number;
+}
+/** A per-tenant, per-billing-period rolled-up summary row as stored in SQLite. */
+export interface BillingPeriodSummary {
+    id: string;
+    tenant: string;
+    capability: string;
+    provider: string;
+    event_count: number;
+    total_cost: number;
+    total_charge: number;
+    total_duration: number;
+    period_start: number;
+    period_end: number;
+    /** Unix epoch ms when this row was last (re-)computed. */
+    updated_at: number;
+}

package/dist/metering/types.js

@@ -0,0 +1 @@
+export {};

package/dist/metering/wal.d.ts

@@ -0,0 +1,49 @@
+import type { MeterEvent } from "./types.js";
+/**
+ * Write-Ahead Log for meter events.
+ *
+ * Provides durable, fail-closed event persistence. Events are written
+ * to disk BEFORE being buffered, ensuring no event is lost even if
+ * the process crashes before flush completes.
+ */
+export declare class MeterWAL {
+    private readonly walPath;
+    private lock;
+    private withLock;
+    constructor(walPath: string);
+    private ensureDir;
+    /**
+     * Append an event to the WAL. appendFileSync is atomic on POSIX (O_APPEND),
+     * so no mutex is needed here. Returns the event with a generated ID.
+     */
+    append(event: MeterEvent & {
+        id?: string;
+    }): MeterEvent & {
+        id: string;
+    };
+    /**
+     * Read all events from the WAL. Returns events in the order they were written.
+     * Skips malformed lines (defensive against incomplete writes).
+     */
+    readAll(): Array<MeterEvent & {
+        id: string;
+    }>;
+    /**
+     * Remove specific event IDs from the WAL. This is done by rewriting
+     * the entire file without the specified events. Mutex-guarded.
+     */
+    remove(eventIds: Set<string>): Promise<void>;
+    private _clear;
+    /**
+     * Clear the entire WAL (typically after successful flush). Mutex-guarded.
+     */
+    clear(): Promise<void>;
+    /**
+     * Check if the WAL is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Get the number of events in the WAL.
+     */
+    count(): number;
+}