@wopr-network/platform-core 1.0.10 → 1.1.0

package/dist/monetization/arbitrage/router.test.js

@@ -0,0 +1,332 @@
+import { Credit } from "@wopr-network/platform-core/credits";
+import { describe, expect, it, vi } from "vitest";
+import { ArbitrageRouter } from "./router.js";
+import { NoProviderAvailableError } from "./types.js";
+// ── Helpers ──
+function makeEntry(overrides = {}) {
+    return {
+        capability: "tts",
+        adapter: "elevenlabs",
+        tier: "hosted",
+        providerCost: 0.15,
+        costUnit: "1K_chars",
+        healthy: true,
+        priority: 0,
+        latencyClass: "normal",
+        enabled: true,
+        ...overrides,
+    };
+}
+function makeRegistry(providers) {
+    const healthOverrides = new Map();
+    return {
+        getProviders: async (capability) => providers
+            .filter((p) => p.capability === capability)
+            .map((p) => {
+            const healthy = healthOverrides.has(p.adapter) ? (healthOverrides.get(p.adapter) ?? p.healthy) : p.healthy;
+            return { ...p, healthy };
+        }),
+        markUnhealthy: (adapter) => {
+            healthOverrides.set(adapter, false);
+        },
+        markHealthy: (adapter) => {
+            healthOverrides.delete(adapter);
+        },
+        refresh: vi.fn(),
+    };
+}
+function makeAdapter(name, capabilities, result) {
+    return {
+        name,
+        capabilities,
+        synthesizeSpeech: vi.fn().mockImplementation(() => {
+            if (result instanceof Error)
+                return Promise.reject(result);
+            return Promise.resolve(result);
+        }),
+    };
+}
+const fakeTTSResult = {
+    result: { audioUrl: "https://example.com/audio.mp3", durationSeconds: 1.5, format: "mp3", characterCount: 100 },
+    cost: Credit.fromDollars(0.015),
+};
+// ── Tests ──
+describe("ArbitrageRouter", () => {
+    describe("selectProvider", () => {
+        it("selects GPU provider when available", async () => {
+            const gpu = makeEntry({ adapter: "chatterbox-tts", tier: "gpu", providerCost: 0.02 });
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([gpu, hosted]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            const decision = await router.selectProvider("tts");
+            expect(decision.provider.adapter).toBe("chatterbox-tts");
+            expect(decision.reason).toBe("gpu-cheapest");
+        });
+        it("selects hosted provider when no GPU available", async () => {
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.15 });
+            const registry = makeRegistry([hosted]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            const decision = await router.selectProvider("tts");
+            expect(decision.provider.adapter).toBe("elevenlabs");
+            expect(decision.reason).toBe("hosted-cheapest");
+        });
+        it("selects cheapest hosted provider (arbitrage)", async () => {
+            const expensive = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.15 });
+            const cheap = makeEntry({ adapter: "openai-tts", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([expensive, cheap]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            const decision = await router.selectProvider("tts");
+            expect(decision.provider.adapter).toBe("openai-tts");
+        });
+        it("uses priority as tiebreaker when costs are equal", async () => {
+            const p1 = makeEntry({ adapter: "a", tier: "hosted", providerCost: 0.12, priority: 2 });
+            const p2 = makeEntry({ adapter: "b", tier: "hosted", providerCost: 0.12, priority: 1 });
+            const registry = makeRegistry([p1, p2]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            const decision = await router.selectProvider("tts");
+            expect(decision.provider.adapter).toBe("b"); // lower priority wins
+        });
+        it("throws NoProviderAvailableError when no providers registered", async () => {
+            const registry = makeRegistry([]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            await expect(router.selectProvider("tts")).rejects.toThrow(NoProviderAvailableError);
+        });
+        it("skips disabled providers", async () => {
+            const disabled = makeEntry({ adapter: "disabled-provider", tier: "gpu", enabled: false });
+            const registry = makeRegistry([disabled]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            await expect(router.selectProvider("tts")).rejects.toThrow(NoProviderAvailableError);
+        });
+        it("skips unhealthy providers", async () => {
+            const unhealthy = makeEntry({ adapter: "sick-provider", tier: "gpu", healthy: false });
+            const registry = makeRegistry([unhealthy]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            await expect(router.selectProvider("tts")).rejects.toThrow(NoProviderAvailableError);
+        });
+    });
+    describe("route", () => {
+        it("routes to GPU provider first", async () => {
+            const gpu = makeEntry({ adapter: "chatterbox-tts", tier: "gpu", providerCost: 0.02 });
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([gpu, hosted]);
+            const gpuAdapter = makeAdapter("chatterbox-tts", ["tts"], fakeTTSResult);
+            const hostedAdapter = makeAdapter("elevenlabs", ["tts"], fakeTTSResult);
+            const adapters = new Map([
+                ["chatterbox-tts", gpuAdapter],
+                ["elevenlabs", hostedAdapter],
+            ]);
+            const router = new ArbitrageRouter({ registry, adapters });
+            await router.route({ capability: "tts", tenantId: "t1", input: { text: "hello" } });
+            expect(gpuAdapter.synthesizeSpeech).toHaveBeenCalledOnce();
+            expect(hostedAdapter.synthesizeSpeech).not.toHaveBeenCalled();
+        });
+        it("falls through to hosted when GPU unavailable", async () => {
+            const gpu = makeEntry({ adapter: "chatterbox-tts", tier: "gpu", providerCost: 0.02, healthy: false });
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([gpu, hosted]);
+            const hostedAdapter = makeAdapter("elevenlabs", ["tts"], fakeTTSResult);
+            const adapters = new Map([["elevenlabs", hostedAdapter]]);
+            const router = new ArbitrageRouter({ registry, adapters });
+            await router.route({ capability: "tts", tenantId: "t1", input: { text: "hello" } });
+            expect(hostedAdapter.synthesizeSpeech).toHaveBeenCalledOnce();
+        });
+        it("failover on 5xx — retries with next provider and marks first unhealthy", async () => {
+            const gpu = makeEntry({ adapter: "chatterbox-tts", tier: "gpu", providerCost: 0.02 });
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([gpu, hosted]);
+            const serverError = Object.assign(new Error("Server error"), { httpStatus: 500 });
+            const gpuAdapter = makeAdapter("chatterbox-tts", ["tts"], serverError);
+            const hostedAdapter = makeAdapter("elevenlabs", ["tts"], fakeTTSResult);
+            const adapters = new Map([
+                ["chatterbox-tts", gpuAdapter],
+                ["elevenlabs", hostedAdapter],
+            ]);
+            const router = new ArbitrageRouter({ registry, adapters });
+            const result = await router.route({ capability: "tts", tenantId: "t1", input: { text: "hello" } });
+            expect(gpuAdapter.synthesizeSpeech).toHaveBeenCalledOnce();
+            expect(hostedAdapter.synthesizeSpeech).toHaveBeenCalledOnce();
+            expect(result.cost).toBe(fakeTTSResult.cost);
+        });
+        it("does NOT failover on 4xx — rethrows error", async () => {
+            // openai-tts at 0.10 is cheaper, so it gets selected first
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const hosted2 = makeEntry({ adapter: "openai-tts", tier: "hosted", providerCost: 0.1 });
+            const registry = makeRegistry([hosted, hosted2]);
+            const clientError = Object.assign(new Error("Bad request"), { httpStatus: 400 });
+            // openai-tts (cheaper) returns 4xx; elevenlabs should NOT be tried
+            const adapterElevenlabs = makeAdapter("elevenlabs", ["tts"], fakeTTSResult);
+            const adapterOpenaiTts = makeAdapter("openai-tts", ["tts"], clientError);
+            const adapters = new Map([
+                ["elevenlabs", adapterElevenlabs],
+                ["openai-tts", adapterOpenaiTts],
+            ]);
+            const router = new ArbitrageRouter({ registry, adapters });
+            await expect(router.route({ capability: "tts", tenantId: "t1", input: { text: "hello" } })).rejects.toMatchObject({ httpStatus: 400 });
+            // 4xx should NOT failover — elevenlabs should not be tried
+            expect(adapterElevenlabs.synthesizeSpeech).not.toHaveBeenCalled();
+        });
+        it("throws NoProviderAvailableError when all providers are down", async () => {
+            const p = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.15 });
+            const registry = makeRegistry([p]);
+            // No adapter registered
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            await expect(router.route({ capability: "tts", tenantId: "t1", input: { text: "hello" } })).rejects.toBeInstanceOf(NoProviderAvailableError);
+        });
+        it("tracks margin via onMarginRecord callback", async () => {
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([hosted]);
+            const adapter = makeAdapter("elevenlabs", ["tts"], { ...fakeTTSResult, cost: Credit.fromDollars(0.012) });
+            const adapters = new Map([["elevenlabs", adapter]]);
+            const marginRecords = [];
+            const router = new ArbitrageRouter({
+                registry,
+                adapters,
+                onMarginRecord: (r) => marginRecords.push(r),
+            });
+            await router.route({
+                capability: "tts",
+                tenantId: "tenant-1",
+                input: { text: "hello" },
+                sellPrice: Credit.fromDollars(0.02),
+            });
+            expect(marginRecords).toHaveLength(1);
+            const record = marginRecords[0];
+            expect(record.tenantId).toBe("tenant-1");
+            expect(record.capability).toBe("tts");
+            expect(record.adapter).toBe("elevenlabs");
+            expect(record.tier).toBe("hosted");
+            expect(record.providerCost.toDollars()).toBe(0.012);
+            expect(record.sellPrice.toDollars()).toBe(0.02);
+            expect(record.margin.toDollars()).toBeCloseTo(0.008, 5);
+            expect(record.marginPct).toBeCloseTo(40, 0);
+            expect(record.timestamp).toBeGreaterThan(0);
+        });
+        it("does not call onMarginRecord when sellPrice is not provided", async () => {
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([hosted]);
+            const adapter = makeAdapter("elevenlabs", ["tts"], fakeTTSResult);
+            const adapters = new Map([["elevenlabs", adapter]]);
+            const onMarginRecord = vi.fn();
+            const router = new ArbitrageRouter({ registry, adapters, onMarginRecord });
+            await router.route({ capability: "tts", tenantId: "t1", input: {} });
+            expect(onMarginRecord).not.toHaveBeenCalled();
+        });
+        it("marks provider healthy on successful response", async () => {
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([hosted]);
+            const markHealthySpy = vi.spyOn(registry, "markHealthy");
+            const adapter = makeAdapter("elevenlabs", ["tts"], fakeTTSResult);
+            const adapters = new Map([["elevenlabs", adapter]]);
+            const router = new ArbitrageRouter({ registry, adapters });
+            await router.route({ capability: "tts", tenantId: "t1", input: {} });
+            expect(markHealthySpy).toHaveBeenCalledWith("elevenlabs");
+        });
+    });
+    describe("registerAdapter", () => {
+        it("registers an adapter in the internal map", async () => {
+            const hosted = makeEntry({ adapter: "elevenlabs", tier: "hosted", providerCost: 0.12 });
+            const registry = makeRegistry([hosted]);
+            const adapters = new Map();
+            const router = new ArbitrageRouter({ registry, adapters });
+            const adapter = makeAdapter("elevenlabs", ["tts"], fakeTTSResult);
+            router.registerAdapter(adapter);
+            const result = await router.route({ capability: "tts", tenantId: "t1", input: {} });
+            expect(result.cost).toBe(fakeTTSResult.cost);
+        });
+    });
+    describe("preferLowLatency", () => {
+        it("prefers fast provider over cheaper slow provider when preferLowLatency is true", async () => {
+            const slow = makeEntry({ adapter: "slow-cheap", tier: "hosted", providerCost: 0.05, latencyClass: "slow" });
+            const fast = makeEntry({ adapter: "fast-expensive", tier: "hosted", providerCost: 0.15, latencyClass: "fast" });
+            const registry = makeRegistry([slow, fast]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map(), preferLowLatency: true });
+            const decision = await router.selectProvider("tts");
+            expect(decision.provider.adapter).toBe("fast-expensive");
+        });
+        it("uses cost-first ordering when preferLowLatency is false (default)", async () => {
+            const slow = makeEntry({ adapter: "slow-cheap", tier: "hosted", providerCost: 0.05, latencyClass: "slow" });
+            const fast = makeEntry({ adapter: "fast-expensive", tier: "hosted", providerCost: 0.15, latencyClass: "fast" });
+            const registry = makeRegistry([slow, fast]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map() });
+            const decision = await router.selectProvider("tts");
+            expect(decision.provider.adapter).toBe("slow-cheap");
+        });
+        it("uses cost then priority as tiebreaker when preferLowLatency is true and latency classes are equal", async () => {
+            // Both are "normal" latency — latencyDiff is 0, so falls through to cost/priority tiebreaker
+            const p1 = makeEntry({
+                adapter: "normal-priority2",
+                tier: "hosted",
+                providerCost: 0.12,
+                priority: 2,
+                latencyClass: "normal",
+            });
+            const p2 = makeEntry({
+                adapter: "normal-priority1",
+                tier: "hosted",
+                providerCost: 0.12,
+                priority: 1,
+                latencyClass: "normal",
+            });
+            const registry = makeRegistry([p1, p2]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map(), preferLowLatency: true });
+            const decision = await router.selectProvider("tts");
+            // Same cost and same latency class — priority tiebreaker picks lower priority number
+            expect(decision.provider.adapter).toBe("normal-priority1");
+        });
+        it("uses cost as tiebreaker when preferLowLatency is true and latency classes are equal but costs differ", async () => {
+            const expensive = makeEntry({
+                adapter: "normal-expensive",
+                tier: "hosted",
+                providerCost: 0.15,
+                latencyClass: "normal",
+            });
+            const cheap = makeEntry({ adapter: "normal-cheap", tier: "hosted", providerCost: 0.1, latencyClass: "normal" });
+            const registry = makeRegistry([expensive, cheap]);
+            const router = new ArbitrageRouter({ registry, adapters: new Map(), preferLowLatency: true });
+            const decision = await router.selectProvider("tts");
+            expect(decision.provider.adapter).toBe("normal-cheap");
+        });
+    });
+    describe("buildFailoverChain (priority tiebreaker coverage)", () => {
+        it("orders GPU failover candidates by priority when costs are equal", async () => {
+            // Two GPU providers at equal cost — priority tiebreaker in buildFailoverChain line 173
+            const gpu1 = makeEntry({ adapter: "gpu-priority2", tier: "gpu", providerCost: 0.02, priority: 2 });
+            const gpu2 = makeEntry({ adapter: "gpu-priority1", tier: "gpu", providerCost: 0.02, priority: 1 });
+            const hostedEntry = makeEntry({ adapter: "hosted-fallback", tier: "hosted", providerCost: 0.15 });
+            const serverError = Object.assign(new Error("Server error"), { httpStatus: 500 });
+            const gpu2Adapter = makeAdapter("gpu-priority2", ["tts"], serverError);
+            const gpu1Adapter = makeAdapter("gpu-priority1", ["tts"], serverError);
+            const hostedAdapter = makeAdapter("hosted-fallback", ["tts"], fakeTTSResult);
+            const registryWithHosted = makeRegistry([gpu1, gpu2, hostedEntry]);
+            const adapters = new Map([
+                ["gpu-priority2", gpu2Adapter],
+                ["gpu-priority1", gpu1Adapter],
+                ["hosted-fallback", hostedAdapter],
+            ]);
+            const router = new ArbitrageRouter({ registry: registryWithHosted, adapters });
+            const result = await router.route({ capability: "tts", tenantId: "t1", input: {} });
+            // Should ultimately reach hosted-fallback after both GPU providers fail
+            expect(result.provider).toBe("hosted-fallback");
+        });
+        it("orders hosted failover candidates by priority when costs are equal", async () => {
+            // Selected provider is GPU. Hosted failover has two providers at equal cost — priority tiebreaker line 177.
+            const gpu = makeEntry({ adapter: "gpu-primary", tier: "gpu", providerCost: 0.02 });
+            const hosted1 = makeEntry({ adapter: "hosted-priority2", tier: "hosted", providerCost: 0.12, priority: 2 });
+            const hosted2 = makeEntry({ adapter: "hosted-priority1", tier: "hosted", providerCost: 0.12, priority: 1 });
+            const registry = makeRegistry([gpu, hosted1, hosted2]);
+            const serverError = Object.assign(new Error("Server error"), { httpStatus: 500 });
+            const gpuAdapter = makeAdapter("gpu-primary", ["tts"], serverError);
+            const hosted1Adapter = makeAdapter("hosted-priority2", ["tts"], serverError);
+            const hosted2Adapter = makeAdapter("hosted-priority1", ["tts"], fakeTTSResult);
+            const adapters = new Map([
+                ["gpu-primary", gpuAdapter],
+                ["hosted-priority2", hosted1Adapter],
+                ["hosted-priority1", hosted2Adapter],
+            ]);
+            const router = new ArbitrageRouter({ registry, adapters });
+            const result = await router.route({ capability: "tts", tenantId: "t1", input: {} });
+            // hosted-priority1 (priority:1) should be tried before hosted-priority2 (priority:2)
+            expect(result.provider).toBe("hosted-priority1");
+        });
+    });
+});

