@cloudpeers-jkl/model-router 0.3.0 → 0.4.0

package/README.md

@@ -59,6 +59,28 @@ In mcp, don't construct deps yourself — import the prewired composition from
 - **Uniform metering:** every call reports through the injected meter with a
   `router` metadata block — provider, tier, taskClass, gate.
 
+## Embed contract (0.4.0)
+
+A separate path from generate — `routeMessages` and `BackendAdapter` are
+unchanged. `routeEmbed({ texts, cloudpeers: { sovereignty_class } }, ctx,
+{ adapters: EmbedAdapter[], meter })` walks the adapters in order and returns
+`{ vectors, dims, model, provider, surface, gate, decision }`.
+
+- **Gate:** the shared `gateRule` (the same rule as `evaluateGate`), always
+  enforced (no monitor stage): `local_only` reaches only `edge` / `self_hosted`
+  surfaces, or a cloud provider listed in `MODEL_ROUTER_BAA_PROVIDERS`. No
+  permitted adapter → `RouterBlockedError` 412.
+- **Terminal errors:** no available adapter → `RouterError` 503
+  `no_embed_backend`. Every permitted adapter failed → 503
+  `embed_backends_failed`, with the last adapter error as `cause`. Exceptions:
+  when every failure was a 4xx `RouterError`, the last one is rethrown
+  unchanged; an aborted `ctx.signal` throws an `AbortError`.
+- **Edge:** `edgeEmbedDescriptor()` is an honest stub (`available()` false,
+  `embed()` throws). Edge embedding runs in the caller's browser
+  (cloudpeers-github `lib/edge/embeddings.ts`); the server never invokes it.
+- **Metering:** one `deps.meter` call per embed, `metadata.router` =
+  `{ op: 'embed', provider, surface, gate, dims, count, decision }`.
+
 ## Env (deploy-time control plane)
 
 `MODEL_ROUTER_TIER0_MODEL` / `MODEL_ROUTER_TIER0_URL` (Tier 0 self-hosted),

package/dist/adapters/anthropic-credentials.js

