@wopr-network/platform-core 1.5.0 → 1.6.0

package/dist/monetization/adapters/rate-table.d.ts

@@ -28,13 +28,16 @@ export interface RateEntry {
     effectivePrice: number;
 }
 /**
- * The rate table.
+ * The rate table — admin-dashboard reference for pricing comparisons.
  *
  * Each capability has both standard and premium entries. Standard is always
  * cheaper than premium for the same capability (that's the whole point).
  *
- * Entries are added as self-hosted adapters are implemented. Currently only
- * TTS (Chatterbox vs ElevenLabs) is in the table.
+ * NOTE: Margin values here are reference defaults for dashboard display.
+ * Runtime margins are authoritative via `getMargin()` / `MARGIN_CONFIG_JSON`.
+ *
+ * NOTE: Text-generation rates are blended (approximate 50/50 input/output).
+ * Real costs vary by workload — output-heavy chat costs more than shown here.
  */
 export declare const RATE_TABLE: RateEntry[];
 /**

package/dist/monetization/adapters/rate-table.js

@@ -11,13 +11,16 @@
  * Premium tier = third-party brand-name APIs, higher cost
  */
 /**
- * The rate table.
+ * The rate table — admin-dashboard reference for pricing comparisons.
  *
  * Each capability has both standard and premium entries. Standard is always
  * cheaper than premium for the same capability (that's the whole point).
  *
- * Entries are added as self-hosted adapters are implemented. Currently only
- * TTS (Chatterbox vs ElevenLabs) is in the table.
+ * NOTE: Margin values here are reference defaults for dashboard display.
+ * Runtime margins are authoritative via `getMargin()` / `MARGIN_CONFIG_JSON`.
+ *
+ * NOTE: Text-generation rates are blended (approximate 50/50 input/output).
+ * Real costs vary by workload — output-heavy chat costs more than shown here.
  */
 export const RATE_TABLE = [
     // TTS - Text-to-Speech
@@ -27,8 +30,8 @@ export const RATE_TABLE = [
         provider: "chatterbox-tts",
         costPerUnit: 0.000002, // Amortized GPU cost
         billingUnit: "per-character",
-        margin: 1.2, // 20% margin
-        effectivePrice: 0.0000024, // $2.40 per 1M chars
+        margin: 1.2, // 20% — dashboard default; runtime uses getMargin()
+        effectivePrice: 0.0000024, // = costPerUnit * margin ($2.40 per 1M chars)
     },
     {
         capability: "tts",
@@ -36,27 +39,27 @@ export const RATE_TABLE = [
         provider: "elevenlabs",
         costPerUnit: 0.000015, // Third-party wholesale
         billingUnit: "per-character",
-        margin: 1.5, // 50% margin
-        effectivePrice: 0.0000225, // $22.50 per 1M chars
+        margin: 1.5, // 50% — dashboard default; runtime uses getMargin()
+        effectivePrice: 0.0000225, // = costPerUnit * margin ($22.50 per 1M chars)
     },
     // Text Generation
     {
         capability: "text-generation",
         tier: "standard",
         provider: "self-hosted-llm",
-        costPerUnit: 0.00000005, // Amortized GPU cost per token (H100)
+        costPerUnit: 0.00000005, // Amortized GPU cost per token (H100), blended in/out
         billingUnit: "per-token",
-        margin: 1.2, // 20% margin
-        effectivePrice: 0.00000006, // $0.06 per 1M tokens
+        margin: 1.2, // 20% — dashboard default; runtime uses getMargin()
+        effectivePrice: 0.00000006, // = costPerUnit * margin ($0.06 per 1M tokens)
     },
     {
         capability: "text-generation",
         tier: "premium",
         provider: "openrouter",
-        costPerUnit: 0.000001, // Fallback per-token rate
+        costPerUnit: 0.000001, // Blended per-token rate (variable across models)
         billingUnit: "per-token",
-        margin: 1.3, // 30% margin
-        effectivePrice: 0.0000013, // $1.30 per 1M tokens
+        margin: 1.3, // 30% — dashboard default; runtime uses getMargin()
+        effectivePrice: 0.0000013, // = costPerUnit * margin ($1.30 per 1M tokens)
     },
     // Future self-hosted adapters will add more entries here:
     // - transcription: self-hosted-whisper (standard) vs deepgram (premium)

package/dist/monetization/adapters/rate-table.test.js

@@ -13,10 +13,18 @@ describe("RATE_TABLE", () => {
         expect(standard).toEqual(expect.objectContaining({ capability: "text-generation", tier: "standard", provider: "self-hosted-llm" }));
         expect(premium).toEqual(expect.objectContaining({ capability: "text-generation", tier: "premium", provider: "openrouter" }));
     });
-    it("standard tier is cheaper than premium tier for same capability", () => {
-        const standardTTS = RATE_TABLE.find((e) => e.capability === "tts" && e.tier === "standard");
-        const premiumTTS = RATE_TABLE.find((e) => e.capability === "tts" && e.tier === "premium");
-        expect(standardTTS?.effectivePrice).toBeLessThan(premiumTTS?.effectivePrice ?? Infinity);
+    it("standard tier is cheaper than premium tier for every capability", () => {
+        const capabilities = new Set(RATE_TABLE.map((e) => e.capability));
+        let compared = 0;
+        for (const capability of capabilities) {
+            const standard = RATE_TABLE.find((e) => e.capability === capability && e.tier === "standard");
+            const premium = RATE_TABLE.find((e) => e.capability === capability && e.tier === "premium");
+            if (standard && premium) {
+                expect(standard.effectivePrice).toBeLessThan(premium.effectivePrice);
+                compared++;
+            }
+        }
+        expect(compared).toBeGreaterThan(0);
     });
     it("effective price equals cost * margin", () => {
         for (const entry of RATE_TABLE) {

package/dist/monetization/socket/socket.d.ts

@@ -4,9 +4,14 @@
  * The socket layer is the glue: it receives a capability request with a tenant ID,
  * selects the right adapter, calls it, emits a MeterEvent, and returns the result.
  * Adapters never touch metering or billing — that's the socket's job.
+ *
+ * When an ArbitrageRouter is configured, the socket delegates provider selection
+ * to the router (GPU-first, cost-sorted, 5xx failover) while keeping ownership
+ * of budget checks, metering, BYOK, and margin calculation.
  */
 import type { MeterEmitter } from "@wopr-network/platform-core/metering";
 import type { AdapterCapability, ProviderAdapter } from "../adapters/types.js";
+import type { ArbitrageRouter } from "../arbitrage/router.js";
 import type { BudgetChecker, SpendLimits } from "../budget/budget-checker.js";
 export interface SocketConfig {
     /** MeterEmitter instance for usage tracking */
@@ -15,6 +20,8 @@ export interface SocketConfig {
     budgetChecker?: BudgetChecker;
     /** Default margin multiplier (default: 1.3) */
     defaultMargin?: number;
+    /** ArbitrageRouter for cost-optimized routing (GPU-first, cheapest, 5xx failover) */
+    router?: ArbitrageRouter;
 }
 export interface SocketRequest {
     /** Who is making the request */
@@ -23,8 +30,10 @@ export interface SocketRequest {
     capability: AdapterCapability;
     /** The request payload (matches the capability's input type) */
     input: unknown;
-    /** Optional: force a specific adapter by name */
+    /** Optional: force a specific adapter by name (highest priority, bypasses router) */
     adapter?: string;
+    /** Optional: model specifier for model-level routing (e.g., "gemini-2.5-pro") */
+    model?: string;
     /** Optional: override margin for this request */
     margin?: number;
     /** Optional: session ID for grouping events */
@@ -43,6 +52,7 @@ export declare class AdapterSocket {
     private readonly meter;
     private readonly budgetChecker?;
     private readonly defaultMargin;
+    private readonly router?;
     constructor(config: SocketConfig);
     /** Register an adapter. Overwrites any existing adapter with the same name. */
     register(adapter: ProviderAdapter): void;
@@ -50,6 +60,8 @@ export declare class AdapterSocket {
     execute<T>(request: SocketRequest): Promise<T>;
     /** List all capabilities across all registered adapters (deduplicated). */
     capabilities(): AdapterCapability[];
-    /** Resolve which adapter to use for a request. */
+    /** Call a specific adapter by name. Used by explicit override and legacy routing. */
+    private executeWithAdapter;
+    /** Resolve which adapter to use for a request (legacy routing — pricingTier or first-match). */
     private resolveAdapter;
 }

package/dist/monetization/socket/socket.js

@@ -4,6 +4,10 @@
  * The socket layer is the glue: it receives a capability request with a tenant ID,
  * selects the right adapter, calls it, emits a MeterEvent, and returns the result.
  * Adapters never touch metering or billing — that's the socket's job.
+ *
+ * When an ArbitrageRouter is configured, the socket delegates provider selection
+ * to the router (GPU-first, cost-sorted, 5xx failover) while keeping ownership
+ * of budget checks, metering, BYOK, and margin calculation.
  */
 import { Credit } from "@wopr-network/platform-core/credits";
 import { withMargin } from "../adapters/types.js";
@@ -20,14 +24,20 @@ export class AdapterSocket {
     meter;
     budgetChecker;
     defaultMargin;
+    router;
     constructor(config) {
         this.meter = config.meter;
         this.budgetChecker = config.budgetChecker;
         this.defaultMargin = config.defaultMargin ?? 1.3;
+        this.router = config.router;
     }
     /** Register an adapter. Overwrites any existing adapter with the same name. */
     register(adapter) {
         this.adapters.set(adapter.name, adapter);
+        // Also register with router so it can call the adapter during failover
+        if (this.router) {
+            this.router.registerAdapter(adapter);
+        }
     }
     /** Execute a capability request against the best adapter. */
     async execute(request) {
@@ -43,14 +53,45 @@ export class AdapterSocket {
                 throw error;
             }
         }
-        const adapter = this.resolveAdapter(request);
-        const method = CAPABILITY_METHOD[request.capability];
-        const fn = adapter[method];
-        if (!fn) {
-            throw new Error(`Adapter "${adapter.name}" is registered for "${request.capability}" but does not implement "${String(method)}"`);
+        // Determine execution path: explicit adapter > arbitrage router > legacy routing
+        let adapterResult;
+        let providerName;
+        let providerSelfHosted;
+        if (request.adapter) {
+            // Explicit adapter override — highest priority, bypasses router
+            const result = await this.executeWithAdapter(request.adapter, request.capability, request.input);
+            adapterResult = result.adapterResult;
+            providerName = result.providerName;
+            providerSelfHosted = result.selfHosted;
+        }
+        else if (this.router) {
+            // Arbitrage router — cost-optimized routing with GPU-first and 5xx failover.
+            // Margin tracking is handled by the meter event below, not the router's callback.
+            // The router's onMarginRecord callback is intentionally unused here — it fires
+            // only when sellPrice is passed to route(), which the socket never does.
+            const routerResult = await this.router.route({
+                capability: request.capability,
+                tenantId: request.tenantId,
+                input: request.input,
+                model: request.model,
+            });
+            adapterResult = routerResult;
+            providerName = routerResult.provider;
+            const routedAdapter = this.adapters.get(providerName);
+            if (!routedAdapter) {
+                throw new Error(`Router selected provider "${providerName}" but it is not registered in the socket. ` +
+                    `Always register adapters via socket.register() — never directly on the router.`);
+            }
+            providerSelfHosted = routedAdapter.selfHosted === true;
+        }
+        else {
+            // Legacy routing — first-match or tier-based
+            const adapter = this.resolveAdapter(request);
+            const result = await this.executeWithAdapter(adapter.name, request.capability, request.input);
+            adapterResult = result.adapterResult;
+            providerName = result.providerName;
+            providerSelfHosted = result.selfHosted;
         }
-        // Call the adapter — if it throws, no meter event is emitted.
-        const adapterResult = await fn.call(adapter, request.input);
         // Compute charge if the adapter didn't supply one
         const margin = request.margin ?? this.defaultMargin;
         const charge = adapterResult.charge ?? withMargin(adapterResult.cost, margin);
@@ -61,10 +102,10 @@ export class AdapterSocket {
             cost: isByok ? Credit.ZERO : adapterResult.cost,
             charge: isByok ? Credit.ZERO : charge,
             capability: request.capability,
-            provider: adapter.name,
+            provider: providerName,
             timestamp: Date.now(),
             ...(request.sessionId ? { sessionId: request.sessionId } : {}),
-            tier: isByok ? "byok" : adapter.selfHosted ? "wopr" : "branded",
+            tier: isByok ? "byok" : providerSelfHosted ? "wopr" : "branded",
         });
         return adapterResult.result;
     }
@@ -78,19 +119,25 @@ export class AdapterSocket {
         }
         return [...seen];
     }
-    /** Resolve which adapter to use for a request. */
-    resolveAdapter(request) {
-        // If a specific adapter is requested, use it (highest priority)
-        if (request.adapter) {
-            const adapter = this.adapters.get(request.adapter);
-            if (!adapter) {
-                throw new Error(`Adapter "${request.adapter}" is not registered`);
-            }
-            if (!adapter.capabilities.includes(request.capability)) {
-                throw new Error(`Adapter "${request.adapter}" does not support capability "${request.capability}"`);
-            }
-            return adapter;
+    /** Call a specific adapter by name. Used by explicit override and legacy routing. */
+    async executeWithAdapter(adapterName, capability, input) {
+        const adapter = this.adapters.get(adapterName);
+        if (!adapter) {
+            throw new Error(`Adapter "${adapterName}" is not registered`);
         }
+        if (!adapter.capabilities.includes(capability)) {
+            throw new Error(`Adapter "${adapterName}" does not support capability "${capability}"`);
+        }
+        const method = CAPABILITY_METHOD[capability];
+        const fn = adapter[method];
+        if (!fn) {
+            throw new Error(`Adapter "${adapter.name}" is registered for "${capability}" but does not implement "${String(method)}"`);
+        }
+        const adapterResult = await fn.call(adapter, input);
+        return { adapterResult, providerName: adapter.name, selfHosted: adapter.selfHosted === true };
+    }
+    /** Resolve which adapter to use for a request (legacy routing — pricingTier or first-match). */
+    resolveAdapter(request) {
         // If a pricing tier is specified, prefer adapters matching that tier
         if (request.pricingTier) {
             const preferSelfHosted = request.pricingTier === "standard";

package/dist/monetization/socket/socket.test.js

@@ -756,4 +756,182 @@ describe("AdapterSocket", () => {
             }
         });
     });
+    // ---------------------------------------------------------------------------
+    // execute -- ArbitrageRouter integration
+    // ---------------------------------------------------------------------------
+    describe("execute -- ArbitrageRouter integration", () => {
+        function stubRouter(overrides = {}) {
+            return {
+                route: vi.fn().mockResolvedValue({
+                    result: { text: "routed-response", model: "deepseek-chat", usage: { inputTokens: 50, outputTokens: 50 } },
+                    cost: Credit.fromDollars(0.001),
+                    provider: "deepseek",
+                }),
+                selectProvider: vi.fn(),
+                registerAdapter: vi.fn(),
+                ...overrides,
+            };
+        }
+        it("delegates to router when configured and no explicit adapter", async () => {
+            const meter = stubMeter();
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter, router });
+            // Register adapter so selfHosted lookup works
+            socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+            const result = await socket.execute({
+                tenantId: "t-1",
+                capability: "text-generation",
+                input: { prompt: "hello" },
+            });
+            expect(result.text).toBe("routed-response");
+            expect(router.route).toHaveBeenCalledOnce();
+            expect(meter.events).toHaveLength(1);
+            expect(meter.events[0].provider).toBe("deepseek");
+        });
+        it("passes model to router for model-level routing", async () => {
+            const meter = stubMeter();
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter, router });
+            socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+            await socket.execute({
+                tenantId: "t-1",
+                capability: "text-generation",
+                input: { prompt: "hello" },
+                model: "gemini-2.5-pro",
+            });
+            expect(router.route).toHaveBeenCalledWith(expect.objectContaining({ model: "gemini-2.5-pro" }));
+        });
+        it("explicit adapter override bypasses router", async () => {
+            const meter = stubMeter();
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter, router });
+            socket.register(stubAdapter({
+                name: "explicit-provider",
+                capabilities: ["transcription"],
+                async transcribe() {
+                    return {
+                        result: { text: "explicit-result", detectedLanguage: "en", durationSeconds: 5 },
+                        cost: Credit.fromDollars(0.05),
+                    };
+                },
+            }));
+            const result = await socket.execute({
+                tenantId: "t-1",
+                capability: "transcription",
+                input: { audioUrl: "https://example.com/audio.mp3" },
+                adapter: "explicit-provider",
+            });
+            expect(result.text).toBe("explicit-result");
+            expect(router.route).not.toHaveBeenCalled();
+            expect(meter.events[0].provider).toBe("explicit-provider");
+        });
+        it("emits BYOK zero cost/charge even with router", async () => {
+            const meter = stubMeter();
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter, router });
+            socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+            await socket.execute({
+                tenantId: "t-1",
+                capability: "text-generation",
+                input: { prompt: "hello" },
+                byok: true,
+            });
+            expect(meter.events).toHaveLength(1);
+            expect(meter.events[0].cost.isZero()).toBe(true);
+            expect(meter.events[0].charge.isZero()).toBe(true);
+            expect(meter.events[0].tier).toBe("byok");
+        });
+        it("applies margin to router result cost", async () => {
+            const meter = stubMeter();
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter, router, defaultMargin: 1.5 });
+            socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+            await socket.execute({
+                tenantId: "t-1",
+                capability: "text-generation",
+                input: { prompt: "hello" },
+            });
+            // Router returns cost $0.001, margin 1.5 → charge $0.0015
+            expect(meter.events[0].cost.toDollars()).toBe(0.001);
+            expect(meter.events[0].charge.toDollars()).toBe(0.0015);
+        });
+        it("sets tier to wopr when router picks self-hosted adapter", async () => {
+            const meter = stubMeter();
+            const router = stubRouter({
+                route: vi.fn().mockResolvedValue({
+                    result: { text: "gpu-response", model: "llama-3", usage: { inputTokens: 25, outputTokens: 25 } },
+                    cost: Credit.fromDollars(0.0001),
+                    provider: "self-hosted-llm",
+                }),
+                registerAdapter: vi.fn(),
+            });
+            const socket = new AdapterSocket({ meter, router });
+            socket.register(stubAdapter({ name: "self-hosted-llm", capabilities: ["text-generation"], selfHosted: true }));
+            await socket.execute({
+                tenantId: "t-1",
+                capability: "text-generation",
+                input: { prompt: "hello" },
+            });
+            expect(meter.events[0].tier).toBe("wopr");
+        });
+        it("sets tier to branded when router picks third-party adapter", async () => {
+            const meter = stubMeter();
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter, router });
+            socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"], selfHosted: false }));
+            await socket.execute({
+                tenantId: "t-1",
+                capability: "text-generation",
+                input: { prompt: "hello" },
+            });
+            expect(meter.events[0].tier).toBe("branded");
+        });
+        it("register() forwards adapter to router.registerAdapter()", () => {
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter: stubMeter(), router });
+            const adapter = stubAdapter({ name: "test-adapter" });
+            socket.register(adapter);
+            expect(router.registerAdapter).toHaveBeenCalledWith(adapter);
+        });
+        it("includes sessionId in meter event when routing via router", async () => {
+            const meter = stubMeter();
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter, router });
+            socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+            await socket.execute({
+                tenantId: "t-1",
+                capability: "text-generation",
+                input: { prompt: "hello" },
+                sessionId: "sess-99",
+            });
+            expect(meter.events[0].sessionId).toBe("sess-99");
+        });
+        it("per-request margin override works with router", async () => {
+            const meter = stubMeter();
+            const router = stubRouter();
+            const socket = new AdapterSocket({ meter, router, defaultMargin: 1.3 });
+            socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+            await socket.execute({
+                tenantId: "t-1",
+                capability: "text-generation",
+                input: { prompt: "hello" },
+                margin: 2.0,
+            });
+            // Router returns cost $0.001, margin override 2.0 → charge $0.002
+            expect(meter.events[0].charge.toDollars()).toBe(0.002);
+        });
+        it("falls back to legacy routing when no router configured", async () => {
+            const meter = stubMeter();
+            // No router — should use legacy resolveAdapter
+            const socket = new AdapterSocket({ meter });
+            socket.register(stubAdapter());
+            const result = await socket.execute({
+                tenantId: "t-1",
+                capability: "transcription",
+                input: { audioUrl: "https://example.com/audio.mp3" },
+            });
+            expect(result.text).toBe("hello");
+            expect(meter.events).toHaveLength(1);
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,7 +36,8 @@
     "./security": "./dist/security/index.js",
     "./setup": "./dist/setup/index.js",
     "./tenancy": "./dist/tenancy/index.js",
-    "./trpc": "./dist/trpc/index.js"
+    "./trpc": "./dist/trpc/index.js",
+    "./*": "./dist/*.js"
   },
   "scripts": {
     "build": "tsc",

package/src/monetization/adapters/rate-table.test.ts

@@ -23,11 +23,21 @@ describe("RATE_TABLE", () => {
     );
   });
 
-  it("standard tier is cheaper than premium tier for same capability", () => {
-    const standardTTS = RATE_TABLE.find((e) => e.capability === "tts" && e.tier === "standard");
-    const premiumTTS = RATE_TABLE.find((e) => e.capability === "tts" && e.tier === "premium");
+  it("standard tier is cheaper than premium tier for every capability", () => {
+    const capabilities = new Set(RATE_TABLE.map((e) => e.capability));
+    let compared = 0;
+
+    for (const capability of capabilities) {
+      const standard = RATE_TABLE.find((e) => e.capability === capability && e.tier === "standard");
+      const premium = RATE_TABLE.find((e) => e.capability === capability && e.tier === "premium");
+
+      if (standard && premium) {
+        expect(standard.effectivePrice).toBeLessThan(premium.effectivePrice);
+        compared++;
+      }
+    }
 
-    expect(standardTTS?.effectivePrice).toBeLessThan(premiumTTS?.effectivePrice ?? Infinity);
+    expect(compared).toBeGreaterThan(0);
   });
 
   it("effective price equals cost * margin", () => {

package/src/monetization/adapters/rate-table.ts

@@ -31,13 +31,16 @@ export interface RateEntry {
 }
 
 /**
- * The rate table.
+ * The rate table — admin-dashboard reference for pricing comparisons.
  *
  * Each capability has both standard and premium entries. Standard is always
  * cheaper than premium for the same capability (that's the whole point).
  *
- * Entries are added as self-hosted adapters are implemented. Currently only
- * TTS (Chatterbox vs ElevenLabs) is in the table.
+ * NOTE: Margin values here are reference defaults for dashboard display.
+ * Runtime margins are authoritative via `getMargin()` / `MARGIN_CONFIG_JSON`.
+ *
+ * NOTE: Text-generation rates are blended (approximate 50/50 input/output).
+ * Real costs vary by workload — output-heavy chat costs more than shown here.
  */
 export const RATE_TABLE: RateEntry[] = [
   // TTS - Text-to-Speech
@@ -47,8 +50,8 @@ export const RATE_TABLE: RateEntry[] = [
     provider: "chatterbox-tts",
     costPerUnit: 0.000002, // Amortized GPU cost
     billingUnit: "per-character",
-    margin: 1.2, // 20% margin
-    effectivePrice: 0.0000024, // $2.40 per 1M chars
+    margin: 1.2, // 20% — dashboard default; runtime uses getMargin()
+    effectivePrice: 0.0000024, // = costPerUnit * margin ($2.40 per 1M chars)
   },
   {
     capability: "tts",
@@ -56,8 +59,8 @@ export const RATE_TABLE: RateEntry[] = [
     provider: "elevenlabs",
     costPerUnit: 0.000015, // Third-party wholesale
     billingUnit: "per-character",
-    margin: 1.5, // 50% margin
-    effectivePrice: 0.0000225, // $22.50 per 1M chars
+    margin: 1.5, // 50% — dashboard default; runtime uses getMargin()
+    effectivePrice: 0.0000225, // = costPerUnit * margin ($22.50 per 1M chars)
   },
 
   // Text Generation
@@ -65,19 +68,19 @@ export const RATE_TABLE: RateEntry[] = [
     capability: "text-generation",
     tier: "standard",
     provider: "self-hosted-llm",
-    costPerUnit: 0.00000005, // Amortized GPU cost per token (H100)
+    costPerUnit: 0.00000005, // Amortized GPU cost per token (H100), blended in/out
     billingUnit: "per-token",
-    margin: 1.2, // 20% margin
-    effectivePrice: 0.00000006, // $0.06 per 1M tokens
+    margin: 1.2, // 20% — dashboard default; runtime uses getMargin()
+    effectivePrice: 0.00000006, // = costPerUnit * margin ($0.06 per 1M tokens)
   },
   {
     capability: "text-generation",
     tier: "premium",
     provider: "openrouter",
-    costPerUnit: 0.000001, // Fallback per-token rate
+    costPerUnit: 0.000001, // Blended per-token rate (variable across models)
     billingUnit: "per-token",
-    margin: 1.3, // 30% margin
-    effectivePrice: 0.0000013, // $1.30 per 1M tokens
+    margin: 1.3, // 30% — dashboard default; runtime uses getMargin()
+    effectivePrice: 0.0000013, // = costPerUnit * margin ($1.30 per 1M tokens)
   },
 
   // Future self-hosted adapters will add more entries here:

package/src/monetization/socket/socket.test.ts

@@ -10,9 +10,11 @@ import type {
   AdapterResult,
   EmbeddingsOutput,
   ProviderAdapter,
+  TextGenerationOutput,
   TranscriptionOutput,
   TTSOutput,
 } from "../adapters/types.js";
+import type { ArbitrageRouter } from "../arbitrage/router.js";
 import { BudgetChecker, type SpendLimits } from "../budget/budget-checker.js";
 import { AdapterSocket, type SocketConfig } from "./socket.js";
 
@@ -934,4 +936,222 @@ describe("AdapterSocket", () => {
       }
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // execute -- ArbitrageRouter integration
+  // ---------------------------------------------------------------------------
+
+  describe("execute -- ArbitrageRouter integration", () => {
+    function stubRouter(overrides: Partial<ArbitrageRouter> = {}): ArbitrageRouter {
+      return {
+        route: vi.fn().mockResolvedValue({
+          result: { text: "routed-response", model: "deepseek-chat", usage: { inputTokens: 50, outputTokens: 50 } },
+          cost: Credit.fromDollars(0.001),
+          provider: "deepseek",
+        }),
+        selectProvider: vi.fn(),
+        registerAdapter: vi.fn(),
+        ...overrides,
+      } as unknown as ArbitrageRouter;
+    }
+
+    it("delegates to router when configured and no explicit adapter", async () => {
+      const meter = stubMeter();
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter, router });
+
+      // Register adapter so selfHosted lookup works
+      socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+
+      const result = await socket.execute<TextGenerationOutput>({
+        tenantId: "t-1",
+        capability: "text-generation",
+        input: { prompt: "hello" },
+      });
+
+      expect(result.text).toBe("routed-response");
+      expect(router.route).toHaveBeenCalledOnce();
+      expect(meter.events).toHaveLength(1);
+      expect(meter.events[0].provider).toBe("deepseek");
+    });
+
+    it("passes model to router for model-level routing", async () => {
+      const meter = stubMeter();
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter, router });
+      socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+
+      await socket.execute<TextGenerationOutput>({
+        tenantId: "t-1",
+        capability: "text-generation",
+        input: { prompt: "hello" },
+        model: "gemini-2.5-pro",
+      });
+
+      expect(router.route).toHaveBeenCalledWith(expect.objectContaining({ model: "gemini-2.5-pro" }));
+    });
+
+    it("explicit adapter override bypasses router", async () => {
+      const meter = stubMeter();
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter, router });
+
+      socket.register(
+        stubAdapter({
+          name: "explicit-provider",
+          capabilities: ["transcription"],
+          async transcribe() {
+            return {
+              result: { text: "explicit-result", detectedLanguage: "en", durationSeconds: 5 },
+              cost: Credit.fromDollars(0.05),
+            };
+          },
+        }),
+      );
+
+      const result = await socket.execute<TranscriptionOutput>({
+        tenantId: "t-1",
+        capability: "transcription",
+        input: { audioUrl: "https://example.com/audio.mp3" },
+        adapter: "explicit-provider",
+      });
+
+      expect(result.text).toBe("explicit-result");
+      expect(router.route).not.toHaveBeenCalled();
+      expect(meter.events[0].provider).toBe("explicit-provider");
+    });
+
+    it("emits BYOK zero cost/charge even with router", async () => {
+      const meter = stubMeter();
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter, router });
+      socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+
+      await socket.execute<TextGenerationOutput>({
+        tenantId: "t-1",
+        capability: "text-generation",
+        input: { prompt: "hello" },
+        byok: true,
+      });
+
+      expect(meter.events).toHaveLength(1);
+      expect(meter.events[0].cost.isZero()).toBe(true);
+      expect(meter.events[0].charge.isZero()).toBe(true);
+      expect(meter.events[0].tier).toBe("byok");
+    });
+
+    it("applies margin to router result cost", async () => {
+      const meter = stubMeter();
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter, router, defaultMargin: 1.5 });
+      socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+
+      await socket.execute<TextGenerationOutput>({
+        tenantId: "t-1",
+        capability: "text-generation",
+        input: { prompt: "hello" },
+      });
+
+      // Router returns cost $0.001, margin 1.5 → charge $0.0015
+      expect(meter.events[0].cost.toDollars()).toBe(0.001);
+      expect(meter.events[0].charge.toDollars()).toBe(0.0015);
+    });
+
+    it("sets tier to wopr when router picks self-hosted adapter", async () => {
+      const meter = stubMeter();
+      const router = stubRouter({
+        route: vi.fn().mockResolvedValue({
+          result: { text: "gpu-response", model: "llama-3", usage: { inputTokens: 25, outputTokens: 25 } },
+          cost: Credit.fromDollars(0.0001),
+          provider: "self-hosted-llm",
+        }),
+        registerAdapter: vi.fn(),
+      } as unknown as Partial<ArbitrageRouter>);
+
+      const socket = new AdapterSocket({ meter, router });
+      socket.register(stubAdapter({ name: "self-hosted-llm", capabilities: ["text-generation"], selfHosted: true }));
+
+      await socket.execute<TextGenerationOutput>({
+        tenantId: "t-1",
+        capability: "text-generation",
+        input: { prompt: "hello" },
+      });
+
+      expect(meter.events[0].tier).toBe("wopr");
+    });
+
+    it("sets tier to branded when router picks third-party adapter", async () => {
+      const meter = stubMeter();
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter, router });
+      socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"], selfHosted: false }));
+
+      await socket.execute<TextGenerationOutput>({
+        tenantId: "t-1",
+        capability: "text-generation",
+        input: { prompt: "hello" },
+      });
+
+      expect(meter.events[0].tier).toBe("branded");
+    });
+
+    it("register() forwards adapter to router.registerAdapter()", () => {
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter: stubMeter(), router });
+
+      const adapter = stubAdapter({ name: "test-adapter" });
+      socket.register(adapter);
+
+      expect(router.registerAdapter).toHaveBeenCalledWith(adapter);
+    });
+
+    it("includes sessionId in meter event when routing via router", async () => {
+      const meter = stubMeter();
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter, router });
+      socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+
+      await socket.execute<TextGenerationOutput>({
+        tenantId: "t-1",
+        capability: "text-generation",
+        input: { prompt: "hello" },
+        sessionId: "sess-99",
+      });
+
+      expect(meter.events[0].sessionId).toBe("sess-99");
+    });
+
+    it("per-request margin override works with router", async () => {
+      const meter = stubMeter();
+      const router = stubRouter();
+      const socket = new AdapterSocket({ meter, router, defaultMargin: 1.3 });
+      socket.register(stubAdapter({ name: "deepseek", capabilities: ["text-generation"] }));
+
+      await socket.execute<TextGenerationOutput>({
+        tenantId: "t-1",
+        capability: "text-generation",
+        input: { prompt: "hello" },
+        margin: 2.0,
+      });
+
+      // Router returns cost $0.001, margin override 2.0 → charge $0.002
+      expect(meter.events[0].charge.toDollars()).toBe(0.002);
+    });
+
+    it("falls back to legacy routing when no router configured", async () => {
+      const meter = stubMeter();
+      // No router — should use legacy resolveAdapter
+      const socket = new AdapterSocket({ meter });
+      socket.register(stubAdapter());
+
+      const result = await socket.execute<TranscriptionOutput>({
+        tenantId: "t-1",
+        capability: "transcription",
+        input: { audioUrl: "https://example.com/audio.mp3" },
+      });
+
+      expect(result.text).toBe("hello");
+      expect(meter.events).toHaveLength(1);
+    });
+  });
 });