package/dist/monetization/arbitrage/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Arbitrage router types — provider entries, routing decisions, and margin tracking.
+ *
+ * WOP-463: Provider arbitrage router for multi-provider routing with maximum margin.
+ */
+import type { Credit } from "@wopr-network/platform-core/credits";
+/** A provider entry in the routing registry. Maps to provider_costs DB rows. */
+export interface ModelProviderEntry {
+    /** Capability or model name */
+    capability: string;
+    /** Which adapter serves it (matches ProviderAdapter.name) */
+    adapter: string;
+    /** Provider tier — GPU infra vs hosted third-party */
+    tier: "gpu" | "hosted";
+    /** Provider's cost to us per unit in USD */
+    providerCost: number;
+    /** Cost unit description */
+    costUnit: string;
+    /** Is this provider currently healthy? */
+    healthy: boolean;
+    /** Priority within same tier (lower = preferred, tiebreaker when costs equal) */
+    priority: number;
+    /** Latency class */
+    latencyClass: "fast" | "normal" | "slow";
+    /** Whether this provider is enabled by admin */
+    enabled: boolean;
+}
+/** Result of a routing decision. */
+export interface RoutingDecision {
+    /** The selected provider entry */
+    provider: ModelProviderEntry;
+    /** All candidates that were considered (for logging/debugging) */
+    candidates: ModelProviderEntry[];
+    /** Why this provider was selected */
+    reason: "gpu-cheapest" | "hosted-cheapest" | "fallback" | "only-option";
+}
+/** Margin tracking record emitted per-request. */
+export interface MarginRecord {
+    /** Tenant who made the request */
+    tenantId: string;
+    /** Capability requested */
+    capability: string;
+    /** Provider that fulfilled it */
+    adapter: string;
+    /** Provider tier */
+    tier: "gpu" | "hosted";
+    /** What we paid the provider */
+    providerCost: Credit;
+    /** What we charged the user */
+    sellPrice: Credit;
+    /** Margin = sellPrice - providerCost */
+    margin: Credit;
+    /** Margin percentage = margin / sellPrice * 100 */
+    marginPct: number;
+    /** Unix epoch ms */
+    timestamp: number;
+}
+export declare class NoProviderAvailableError extends Error {
+    readonly capability: string;
+    readonly httpStatus = 503;
+    constructor(capability: string);
+}

