@cloudpeers-jkl/model-router 0.2.0

package/dist/schema.d.ts

@@ -0,0 +1,335 @@
+/**
+ * §4 — Zod schema for the router entry point: Anthropic Messages request
+ * shape + the `cloudpeers` extension envelope. Validated on every
+ * routeMessages/routeMessagesStream call; shape errors are 400
+ * (RouterValidationError), per §7.1 #1.
+ *
+ * The envelope is strict (unknown keys rejected) — a typo'd
+ * `sovereignty_class` must fail loudly, never default. The Anthropic layer
+ * is permissive on content-block internals so provider-shape evolution
+ * doesn't require lockstep schema bumps.
+ */
+import { z } from 'zod';
+import type { RouterMessagesRequest } from './types.js';
+export declare const cloudpeersEnvelopeSchema: z.ZodObject<{
+    v: z.ZodOptional<z.ZodLiteral<1>>;
+    sovereignty_class: z.ZodEnum<["local_only", "aggregate_only", "externalizable"]>;
+    task_class: z.ZodEnum<["extraction", "classification", "coaching", "reasoning", "synthesis"]>;
+    mandate_id: z.ZodOptional<z.ZodString>;
+    policy_id: z.ZodOptional<z.ZodString>;
+    attribution_chain: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    trust_level: z.ZodOptional<z.ZodEnum<["L0", "L1", "L2", "L3", "L4", "L5"]>>;
+    backend_hint: z.ZodOptional<z.ZodEnum<["selfhosted", "gemini", "anthropic"]>>;
+    tool_use_strict: z.ZodOptional<z.ZodBoolean>;
+    byok: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        key_ref: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        key_ref: string;
+    }, {
+        provider: string;
+        key_ref: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+    task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
+    v?: 1 | 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;
+        key_ref: string;
+    } | undefined;
+}, {
+    sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+    task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
+    v?: 1 | 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;
+        key_ref: string;
+    } | undefined;
+}>;
+export declare const routerMessagesRequestSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant"]>;
+        content: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, "many">]>;
+    }, "strip", z.ZodTypeAny, {
+        role: "user" | "assistant";
+        content: string | z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }, {
+        role: "user" | "assistant";
+        content: string | z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }>, "many">;
+    system: z.ZodOptional<z.ZodString>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    tool_choice: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    stream: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    cloudpeers: z.ZodObject<{
+        v: z.ZodOptional<z.ZodLiteral<1>>;
+        sovereignty_class: z.ZodEnum<["local_only", "aggregate_only", "externalizable"]>;
+        task_class: z.ZodEnum<["extraction", "classification", "coaching", "reasoning", "synthesis"]>;
+        mandate_id: z.ZodOptional<z.ZodString>;
+        policy_id: z.ZodOptional<z.ZodString>;
+        attribution_chain: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        trust_level: z.ZodOptional<z.ZodEnum<["L0", "L1", "L2", "L3", "L4", "L5"]>>;
+        backend_hint: z.ZodOptional<z.ZodEnum<["selfhosted", "gemini", "anthropic"]>>;
+        tool_use_strict: z.ZodOptional<z.ZodBoolean>;
+        byok: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            key_ref: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            provider: string;
+            key_ref: string;
+        }, {
+            provider: string;
+            key_ref: string;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
+        v?: 1 | 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;
+            key_ref: string;
+        } | undefined;
+    }, {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
+        v?: 1 | 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;
+            key_ref: string;
+        } | undefined;
+    }>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    model: z.ZodOptional<z.ZodString>;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant"]>;
+        content: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, "many">]>;
+    }, "strip", z.ZodTypeAny, {
+        role: "user" | "assistant";
+        content: string | z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }, {
+        role: "user" | "assistant";
+        content: string | z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }>, "many">;
+    system: z.ZodOptional<z.ZodString>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    tool_choice: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    stream: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    cloudpeers: z.ZodObject<{
+        v: z.ZodOptional<z.ZodLiteral<1>>;
+        sovereignty_class: z.ZodEnum<["local_only", "aggregate_only", "externalizable"]>;
+        task_class: z.ZodEnum<["extraction", "classification", "coaching", "reasoning", "synthesis"]>;
+        mandate_id: z.ZodOptional<z.ZodString>;
+        policy_id: z.ZodOptional<z.ZodString>;
+        attribution_chain: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        trust_level: z.ZodOptional<z.ZodEnum<["L0", "L1", "L2", "L3", "L4", "L5"]>>;
+        backend_hint: z.ZodOptional<z.ZodEnum<["selfhosted", "gemini", "anthropic"]>>;
+        tool_use_strict: z.ZodOptional<z.ZodBoolean>;
+        byok: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            key_ref: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            provider: string;
+            key_ref: string;
+        }, {
+            provider: string;
+            key_ref: string;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
+        v?: 1 | 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;
+            key_ref: string;
+        } | undefined;
+    }, {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
+        v?: 1 | 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;
+            key_ref: string;
+        } | undefined;
+    }>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    model: z.ZodOptional<z.ZodString>;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant"]>;
+        content: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, "many">]>;
+    }, "strip", z.ZodTypeAny, {
+        role: "user" | "assistant";
+        content: string | z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }, {
+        role: "user" | "assistant";
+        content: string | z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }>, "many">;
+    system: z.ZodOptional<z.ZodString>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    tool_choice: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    stream: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    cloudpeers: z.ZodObject<{
+        v: z.ZodOptional<z.ZodLiteral<1>>;
+        sovereignty_class: z.ZodEnum<["local_only", "aggregate_only", "externalizable"]>;
+        task_class: z.ZodEnum<["extraction", "classification", "coaching", "reasoning", "synthesis"]>;
+        mandate_id: z.ZodOptional<z.ZodString>;
+        policy_id: z.ZodOptional<z.ZodString>;
+        attribution_chain: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        trust_level: z.ZodOptional<z.ZodEnum<["L0", "L1", "L2", "L3", "L4", "L5"]>>;
+        backend_hint: z.ZodOptional<z.ZodEnum<["selfhosted", "gemini", "anthropic"]>>;
+        tool_use_strict: z.ZodOptional<z.ZodBoolean>;
+        byok: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            key_ref: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            provider: string;
+            key_ref: string;
+        }, {
+            provider: string;
+            key_ref: string;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
+        v?: 1 | 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;
+            key_ref: string;
+        } | undefined;
+    }, {
+        sovereignty_class: "local_only" | "aggregate_only" | "externalizable";
+        task_class: "extraction" | "classification" | "coaching" | "reasoning" | "synthesis";
+        v?: 1 | 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;
+            key_ref: string;
+        } | undefined;
+    }>;
+}, z.ZodTypeAny, "passthrough">>;
+/** Parse + narrow. Throws RouterValidationError (statusCode 400) on shape errors. */
+export declare function parseRouterRequest(input: unknown): RouterMessagesRequest;