package/src/monetization/socket/socket.ts

@@ -4,12 +4,17 @@
  * The socket layer is the glue: it receives a capability request with a tenant ID,
  * selects the right adapter, calls it, emits a MeterEvent, and returns the result.
  * Adapters never touch metering or billing — that's the socket's job.
+ *
+ * When an ArbitrageRouter is configured, the socket delegates provider selection
+ * to the router (GPU-first, cost-sorted, 5xx failover) while keeping ownership
+ * of budget checks, metering, BYOK, and margin calculation.
  */
 
 import { Credit } from "@wopr-network/platform-core/credits";
 import type { MeterEmitter } from "@wopr-network/platform-core/metering";
 import type { AdapterCapability, AdapterResult, ProviderAdapter } from "../adapters/types.js";
 import { withMargin } from "../adapters/types.js";
+import type { ArbitrageRouter } from "../arbitrage/router.js";
 import type { BudgetChecker, SpendLimits } from "../budget/budget-checker.js";
 
 export interface SocketConfig {
@@ -19,6 +24,8 @@ export interface SocketConfig {
   budgetChecker?: BudgetChecker;
   /** Default margin multiplier (default: 1.3) */
   defaultMargin?: number;
+  /** ArbitrageRouter for cost-optimized routing (GPU-first, cheapest, 5xx failover) */
+  router?: ArbitrageRouter;
 }
 
 export interface SocketRequest {
@@ -28,8 +35,10 @@ export interface SocketRequest {
   capability: AdapterCapability;
   /** The request payload (matches the capability's input type) */
   input: unknown;
-  /** Optional: force a specific adapter by name */
+  /** Optional: force a specific adapter by name (highest priority, bypasses router) */
   adapter?: string;
+  /** Optional: model specifier for model-level routing (e.g., "gemini-2.5-pro") */
+  model?: string;
   /** Optional: override margin for this request */
   margin?: number;
   /** Optional: session ID for grouping events */
@@ -58,16 +67,22 @@ export class AdapterSocket {
   private readonly meter: MeterEmitter;
   private readonly budgetChecker?: BudgetChecker;
   private readonly defaultMargin: number;
+  private readonly router?: ArbitrageRouter;
 
   constructor(config: SocketConfig) {
     this.meter = config.meter;
     this.budgetChecker = config.budgetChecker;
     this.defaultMargin = config.defaultMargin ?? 1.3;
+    this.router = config.router;
   }
 
   /** Register an adapter. Overwrites any existing adapter with the same name. */
   register(adapter: ProviderAdapter): void {
     this.adapters.set(adapter.name, adapter);
+    // Also register with router so it can call the adapter during failover
+    if (this.router) {
+      this.router.registerAdapter(adapter);
+    }
   }
 
   /** Execute a capability request against the best adapter. */
@@ -85,19 +100,47 @@ export class AdapterSocket {
       }
     }
 
-    const adapter = this.resolveAdapter(request);
-    const method = CAPABILITY_METHOD[request.capability];
-    const fn = adapter[method] as ((input: unknown) => Promise<AdapterResult<T>>) | undefined;
+    // Determine execution path: explicit adapter > arbitrage router > legacy routing
+    let adapterResult: AdapterResult<T>;
+    let providerName: string;
+    let providerSelfHosted: boolean;
 
-    if (!fn) {
-      throw new Error(
-        `Adapter "${adapter.name}" is registered for "${request.capability}" but does not implement "${String(method)}"`,
-      );
+    if (request.adapter) {
+      // Explicit adapter override — highest priority, bypasses router
+      const result = await this.executeWithAdapter<T>(request.adapter, request.capability, request.input);
+      adapterResult = result.adapterResult;
+      providerName = result.providerName;
+      providerSelfHosted = result.selfHosted;
+    } else if (this.router) {
+      // Arbitrage router — cost-optimized routing with GPU-first and 5xx failover.
+      // Margin tracking is handled by the meter event below, not the router's callback.
+      // The router's onMarginRecord callback is intentionally unused here — it fires
+      // only when sellPrice is passed to route(), which the socket never does.
+      const routerResult = await this.router.route<T>({
+        capability: request.capability,
+        tenantId: request.tenantId,
+        input: request.input,
+        model: request.model,
+      });
+      adapterResult = routerResult;
+      providerName = routerResult.provider;
+      const routedAdapter = this.adapters.get(providerName);
+      if (!routedAdapter) {
+        throw new Error(
+          `Router selected provider "${providerName}" but it is not registered in the socket. ` +
+            `Always register adapters via socket.register() — never directly on the router.`,
+        );
+      }
+      providerSelfHosted = routedAdapter.selfHosted === true;
+    } else {
+      // Legacy routing — first-match or tier-based
+      const adapter = this.resolveAdapter(request);
+      const result = await this.executeWithAdapter<T>(adapter.name, request.capability, request.input);
+      adapterResult = result.adapterResult;
+      providerName = result.providerName;
+      providerSelfHosted = result.selfHosted;
     }
 
-    // Call the adapter — if it throws, no meter event is emitted.
-    const adapterResult = await fn.call(adapter, request.input);
-
     // Compute charge if the adapter didn't supply one
     const margin = request.margin ?? this.defaultMargin;
     const charge = adapterResult.charge ?? withMargin(adapterResult.cost, margin);
@@ -109,10 +152,10 @@ export class AdapterSocket {
       cost: isByok ? Credit.ZERO : adapterResult.cost,
       charge: isByok ? Credit.ZERO : charge,
       capability: request.capability,
-      provider: adapter.name,
+      provider: providerName,
       timestamp: Date.now(),
       ...(request.sessionId ? { sessionId: request.sessionId } : {}),
-      tier: isByok ? "byok" : adapter.selfHosted ? "wopr" : "branded",
+      tier: isByok ? "byok" : providerSelfHosted ? "wopr" : "branded",
     });
 
     return adapterResult.result;
@@ -129,20 +172,34 @@ export class AdapterSocket {
     return [...seen];
   }
 
-  /** Resolve which adapter to use for a request. */
-  private resolveAdapter(request: SocketRequest): ProviderAdapter {
-    // If a specific adapter is requested, use it (highest priority)
-    if (request.adapter) {
-      const adapter = this.adapters.get(request.adapter);
-      if (!adapter) {
-        throw new Error(`Adapter "${request.adapter}" is not registered`);
-      }
-      if (!adapter.capabilities.includes(request.capability)) {
-        throw new Error(`Adapter "${request.adapter}" does not support capability "${request.capability}"`);
-      }
-      return adapter;
+  /** Call a specific adapter by name. Used by explicit override and legacy routing. */
+  private async executeWithAdapter<T>(
+    adapterName: string,
+    capability: AdapterCapability,
+    input: unknown,
+  ): Promise<{ adapterResult: AdapterResult<T>; providerName: string; selfHosted: boolean }> {
+    const adapter = this.adapters.get(adapterName);
+    if (!adapter) {
+      throw new Error(`Adapter "${adapterName}" is not registered`);
+    }
+    if (!adapter.capabilities.includes(capability)) {
+      throw new Error(`Adapter "${adapterName}" does not support capability "${capability}"`);
     }
 
+    const method = CAPABILITY_METHOD[capability];
+    const fn = adapter[method] as ((input: unknown) => Promise<AdapterResult<T>>) | undefined;
+    if (!fn) {
+      throw new Error(
+        `Adapter "${adapter.name}" is registered for "${capability}" but does not implement "${String(method)}"`,
+      );
+    }
+
+    const adapterResult = await fn.call(adapter, input);
+    return { adapterResult, providerName: adapter.name, selfHosted: adapter.selfHosted === true };
+  }
+
+  /** Resolve which adapter to use for a request (legacy routing — pricingTier or first-match). */
+  private resolveAdapter(request: SocketRequest): ProviderAdapter {
     // If a pricing tier is specified, prefer adapters matching that tier
     if (request.pricingTier) {
       const preferSelfHosted = request.pricingTier === "standard";