package/dist/monetization/arbitrage/types.js

@@ -0,0 +1,14 @@
+/**
+ * Arbitrage router types — provider entries, routing decisions, and margin tracking.
+ *
+ * WOP-463: Provider arbitrage router for multi-provider routing with maximum margin.
+ */
+export class NoProviderAvailableError extends Error {
+    capability;
+    httpStatus = 503;
+    constructor(capability) {
+        super(`No provider available for capability "${capability}"`);
+        this.name = "NoProviderAvailableError";
+        this.capability = capability;
+    }
+}

package/dist/monetization/arbitrage/types.test.d.ts

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

package/dist/monetization/arbitrage/types.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { NoProviderAvailableError } from "./types.js";
+describe("NoProviderAvailableError", () => {
+    it("has correct name property", () => {
+        const err = new NoProviderAvailableError("tts");
+        expect(err.name).toBe("NoProviderAvailableError");
+    });
+    it("has correct capability property", () => {
+        const err = new NoProviderAvailableError("tts");
+        expect(err.capability).toBe("tts");
+    });
+    it("has httpStatus 503", () => {
+        const err = new NoProviderAvailableError("tts");
+        expect(err.httpStatus).toBe(503);
+    });
+    it("message includes the capability name", () => {
+        const err = new NoProviderAvailableError("image-generation");
+        expect(err.message).toContain("image-generation");
+    });
+    it("is an instance of Error", () => {
+        const err = new NoProviderAvailableError("tts");
+        expect(err).toBeInstanceOf(Error);
+    });
+});

