@cloudpeers-jkl/model-router 0.2.2 → 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.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Anthropic credentials for the router adapter — Workload Identity Federation first,
+ * static API key as the fallback.
+ *
+ * Federation (docs: platform.claude.com/docs/en/manage-claude/wif-providers/gcp): the Cloud Run
+ * service account's Google-signed identity token (metadata server, audience
+ * https://api.anthropic.com) is exchanged at POST /v1/oauth/token (RFC 7523 jwt-bearer) for a
+ * short-lived `sk-ant-oat01-…` access token bound to an Anthropic service account. No static
+ * secret exists to mint, store, rotate, or leak. Register: docs/MODEL_PROVIDER_POSTURE_REGISTER.
+ *
+ * Precedence follows the Anthropic SDKs: ANTHROPIC_API_KEY, when set, wins over federation.
+ * Migration therefore ends by UNSETTING the key on the service (docs § Migrate from API keys).
+ *
+ * Federation env (all four required; the workspace id is required because our rules cover
+ * more than one workspace):
+ *   ANTHROPIC_FEDERATION_RULE_ID   fdrl_…
+ *   ANTHROPIC_ORGANIZATION_ID      org uuid
+ *   ANTHROPIC_SERVICE_ACCOUNT_ID   svac_…
+ *   ANTHROPIC_WORKSPACE_ID         wrkspc_…
+ * Optional: ANTHROPIC_IDENTITY_TOKEN_FILE (a projected token file instead of the metadata server).
+ */
+export type AuthMode = 'api_key' | 'federation' | 'none';
+export interface FederationConfig {
+    ruleId: string;
+    organizationId: string;
+    serviceAccountId: string;
+    workspaceId?: string;
+    identityTokenFile?: string;
+}
+export declare function federationConfig(env?: NodeJS.ProcessEnv): FederationConfig | null;
+/** Which credential source the adapter will use — mirrors the SDK precedence (key above federation). */
+export declare function authMode(env?: NodeJS.ProcessEnv): AuthMode;
+export interface CredentialDeps {
+    fetch: typeof fetch;
+    now: () => number;
+    readFile?: (path: string) => Promise<string>;
+}
+export declare class AnthropicCredentials {
+    private readonly env;
+    private readonly deps;
+    private cached;
+    private inflight;
+    constructor(env?: NodeJS.ProcessEnv, deps?: CredentialDeps);
+    mode(): AuthMode;
+    /** Headers to send on a Messages call. Throws when neither credential source is configured. */
+    headers(): Promise<Record<string, string>>;
+    private accessToken;
+    private identityToken;
+    private exchange;
+}
+export declare function sharedCredentials(): AnthropicCredentials;
+/** Test hook. */
+export declare function __resetSharedCredentials(): void;

package/dist/adapters/anthropic-credentials.js

