@wopr-network/platform-core 1.74.0 → 1.75.0

package/dist/monetization/credits/runtime-cron.test.js

@@ -2,9 +2,11 @@ import { Credit, DrizzleLedger, InsufficientBalanceError } from "@wopr-network/p
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { RESOURCE_TIERS } from "../../fleet/resource-tiers.js";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
-import { buildResourceTierCosts, DAILY_BOT_COST, runRuntimeDeductions } from "./runtime-cron.js";
+import { buildResourceTierCosts, DAILY_BOT_COST, dailyBotCost, runRuntimeDeductions } from "./runtime-cron.js";
 describe("runRuntimeDeductions", () => {
     const TODAY = "2025-01-01";
+    /** Dynamic daily cost for TODAY's month (January = 31 days) */
+    const COST = dailyBotCost(TODAY);
     let pool;
     let ledger;
     beforeAll(async () => {
@@ -20,7 +22,7 @@ describe("runRuntimeDeductions", () => {
         await ledger.seedSystemAccounts();
     });
     it("DAILY_BOT_COST equals 17 cents", () => {
-        expect(DAILY_BOT_COST.toCents()).toBe(17);
+        expect(DAILY_BOT_COST.toCentsRounded()).toBe(17);
     });
     it("returns empty result when no tenants have balance", async () => {
         const result = await runRuntimeDeductions({
@@ -51,7 +53,7 @@ describe("runRuntimeDeductions", () => {
         });
         expect(result.processed).toBe(1);
         expect(result.suspended).toEqual([]);
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(500 - 2 * 17);
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(Credit.fromCents(500).subtract(COST.multiply(2)).toCentsRounded());
     });
     it("partial deduction and suspension when balance is insufficient", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(10), "purchase", { description: "top-up" });
@@ -120,7 +122,7 @@ describe("runRuntimeDeductions", () => {
     });
     it("catches InsufficientBalanceError from debit and suspends", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
-        vi.spyOn(ledger, "debit").mockRejectedValue(new InsufficientBalanceError(Credit.fromCents(0), Credit.fromCents(17)));
+        vi.spyOn(ledger, "debit").mockRejectedValue(new InsufficientBalanceError(Credit.fromCents(0), COST));
         const onSuspend = vi.fn();
         const result = await runRuntimeDeductions({
             ledger,
@@ -135,7 +137,7 @@ describe("runRuntimeDeductions", () => {
     });
     it("catches InsufficientBalanceError without onSuspend callback", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
-        vi.spyOn(ledger, "debit").mockRejectedValue(new InsufficientBalanceError(Credit.fromCents(0), Credit.fromCents(17)));
+        vi.spyOn(ledger, "debit").mockRejectedValue(new InsufficientBalanceError(Credit.fromCents(0), COST));
         const result = await runRuntimeDeductions({
             ledger,
             date: TODAY,
@@ -171,7 +173,7 @@ describe("runRuntimeDeductions", () => {
         expect(onLowBalance).toHaveBeenCalledOnce();
         const [calledTenant, calledBalance] = onLowBalance.mock.calls[0];
         expect(calledTenant).toBe("tenant-1");
-        expect(calledBalance.toCents()).toBe(93);
+        expect(calledBalance.toCentsRounded()).toBe(Credit.fromCents(110).subtract(COST).toCentsRounded());
     });
     it("does NOT fire onLowBalance when balance was already below threshold before deduction", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(90), "purchase", { description: "top-up" });
@@ -185,7 +187,7 @@ describe("runRuntimeDeductions", () => {
         expect(onLowBalance).not.toHaveBeenCalled();
     });
     it("fires onCreditsExhausted when full deduction causes balance to drop to 0", async () => {
-        await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", { description: "top-up" });
+        await ledger.credit("tenant-1", COST, "purchase", { description: "top-up" });
         const onCreditsExhausted = vi.fn();
         await runRuntimeDeductions({
             ledger,
@@ -197,8 +199,8 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
     });
     it("suspends tenant when full deduction causes balance to drop to exactly 0", async () => {
-        // Balance = exactly 1 bot * DAILY_BOT_COST = 17 cents → full deduction → 0
-        await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", { description: "top-up" });
+        // Balance = exactly 1 bot * dailyBotCost → full deduction → 0
+        await ledger.credit("tenant-1", COST, "purchase", { description: "top-up" });
         const onSuspend = vi.fn();
         const onCreditsExhausted = vi.fn();
         const result = await runRuntimeDeductions({
@@ -237,7 +239,7 @@ describe("runRuntimeDeductions", () => {
         expect((await ledger.balance("tenant-1")).toCents()).toBe(0);
     });
     it("skips resource tier partial debit when balance is exactly 0 after runtime", async () => {
-        await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", { description: "top-up" });
+        await ledger.credit("tenant-1", COST, "purchase", { description: "top-up" });
         const onCreditsExhausted = vi.fn();
         const result = await runRuntimeDeductions({
             ledger,
@@ -255,7 +257,7 @@ describe("runRuntimeDeductions", () => {
         // triggering the zero-crossing suspend in the runtime block.
         // Storage cost (5 cents) then tries to suspend again via its else-branch (balance 0 < 5).
         // The !result.suspended.includes(tenantId) guard must prevent onSuspend being called twice.
-        await ledger.credit("tenant-1", Credit.fromCents(17), "purchase", { description: "top-up" });
+        await ledger.credit("tenant-1", COST, "purchase", { description: "top-up" });
         const onSuspend = vi.fn();
         const result = await runRuntimeDeductions({
             ledger,
@@ -269,9 +271,9 @@ describe("runRuntimeDeductions", () => {
         expect(onSuspend).toHaveBeenCalledTimes(1);
     });
     it("buildResourceTierCosts: deducts pro tier surcharge via getResourceTierCosts", async () => {
-        const proTierCost = RESOURCE_TIERS.pro.dailyCost.toCents();
-        const startBalance = 17 + proTierCost + 10;
-        await ledger.credit("tenant-1", Credit.fromCents(startBalance), "purchase", { description: "top-up" });
+        const proTierCost = RESOURCE_TIERS.pro.dailyCost;
+        const startCredit = COST.add(proTierCost).add(Credit.fromCents(10));
+        await ledger.credit("tenant-1", startCredit, "purchase", { description: "top-up" });
         const mockRepo = {
             getResourceTier: async (_botId) => "pro",
         };
@@ -282,8 +284,7 @@ describe("runRuntimeDeductions", () => {
             getActiveBotCount: async () => 1,
             getResourceTierCosts,
         });
-        const expected = startBalance - 17 - proTierCost;
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(expected);
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(10);
     });
     it("treats unique constraint violation from concurrent debit as already-billed (skip, not error)", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
@@ -300,26 +301,31 @@ describe("runRuntimeDeductions", () => {
     });
     it("is idempotent — second run on same date does not double-deduct", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "top-up" });
+        const JUNE_DATE = "2025-06-15";
+        const JUNE_COST = dailyBotCost(JUNE_DATE);
+        const expectedBalance = Credit.fromCents(500).subtract(JUNE_COST);
         const cfg = {
             ledger,
             getActiveBotCount: async () => 1,
-            date: "2025-06-15",
+            date: JUNE_DATE,
         };
         const first = await runRuntimeDeductions(cfg);
         expect(first.processed).toBe(1);
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(500 - 17);
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(expectedBalance.toCentsRounded());
         const second = await runRuntimeDeductions(cfg);
         expect(second.processed).toBe(0);
         expect(second.skipped).toContain("tenant-1");
         // Balance unchanged after second run
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(500 - 17);
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(expectedBalance.toCentsRounded());
     });
     it("bills surcharges on retry when runtime was already billed (crash recovery)", async () => {
         // Setup: tenant with enough balance for runtime + tier + storage + addon
         await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
+        const JUL_DATE = "2025-07-01";
+        const JUL_COST = dailyBotCost(JUL_DATE);
         const cfg = {
             ledger,
-            date: "2025-07-01",
+            date: JUL_DATE,
             getActiveBotCount: async () => 1,
             getResourceTierCosts: async () => Credit.fromCents(10),
             getStorageTierCosts: async () => Credit.fromCents(8),
@@ -328,23 +334,28 @@ describe("runRuntimeDeductions", () => {
         // First run — bills everything
         const first = await runRuntimeDeductions(cfg);
         expect(first.processed).toBe(1);
-        // 1000 - 17 (runtime) - 10 (tier) - 8 (storage) - 5 (addon) = 960
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+        const expectedAfterFirst = Credit.fromCents(1000)
+            .subtract(JUL_COST)
+            .subtract(Credit.fromCents(10))
+            .subtract(Credit.fromCents(8))
+            .subtract(Credit.fromCents(5));
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(expectedAfterFirst.toCentsRounded());
         // Second run — all already billed, should skip
         const second = await runRuntimeDeductions(cfg);
         expect(second.skipped).toContain("tenant-1");
         expect(second.processed).toBe(0);
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(expectedAfterFirst.toCentsRounded());
     });
     it("bills remaining surcharges when runtime was billed but surcharges were not (simulated crash)", async () => {
         // Setup: tenant with enough balance
         await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
         // Simulate crash: manually debit only the runtime charge (as if the cron crashed after this)
-        await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
-            description: "Daily runtime: 1 bot(s) x $0.17",
+        await ledger.debit("tenant-1", COST, "bot_runtime", {
+            description: `Daily runtime: 1 bot(s) x $${COST.toDollars().toFixed(4)}`,
             referenceId: `runtime:2025-07-02:tenant-1`,
         });
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(983); // 1000 - 17
+        const afterRuntime = Credit.fromCents(1000).subtract(COST);
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(afterRuntime.toCentsRounded());
         // Retry run — runtime already billed, but surcharges should still be billed
         const result = await runRuntimeDeductions({
             ledger,
@@ -356,21 +367,25 @@ describe("runRuntimeDeductions", () => {
         });
         expect(result.processed).toBe(1);
         expect(result.skipped).not.toContain("tenant-1");
-        // 983 - 10 (tier) - 8 (storage) - 5 (addon) = 960
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+        const expectedFinal = afterRuntime
+            .subtract(Credit.fromCents(10))
+            .subtract(Credit.fromCents(8))
+            .subtract(Credit.fromCents(5));
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(expectedFinal.toCentsRounded());
     });
     it("bills only missing surcharges when some were already committed (simulated partial crash)", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
         // Simulate: runtime + tier already billed, storage + addon not yet
-        await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
-            description: "Daily runtime: 1 bot(s) x $0.17",
+        await ledger.debit("tenant-1", COST, "bot_runtime", {
+            description: `Daily runtime: 1 bot(s) x $${COST.toDollars().toFixed(4)}`,
             referenceId: `runtime:2025-07-03:tenant-1`,
         });
         await ledger.debit("tenant-1", Credit.fromCents(10), "resource_upgrade", {
             description: "Daily resource tier surcharge",
             referenceId: `runtime-tier:2025-07-03:tenant-1`,
         });
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(973); // 1000 - 17 - 10
+        const afterRuntimeAndTier = Credit.fromCents(1000).subtract(COST).subtract(Credit.fromCents(10));
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(afterRuntimeAndTier.toCentsRounded());
         const result = await runRuntimeDeductions({
             ledger,
             date: "2025-07-03",
@@ -380,8 +395,8 @@ describe("runRuntimeDeductions", () => {
             getAddonCosts: async () => Credit.fromCents(5),
         });
         expect(result.processed).toBe(1);
-        // 973 - 8 (storage) - 5 (addon) = 960
-        expect((await ledger.balance("tenant-1")).toCents()).toBe(960);
+        const expectedFinal = afterRuntimeAndTier.subtract(Credit.fromCents(8)).subtract(Credit.fromCents(5));
+        expect((await ledger.balance("tenant-1")).toCentsRounded()).toBe(expectedFinal.toCentsRounded());
     });
     it("does not double-debit runtime on retry after partial deduction + crash", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(10), "purchase", { description: "top-up" });
@@ -405,7 +420,7 @@ describe("runRuntimeDeductions", () => {
     it("trial balance remains balanced after crash-recovery billing", async () => {
         await ledger.credit("tenant-1", Credit.fromCents(1000), "purchase", { description: "top-up" });
         // Simulate crash: only runtime billed
-        await ledger.debit("tenant-1", DAILY_BOT_COST, "bot_runtime", {
+        await ledger.debit("tenant-1", COST, "bot_runtime", {
             description: "Daily runtime: 1 bot(s) x $0.17",
             referenceId: `runtime:2025-07-05:tenant-1`,
         });

package/dist/monetization/credits/storage-tier-billing.test.js

@@ -5,6 +5,7 @@ import { DrizzleBotBilling } from "./bot-billing.js";
 describe("bot-billing storage tier", () => {
     let pool;
     let db;
+    let repo;
     let billing;
     beforeAll(async () => {
         ({ db, pool } = await createTestDb());
@@ -16,14 +17,17 @@ describe("bot-billing storage tier", () => {
     });
     beforeEach(async () => {
         await rollbackTestTransaction(pool);
-        billing = new DrizzleBotBilling(new DrizzleBotInstanceRepository(db));
+        repo = new DrizzleBotInstanceRepository(db);
+        billing = new DrizzleBotBilling(repo);
     });
     it("new bot defaults to standard storage tier", async () => {
         await billing.registerBot("bot-1", "tenant-1", "TestBot");
+        await repo.startBilling("bot-1");
         expect(await billing.getStorageTier("bot-1")).toBe("standard");
     });
     it("setStorageTier updates tier", async () => {
         await billing.registerBot("bot-1", "tenant-1", "TestBot");
+        await repo.startBilling("bot-1");
         await billing.setStorageTier("bot-1", "pro");
         expect(await billing.getStorageTier("bot-1")).toBe("pro");
     });
@@ -32,8 +36,11 @@ describe("bot-billing storage tier", () => {
     });
     it("getStorageTierCostsForTenant sums active bot storage costs", async () => {
         await billing.registerBot("bot-1", "tenant-1", "Bot1");
+        await repo.startBilling("bot-1");
         await billing.registerBot("bot-2", "tenant-1", "Bot2");
+        await repo.startBilling("bot-2");
         await billing.registerBot("bot-3", "tenant-1", "Bot3");
+        await repo.startBilling("bot-3");
         await billing.setStorageTier("bot-1", "plus"); // 3 credits/day
         await billing.setStorageTier("bot-2", "max"); // 15 credits/day
         // bot-3 stays standard                        // 0 credits/day
@@ -41,6 +48,7 @@ describe("bot-billing storage tier", () => {
     });
     it("getStorageTierCostsForTenant excludes suspended bots", async () => {
         await billing.registerBot("bot-1", "tenant-1", "Bot1");
+        await repo.startBilling("bot-1");
         await billing.setStorageTier("bot-1", "pro"); // 8 credits/day
         await billing.suspendBot("bot-1");
         expect((await billing.getStorageTierCostsForTenant("tenant-1")).toCents()).toBe(0);

package/dist/monetization/credits/storage-tier-cron.test.js

@@ -1,9 +1,10 @@
 import { Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
-import { runRuntimeDeductions } from "./runtime-cron.js";
+import { dailyBotCost, runRuntimeDeductions } from "./runtime-cron.js";
 describe("runtime cron with storage tiers", () => {
     const TODAY = "2025-01-01";
+    const BASE_COST_CREDIT = dailyBotCost(TODAY);
     let pool;
     let db;
     let ledger;
@@ -28,8 +29,9 @@ describe("runtime cron with storage tiers", () => {
         });
         expect(result.processed).toBe(1);
         const balance = await ledger.balance("t1");
-        // 1000 - 17 (base) - 8 (pro storage surcharge) = 975
-        expect(balance.toCents()).toBe(975);
+        // 1000 - dailyBotCost (base) - 8 (pro storage surcharge)
+        const expected = Credit.fromCents(1000).subtract(BASE_COST_CREDIT).subtract(Credit.fromCents(8));
+        expect(balance.toCents()).toBe(expected.toCents());
     });
     it("debits only base cost for standard storage tier (zero surcharge)", async () => {
         await ledger.credit("t1", Credit.fromCents(1000), "purchase");
@@ -40,7 +42,8 @@ describe("runtime cron with storage tiers", () => {
             getStorageTierCosts: async () => Credit.ZERO,
         });
         expect(result.processed).toBe(1);
-        expect((await ledger.balance("t1")).toCents()).toBe(983); // 1000 - 17
+        const expectedStd = Credit.fromCents(1000).subtract(BASE_COST_CREDIT);
+        expect((await ledger.balance("t1")).toCents()).toBe(expectedStd.toCents());
     });
     it("skips storage surcharge when callback not provided (backward compat)", async () => {
         await ledger.credit("t1", Credit.fromCents(1000), "purchase");
@@ -50,10 +53,13 @@ describe("runtime cron with storage tiers", () => {
             getActiveBotCount: async () => 1,
         });
         expect(result.processed).toBe(1);
-        expect((await ledger.balance("t1")).toCents()).toBe(983); // 1000 - 17
+        const expectedBackcompat = Credit.fromCents(1000).subtract(BASE_COST_CREDIT);
+        expect((await ledger.balance("t1")).toCents()).toBe(expectedBackcompat.toCents());
     });
     it("suspends tenant when storage surcharge exhausts remaining balance", async () => {
-        await ledger.credit("t1", Credit.fromCents(20), "purchase"); // Only 20 cents
+        // Seed just enough for base cost + 3 cents, so storage surcharge (8) exceeds remainder
+        const seed = BASE_COST_CREDIT.add(Credit.fromCents(3));
+        await ledger.credit("t1", seed, "purchase");
         const suspended = [];
         const result = await runRuntimeDeductions({
             ledger,
@@ -64,7 +70,7 @@ describe("runtime cron with storage tiers", () => {
                 suspended.push(tenantId);
             },
         });
-        // 20 - 17 = 3 remaining, then 8 surcharge > 3, so partial debit + suspend
+        // seed - BASE_COST = 3 remaining, then 8 surcharge > 3, so partial debit + suspend
         expect(result.processed).toBe(1);
         expect(result.suspended).toContain("t1");
         expect((await ledger.balance("t1")).toCents()).toBe(0);

package/dist/server/__tests__/container.test.js

@@ -142,6 +142,8 @@ describe("createTestContainer", () => {
         };
         const gateway = {
             serviceKeyRepo: {},
+            meter: {},
+            budgetChecker: {},
         };
         const hotPool = {
             start: async () => ({ stop: () => { } }),
@@ -158,7 +160,9 @@ describe("createTestContainer", () => {
         expect(c.hotPool).not.toBeNull();
     });
     it("overrides merge without affecting other defaults", () => {
-        const c = createTestContainer({ gateway: { serviceKeyRepo: {} } });
+        const c = createTestContainer({
+            gateway: { serviceKeyRepo: {}, meter: {}, budgetChecker: {} },
+        });
         // Overridden field
         expect(c.gateway).not.toBeNull();
         // Other feature services remain null

package/dist/server/container.d.ts

@@ -44,6 +44,8 @@ export interface StripeServices {
 }
 export interface GatewayServices {
     serviceKeyRepo: IServiceKeyRepository;
+    meter: import("../metering/emitter.js").MeterEmitter;
+    budgetChecker: import("../monetization/budget/budget-checker.js").IBudgetChecker;
 }
 export interface HotPoolServices {
     /** Start the pool manager (replenish loop + cleanup). */

package/dist/server/container.js

@@ -126,8 +126,13 @@ export async function buildContainer(bootConfig) {
     let gateway = null;
     if (bootConfig.features.gateway) {
         const { DrizzleServiceKeyRepository } = await import("../gateway/service-key-repository.js");
+        const { MeterEmitter } = await import("../metering/emitter.js");
+        const { DrizzleMeterEventRepository } = await import("../metering/meter-event-repository.js");
+        const { DrizzleBudgetChecker } = await import("../monetization/budget/budget-checker.js");
         const serviceKeyRepo = new DrizzleServiceKeyRepository(db);
-        gateway = { serviceKeyRepo };
+        const meter = new MeterEmitter(new DrizzleMeterEventRepository(db), { flushIntervalMs: 5_000 });
+        const budgetChecker = new DrizzleBudgetChecker(db, { cacheTtlMs: 30_000 });
+        gateway = { serviceKeyRepo, meter, budgetChecker };
     }
     // 12. Build the container (hotPool bound after construction)
     const result = {

package/dist/server/index.js

@@ -37,7 +37,7 @@ export { createTestContainer } from "./test-container.js";
 export async function bootPlatformServer(config) {
     const container = await buildContainer(config);
     const app = new Hono();
-    mountRoutes(app, container, {
+    await mountRoutes(app, container, {
         provisionSecret: config.provisionSecret,
         cryptoServiceKey: config.cryptoServiceKey,
         platformDomain: container.productConfig.product?.domain ?? "localhost",

package/dist/server/mount-routes.d.ts

@@ -27,4 +27,4 @@ export interface MountConfig {
  *   6. Product-specific route plugins
  *   7. Tenant proxy middleware (catch-all — must be last)
  */
-export declare function mountRoutes(app: Hono, container: PlatformContainer, config: MountConfig, plugins?: RoutePlugin[]): void;
+export declare function mountRoutes(app: Hono, container: PlatformContainer, config: MountConfig, plugins?: RoutePlugin[]): Promise<void>;

package/dist/server/mount-routes.js

@@ -28,7 +28,7 @@ import { createStripeWebhookRoutes } from "./routes/stripe-webhook.js";
  *   6. Product-specific route plugins
  *   7. Tenant proxy middleware (catch-all — must be last)
  */
-export function mountRoutes(app, container, config, plugins = []) {
+export async function mountRoutes(app, container, config, plugins = []) {
     // 1. CORS middleware
     const origins = deriveCorsOrigins(container.productConfig.product, container.productConfig.domains);
     app.use("*", cors({
@@ -60,7 +60,40 @@ export function mountRoutes(app, container, config, plugins = []) {
             maxInstancesPerTenant: fleetConfig?.maxInstances ?? 5,
         }));
     }
-    // 6. Product-specific route plugins
+    // 6. Metered inference gateway (when gateway is enabled)
+    if (container.gateway) {
+        // Validate billing config exists in DB — fail hard, no silent defaults
+        const billingConfig = container.productConfig.billing;
+        const marginConfig = billingConfig?.marginConfig;
+        if (!marginConfig?.default) {
+            throw new Error("Gateway enabled but product_billing_config.margin_config.default is not set. " +
+                "Seed the DB: INSERT INTO product_billing_config (product_id, margin_config) VALUES ('<id>', '{\"default\": 4.0}')");
+        }
+        // Live margin — reads from productConfig per-request (DB-cached with TTL)
+        const initialMargin = marginConfig.default;
+        const resolveMargin = () => {
+            const cfg = container.productConfig.billing?.marginConfig;
+            return cfg?.default ?? initialMargin;
+        };
+        const gw = container.gateway;
+        const { mountGateway } = await import("../gateway/index.js");
+        mountGateway(app, {
+            meter: gw.meter,
+            budgetChecker: gw.budgetChecker,
+            creditLedger: container.creditLedger,
+            resolveMargin,
+            providers: {
+                openrouter: process.env.OPENROUTER_API_KEY
+                    ? { apiKey: process.env.OPENROUTER_API_KEY, baseUrl: process.env.OPENROUTER_BASE_URL || undefined }
+                    : undefined,
+            },
+            resolveServiceKey: async (key) => {
+                const tenant = await gw.serviceKeyRepo.resolve(key);
+                return tenant ?? null;
+            },
+        });
+    }
+    // 7. Product-specific route plugins
     for (const plugin of plugins) {
         app.route(plugin.path, plugin.handler(container));
     }

package/dist/server/routes/__tests__/admin.test.js

@@ -144,6 +144,7 @@ describe("createAdminRouter", () => {
                     },
                     serviceKeyRepo: {},
                 },
+                gateway: { serviceKeyRepo: {}, meter: {}, budgetChecker: {} },
             });
             const caller = makeCaller(container);
             const result = await caller.admin.listAllInstances();
@@ -185,6 +186,7 @@ describe("createAdminRouter", () => {
                     },
                     serviceKeyRepo: {},
                 },
+                gateway: { serviceKeyRepo: {}, meter: {}, budgetChecker: {} },
             });
             const caller = makeCaller(container);
             const result = await caller.admin.listAllInstances();
@@ -229,9 +231,7 @@ describe("createAdminRouter", () => {
             };
             const container = createTestContainer({
                 pool: mockPool,
-                gateway: {
-                    serviceKeyRepo: {},
-                },
+                gateway: { serviceKeyRepo: {}, meter: {}, budgetChecker: {} },
             });
             const caller = makeCaller(container);
             const result = await caller.admin.billingOverview();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.74.0",
+  "version": "1.75.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/fleet/drizzle-bot-instance-repository.ts

@@ -218,15 +218,28 @@ export class DrizzleBotInstanceRepository implements IBotInstanceRepository {
       .where(eq(botInstances.id, botId));
   }
 
-  async register(botId: string, tenantId: string, name: string): Promise<void> {
+  async register(
+    botId: string,
+    tenantId: string,
+    name: string,
+    billingState: BillingState = "inactive",
+  ): Promise<void> {
     await this.db.insert(botInstances).values({
       id: botId,
       tenantId,
       name,
-      billingState: "active",
+      billingState,
     });
   }
 
+  async startBilling(botId: string): Promise<void> {
+    await this.db.update(botInstances).set({ billingState: "active" }).where(eq(botInstances.id, botId));
+  }
+
+  async stopBilling(botId: string): Promise<void> {
+    await this.db.update(botInstances).set({ billingState: "inactive" }).where(eq(botInstances.id, botId));
+  }
+
   async getStorageTier(botId: string): Promise<string | null> {
     const row = (
       await this.db

package/src/fleet/instance.ts

@@ -109,6 +109,27 @@ export class Instance {
     this.emit("bot.created");
   }
 
+  /**
+   * Start billing for this instance ($5/month prorated daily).
+   * Call after creation for persistent, billable instances (e.g., Paperclip).
+   * Ephemeral instances (e.g., Holy Ship) skip this — they bill per-token at the gateway.
+   */
+  async startBilling(): Promise<void> {
+    if (!this.instanceRepo) {
+      logger.warn("startBilling() called but no instanceRepo available", { id: this.id });
+      return;
+    }
+    await this.instanceRepo.setBillingState(this.id, "active");
+    logger.info("Billing started for instance", { id: this.id, name: this.profile.name });
+  }
+
+  /** Stop billing for this instance (e.g., on suspend or downgrade). */
+  async stopBilling(): Promise<void> {
+    if (!this.instanceRepo) return;
+    await this.instanceRepo.setBillingState(this.id, "suspended");
+    logger.info("Billing stopped for instance", { id: this.id, name: this.profile.name });
+  }
+
   async start(): Promise<void> {
     this.assertLocal("start()");
     return this.withLock(async () => {

package/src/fleet/repository-types.ts

@@ -78,7 +78,7 @@ export interface SelfHostedNodeRegistration extends NodeRegistration {
 // ---------------------------------------------------------------------------
 
 /** Billing lifecycle states for a bot instance. */
-export type BillingState = "active" | "suspended" | "destroyed";
+export type BillingState = "active" | "inactive" | "suspended" | "destroyed";
 
 /** Plain domain object for a bot instance — mirrors `bot_instances` table. */
 export interface BotInstance {

package/src/gateway/proxy.ts

@@ -29,7 +29,11 @@ import type { GatewayAuthEnv } from "./service-key-auth.js";
 import { proxySSEStream } from "./streaming.js";
 import type { FetchFn, GatewayConfig, ProviderConfig } from "./types.js";
 
-const DEFAULT_MARGIN = 1.3;
+/**
+ * Fallback only used when resolveMargin is not provided (tests only).
+ * Production MUST provide resolveMargin — mountRoutes enforces this.
+ */
+const TEST_ONLY_MARGIN = 1.3;
 
 /** Max call duration cap: 4 hours = 240 minutes. */
 const MAX_CALL_DURATION_MINUTES = 240;
@@ -96,7 +100,10 @@ export function buildProxyDeps(config: GatewayConfig): ProxyDeps {
     providers: config.providers,
     defaultModel: config.defaultModel,
     resolveDefaultModel: config.resolveDefaultModel,
-    defaultMargin: config.defaultMargin ?? DEFAULT_MARGIN,
+    get defaultMargin() {
+      if (config.resolveMargin) return config.resolveMargin();
+      return config.defaultMargin ?? TEST_ONLY_MARGIN;
+    },
     fetchFn: config.fetchFn ?? fetch,
     arbitrageRouter: config.arbitrageRouter,
     rateLookupFn: config.rateLookupFn,

package/src/gateway/types.ts

@@ -115,8 +115,10 @@ export interface GatewayConfig {
   graceBufferCents?: number;
   /** Upstream provider credentials */
   providers: ProviderConfig;
-  /** Default margin multiplier (default: 1.3 = 30%) */
+  /** Static margin (for tests only). Production should use resolveMargin. */
   defaultMargin?: number;
+  /** Live margin resolver — called per-request, reads from DB. Takes priority over defaultMargin. */
+  resolveMargin?: () => number;
   /** Optional arbitrage router for multi-provider cost optimization (WOP-463) */
   arbitrageRouter?: import("../monetization/arbitrage/router.js").ArbitrageRouter;
   /** Injectable fetch for testing */

package/src/index.ts

@@ -48,3 +48,7 @@ export * from "./tenancy/index.js";
 
 // tRPC
 export * from "./trpc/index.js";
+// monorepo e2e cutover test
+// hybrid dockerfile e2e
+// sequential build test
+// lockfile build