package/dist/monetization/budget/budget-checker.bench.d.ts

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

package/dist/monetization/budget/budget-checker.bench.js

@@ -0,0 +1,34 @@
+import { afterAll, beforeAll, bench, describe } from "vitest";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { DrizzleBudgetChecker } from "./budget-checker.js";
+const limits = {
+    maxSpendPerHour: 10.0,
+    maxSpendPerMonth: 100.0,
+    label: "bench",
+};
+let db;
+let pool;
+beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+});
+afterAll(async () => {
+    await pool.close();
+});
+describe("BudgetChecker throughput", () => {
+    let checker;
+    beforeAll(async () => {
+        await truncateAllTables(pool);
+        checker = new DrizzleBudgetChecker(db, { cacheTtlMs: 30_000, cacheMaxSize: 1000 });
+    });
+    let tenantIdx = 0;
+    bench("budget check (cache hit)", () => {
+        // First call populates cache, subsequent calls hit cache
+        checker.check("tenant-0", limits);
+    }, { iterations: 100_000 });
+    bench("budget check (cache miss — cold path)", () => {
+        // Invalidate before each check to force DB query
+        const tenant = `tenant-${tenantIdx++ % 100}`;
+        checker.invalidate(tenant);
+        checker.check(tenant, limits);
+    }, { iterations: 10_000 });
+});

