@wopr-network/platform-core 0.1.0

package/src/metering/dlq.ts

@@ -0,0 +1,102 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { MeterEvent } from "./types.js";
+
+/**
+ * Dead-Letter Queue for meter events that failed to flush after max retries.
+ *
+ * Events written here are permanently failed and require manual intervention
+ * to recover. This ensures we never silently drop billing events.
+ */
+export class MeterDLQ {
+  private readonly dlqPath: string;
+
+  constructor(dlqPath: string) {
+    this.dlqPath = dlqPath;
+    this.ensureDir();
+  }
+
+  private ensureDir(): void {
+    const dir = dirname(this.dlqPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Append a failed event to the DLQ with failure metadata.
+   */
+  append(event: MeterEvent & { id: string }, error: string, retries: number): void {
+    const dlqEntry = {
+      ...event,
+      dlq_timestamp: Date.now(),
+      dlq_error: error,
+      dlq_retries: retries,
+    };
+
+    const line = `${JSON.stringify(dlqEntry)}\n`;
+    appendFileSync(this.dlqPath, line, { encoding: "utf8", flag: "a" });
+  }
+
+  /**
+   * Read all events from the DLQ for manual recovery.
+   */
+  readAll(): Array<
+    MeterEvent & {
+      id: string;
+      dlq_timestamp: number;
+      dlq_error: string;
+      dlq_retries: number;
+    }
+  > {
+    if (!existsSync(this.dlqPath)) {
+      return [];
+    }
+
+    const content = readFileSync(this.dlqPath, "utf8");
+    if (!content.trim()) {
+      return [];
+    }
+
+    const entries: Array<
+      MeterEvent & {
+        id: string;
+        dlq_timestamp: number;
+        dlq_error: string;
+        dlq_retries: number;
+      }
+    > = [];
+    for (const line of content.trim().split("\n")) {
+      try {
+        entries.push(JSON.parse(line));
+      } catch {
+        // Skip malformed lines (e.g., from incomplete writes during error conditions).
+      }
+    }
+    return entries;
+  }
+
+  /**
+   * Get the number of events in the DLQ.
+   */
+  count(): number {
+    let content: string;
+    try {
+      content = readFileSync(this.dlqPath, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return 0;
+      }
+      throw err;
+    }
+    if (!content) {
+      return 0;
+    }
+    let n = 0;
+    for (let i = 0; i < content.length; i++) {
+      if (content.charCodeAt(i) === 10) n++;
+    }
+    if (content.length > 0 && content.charCodeAt(content.length - 1) !== 10) n++;
+    return n;
+  }
+}

package/src/metering/drizzle-usage-summary-repository.ts

@@ -0,0 +1,167 @@
+import { and, count, desc, eq, gte, lt, lte, max, min, sql, sum } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { meterEvents, usageSummaries } from "../db/schema/meter-events.js";
+import type { UsageSummary } from "./types.js";
+
+export interface AggregatedWindowRow {
+  tenant: string;
+  capability: string;
+  provider: string;
+  eventCount: number;
+  totalCost: number;
+  totalCharge: number;
+  totalDuration: number;
+}
+
+export interface UsageSummaryInsert {
+  id: string;
+  tenant: string;
+  capability: string;
+  provider: string;
+  eventCount: number;
+  totalCost: number;
+  totalCharge: number;
+  totalDuration: number;
+  windowStart: number;
+  windowEnd: number;
+}
+
+export interface IUsageSummaryRepository {
+  /** Get the maximum windowEnd across all usage summaries. Returns 0 if none. */
+  getLastWindowEnd(): Promise<number>;
+
+  /** Get the earliest meter event timestamp before the given time. Returns null if none. */
+  getEarliestEventTimestamp(before: number): Promise<number | null>;
+
+  /** Get aggregated event groups for a time window [start, end). */
+  getAggregatedEvents(windowStart: number, windowEnd: number): Promise<AggregatedWindowRow[]>;
+
+  /** Insert a single usage summary row. */
+  insertSummary(values: UsageSummaryInsert): Promise<void>;
+
+  /** Insert multiple usage summary rows in a transaction. */
+  insertSummariesBatch(rows: UsageSummaryInsert[]): Promise<void>;
+
+  /** Query usage summaries for a tenant within a time range. */
+  querySummaries(tenant: string, opts?: { since?: number; until?: number; limit?: number }): Promise<UsageSummary[]>;
+
+  /** Get a tenant's total usage since a given time. */
+  getTenantTotal(
+    tenant: string,
+    since: number,
+  ): Promise<{ totalCost: number; totalCharge: number; eventCount: number }>;
+}
+
+export class DrizzleUsageSummaryRepository implements IUsageSummaryRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async getLastWindowEnd(): Promise<number> {
+    const row = (await this.db.select({ lastEnd: max(usageSummaries.windowEnd) }).from(usageSummaries))[0];
+    return row?.lastEnd ?? 0;
+  }
+
+  async getEarliestEventTimestamp(before: number): Promise<number | null> {
+    const row = (
+      await this.db
+        .select({ ts: min(meterEvents.timestamp) })
+        .from(meterEvents)
+        .where(lt(meterEvents.timestamp, before))
+    )[0];
+    return row?.ts ?? null;
+  }
+
+  async getAggregatedEvents(windowStart: number, windowEnd: number): Promise<AggregatedWindowRow[]> {
+    const rows = await this.db
+      .select({
+        tenant: meterEvents.tenant,
+        capability: meterEvents.capability,
+        provider: meterEvents.provider,
+        eventCount: count(),
+        totalCost: sum(meterEvents.cost),
+        totalCharge: sum(meterEvents.charge),
+        totalDuration: sql<number>`COALESCE(SUM(${meterEvents.duration}), 0)`,
+      })
+      .from(meterEvents)
+      .where(and(gte(meterEvents.timestamp, windowStart), lt(meterEvents.timestamp, windowEnd)))
+      .groupBy(meterEvents.tenant, meterEvents.capability, meterEvents.provider);
+
+    return rows.map((r) => ({
+      tenant: r.tenant,
+      capability: r.capability,
+      provider: r.provider,
+      eventCount: r.eventCount,
+      totalCost: Number(r.totalCost),
+      totalCharge: Number(r.totalCharge),
+      totalDuration: Number(r.totalDuration),
+    }));
+  }
+
+  async insertSummary(values: UsageSummaryInsert): Promise<void> {
+    await this.db.insert(usageSummaries).values(values);
+  }
+
+  async insertSummariesBatch(rows: UsageSummaryInsert[]): Promise<void> {
+    if (rows.length === 0) return;
+    const CHUNK_SIZE = 1000; // safe limit: each row has ~10 columns, 1000*10 < 65535 param limit
+    await this.db.transaction(async (tx) => {
+      for (let i = 0; i < rows.length; i += CHUNK_SIZE) {
+        await tx.insert(usageSummaries).values(rows.slice(i, i + CHUNK_SIZE));
+      }
+    });
+  }
+
+  async querySummaries(
+    tenant: string,
+    opts: { since?: number; until?: number; limit?: number } = {},
+  ): Promise<UsageSummary[]> {
+    const conditions = [eq(usageSummaries.tenant, tenant)];
+    if (opts.since != null) {
+      conditions.push(gte(usageSummaries.windowStart, opts.since));
+    }
+    if (opts.until != null) {
+      conditions.push(lte(usageSummaries.windowEnd, opts.until));
+    }
+    const limit = Math.min(Math.max(1, opts.limit ?? 100), 1000);
+
+    return this.db
+      .select({
+        tenant: usageSummaries.tenant,
+        capability: usageSummaries.capability,
+        provider: usageSummaries.provider,
+        event_count: usageSummaries.eventCount,
+        total_cost: usageSummaries.totalCost,
+        total_charge: usageSummaries.totalCharge,
+        total_duration: usageSummaries.totalDuration,
+        window_start: usageSummaries.windowStart,
+        window_end: usageSummaries.windowEnd,
+      })
+      .from(usageSummaries)
+      .where(and(...conditions))
+      .orderBy(desc(usageSummaries.windowStart))
+      .limit(limit);
+  }
+
+  async getTenantTotal(
+    tenant: string,
+    since: number,
+  ): Promise<{ totalCost: number; totalCharge: number; eventCount: number }> {
+    const row = (
+      await this.db
+        .select({
+          totalCost: sql<number>`COALESCE(SUM(${usageSummaries.totalCost}), 0)`,
+          totalCharge: sql<number>`COALESCE(SUM(${usageSummaries.totalCharge}), 0)`,
+          eventCount: sql<number>`COALESCE(SUM(${usageSummaries.eventCount}), 0)`,
+        })
+        .from(usageSummaries)
+        .where(and(eq(usageSummaries.tenant, tenant), gte(usageSummaries.windowStart, since)))
+    )[0];
+
+    return {
+      totalCost: Number(row?.totalCost ?? 0),
+      totalCharge: Number(row?.totalCharge ?? 0),
+      eventCount: Number(row?.eventCount ?? 0),
+    };
+  }
+}
+
+export { DrizzleUsageSummaryRepository as UsageSummaryRepository };

package/src/metering/emitter.test.ts

@@ -0,0 +1,202 @@
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { PGlite } from "@electric-sql/pglite";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { Credit } from "../credits/credit.js";
+import { MeterDLQ } from "./dlq.js";
+import { DrizzleMeterEmitter } from "./emitter.js";
+import { DrizzleMeterEventRepository } from "./meter-event-repository.js";
+import type { MeterEvent } from "./types.js";
+
+function makeTempDir(): string {
+  const dir = join(tmpdir(), `emitter-test-${crypto.randomUUID()}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function makeEvent(overrides: Partial<MeterEvent> = {}): MeterEvent {
+  return {
+    tenant: "t1",
+    cost: Credit.fromCents(1),
+    charge: Credit.fromCents(2),
+    capability: "llm",
+    provider: "openai",
+    timestamp: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("DrizzleMeterEmitter — happy path", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let emitter: DrizzleMeterEmitter;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+    await rollbackTestTransaction(pool);
+    tempDir = makeTempDir();
+    const repo = new DrizzleMeterEventRepository(db);
+    emitter = new DrizzleMeterEmitter(repo, {
+      flushIntervalMs: 60_000,
+      batchSize: 100,
+      walPath: join(tempDir, "wal.jsonl"),
+      dlqPath: join(tempDir, "dlq.jsonl"),
+      maxRetries: 3,
+    });
+    await emitter.ready;
+  });
+
+  afterEach(async () => {
+    // Flush remaining events before close() to drain the buffer synchronously
+    await emitter.flush();
+    emitter.close();
+    await endTestTransaction(pool);
+    await pool.close();
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  });
+
+  it("writes a meter event to the database after flush", async () => {
+    emitter.emit(makeEvent({ tenant: "t1", capability: "voice" }));
+    expect(emitter.pending).toBe(1);
+
+    const flushed = await emitter.flush();
+    expect(flushed).toBe(1);
+    expect(emitter.pending).toBe(0);
+
+    const rows = await emitter.queryEvents("t1");
+    expect(rows).toHaveLength(1);
+    expect(rows[0].tenant).toBe("t1");
+    expect(rows[0].capability).toBe("voice");
+    expect(rows[0].cost).toBe(Credit.fromCents(1).toRaw());
+    expect(rows[0].charge).toBe(Credit.fromCents(2).toRaw());
+  });
+
+  it("persists multiple events in one flush", async () => {
+    emitter.emit(makeEvent({ tenant: "t1" }));
+    emitter.emit(makeEvent({ tenant: "t1" }));
+    emitter.emit(makeEvent({ tenant: "t2" }));
+
+    const flushed = await emitter.flush();
+    expect(flushed).toBe(3);
+
+    const t1Rows = await emitter.queryEvents("t1");
+    expect(t1Rows).toHaveLength(2);
+
+    const t2Rows = await emitter.queryEvents("t2");
+    expect(t2Rows).toHaveLength(1);
+  });
+
+  it("flush returns 0 when buffer is empty", async () => {
+    expect(await emitter.flush()).toBe(0);
+  });
+
+  it("silently drops events emitted after close", async () => {
+    emitter.close();
+    emitter.emit(makeEvent());
+    expect(emitter.pending).toBe(0);
+  });
+
+  it("persists sessionId, duration, usage, tier, and metadata", async () => {
+    emitter.emit(
+      makeEvent({
+        sessionId: "sess-1",
+        duration: 5000,
+        usage: { units: 100, unitType: "tokens" },
+        tier: "wopr",
+        metadata: { model: "gpt-4" },
+      }),
+    );
+    await emitter.flush();
+
+    const rows = await emitter.queryEvents("t1");
+    expect(rows[0].session_id).toBe("sess-1");
+    expect(rows[0].duration).toBe(5000);
+    expect(rows[0].usage_units).toBe(100);
+    expect(rows[0].usage_unit_type).toBe("tokens");
+    expect(rows[0].tier).toBe("wopr");
+    expect(JSON.parse(rows[0].metadata as string)).toEqual({ model: "gpt-4" });
+  });
+});
+
+describe("DrizzleMeterEmitter — DLQ failure paths", () => {
+  it("moves events to DLQ after maxRetries failures", async () => {
+    const { db: failDb, pool: failPool } = await createTestDb();
+    const failTempDir = makeTempDir();
+    const dlqPath = join(failTempDir, "dlq.jsonl");
+
+    const failRepo = new DrizzleMeterEventRepository(failDb);
+    const em = new DrizzleMeterEmitter(failRepo, {
+      flushIntervalMs: 60_000,
+      walPath: join(failTempDir, "wal.jsonl"),
+      dlqPath,
+      maxRetries: 1,
+    });
+    await em.ready;
+
+    em.emit(makeEvent());
+
+    // Drop the table so flush fails
+    await failPool.query("DROP TABLE meter_events CASCADE");
+    await em.flush();
+
+    // maxRetries=1: first failure hits the limit => DLQ
+    const dlq = new MeterDLQ(dlqPath);
+    expect(dlq.count()).toBe(1);
+    expect(em.pending).toBe(0);
+
+    em.close();
+    await failPool.close();
+    try {
+      rmSync(failTempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  it("retries failed events before moving to DLQ", async () => {
+    const { db: failDb, pool: failPool } = await createTestDb();
+    const failTempDir = makeTempDir();
+    const dlqPath = join(failTempDir, "dlq.jsonl");
+
+    const failRepo2 = new DrizzleMeterEventRepository(failDb);
+    const em = new DrizzleMeterEmitter(failRepo2, {
+      flushIntervalMs: 60_000,
+      walPath: join(failTempDir, "wal.jsonl"),
+      dlqPath,
+      maxRetries: 2,
+    });
+    await em.ready;
+
+    em.emit(makeEvent());
+
+    // First flush fails
+    await failPool.query("DROP TABLE meter_events CASCADE");
+    await em.flush();
+
+    // After first failure (maxRetries=2): still in buffer for retry
+    expect(em.pending).toBe(1);
+
+    // DLQ should be empty — not yet reached maxRetries
+    const dlq = new MeterDLQ(dlqPath);
+    expect(dlq.count()).toBe(0);
+
+    // Clear the buffer before close to avoid a DLQ write race during cleanup
+    (em as unknown as { buffer: unknown[] }).buffer = [];
+    em.close();
+    await failPool.close();
+    try {
+      rmSync(failTempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+});

package/src/metering/emitter.ts

@@ -0,0 +1,227 @@
+import { config } from "../config/index.js";
+import { Credit } from "../credits/credit.js";
+import { MeterDLQ } from "./dlq.js";
+import type { IMeterEventRepository } from "./meter-event-repository.js";
+import type { MeterEvent, MeterEventRow } from "./types.js";
+import { MeterWAL } from "./wal.js";
+
+const DEFAULT_WAL_PATH = process.env.METER_WAL_PATH ?? "./data/meter-wal.jsonl";
+const DEFAULT_DLQ_PATH = process.env.METER_DLQ_PATH ?? "./data/meter-dlq.jsonl";
+const DEFAULT_MAX_RETRIES = config.billing.meterMaxRetries;
+
+export interface IMeterEmitter {
+  emit(event: MeterEvent): void;
+  flush(): Promise<number>;
+  readonly pending: number;
+  close(): void;
+  queryEvents(tenant: string, limit?: number): Promise<MeterEventRow[]>;
+}
+
+/**
+ * Fire-and-forget meter event emitter with fail-closed durability.
+ *
+ * Buffers events in memory and flushes them to the database in batches,
+ * ensuring zero latency impact on the observed API calls.
+ *
+ * FAIL-CLOSED POLICY:
+ * - Events are written to WAL (write-ahead log) on disk BEFORE buffering
+ * - If flush fails, events are retried up to MAX_RETRIES times
+ * - After MAX_RETRIES, events move to DLQ (dead-letter queue) for manual recovery
+ * - On startup, unflushed WAL events are replayed idempotently
+ */
+export class DrizzleMeterEmitter implements IMeterEmitter {
+  private buffer: Array<MeterEvent & { id: string }> = [];
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private readonly flushIntervalMs: number;
+  private readonly batchSize: number;
+  private readonly maxRetries: number;
+  private closed = false;
+  private readonly wal: MeterWAL;
+  private readonly dlq: MeterDLQ;
+  private readonly retryCount = new Map<string, number>();
+  /** Resolves when the initial WAL replay has completed. */
+  readonly ready: Promise<void>;
+
+  constructor(
+    private readonly repo: IMeterEventRepository,
+    opts: {
+      flushIntervalMs?: number;
+      batchSize?: number;
+      walPath?: string;
+      dlqPath?: string;
+      maxRetries?: number;
+    } = {},
+  ) {
+    this.flushIntervalMs = opts.flushIntervalMs ?? 1000;
+    this.batchSize = opts.batchSize ?? 100;
+    this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+
+    this.wal = new MeterWAL(opts.walPath ?? DEFAULT_WAL_PATH);
+    this.dlq = new MeterDLQ(opts.dlqPath ?? DEFAULT_DLQ_PATH);
+
+    // Replay any unflushed WAL events from a previous session.
+    this.ready = this.replayWAL();
+
+    this.flushTimer = setInterval(() => this.flush(), this.flushIntervalMs);
+    // Do not keep the process alive just for metering flushes.
+    if (this.flushTimer.unref) {
+      this.flushTimer.unref();
+    }
+  }
+
+  /**
+   * Replay unflushed events from the WAL on startup.
+   * Idempotent: skips events already in the database.
+   * Returns a promise that resolves when the replay is complete.
+   */
+  private async replayWAL(): Promise<void> {
+    const walEvents = this.wal.readAll();
+    if (walEvents.length === 0) return;
+
+    await this.replayWALAsync(walEvents);
+  }
+
+  /**
+   * Reconstitute Credit fields on WAL events after JSON deserialization.
+   * Credit.toJSON() serializes to a raw number, so after JSON.parse the
+   * cost/charge fields are plain numbers — convert them back to Credit.
+   */
+  private reconstituteCreditFields(events: Array<MeterEvent & { id: string }>): Array<MeterEvent & { id: string }> {
+    return events.map((e) => ({
+      ...e,
+      cost: e.cost instanceof Credit ? e.cost : Credit.fromRaw(e.cost as unknown as number),
+      charge: e.charge instanceof Credit ? e.charge : Credit.fromRaw(e.charge as unknown as number),
+    }));
+  }
+
+  private async replayWALAsync(walEvents: Array<MeterEvent & { id: string }>): Promise<void> {
+    // Reconstitute Credit objects from raw numbers after JSON deserialization.
+    walEvents = this.reconstituteCreditFields(walEvents);
+    // Check which events are already in the database.
+    const existingIds = new Set<string>();
+    for (const e of walEvents) {
+      if (await this.repo.existsById(e.id)) {
+        existingIds.add(e.id);
+      }
+    }
+
+    // Replay only new events.
+    const toReplay = walEvents.filter((e) => !existingIds.has(e.id));
+    if (toReplay.length > 0) {
+      this.buffer.push(...toReplay);
+      const flushed = await this.flush();
+      if (flushed === 0) {
+        // Flush failed -- events remain in WAL and buffer for retry.
+        return;
+      }
+    }
+
+    // Remove already-persisted events from WAL (idempotent cleanup).
+    if (existingIds.size > 0) {
+      await this.wal.remove(existingIds);
+    }
+  }
+
+  /** Emit a meter event. Non-blocking -- buffers in memory after WAL write. */
+  emit(event: MeterEvent): void {
+    if (this.closed) return;
+
+    // FAIL-CLOSED: Write to WAL first, then buffer.
+    // append() is synchronous (appendFileSync), so the WAL write completes
+    // before buffer.push() — crash safety is guaranteed.
+    const eventWithId = this.wal.append(event);
+    this.buffer.push(eventWithId);
+
+    if (this.buffer.length >= this.batchSize) {
+      void this.flush();
+    }
+  }
+
+  /** Flush buffered events to the database with retry and DLQ logic. */
+  async flush(): Promise<number> {
+    if (this.buffer.length === 0) return 0;
+    const batch = this.buffer.splice(0);
+
+    try {
+      await this.repo.insertBatch(
+        batch.map((e) => ({
+          id: e.id,
+          tenant: e.tenant,
+          cost: e.cost.toRaw(),
+          charge: e.charge.toRaw(),
+          capability: e.capability,
+          provider: e.provider,
+          timestamp: e.timestamp,
+          sessionId: e.sessionId ?? null,
+          duration: e.duration ?? null,
+          usageUnits: e.usage?.units ?? null,
+          usageUnitType: e.usage?.unitType ?? null,
+          tier: e.tier ?? null,
+          metadata: e.metadata ? JSON.stringify(e.metadata) : null,
+        })),
+      );
+
+      // Success: remove from WAL and reset retry counters.
+      const flushedIds = new Set(batch.map((e) => e.id));
+      await this.wal.remove(flushedIds);
+      for (const id of flushedIds) {
+        this.retryCount.delete(id);
+      }
+
+      return batch.length;
+    } catch (error) {
+      // Failure: track retries and move to DLQ if max exceeded.
+      const toRetry: Array<MeterEvent & { id: string }> = [];
+      const toDLQ: Array<MeterEvent & { id: string }> = [];
+
+      for (const event of batch) {
+        const retries = (this.retryCount.get(event.id) ?? 0) + 1;
+        this.retryCount.set(event.id, retries);
+
+        if (retries >= this.maxRetries) {
+          // Max retries exceeded -- move to DLQ.
+          toDLQ.push(event);
+          this.dlq.append(event, String(error), retries);
+          this.retryCount.delete(event.id);
+        } else {
+          // Retry on next flush.
+          toRetry.push(event);
+        }
+      }
+
+      // Remove DLQ events from WAL (they're now in DLQ).
+      if (toDLQ.length > 0) {
+        const dlqIds = new Set(toDLQ.map((e) => e.id));
+        await this.wal.remove(dlqIds);
+      }
+
+      // Re-add retry events to buffer.
+      this.buffer.unshift(...toRetry);
+
+      return 0;
+    }
+  }
+
+  /** Number of events currently buffered. */
+  get pending(): number {
+    return this.buffer.length;
+  }
+
+  /** Stop the flush timer and flush remaining events. */
+  close(): void {
+    this.closed = true;
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    void this.flush();
+  }
+
+  /** Query persisted events (for testing / diagnostics). */
+  async queryEvents(tenant: string, limit = 50): Promise<MeterEventRow[]> {
+    return this.repo.queryByTenant(tenant, limit);
+  }
+}
+
+// Backward-compat alias.
+export { DrizzleMeterEmitter as MeterEmitter };