@cloudpeers-jkl/model-router 0.2.1 → 0.3.0

package/README.md

@@ -68,7 +68,9 @@ plus the provider keys (`ANTHROPIC_API_KEY`, `GEMINI_SERVER_API_KEY`/`GEMINI_API
 
 ## Publishing
 
-Not yet published. Consumed in-repo via relative imports (see
-`server/lib/model-router.ts`). To publish for external consumers
-(carepeers seams, gemini-proxy in Deno): `npm run build && npm publish`
-from this directory — `dist/` is what ships.
+Published on npm since 2026-07-15 (`@cloudpeers-jkl/model-router`, current
+0.2.1); carepeers consumes the npm package. mcp itself consumes this source
+in-repo via relative imports (see `server/lib/model-router.ts`) — source and
+package must not drift, so publish after any change here:
+`npm publish --access public` from this directory (`prepublishOnly` builds
+`dist/`; requires JKL's npm browser 2FA).

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: (...a) => globalThis.fetch(...a), 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/index.d.ts

@@ -7,7 +7,7 @@
 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 type { RouteContext, MessagesStreamResult } from './router.js';
 export { capabilityMatrix } from './capabilities.js';

package/dist/index.js

@@ -7,7 +7,7 @@
 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 { capabilityMatrix } from './capabilities.js';
 export { anthropicAdapter } from './adapters/anthropic.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,13 @@ export declare function gateEnforced(): boolean;
  * Never triggers for aggregate_only/externalizable (spec scope: local_only).
  */
 export declare function evaluateGate(sovereigntyClass: SovereigntyClass, tier: TierDef): 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
+ * the tier's policy model serves. Tier 0 always serves its own model — the
+ * self-hosted endpoint decides what it hosts, not the caller.
+ */
+export declare function modelMatchesProvider(model: string, provider: Provider): boolean;
 /**
  * Resolve the tier chain for a request: the static task-class chain,
  * optionally reordered by an advisory backend_hint (§4). The hint never adds

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(',')
@@ -31,6 +105,19 @@ export function evaluateGate(sovereigntyClass, tier) {
         return 'allowed'; // Stage 2 governed egress
     return gateEnforced() ? 'blocked' : 'would_block'; // Stage 3 : Stage 1
 }
+/**
+ * §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
+ * the tier's policy model serves. Tier 0 always serves its own model — the
+ * self-hosted endpoint decides what it hosts, not the caller.
+ */
+export function modelMatchesProvider(model, provider) {
+    if (provider === 'gemini')
+        return /^(models\/)?gemini/i.test(model);
+    if (provider === 'anthropic')
+        return /^claude/i.test(model);
+    return false; // selfhosted: never caller-selected
+}
 /**
  * Resolve the tier chain for a request: the static task-class chain,
  * optionally reordered by an advisory backend_hint (§4). The hint never adds

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, 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 ?? '';
@@ -34,6 +34,10 @@ function stripEnvelope(req, model) {
     const { cloudpeers: _cloudpeers, stream: _stream, ...rest } = req;
     return { ...rest, model };
 }
+/** §4 — caller model honored when it belongs to the tier's provider family. */
+function servedModel(req, tier) {
+    return req.model && modelMatchesProvider(req.model, tier.provider) ? req.model : tier.model;
+}
 /**
  * §7.1 #2/#4 + A1.2 — pre-call enforcement that applies to the request as a
  * whole. Fail closed: a named instrument with no wired verifier blocks.
@@ -65,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
@@ -80,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
         }
@@ -116,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 };
     }
 }
@@ -129,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),
@@ -160,7 +185,7 @@ async function postCall(candidate, stripped, response, latencyMs, req, ctx, deps
         .meter({
         userId: ctx.userId,
         serviceId: ctx.serviceId,
-        model: candidate.tier.model,
+        model: stripped.model ?? candidate.tier.model,
         operation: ctx.operation,
         promptTokens: usage.tokens_in,
         completionTokens: usage.tokens_out,
@@ -171,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 } : {}),
             },
         },
@@ -187,12 +213,12 @@ 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;
     for await (const candidate of eligibleTiers(req, ctx, deps, state)) {
-        const stripped = stripEnvelope(req, candidate.tier.model);
+        const stripped = stripEnvelope(req, servedModel(req, candidate.tier));
         const started = performance.now();
         try {
             const response = await candidate.adapter.invoke(stripped, {
@@ -201,16 +227,18 @@ 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,
-                model: candidate.tier.model,
+                model: stripped.model ?? candidate.tier.model,
                 tier: candidate.tier.tier,
                 escalations,
                 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.
@@ -228,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);
 }
 /**
@@ -240,11 +270,11 @@ 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;
-        const stripped = stripEnvelope(req, candidate.tier.model);
+        const stripped = stripEnvelope(req, servedModel(req, candidate.tier));
         const gate = state.requestGate === 'would_block' ? 'would_block' : candidate.gate;
         const started = performance.now();
         const events = candidate.adapter.invokeStream(stripped, {
@@ -277,20 +307,21 @@ export async function routeMessagesStream(input, ctx, deps) {
                 type: 'message',
                 role: 'assistant',
                 content: [],
-                model: candidate.tier.model,
+                model: stripped.model ?? candidate.tier.model,
                 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,
-            model: candidate.tier.model,
+            model: stripped.model ?? candidate.tier.model,
             tier: candidate.tier.tier,
             gate,
             stream: metered(),
         };
     }
+    console.warn(`[stage1-decision] ${JSON.stringify(stageOneDecision(env, state, null))}`);
     throw exhaustedError(env, state, null);
 }
 /**

package/dist/types.d.ts

@@ -237,6 +237,27 @@ 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;
@@ -246,6 +267,7 @@ export interface MessagesRouteResult {
     degraded: boolean;
     gate: GateOutcome;
     usage: UsageEvent;
+    decision: StageOneDecision;
 }
 export interface TierDef {
     tier: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudpeers-jkl/model-router",
-  "version": "0.2.1",
+  "version": "0.3.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": {
@@ -21,9 +22,9 @@
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
-  "peerDependencies": {
-    "@google/generative-ai": ">=0.24.0",
-    "zod": ">=3.22.0"
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "zod": "^3.24.2"
   },
   "repository": {
     "type": "git",

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" }
+  ]
+}