package/dist/monetization/budget/budget-checker.d.ts

@@ -0,0 +1,89 @@
+import type { DrizzleDb } from "../../db/index.js";
+/**
+ * Spend limits passed by callers (replaces dead TierStore/SpendOverrideStore).
+ */
+export interface SpendLimits {
+    /** Hourly spending limit in USD (null = unlimited) */
+    maxSpendPerHour: number | null;
+    /** Monthly spending limit in USD (null = unlimited) */
+    maxSpendPerMonth: number | null;
+    /** Human-readable label for error messages */
+    label?: string;
+}
+/**
+ * Result of a pre-call budget check.
+ */
+export interface BudgetCheckResult {
+    allowed: boolean;
+    /** If not allowed, the reason */
+    reason?: string;
+    /** HTTP status to return (429 = Too Many Requests) */
+    httpStatus?: number;
+    /** Current hourly spend */
+    currentHourlySpend: number;
+    /** Current monthly spend */
+    currentMonthlySpend: number;
+    /** Hourly limit (null = unlimited) */
+    maxSpendPerHour: number | null;
+    /** Monthly limit (null = unlimited) */
+    maxSpendPerMonth: number | null;
+}
+/**
+ * Configuration for the budget checker.
+ */
+export interface BudgetCheckerConfig {
+    /** Cache TTL in milliseconds (default: 30000ms = 30s) */
+    cacheTtlMs?: number;
+    /** Maximum cache size (default: 1000 entries) */
+    cacheMaxSize?: number;
+}
+export interface IBudgetChecker {
+    check(tenant: string, limits: SpendLimits): Promise<BudgetCheckResult>;
+    invalidate(tenant: string): void;
+    clearCache(): void;
+}
+/**
+ * Pre-call budget checker with in-memory LRU cache.
+ *
+ * Before every upstream API call, this middleware queries the tenant's
+ * accumulated spend from meter_events + usage_summaries and compares it
+ * against caller-provided spend limits. If the budget is exceeded, the
+ * call is rejected with HTTP 429.
+ *
+ * Design:
+ * - Uses an in-memory LRU cache with ~30s TTL to avoid DB queries on every request
+ * - Fail-closed: if DB is unavailable or cache miss fails, reject the call
+ * - Callers pass SpendLimits directly (no more TierStore dependency)
+ */
+export declare class DrizzleBudgetChecker implements IBudgetChecker {
+    private readonly db;
+    private readonly cache;
+    private readonly cacheTtlMs;
+    constructor(db: DrizzleDb, config?: BudgetCheckerConfig);
+    /**
+     * Check if a tenant can make an API call given their current spend.
+     *
+     * @param tenant - Tenant identifier
+     * @param limits - Spend limits for this tenant
+     * @returns BudgetCheckResult indicating whether the call is allowed
+     */
+    check(tenant: string, limits: SpendLimits): Promise<BudgetCheckResult>;
+    /**
+     * Query current budget data from the DB.
+     * Combines data from meter_events buffer + usage_summaries.
+     */
+    private queryBudgetData;
+    /**
+     * Get the start of the current month (unix epoch ms).
+     */
+    private getMonthStart;
+    /**
+     * Invalidate cache for a specific tenant (useful after spend updates).
+     */
+    invalidate(tenant: string): void;
+    /**
+     * Clear the entire cache.
+     */
+    clearCache(): void;
+}
+export { DrizzleBudgetChecker as BudgetChecker };