@@ -0,0 +1,122 @@
+/**
+ * Anthropic credentials for the router adapter — Workload Identity Federation first,
+ * static API key as the fallback.
+ *
+ * Federation (docs: platform.claude.com/docs/en/manage-claude/wif-providers/gcp): the Cloud Run
+ * service account's Google-signed identity token (metadata server, audience
+ * https://api.anthropic.com) is exchanged at POST /v1/oauth/token (RFC 7523 jwt-bearer) for a
+ * short-lived `sk-ant-oat01-…` access token bound to an Anthropic service account. No static
+ * secret exists to mint, store, rotate, or leak. Register: docs/MODEL_PROVIDER_POSTURE_REGISTER.
+ *
+ * Precedence follows the Anthropic SDKs: ANTHROPIC_API_KEY, when set, wins over federation.
+ * Migration therefore ends by UNSETTING the key on the service (docs § Migrate from API keys).
+ *
+ * Federation env (all four required; the workspace id is required because our rules cover
+ * more than one workspace):
+ *   ANTHROPIC_FEDERATION_RULE_ID   fdrl_…
+ *   ANTHROPIC_ORGANIZATION_ID      org uuid
+ *   ANTHROPIC_SERVICE_ACCOUNT_ID   svac_…
+ *   ANTHROPIC_WORKSPACE_ID         wrkspc_…
+ * Optional: ANTHROPIC_IDENTITY_TOKEN_FILE (a projected token file instead of the metadata server).
+ */
+const TOKEN_URL = 'https://api.anthropic.com/v1/oauth/token';
+const AUDIENCE = 'https://api.anthropic.com';
+const METADATA_URL = `http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${encodeURIComponent(AUDIENCE)}&format=full`;
+const ADVISORY_REFRESH_MS = 120000; // refresh two minutes before expiry (SDK schedule)
+export function federationConfig(env = process.env) {
+    const ruleId = env.ANTHROPIC_FEDERATION_RULE_ID;
+    const organizationId = env.ANTHROPIC_ORGANIZATION_ID;
+    const serviceAccountId = env.ANTHROPIC_SERVICE_ACCOUNT_ID;
+    if (!ruleId || !organizationId || !serviceAccountId)
+        return null;
+    return { ruleId, organizationId, serviceAccountId, workspaceId: env.ANTHROPIC_WORKSPACE_ID, identityTokenFile: env.ANTHROPIC_IDENTITY_TOKEN_FILE };
+}
+/** Which credential source the adapter will use — mirrors the SDK precedence (key above federation). */
+export function authMode(env = process.env) {
+    if (env.ANTHROPIC_API_KEY)
+        return 'api_key';
+    if (federationConfig(env))
+        return 'federation';
+    return 'none';
+}
+export class AnthropicCredentials {
+    constructor(env = process.env, deps = { fetch: (input, init) => globalThis.fetch(input, init), now: () => Date.now() }) {
+        this.env = env;
+        this.deps = deps;
+        this.cached = null;
+        this.inflight = null;
+    }
+    mode() { return authMode(this.env); }
+    /** Headers to send on a Messages call. Throws when neither credential source is configured. */
+    async headers() {
+        const mode = this.mode();
+        if (mode === 'api_key')
+            return { 'x-api-key': this.env.ANTHROPIC_API_KEY };
+        if (mode === 'federation')
+            return { Authorization: `Bearer ${await this.accessToken()}` };
+        throw new Error('Anthropic credentials not configured (set ANTHROPIC_API_KEY or the ANTHROPIC_FEDERATION_* variables)');
+    }
+    async accessToken() {
+        const now = this.deps.now();
+        if (this.cached && this.cached.expiresAt - ADVISORY_REFRESH_MS > now)
+            return this.cached.accessToken;
+        if (!this.inflight) {
+            this.inflight = this.exchange().finally(() => { this.inflight = null; });
+        }
+        try {
+            const fresh = await this.inflight;
+            this.cached = fresh;
+            return fresh.accessToken;
+        }
+        catch (e) {
+            // Advisory window: a still-valid cached token is better than failing the request.
+            if (this.cached && this.cached.expiresAt - 30000 > now)
+                return this.cached.accessToken;
+            throw e;
+        }
+    }
+    async identityToken(cfg) {
+        if (cfg.identityTokenFile) {
+            const read = this.deps.readFile ?? (async (p) => (await import('node:fs/promises')).readFile(p, 'utf8'));
+            return (await read(cfg.identityTokenFile)).trim();
+        }
+        const res = await this.deps.fetch(METADATA_URL, { headers: { 'Metadata-Flavor': 'Google' } });
+        if (!res.ok)
+            throw new Error(`Google metadata identity token ${res.status} (is this workload on Cloud Run with a service account?)`);
+        return (await res.text()).trim();
+    }
+    async exchange() {
+        const cfg = federationConfig(this.env);
+        if (!cfg)
+            throw new Error('federation not configured');
+        const assertion = await this.identityToken(cfg);
+        const body = {
+            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+            assertion,
+            federation_rule_id: cfg.ruleId,
+            organization_id: cfg.organizationId,
+            service_account_id: cfg.serviceAccountId,
+        };
+        if (cfg.workspaceId)
+            body.workspace_id = cfg.workspaceId;
+        const res = await this.deps.fetch(TOKEN_URL, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+        if (!res.ok) {
+            // The exchange returns an opaque 401 on deny; the reason is on the console's authentication history page.
+            throw new Error(`Anthropic token exchange ${res.status} (see platform.claude.com/settings/workload-identity-federation?tab=history)`);
+        }
+        const data = (await res.json());
+        if (!data.access_token)
+            throw new Error('Anthropic token exchange returned no access_token');
+        const ttlMs = Math.max(60, data.expires_in ?? 600) * 1000;
+        return { accessToken: data.access_token, expiresAt: this.deps.now() + ttlMs };
+    }
+}
+/** Process-wide instance for the adapter (one cache per process). */
+let shared = null;
+export function sharedCredentials() {
+    if (!shared)
+        shared = new AnthropicCredentials();
+    return shared;
+}
+/** Test hook. */
+export function __resetSharedCredentials() { shared = null; }

package/dist/adapters/anthropic.js

@@ -1,9 +1,10 @@
+import { sharedCredentials } from './anthropic-credentials.js';
 const API_URL = 'https://api.anthropic.com/v1/messages';
 const API_VERSION = '2023-06-01';
 const TIMEOUT_MS = 30000;
-function apiKey() {
-    return process.env.ANTHROPIC_API_KEY ?? '';
-}
+// Credentials: Workload Identity Federation (short-lived, per-service identity) with the static
+// key as fallback — see ./anthropic-credentials.ts. The adapter never reads the key directly.
+const creds = () => sharedCredentials();
 function buildBody(req, stream) {
     return JSON.stringify({
         model: req.model,
@@ -31,10 +32,10 @@ export function anthropicAdapter() {
             supports_streaming_tool_use: true,
             max_tools_per_request: null,
         },
-        available: () => !!apiKey(),
+        available: () => creds().mode() !== 'none',
         async isEligible(_req, _ctx) {
-            if (!apiKey())
-                return { eligible: false, reason: 'ANTHROPIC_API_KEY not configured' };
+            if (creds().mode() === 'none')
+                return { eligible: false, reason: 'Anthropic credentials not configured (ANTHROPIC_API_KEY or ANTHROPIC_FEDERATION_*)' };
             return { eligible: true, estimated_latency_ms: 2000, estimated_cost_cents: 0 };
         },
         async invoke(req, ctx) {
@@ -44,7 +45,7 @@ export function anthropicAdapter() {
             try {
                 const res = await fetch(API_URL, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey(), 'anthropic-version': API_VERSION },
+                    headers: { 'Content-Type': 'application/json', 'anthropic-version': API_VERSION, ...(await creds().headers()) },
                     body: buildBody(req, false),
                     signal: controller.signal,
                 });
@@ -70,7 +71,7 @@ export function anthropicAdapter() {
             try {
                 res = await fetch(API_URL, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey(), 'anthropic-version': API_VERSION },
+                    headers: { 'Content-Type': 'application/json', 'anthropic-version': API_VERSION, ...(await creds().headers()) },
                     body: buildBody(req, true),
                     signal: controller.signal,
                 });

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

@@ -7,14 +7,17 @@
 export * from './types.js';
 export { RouterError, RouterValidationError, RouterBlockedError } from './errors.js';
 export { parseRouterRequest, routerMessagesRequestSchema, cloudpeersEnvelopeSchema } from './schema.js';
-export { TIERS, TASK_ROUTES, evaluateGate, gateEnforced, resolveChain } from './policy.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

@@ -7,8 +7,10 @@
 export * from './types.js';
 export { RouterError, RouterValidationError, RouterBlockedError } from './errors.js';
 export { parseRouterRequest, routerMessagesRequestSchema, cloudpeersEnvelopeSchema } from './schema.js';
-export { TIERS, TASK_ROUTES, evaluateGate, gateEnforced, resolveChain } from './policy.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

@@ -1,25 +1,8 @@
-/**
- * Policy (the central control plane, distributed as deploy-time config).
- *
- * Tier table per the 2026-07-09 resolutions (supersedes the April spec table):
- *   Tier 0 — self-hosted in-boundary (OpenMed extraction / Nemotron pending
- *            the Q3 eval; the ONLY tier permitted for local_only once the
- *            hard gate flips)
- *   Tier 1 — Gemini Flash  (fast, non-PHI; local_only only under Vertex BAA)
- *   Tier 2 — Claude        (primary reasoning; local_only only under BAA)
- * No OpenAI tier, by directive.
- *
- * Privacy gate — interim cloud-PHI policy (decision 2026-07-09), three stages:
- *   Stage 1 MONITOR (default): local_only → cloud logs `would_block`, proceeds.
- *   Stage 2 governed egress:   providers listed in MODEL_ROUTER_BAA_PROVIDERS
- *                              (set ONLY once the instrument is executed) are
- *                              permitted for local_only.
- *   Stage 3 enforce:           MODEL_PRIVACY_GATE_ENFORCE=true — local_only is
- *                              Tier-0-or-BAA only, fail closed.
- */
 import type { GateOutcome, Provider, SovereigntyClass, TaskClass, TierDef } from './types.js';
+/** The §N+1.1 artifact as loaded (or the baked fallback) — projection input, read-only. */
+export declare function routingPolicyArtifact(): Record<string, unknown>;
 export declare const TIERS: Record<number, TierDef>;
-/** Static routing table (confidence v1): tier chain per task class, in order. */
+/** Static routing table (confidence v1): tier chain per task class, in order. Loaded from routing-policy.json. */
 export declare const TASK_ROUTES: Record<TaskClass, number[]>;
 export declare function gateEnforced(): boolean;
 /**
@@ -27,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

@@ -1,16 +1,90 @@
-export const TIERS = {
-    0: { tier: 0, provider: 'selfhosted', model: process.env.MODEL_ROUTER_TIER0_MODEL || 'openmed-extraction', cloud: false },
-    1: { tier: 1, provider: 'gemini', model: process.env.MODEL_ROUTER_GEMINI_MODEL || 'gemini-2.5-flash', cloud: true },
-    2: { tier: 2, provider: 'anthropic', model: process.env.MODEL_ROUTER_ANTHROPIC_MODEL || 'claude-haiku-4-5', cloud: true },
-};
-/** Static routing table (confidence v1): tier chain per task class, in order. */
-export const TASK_ROUTES = {
-    extraction: [0, 1],
-    classification: [0, 1],
-    coaching: [1, 2],
-    reasoning: [2, 1],
-    synthesis: [2, 1],
+/**
+ * Policy (the central control plane, distributed as deploy-time config).
+ *
+ * Tier table per the 2026-07-09 resolutions (supersedes the April spec table):
+ *   Tier 0 — self-hosted in-boundary (OpenMed extraction / Nemotron pending
+ *            the Q3 eval; the ONLY tier permitted for local_only once the
+ *            hard gate flips)
+ *   Tier 1 — Gemini Flash  (fast, non-PHI; local_only only under Vertex BAA)
+ *   Tier 2 — Claude        (primary reasoning; local_only only under BAA)
+ * No OpenAI tier, by directive.
+ *
+ * Privacy gate — interim cloud-PHI policy (decision 2026-07-09), three stages:
+ *   Stage 1 MONITOR (default): local_only → cloud logs `would_block`, proceeds.
+ *   Stage 2 governed egress:   providers listed in MODEL_ROUTER_BAA_PROVIDERS
+ *                              (set ONLY once the instrument is executed) are
+ *                              permitted for local_only.
+ *   Stage 3 enforce:           MODEL_PRIVACY_GATE_ENFORCE=true — local_only is
+ *                              Tier-0-or-BAA only, fail closed.
+ */
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+/**
+ * §N+1.1 — routing-policy.json (package root) is the governance source of
+ * truth the router executes from. Baked-in defaults below exist only as the
+ * fail-safe when the artifact is missing or invalid (fail-safe, not
+ * fail-open: same values, loudly logged).
+ */
+const artifactTierSchema = z
+    .object({
+    tier: z.number().int().min(0),
+    provider: z.enum(['selfhosted', 'gemini', 'anthropic']),
+    default_model: z.string().min(1),
+    model_env_override: z.string().min(1),
+    cloud: z.boolean(),
+})
+    .passthrough();
+const artifactSchema = z
+    .object({
+    version: z.literal(1),
+    tiers: z.array(artifactTierSchema).min(1),
+    task_routes: z.record(z.string(), z.array(z.number().int()).min(1)),
+})
+    .passthrough();
+const TASK_CLASSES = ['extraction', 'classification', 'coaching', 'reasoning', 'synthesis'];
+const BAKED = {
+    version: 1,
+    tiers: [
+        { tier: 0, provider: 'selfhosted', default_model: 'openmed-extraction', model_env_override: 'MODEL_ROUTER_TIER0_MODEL', cloud: false },
+        { tier: 1, provider: 'gemini', default_model: 'gemini-2.5-flash', model_env_override: 'MODEL_ROUTER_GEMINI_MODEL', cloud: true },
+        { tier: 2, provider: 'anthropic', default_model: 'claude-haiku-4-5', model_env_override: 'MODEL_ROUTER_ANTHROPIC_MODEL', cloud: true },
+    ],
+    task_routes: { extraction: [0, 1], classification: [0, 1], coaching: [1, 2], reasoning: [2, 1], synthesis: [2, 1] },
 };
+/** Full parsed artifact (for the governance projection); baked shape on fallback. */
+let loadedArtifact = BAKED;
+function loadArtifact() {
+    try {
+        const raw = readFileSync(new URL('../routing-policy.json', import.meta.url), 'utf8');
+        const parsed = artifactSchema.parse(JSON.parse(raw));
+        const tierNos = new Set(parsed.tiers.map((t) => t.tier));
+        for (const tc of TASK_CLASSES) {
+            const chain = parsed.task_routes[tc];
+            if (!chain)
+                throw new Error(`task_routes missing task class "${tc}"`);
+            for (const n of chain)
+                if (!tierNos.has(n))
+                    throw new Error(`task_routes.${tc} references undefined tier ${n}`);
+        }
+        loadedArtifact = parsed;
+        return parsed;
+    }
+    catch (err) {
+        console.error(`[routing-policy] failed to load routing-policy.json — falling back to baked-in defaults: ${err.message}`);
+        return BAKED;
+    }
+}
+const artifact = loadArtifact();
+/** The §N+1.1 artifact as loaded (or the baked fallback) — projection input, read-only. */
+export function routingPolicyArtifact() {
+    return loadedArtifact;
+}
+export const TIERS = Object.fromEntries(artifact.tiers.map((t) => [
+    t.tier,
+    { tier: t.tier, provider: t.provider, model: process.env[t.model_env_override] || t.default_model, cloud: t.cloud },
+]));
+/** Static routing table (confidence v1): tier chain per task class, in order. Loaded from routing-policy.json. */
+export const TASK_ROUTES = Object.fromEntries(TASK_CLASSES.map((tc) => [tc, artifact.task_routes[tc]]));
 function baaProviders() {
     return new Set((process.env.MODEL_ROUTER_BAA_PROVIDERS ?? '')
         .split(',')
@@ -25,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/router.js

@@ -14,7 +14,7 @@
  * stable interface: the Stage-3 enforcement flip decision is made from them.
  */
 import { RouterBlockedError } from './errors.js';
-import { evaluateGate, modelMatchesProvider, resolveChain, TIERS } from './policy.js';
+import { evaluateGate, gateEnforced, modelMatchesProvider, resolveChain, TIERS } from './policy.js';
 import { parseRouterRequest } from './schema.js';
 function firstText(content) {
     return content.find((b) => b.type === 'text')?.text ?? '';
@@ -69,6 +69,25 @@ async function checkQuotaOnce(req, ctx, deps) {
         throw new Error(`Token quota exceeded. ${quotaCheck.remainingTokens} tokens remaining. Quota resets at ${quotaCheck.quotaResetAt}.`);
     }
 }
+function tierKey(tier) {
+    return `tier${tier.tier}/${tier.provider}`;
+}
+/** §N.5 — build the Stage-1 decision record for this request. */
+function stageOneDecision(env, state, chosen) {
+    const decision = {
+        sovereignty_class: env.sovereignty_class,
+        eligible_set: [...state.walked],
+        chosen_backend: chosen ? tierKey(chosen.tier) : null,
+    };
+    if (env.sovereignty_class === 'local_only') {
+        decision.no_egress_proof = {
+            gate_enforced: gateEnforced(),
+            cloud_tiers_blocked: [...state.blockedCloud],
+            chosen_backend_cloud: chosen?.tier.cloud ?? false,
+        };
+    }
+    return decision;
+}
 /**
  * Walk the chain applying availability, the privacy gate, per-backend policy,
  * and adapter eligibility (§3.3/§7.1 #3-4, §8.2). Yields callable candidates
@@ -84,6 +103,7 @@ async function* eligibleTiers(req, ctx, deps, state) {
             continue; // tier not deployed (e.g. Tier 0 pre-OpenMed) — next
         const gate = evaluateGate(env.sovereignty_class, tier);
         if (gate === 'blocked') {
+            state.blockedCloud.push(tierKey(tier));
             console.warn(`[privacy-gate] BLOCKED local_only → tier${tier.tier}/${tier.provider} (op=${ctx.operation} svc=${ctx.serviceId})`);
             continue; // fail closed on this tier
         }
@@ -120,6 +140,7 @@ async function* eligibleTiers(req, ctx, deps, state) {
             console.warn(`[model-router] tier${tier.tier}/${tier.provider} ineligible: ${reason}`);
             continue;
         }
+        state.walked.push(tierKey(tier));
         yield { tier, adapter, gate };
     }
 }
@@ -133,7 +154,7 @@ function exhaustedError(env, state, lastError) {
     return lastError ?? new Error(`No available tier for task class ${env.task_class}`);
 }
 /** §7.2 post-call hooks + §10 uniform metering. Observation-only; never gates. */
-async function postCall(candidate, stripped, response, latencyMs, req, ctx, deps, state) {
+async function postCall(candidate, stripped, response, latencyMs, req, ctx, deps, state, decision) {
     const env = req.cloudpeers;
     const usage = {
         ...candidate.adapter.reportUsage(stripped, response),
@@ -175,6 +196,7 @@ async function postCall(candidate, stripped, response, latencyMs, req, ctx, deps
                 tier: candidate.tier.tier,
                 taskClass: env.task_class,
                 gate,
+                decision,
                 ...(outcomeMatches !== undefined ? { outcome_matches_mandate: outcomeMatches } : {}),
             },
         },
@@ -191,7 +213,7 @@ export async function routeMessages(input, ctx, deps) {
     const env = req.cloudpeers;
     await enforcePreCall(env, deps);
     await checkQuotaOnce(req, ctx, deps);
-    const state = { requestGate: 'allowed', toolStrictViolation: false };
+    const state = { requestGate: 'allowed', toolStrictViolation: false, walked: [], blockedCloud: [] };
     let escalations = 0;
     let lastError = null;
     let bestEffort = null;
@@ -205,7 +227,8 @@ export async function routeMessages(input, ctx, deps) {
                 operation: ctx.operation,
                 signal: ctx.signal,
             });
-            const usage = await postCall(candidate, stripped, response, Math.round(performance.now() - started), req, ctx, deps, state);
+            const decision = stageOneDecision(env, state, candidate);
+            const usage = await postCall(candidate, stripped, response, Math.round(performance.now() - started), req, ctx, deps, state, decision);
             const result = {
                 response,
                 provider: candidate.tier.provider,
@@ -215,6 +238,7 @@ export async function routeMessages(input, ctx, deps) {
                 degraded: false,
                 gate: state.requestGate === 'would_block' ? 'would_block' : candidate.gate,
                 usage,
+                decision,
             };
             if (ctx.validate && !ctx.validate(firstText(response.content))) {
                 // Confidence v1: shape validation failed — keep as best-effort, escalate.
@@ -232,6 +256,8 @@ export async function routeMessages(input, ctx, deps) {
     }
     if (bestEffort)
         return { ...bestEffort, escalations };
+    // §N.5 — the denial is a Stage-1 decision too; stable structured line, one per 412.
+    console.warn(`[stage1-decision] ${JSON.stringify(stageOneDecision(env, state, null))}`);
     throw exhaustedError(env, state, lastError);
 }
 /**
@@ -244,7 +270,7 @@ export async function routeMessagesStream(input, ctx, deps) {
     const env = req.cloudpeers;
     await enforcePreCall(env, deps);
     await checkQuotaOnce(req, ctx, deps);
-    const state = { requestGate: 'allowed', toolStrictViolation: false };
+    const state = { requestGate: 'allowed', toolStrictViolation: false, walked: [], blockedCloud: [] };
     for await (const candidate of eligibleTiers(req, ctx, deps, state)) {
         if (!candidate.adapter.supports_streaming)
             continue;
@@ -285,7 +311,7 @@ export async function routeMessagesStream(input, ctx, deps) {
                 stop_reason: stopReason,
                 usage: { input_tokens: inputTokens, output_tokens: outputTokens },
             };
-            await postCall(candidate, stripped, response, Math.round(performance.now() - started), req, ctx, deps, state);
+            await postCall(candidate, stripped, response, Math.round(performance.now() - started), req, ctx, deps, state, stageOneDecision(env, state, candidate));
         };
         return {
             provider: candidate.tier.provider,
@@ -295,6 +321,7 @@ export async function routeMessagesStream(input, ctx, deps) {
             stream: metered(),
         };
     }
+    console.warn(`[stage1-decision] ${JSON.stringify(stageOneDecision(env, state, null))}`);
     throw exhaustedError(env, state, null);
 }
 /**

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;
@@ -237,20 +245,81 @@ export interface RouterResult {
     totalTokens: number;
 }
 /** Spec-API result: full Anthropic response + the routing telemetry. */
+/**
+ * §N.5 Stage-1 decision record — one per routing decision, success or 412.
+ * `no_egress_proof` is present only for `local_only`: the router's claim about
+ * cloud egress for this request. The empirical proof lives outside the library
+ * (gateway harness zero-canary assertion, joined by trace); this record is the
+ * claim and the join key's payload.
+ */
+export interface StageOneDecision {
+    sovereignty_class: CloudpeersEnvelope['sovereignty_class'];
+    /** `tier{n}/{provider}` candidates that passed the gate walk, in chain order. */
+    eligible_set: string[];
+    /** null on a 412 (empty eligible set). */
+    chosen_backend: string | null;
+    no_egress_proof?: {
+        gate_enforced: boolean;
+        /** Cloud tiers the gate failed closed on. */
+        cloud_tiers_blocked: string[];
+        /** true only when a cloud tier served the request (BAA-governed or monitor mode). */
+        chosen_backend_cloud: boolean;
+    };
+}
 export interface MessagesRouteResult {
     response: AnthropicMessagesResponse;
-    provider: Provider;
+    provider: GenerateProvider;
     model: string;
     tier: number;
     escalations: number;
     degraded: boolean;
     gate: GateOutcome;
     usage: UsageEvent;
+    decision: StageOneDecision;
 }
 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.2.2",
+  "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",
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "routing-policy.json",
     "README.md"
   ],
   "scripts": {

package/routing-policy.json

@@ -0,0 +1,68 @@
+{
+  "$comment": "§N+1.1 governance source of truth — the file the router EXECUTES from, not a description of it. tiers + task_routes are loaded by src/policy.ts at module init (fail-safe: baked-in defaults on parse failure). A credential-less human reading this one artifact can enumerate every routing rule, every backend, what fails closed, and current status. The /.well-known/ucp/inference-router projection is generated from this file and the live adapter matrix — never hand-reconciled. Edit here; never edit the projection.",
+  "version": 1,
+  "updated": "2026-07-29",
+  "tiers": [
+    {
+      "tier": 0,
+      "provider": "selfhosted",
+      "default_model": "openmed-extraction",
+      "model_env_override": "MODEL_ROUTER_TIER0_MODEL",
+      "cloud": false,
+      "build_status": "not deployed — MODEL_ROUTER_TIER0_URL unset; OpenMed extraction / Nemotron pending the Q3 eval. The only tier permitted for local_only under the enforced gate (absent a BAA provider)."
+    },
+    {
+      "tier": 1,
+      "provider": "gemini",
+      "default_model": "gemini-2.5-flash",
+      "model_env_override": "MODEL_ROUTER_GEMINI_MODEL",
+      "cloud": true,
+      "build_status": "live"
+    },
+    {
+      "tier": 2,
+      "provider": "anthropic",
+      "default_model": "claude-haiku-4-5",
+      "model_env_override": "MODEL_ROUTER_ANTHROPIC_MODEL",
+      "cloud": true,
+      "build_status": "live — Claude primary (ahead of EoQ3)"
+    }
+  ],
+  "no_providers": ["openai"],
+  "task_routes": {
+    "extraction": [0, 1],
+    "classification": [0, 1],
+    "coaching": [1, 2],
+    "reasoning": [2, 1],
+    "synthesis": [2, 1]
+  },
+  "sovereignty": {
+    "local_only": "non-cloud tiers only, or a provider listed in MODEL_ROUTER_BAA_PROVIDERS (executed instrument required). Never silently routed to cloud.",
+    "aggregate_only": "any tier on the task route",
+    "externalizable": "any tier on the task route"
+  },
+  "privacy_gate": {
+    "stages": [
+      "Stage 1 MONITOR (historical default): local_only → cloud logs would_block, proceeds",
+      "Stage 2 governed egress: MODEL_ROUTER_BAA_PROVIDERS allowlist",
+      "Stage 3 ENFORCE: MODEL_PRIVACY_GATE_ENFORCE=true — local_only is Tier-0-or-BAA only"
+    ],
+    "current_stage": 3,
+    "enforcing_since": "2026-07-23",
+    "decision_record": "§N.5 — {sovereignty_class, eligible_set, chosen_backend, no_egress_proof} emitted per decision (meter metadata on success, [stage1-decision] log line on 412)"
+  },
+  "fail_closed_rules": [
+    "Empty eligible set → 412 routing_blocked. Never a silent fallback to an unapproved path.",
+    "mandate_id present but no mandate verifier wired → 412 mandate_verifier_unavailable",
+    "policy_id present but no policy engine wired → 412 policy_engine_unavailable",
+    "tool_use_strict with no tool-capable eligible backend → 422 tool_use_unsupported",
+    "Caller-supplied model outside the serving tier's provider family is ignored, never escalated"
+  ],
+  "roadmap": [
+    { "phase": "shipped 2026-07-15", "item": "embedded-library router (Amendment A1) live in mcp + carepeers" },
+    { "phase": "shipped 2026-07-23", "item": "privacy gate Stage-3 ENFORCE (a16d397)" },
+    { "phase": "in progress", "item": "agentgateway v1.4.0 shadow adoption; Stage-1 seam moves between services (CEL + NemoClaw webhook) — AGENTGATEWAY_ADOPTION_ADR_2026-07-29" },
+    { "phase": "Q3 2026", "item": "Tier 0 self-hosted deployment (OpenMed/Nemotron) — closes the local_only execution gap" },
+    { "phase": "Q4 2026", "item": "gemini-proxy sunset completes (§15.5); Stage-2 latency/cost/quality selection behind the gateway" }
+  ]
+}