@@ -40,7 +40,7 @@ export function authMode(env = process.env) {
     return 'none';
 }
 export class AnthropicCredentials {
-    constructor(env = process.env, deps = { fetch: (...a) => globalThis.fetch(...a), now: () => Date.now() }) {
+    constructor(env = process.env, deps = { fetch: (input, init) => globalThis.fetch(input, init), now: () => Date.now() }) {
         this.env = env;
         this.deps = deps;
         this.cached = null;

package/dist/adapters/edge.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Edge (on-device) embed descriptor — surface: edge. Honest stub.
+ *
+ * The real edge execution runs in the visitor's browser (cloudpeers-github
+ * `lib/edge/embeddings.ts`: ONNX Runtime Web, all-MiniLM-L6-v2 q8, 384 dims,
+ * weights served same-origin). The text never reaches a server, so the
+ * server never invokes this adapter: `available()` is false and `embed()`
+ * throws. It exists so the capability surface and the gate can name the edge
+ * surface truthfully — `cloud:false`, therefore permitted for local_only —
+ * and so browser-side metering rows can carry a provider the router knows.
+ *
+ * A client-side embedder (browser/app) may construct its own EmbedAdapter
+ * with id 'edge' and surface 'edge' that does run locally, and pass it to
+ * routeEmbed in that runtime.
+ */
+import type { EmbedAdapter } from '../types.js';
+/**
+ * The model the browser edge embedder ships today.
+ * Keep in sync with cloudpeers-github `lib/edge/embeddings.ts` EDGE_MODEL (id, dims).
+ */
+export declare const EDGE_EMBED_MODEL: {
+    readonly id: "Xenova/all-MiniLM-L6-v2";
+    readonly dims: 384;
+    readonly license: "Apache-2.0";
+};
+export declare function edgeEmbedDescriptor(): EmbedAdapter;

package/dist/adapters/edge.js

@@ -0,0 +1,16 @@
+/**
+ * The model the browser edge embedder ships today.
+ * Keep in sync with cloudpeers-github `lib/edge/embeddings.ts` EDGE_MODEL (id, dims).
+ */
+export const EDGE_EMBED_MODEL = { id: 'Xenova/all-MiniLM-L6-v2', dims: 384, license: 'Apache-2.0' };
+export function edgeEmbedDescriptor() {
+    return {
+        id: 'edge',
+        display_name: 'on-device embedder (runs in the caller runtime, never on a server)',
+        surface: 'edge',
+        available: () => false,
+        async embed(_texts, _ctx) {
+            throw new Error('edge embedding executes on the caller device; the server never invokes it');
+        },
+    };
+}

package/dist/capabilities.d.ts

@@ -4,9 +4,9 @@
  * reflects truth"). Embedded-library v1 exposes this as a function; the
  * mcp server surfaces it on its discovery endpoints.
  */
-import type { BackendAdapter, BackendSurface, Provider, ToolUseCapability } from './types.js';
+import type { BackendAdapter, BackendSurface, GenerateProvider, ToolUseCapability } from './types.js';
 export interface BackendCapabilities {
-    id: Provider;
+    id: GenerateProvider;
     display_name: string;
     surface: BackendSurface;
     available: boolean;
@@ -15,4 +15,4 @@ export interface BackendCapabilities {
     supports_prompt_caching: boolean;
     tool_use: ToolUseCapability;
 }
-export declare function capabilityMatrix(adapters: Partial<Record<Provider, BackendAdapter>>): BackendCapabilities[];
+export declare function capabilityMatrix(adapters: Partial<Record<GenerateProvider, BackendAdapter>>): BackendCapabilities[];

package/dist/embed.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Embed contract — `routeEmbed` (edge-inference Phase 1, 2026-09-24).
+ *
+ * Deliberately separate from the generate path (routeMessages / BackendAdapter
+ * / tier chain), which is untouched. Flow: validate (400) → order adapters
+ * (advisory backend_hint) → per adapter: availability → privacy gate →
+ * embed → shape check (a malformed result escalates to the next adapter) →
+ * uniform metering through the injected meter.
+ *
+ * Gate: the same rule as `evaluateGate` — for local_only, cloud surfaces are
+ * permitted only through a MODEL_ROUTER_BAA_PROVIDERS provider; edge and
+ * self_hosted (cloud:false) are always permitted — but always in ENFORCE
+ * mode. There is no monitor stage for embed: this path has no legacy callers
+ * to keep working, so it fails closed from its first release. A local_only
+ * embed with no permitted adapter throws RouterBlockedError (412).
+ */
+import { z } from 'zod';
+import type { EmbedAdapter, EmbedDeps, EmbedRequest, EmbedRouteResult, GateOutcome, SovereigntyClass } from './types.js';
+export declare const MAX_EMBED_TEXTS = 256;
+export declare const MAX_EMBED_TEXT_CHARS = 8192;
+export declare const embedRequestSchema: z.ZodObject<{
+    texts: z.ZodArray<z.ZodString, "many">;
+    cloudpeers: z.ZodObject<{
+        v: z.ZodOptional<z.ZodLiteral<1>>;
+        sovereignty_class: z.ZodEnum<["local_only", "aggregate_only", "externalizable"]>;
+        backend_hint: z.ZodOptional<z.ZodEnum<["selfhosted", "gemini", "anthropic", "edge"]>>;
+    }, "strict", z.ZodTypeAny, {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | "edge" | undefined;
+    }, {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | "edge" | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    texts: string[];
+    cloudpeers: {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | "edge" | undefined;
+    };
+}, {
+    texts: string[];
+    cloudpeers: {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | "edge" | undefined;
+    };
+}>;
+/** Parse + narrow. Throws RouterValidationError (statusCode 400) on shape errors. */
+export declare function parseEmbedRequest(input: unknown): EmbedRequest;
+export interface EmbedContext {
+    userId: string;
+    serviceId: string;
+    /** Metering label (token-tracker `operation`). */
+    operation: string;
+    metadata?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+/**
+ * The embed gate: evaluateGate's rule with the monitor stage removed.
+ * `would_block` (monitor) is promoted to `blocked`.
+ */
+export declare function evaluateEmbedGate(sovereigntyClass: SovereigntyClass, adapter: EmbedAdapter): GateOutcome;
+export declare function routeEmbed(input: unknown, ctx: EmbedContext, deps: EmbedDeps): Promise<EmbedRouteResult>;

package/dist/embed.js

@@ -0,0 +1,176 @@
+/**
+ * Embed contract — `routeEmbed` (edge-inference Phase 1, 2026-09-24).
+ *
+ * Deliberately separate from the generate path (routeMessages / BackendAdapter
+ * / tier chain), which is untouched. Flow: validate (400) → order adapters
+ * (advisory backend_hint) → per adapter: availability → privacy gate →
+ * embed → shape check (a malformed result escalates to the next adapter) →
+ * uniform metering through the injected meter.
+ *
+ * Gate: the same rule as `evaluateGate` — for local_only, cloud surfaces are
+ * permitted only through a MODEL_ROUTER_BAA_PROVIDERS provider; edge and
+ * self_hosted (cloud:false) are always permitted — but always in ENFORCE
+ * mode. There is no monitor stage for embed: this path has no legacy callers
+ * to keep working, so it fails closed from its first release. A local_only
+ * embed with no permitted adapter throws RouterBlockedError (412).
+ */
+import { z } from 'zod';
+import { RouterBlockedError, RouterError, RouterValidationError } from './errors.js';
+import { gateRule } from './policy.js';
+export const MAX_EMBED_TEXTS = 256;
+export const MAX_EMBED_TEXT_CHARS = 8192;
+const PROVIDERS = ['selfhosted', 'gemini', 'anthropic', 'edge'];
+export const embedRequestSchema = z
+    .object({
+    texts: z.array(z.string().min(1).max(MAX_EMBED_TEXT_CHARS)).min(1).max(MAX_EMBED_TEXTS),
+    cloudpeers: z
+        .object({
+        v: z.literal(1).optional(),
+        sovereignty_class: z.enum(['local_only', 'aggregate_only', 'externalizable']),
+        backend_hint: z.enum(PROVIDERS).optional(),
+    })
+        .strict(),
+})
+    .strict();
+/** Parse + narrow. Throws RouterValidationError (statusCode 400) on shape errors. */
+export function parseEmbedRequest(input) {
+    const parsed = embedRequestSchema.safeParse(input);
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+        throw new RouterValidationError(`Invalid embed request: ${detail}`);
+    }
+    return parsed.data;
+}
+/**
+ * The embed gate: evaluateGate's rule with the monitor stage removed.
+ * `would_block` (monitor) is promoted to `blocked`.
+ */
+export function evaluateEmbedGate(sovereigntyClass, adapter) {
+    const outcome = gateRule(sovereigntyClass, adapter.surface === 'cloud', adapter.id);
+    return outcome === 'would_block' ? 'blocked' : outcome;
+}
+function key(a) {
+    return `embed/${a.id}`;
+}
+function ordered(adapters, hint) {
+    if (!hint)
+        return adapters;
+    return [...adapters.filter((a) => a.id === hint), ...adapters.filter((a) => a.id !== hint)];
+}
+function wellFormed(out, n) {
+    return (Array.isArray(out.vectors) &&
+        out.vectors.length === n &&
+        Number.isInteger(out.dims) &&
+        out.dims > 0 &&
+        out.vectors.every((v) => v.length === out.dims));
+}
+function abortError() {
+    const aborted = new Error('embed request aborted');
+    aborted.name = 'AbortError';
+    return aborted;
+}
+export async function routeEmbed(input, ctx, deps) {
+    const req = parseEmbedRequest(input);
+    const sov = req.cloudpeers.sovereignty_class;
+    const walked = [];
+    const blockedCloud = [];
+    let escalations = 0;
+    let lastError = null;
+    /** True while every adapter failure so far has been a caller-side (4xx) RouterError. */
+    let allClientErrors = true;
+    const decisionFor = (chosen) => {
+        const d = {
+            sovereignty_class: sov,
+            eligible_set: [...walked],
+            chosen_backend: chosen ? key(chosen) : null,
+        };
+        if (sov === 'local_only') {
+            d.no_egress_proof = {
+                gate_enforced: true,
+                cloud_tiers_blocked: [...blockedCloud],
+                chosen_backend_cloud: chosen ? chosen.surface === 'cloud' : false,
+            };
+        }
+        return d;
+    };
+    for (const adapter of ordered(deps.adapters, req.cloudpeers.backend_hint)) {
+        if (ctx.signal?.aborted)
+            throw abortError();
+        if (!adapter.available())
+            continue;
+        const gate = evaluateEmbedGate(sov, adapter);
+        if (gate === 'blocked') {
+            blockedCloud.push(key(adapter));
+            console.warn(`[privacy-gate] BLOCKED local_only → ${key(adapter)} (op=${ctx.operation} svc=${ctx.serviceId})`);
+            continue;
+        }
+        walked.push(key(adapter));
+        const started = performance.now();
+        try {
+            const out = await adapter.embed(req.texts, {
+                userId: ctx.userId,
+                serviceId: ctx.serviceId,
+                operation: ctx.operation,
+                signal: ctx.signal,
+            });
+            if (!wellFormed(out, req.texts.length))
+                throw new Error('malformed embed result (vector count or dims)');
+            const latency_ms = Math.round(performance.now() - started);
+            const decision = decisionFor(adapter);
+            await deps
+                .meter({
+                userId: ctx.userId,
+                serviceId: ctx.serviceId,
+                model: out.model,
+                operation: ctx.operation,
+                promptTokens: out.tokens_in ?? 0,
+                completionTokens: 0,
+                metadata: {
+                    ...ctx.metadata,
+                    router: {
+                        op: 'embed',
+                        provider: adapter.id,
+                        surface: adapter.surface,
+                        gate,
+                        dims: out.dims,
+                        count: out.vectors.length,
+                        decision,
+                    },
+                },
+            })
+                .catch((err) => console.error('[model-router] embed metering failed (non-blocking):', err?.message));
+            return {
+                ...out,
+                provider: adapter.id,
+                surface: adapter.surface,
+                gate,
+                latency_ms,
+                escalations,
+                decision,
+            };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (!(lastError instanceof RouterError && lastError.statusCode >= 400 && lastError.statusCode < 500)) {
+                allClientErrors = false;
+            }
+            escalations++;
+            console.warn(`[model-router] ${key(adapter)} failed (op=${ctx.operation}): ${lastError.message}`);
+        }
+    }
+    console.warn(`[stage1-decision] ${JSON.stringify(decisionFor(null))}`);
+    if (sov === 'local_only' && walked.length === 0) {
+        throw new RouterBlockedError('No permitted embed backend for local_only (edge/self_hosted unavailable, no BAA provider)', 412, 'routing_blocked');
+    }
+    if (ctx.signal?.aborted)
+        throw abortError();
+    if (lastError) {
+        // Every failure was the caller's (4xx RouterError): surface it unchanged, not as an outage.
+        if (allClientErrors)
+            throw lastError;
+        const unavailable = new RouterError(`Every permitted embed backend failed; last: ${lastError.message}`, 503, 'embed_backends_failed');
+        unavailable.cause = lastError;
+        throw unavailable;
+    }
+    throw new RouterError('No available embed backend', 503, 'no_embed_backend');
+}

package/dist/index.d.ts

@@ -9,12 +9,15 @@ export { RouterError, RouterValidationError, RouterBlockedError } from './errors
 export { parseRouterRequest, routerMessagesRequestSchema, cloudpeersEnvelopeSchema } from './schema.js';
 export { TIERS, TASK_ROUTES, evaluateGate, gateEnforced, resolveChain, routingPolicyArtifact } from './policy.js';
 export { routeModel, routeMessages, routeMessagesStream } from './router.js';
+export { routeEmbed, parseEmbedRequest, embedRequestSchema, evaluateEmbedGate } from './embed.js';
+export type { EmbedContext } from './embed.js';
+export { edgeEmbedDescriptor, EDGE_EMBED_MODEL } from './adapters/edge.js';
 export type { RouteContext, MessagesStreamResult } from './router.js';
 export { capabilityMatrix } from './capabilities.js';
 export type { BackendCapabilities } from './capabilities.js';
 export { anthropicAdapter } from './adapters/anthropic.js';
 export { geminiAdapter, anthropicToGeminiContents, geminiResponseToAnthropic, geminiChunksToSSE, geminiFinishToStopReason, } from './adapters/gemini.js';
 export { selfhostedAdapter, messagesToPrompt } from './adapters/selfhosted.js';
-import type { BackendAdapter, Provider } from './types.js';
+import type { BackendAdapter, GenerateProvider } from './types.js';
 /** The approved backend set (A1.2): selfhosted, gemini, anthropic. No OpenAI. */
-export declare function defaultBackendAdapters(): Record<Provider, BackendAdapter>;
+export declare function defaultBackendAdapters(): Record<GenerateProvider, BackendAdapter>;

package/dist/index.js

@@ -9,6 +9,8 @@ export { RouterError, RouterValidationError, RouterBlockedError } from './errors
 export { parseRouterRequest, routerMessagesRequestSchema, cloudpeersEnvelopeSchema } from './schema.js';
 export { TIERS, TASK_ROUTES, evaluateGate, gateEnforced, resolveChain, routingPolicyArtifact } from './policy.js';
 export { routeModel, routeMessages, routeMessagesStream } from './router.js';
+export { routeEmbed, parseEmbedRequest, embedRequestSchema, evaluateEmbedGate } from './embed.js';
+export { edgeEmbedDescriptor, EDGE_EMBED_MODEL } from './adapters/edge.js';
 export { capabilityMatrix } from './capabilities.js';
 export { anthropicAdapter } from './adapters/anthropic.js';
 export { geminiAdapter, anthropicToGeminiContents, geminiResponseToAnthropic, geminiChunksToSSE, geminiFinishToStopReason, } from './adapters/gemini.js';

package/dist/policy.d.ts

@@ -10,6 +10,8 @@ export declare function gateEnforced(): boolean;
  * Never triggers for aggregate_only/externalizable (spec scope: local_only).
  */
 export declare function evaluateGate(sovereigntyClass: SovereigntyClass, tier: TierDef): GateOutcome;
+/** The gate rule itself, shared by evaluateGate (tiers) and evaluateEmbedGate (embed adapters). */
+export declare function gateRule(sovereigntyClass: SovereigntyClass, cloud: boolean, provider: Provider): GateOutcome;
 /**
  * §4 — the caller's `model` is honored when it belongs to the selected
  * tier's provider family (a gemini caller may pick flash vs pro); otherwise

package/dist/policy.js

@@ -99,9 +99,13 @@ export function gateEnforced() {
  * Never triggers for aggregate_only/externalizable (spec scope: local_only).
  */
 export function evaluateGate(sovereigntyClass, tier) {
-    if (sovereigntyClass !== 'local_only' || !tier.cloud)
+    return gateRule(sovereigntyClass, tier.cloud, tier.provider);
+}
+/** The gate rule itself, shared by evaluateGate (tiers) and evaluateEmbedGate (embed adapters). */
+export function gateRule(sovereigntyClass, cloud, provider) {
+    if (sovereigntyClass !== 'local_only' || !cloud)
         return 'allowed';
-    if (baaProviders().has(tier.provider))
+    if (baaProviders().has(provider))
         return 'allowed'; // Stage 2 governed egress
     return gateEnforced() ? 'blocked' : 'would_block'; // Stage 3 : Stage 1
 }

package/dist/schema.d.ts

@@ -35,11 +35,11 @@ export declare const cloudpeersEnvelopeSchema: z.ZodObject<{
     sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
     task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
     v?: 1 | undefined;
+    backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
     mandate_id?: string | undefined;
     policy_id?: string | undefined;
     attribution_chain?: string[] | undefined;
     trust_level?: "L0" | "L1" | "L2" | "L3" | "L4" | "L5" | undefined;
-    backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
     tool_use_strict?: boolean | undefined;
     byok?: {
         provider: string;
@@ -49,11 +49,11 @@ export declare const cloudpeersEnvelopeSchema: z.ZodObject<{
     sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
     task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
     v?: 1 | undefined;
+    backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
     mandate_id?: string | undefined;
     policy_id?: string | undefined;
     attribution_chain?: string[] | undefined;
     trust_level?: "L0" | "L1" | "L2" | "L3" | "L4" | "L5" | undefined;
-    backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
     tool_use_strict?: boolean | undefined;
     byok?: {
         provider: string;
@@ -125,11 +125,11 @@ export declare const routerMessagesRequestSchema: z.ZodObject<{
         sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
         task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
         v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         mandate_id?: string | undefined;
         policy_id?: string | undefined;
         attribution_chain?: string[] | undefined;
         trust_level?: "L0" | "L1" | "L2" | "L3" | "L4" | "L5" | undefined;
-        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         tool_use_strict?: boolean | undefined;
         byok?: {
             provider: string;
@@ -139,11 +139,11 @@ export declare const routerMessagesRequestSchema: z.ZodObject<{
         sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
         task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
         v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         mandate_id?: string | undefined;
         policy_id?: string | undefined;
         attribution_chain?: string[] | undefined;
         trust_level?: "L0" | "L1" | "L2" | "L3" | "L4" | "L5" | undefined;
-        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         tool_use_strict?: boolean | undefined;
         byok?: {
             provider: string;
@@ -215,11 +215,11 @@ export declare const routerMessagesRequestSchema: z.ZodObject<{
         sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
         task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
         v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         mandate_id?: string | undefined;
         policy_id?: string | undefined;
         attribution_chain?: string[] | undefined;
         trust_level?: "L0" | "L1" | "L2" | "L3" | "L4" | "L5" | undefined;
-        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         tool_use_strict?: boolean | undefined;
         byok?: {
             provider: string;
@@ -229,11 +229,11 @@ export declare const routerMessagesRequestSchema: z.ZodObject<{
         sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
         task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
         v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         mandate_id?: string | undefined;
         policy_id?: string | undefined;
         attribution_chain?: string[] | undefined;
         trust_level?: "L0" | "L1" | "L2" | "L3" | "L4" | "L5" | undefined;
-        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         tool_use_strict?: boolean | undefined;
         byok?: {
             provider: string;
@@ -305,11 +305,11 @@ export declare const routerMessagesRequestSchema: z.ZodObject<{
         sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
         task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
         v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         mandate_id?: string | undefined;
         policy_id?: string | undefined;
         attribution_chain?: string[] | undefined;
         trust_level?: "L0" | "L1" | "L2" | "L3" | "L4" | "L5" | undefined;
-        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         tool_use_strict?: boolean | undefined;
         byok?: {
             provider: string;
@@ -319,11 +319,11 @@ export declare const routerMessagesRequestSchema: z.ZodObject<{
         sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
         task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
         v?: 1 | undefined;
+        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         mandate_id?: string | undefined;
         policy_id?: string | undefined;
         attribution_chain?: string[] | undefined;
         trust_level?: "L0" | "L1" | "L2" | "L3" | "L4" | "L5" | undefined;
-        backend_hint?: "selfhosted" | "gemini" | "anthropic" | undefined;
         tool_use_strict?: boolean | undefined;
         byok?: {
             provider: string;

package/dist/types.d.ts

@@ -16,7 +16,15 @@
 export type SovereigntyClass = 'local_only' | 'aggregate_only' | 'externalizable';
 /** Static task classes (confidence v1 — no learned complexity classifier). */
 export type TaskClass = 'extraction' | 'classification' | 'coaching' | 'reasoning' | 'synthesis';
-export type Provider = 'selfhosted' | 'gemini' | 'anthropic';
+/**
+ * `edge` = on-device execution in the caller's browser/app (LiteRT / ONNX
+ * WASM). It appears only on the embed contract (`EmbedAdapter`); the
+ * generate path (tier table, routing-policy.json, backend_hint) never
+ * resolves to it.
+ */
+export type Provider = 'selfhosted' | 'gemini' | 'anthropic' | 'edge';
+/** Providers the generate path (tier chain / BackendAdapter) can resolve to. */
+export type GenerateProvider = Exclude<Provider, 'edge'>;
 export type BackendSurface = 'cloud' | 'self_hosted' | 'edge';
 export type GateOutcome = 'allowed' | 'would_block' | 'blocked';
 export interface TextBlock {
@@ -60,7 +68,7 @@ export interface CloudpeersEnvelope {
     /** Lab Zero delegation grant. */
     trust_level?: 'L0' | 'L1' | 'L2' | 'L3' | 'L4' | 'L5';
     /** Advisory backend selector — reorders the tier chain, never bypasses the gate. */
-    backend_hint?: Provider;
+    backend_hint?: GenerateProvider;
     /** §8.2 — reject 422 instead of degrading when tool-use support is missing. */
     tool_use_strict?: boolean;
     /** §10.2 — accepted by the schema, REJECTED by the router (deferred per A1.2). */
@@ -138,7 +146,7 @@ export interface InvocationContext {
     signal?: AbortSignal;
 }
 export interface BackendAdapter {
-    id: Provider;
+    id: GenerateProvider;
     display_name: string;
     surface: BackendSurface;
     supports_streaming: boolean;
@@ -189,7 +197,7 @@ export interface PolicyVerdict {
 export interface RouterHooks {
     verifyMandate?: (mandateId: string) => Promise<MandateVerdict>;
     applyPolicy?: (policyId: string, call: {
-        backend_id: Provider;
+        backend_id: GenerateProvider;
         model: string;
         tier: number;
     }) => Promise<PolicyVerdict>;
@@ -201,7 +209,7 @@ export interface RouterHooks {
     writeAttribution?: (chain: string[], usage: UsageEvent) => Promise<void>;
 }
 export interface RouterDeps {
-    adapters: Partial<Record<Provider, BackendAdapter>>;
+    adapters: Partial<Record<GenerateProvider, BackendAdapter>>;
     meter: Meter;
     quota: QuotaFn;
     hooks?: RouterHooks;
@@ -225,7 +233,7 @@ export interface RouterRequest {
 }
 export interface RouterResult {
     text: string;
-    provider: Provider;
+    provider: GenerateProvider;
     model: string;
     tier: number;
     escalations: number;
@@ -260,7 +268,7 @@ export interface StageOneDecision {
 }
 export interface MessagesRouteResult {
     response: AnthropicMessagesResponse;
-    provider: Provider;
+    provider: GenerateProvider;
     model: string;
     tier: number;
     escalations: number;
@@ -271,8 +279,47 @@ export interface MessagesRouteResult {
 }
 export interface TierDef {
     tier: number;
-    provider: Provider;
+    provider: GenerateProvider;
     model: string;
     /** Cloud tiers are subject to the local_only privacy gate. */
     cloud: boolean;
 }
+export interface EmbedOutput {
+    vectors: number[][];
+    dims: number;
+    model: string;
+    /** Provider-reported input tokens, when the backend reports them. */
+    tokens_in?: number;
+}
+export interface EmbedAdapter {
+    id: Provider;
+    display_name: string;
+    surface: BackendSurface;
+    /** Deploy-time availability (key/endpoint configured / executable here). */
+    available(): boolean;
+    embed(texts: string[], ctx: InvocationContext): Promise<EmbedOutput>;
+}
+export interface EmbedEnvelope {
+    v?: 1;
+    sovereignty_class: SovereigntyClass;
+    /** Advisory: moves this provider's adapter to the front; never bypasses the gate. */
+    backend_hint?: Provider;
+}
+export interface EmbedRequest {
+    texts: string[];
+    cloudpeers: EmbedEnvelope;
+}
+export interface EmbedDeps {
+    /** Candidate adapters in preference order. */
+    adapters: EmbedAdapter[];
+    meter: Meter;
+}
+export interface EmbedRouteResult extends EmbedOutput {
+    provider: Provider;
+    surface: BackendSurface;
+    gate: GateOutcome;
+    latency_ms: number;
+    /** Adapters that failed before this one served. */
+    escalations: number;
+    decision: StageOneDecision;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudpeers-jkl/model-router",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "cloudpeers inference router — embedded library (no central data plane). Sovereignty privacy gate, static task-class routing, Anthropic Messages lingua franca, uniform metering.",
   "type": "module",
   "license": "MIT",