package/dist/schema.js

@@ -0,0 +1,68 @@
+/**
+ * §4 — Zod schema for the router entry point: Anthropic Messages request
+ * shape + the `cloudpeers` extension envelope. Validated on every
+ * routeMessages/routeMessagesStream call; shape errors are 400
+ * (RouterValidationError), per §7.1 #1.
+ *
+ * The envelope is strict (unknown keys rejected) — a typo'd
+ * `sovereignty_class` must fail loudly, never default. The Anthropic layer
+ * is permissive on content-block internals so provider-shape evolution
+ * doesn't require lockstep schema bumps.
+ */
+import { z } from 'zod';
+import { RouterValidationError } from './errors.js';
+const contentBlockSchema = z
+    .object({ type: z.string() })
+    .passthrough();
+const messageSchema = z.object({
+    role: z.enum(['user', 'assistant']),
+    content: z.union([z.string().min(1), z.array(contentBlockSchema).min(1)]),
+});
+const toolSchema = z
+    .object({
+    name: z.string().min(1),
+    description: z.string().optional(),
+    input_schema: z.record(z.unknown()),
+})
+    .passthrough();
+export const cloudpeersEnvelopeSchema = z
+    .object({
+    v: z.literal(1).optional(),
+    sovereignty_class: z.enum(['local_only', 'aggregate_only', 'externalizable']),
+    task_class: z.enum(['extraction', 'classification', 'coaching', 'reasoning', 'synthesis']),
+    mandate_id: z.string().min(1).optional(),
+    policy_id: z.string().min(1).optional(),
+    attribution_chain: z.array(z.string()).optional(),
+    trust_level: z.enum(['L0', 'L1', 'L2', 'L3', 'L4', 'L5']).optional(),
+    backend_hint: z.enum(['selfhosted', 'gemini', 'anthropic']).optional(),
+    tool_use_strict: z.boolean().optional(),
+    byok: z
+        .object({ provider: z.string().min(1), key_ref: z.string().min(1) })
+        .optional(),
+})
+    .strict();
+export const routerMessagesRequestSchema = z
+    .object({
+    model: z.string().optional(),
+    messages: z.array(messageSchema).min(1),
+    system: z.string().optional(),
+    max_tokens: z.number().int().positive().optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    tools: z.array(toolSchema).optional(),
+    tool_choice: z.record(z.unknown()).optional(),
+    stream: z.boolean().optional(),
+    metadata: z.record(z.unknown()).optional(),
+    cloudpeers: cloudpeersEnvelopeSchema,
+})
+    .passthrough();
+/** Parse + narrow. Throws RouterValidationError (statusCode 400) on shape errors. */
+export function parseRouterRequest(input) {
+    const parsed = routerMessagesRequestSchema.safeParse(input);
+    if (!parsed.success) {
+        const detail = parsed.error.issues
+            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; ');
+        throw new RouterValidationError(`Invalid router request: ${detail}`);
+    }
+    return parsed.data;
+}

package/dist/types.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @cloudpeers-jkl/model-router — types.
+ *
+ * Two API layers, one core:
+ *   - v1 convenience API (`routeModel`): prompt-in/text-out, kept for the
+ *     call sites migrated before extraction (behavior-identical).
+ *   - Spec API (`routeMessages`): Anthropic Messages lingua franca +
+ *     `cloudpeers` envelope, per INFERENCE_ROUTER_SPEC.md §4/§5 (canonical
+ *     copy in cloudpeers-github/docs/architecture/, Amendment A1 applies).
+ *
+ * Decisions encoded: embedded library, no central data plane (2026-07-09);
+ * Tier 0 = self-hosted in-boundary; privacy gate stages (MONITOR default);
+ * approved providers ONLY: anthropic, gemini, selfhosted. OpenAI excluded
+ * by directive. BYOK deferred (A1.2).
+ */
+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';
+export type BackendSurface = 'cloud' | 'self_hosted' | 'edge';
+export type GateOutcome = 'allowed' | 'would_block' | 'blocked';
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+export interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | ContentBlock[];
+    is_error?: boolean;
+}
+export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock;
+export interface AnthropicMessage {
+    role: 'user' | 'assistant';
+    content: string | ContentBlock[];
+}
+export interface ToolDefinition {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+}
+/** The `cloudpeers` extension envelope (§4). Stripped before any provider call. */
+export interface CloudpeersEnvelope {
+    v?: 1;
+    sovereignty_class: SovereigntyClass;
+    /** v1 embedded routing key (static task-class tier chains, 2026-07-09 resolution 3). */
+    task_class: TaskClass;
+    /** AP2 mandate the inference is bound to (§7.1 #2). */
+    mandate_id?: string;
+    /** NemoClaw policy to enforce pre/post call (§7.1 #4). */
+    policy_id?: string;
+    /** ERC-8183 upstream hop IDs (§7.2 #2). */
+    attribution_chain?: string[];
+    /** 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;
+    /** §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). */
+    byok?: {
+        provider: string;
+        key_ref: string;
+    };
+}
+export interface AnthropicMessagesRequest {
+    model?: string;
+    messages: AnthropicMessage[];
+    system?: string;
+    max_tokens?: number;
+    temperature?: number;
+    tools?: ToolDefinition[];
+    tool_choice?: Record<string, unknown>;
+    stream?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export type RouterMessagesRequest = AnthropicMessagesRequest & {
+    cloudpeers: CloudpeersEnvelope;
+};
+export interface AnthropicUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+export interface AnthropicMessagesResponse {
+    id: string;
+    type: 'message';
+    role: 'assistant';
+    content: ContentBlock[];
+    model: string;
+    stop_reason: string | null;
+    usage: AnthropicUsage;
+}
+/** SSE event in Anthropic streaming shape (message_start, content_block_delta, …). */
+export interface AnthropicSSEEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export interface ToolUseCapability {
+    supports_tool_use: boolean;
+    supports_parallel_tool_use: boolean;
+    preserves_block_position: boolean;
+    supports_streaming_tool_use: boolean;
+    max_tools_per_request: number | null;
+}
+export type EligibilityResult = {
+    eligible: true;
+    estimated_latency_ms: number;
+    estimated_cost_cents: number;
+} | {
+    eligible: false;
+    reason: string;
+};
+export interface UsageEvent {
+    backend_id: string;
+    tokens_in: number;
+    tokens_out: number;
+    latency_ms: number;
+    cost_cents: number;
+    cache_hit: boolean;
+    cache_unsupported?: true;
+    sovereignty_class: SovereigntyClass;
+}
+export interface SelectionContext {
+    sovereignty_class: SovereigntyClass;
+    tier: number;
+    gate: GateOutcome;
+}
+export interface InvocationContext {
+    userId: string;
+    serviceId: string;
+    operation: string;
+    signal?: AbortSignal;
+}
+export interface BackendAdapter {
+    id: Provider;
+    display_name: string;
+    surface: BackendSurface;
+    supports_streaming: boolean;
+    supports_tool_use: boolean;
+    supports_prompt_caching: boolean;
+    tool_use: ToolUseCapability;
+    /** Deploy-time availability (key/endpoint configured). */
+    available(): boolean;
+    /** Called by the selector before invocation (§3.3). */
+    isEligible(req: AnthropicMessagesRequest, ctx: SelectionContext): Promise<EligibilityResult>;
+    /** The envelope is stripped by the router before invoke sees the request. */
+    invoke(req: AnthropicMessagesRequest, ctx: InvocationContext): Promise<AnthropicMessagesResponse>;
+    invokeStream(req: AnthropicMessagesRequest, ctx: InvocationContext): AsyncIterable<AnthropicSSEEvent>;
+    /** §10 symmetric observability. latency_ms/sovereignty_class overwritten by the router. */
+    reportUsage(req: AnthropicMessagesRequest, res: AnthropicMessagesResponse): UsageEvent;
+}
+export interface MeterEvent {
+    userId: string;
+    serviceId: string;
+    model: string;
+    operation: string;
+    promptTokens: number;
+    completionTokens: number;
+    metadata?: Record<string, unknown>;
+}
+export type Meter = (event: MeterEvent) => Promise<unknown>;
+export type QuotaFn = (userId: string, estimatedTokens: number) => Promise<{
+    allowed: boolean;
+    remainingTokens?: number;
+    quotaResetAt?: unknown;
+    message?: string;
+}>;
+export interface MandateVerdict {
+    valid: boolean;
+    /** Required when valid=false: 'expired' → 410, 'revoked' → 409, else 412. */
+    reason?: 'expired' | 'revoked' | string;
+}
+export interface PolicyVerdict {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * §7 enforcement hooks. Fail-closed contract: if the request names a
+ * mandate_id or policy_id and the corresponding hook is not wired, the
+ * router blocks — an enforcement instrument the caller bound to must never
+ * be silently skipped. Post-call hooks are observation-only in v1 (§7.2).
+ */
+export interface RouterHooks {
+    verifyMandate?: (mandateId: string) => Promise<MandateVerdict>;
+    applyPolicy?: (policyId: string, call: {
+        backend_id: Provider;
+        model: string;
+        tier: number;
+    }) => Promise<PolicyVerdict>;
+    /** §7.2 #1 — Guardian outcome verification. Result recorded, never gating (v1). */
+    verifyOutcome?: (mandateId: string, response: AnthropicMessagesResponse) => Promise<{
+        outcome_matches_mandate: boolean;
+    }>;
+    /** §7.2 #2 — append this router hop to the attribution chain and persist. */
+    writeAttribution?: (chain: string[], usage: UsageEvent) => Promise<void>;
+}
+export interface RouterDeps {
+    adapters: Partial<Record<Provider, BackendAdapter>>;
+    meter: Meter;
+    quota: QuotaFn;
+    hooks?: RouterHooks;
+}
+export interface RouterRequest {
+    taskClass: TaskClass;
+    prompt: string;
+    system?: string;
+    /** REQUIRED — the caller declares the data class of the request context.
+     *  Entity-level tagging per the 2026-07-09 resolutions (per-token retired). */
+    sovereigntyClass: SovereigntyClass;
+    /** Metering label (token-tracker `operation`). */
+    operation: string;
+    userId: string;
+    serviceId: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Confidence v1: validate the response shape; failure escalates a tier. */
+    validate?: (text: string) => boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface RouterResult {
+    text: string;
+    provider: Provider;
+    model: string;
+    tier: number;
+    escalations: number;
+    /** True when every tier failed validation and this is best-effort output. */
+    degraded: boolean;
+    gate: GateOutcome;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/** Spec-API result: full Anthropic response + the routing telemetry. */
+export interface MessagesRouteResult {
+    response: AnthropicMessagesResponse;
+    provider: Provider;
+    model: string;
+    tier: number;
+    escalations: number;
+    degraded: boolean;
+    gate: GateOutcome;
+    usage: UsageEvent;
+}
+export interface TierDef {
+    tier: number;
+    provider: Provider;
+    model: string;
+    /** Cloud tiers are subject to the local_only privacy gate. */
+    cloud: boolean;
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * @cloudpeers-jkl/model-router — types.
+ *
+ * Two API layers, one core:
+ *   - v1 convenience API (`routeModel`): prompt-in/text-out, kept for the
+ *     call sites migrated before extraction (behavior-identical).
+ *   - Spec API (`routeMessages`): Anthropic Messages lingua franca +
+ *     `cloudpeers` envelope, per INFERENCE_ROUTER_SPEC.md §4/§5 (canonical
+ *     copy in cloudpeers-github/docs/architecture/, Amendment A1 applies).
+ *
+ * Decisions encoded: embedded library, no central data plane (2026-07-09);
+ * Tier 0 = self-hosted in-boundary; privacy gate stages (MONITOR default);
+ * approved providers ONLY: anthropic, gemini, selfhosted. OpenAI excluded
+ * by directive. BYOK deferred (A1.2).
+ */
+export {};