modelrig 0.1.0 → 0.3.0

package/dist/config.d.ts

@@ -6,6 +6,12 @@
 import type { CapabilityFlag, ProviderId } from "./types/provider";
 export interface RigConfig {
     readonly routesDir: string;
+    /** OPTIONAL directory of deployment-bundled INTERNAL infra routes, merged
+     * INTO `routesDir`'s routes (union, not replacement) by createRig. The server
+     * passes its gateway-internal-routes/ here so run-judge@v1 /
+     * analyst-summarize@v1 always resolve, independent of the operator's
+     * MODELRIG_ROUTES_DIR. Absent ⇒ exactly the pre-existing single-dir behavior. */
+    readonly extraRoutesDir?: string;
     readonly telemetryDbPath: string;
     readonly keys: {
         readonly gemini?: string;
@@ -58,7 +64,101 @@ export interface RigConfig {
      *   direct      self-host + our own deployments     their own database
      */
     readonly export?: ApiExportConfig | DirectExportConfig;
+    /**
+     * OTLP span emission (E1) — ADDITIVE alongside `export`, never instead of it.
+     * `null` means no endpoint configured ⇒ no emitter is ever constructed and
+     * behaviour is unchanged (spec §6a). Set via MODELRIG_OTLP_ENDPOINT (+ optional
+     * MODELRIG_OTLP_HEADERS). `loadConfigFromEnv` ALWAYS resolves this (to null or
+     * a config) so `/status` can answer "configured|disabled" honestly; the field
+     * is optional only so hand-built configs (tests) need not spell out the
+     * off case — an absent value is read identically to null.
+     */
+    readonly otlp?: OtlpConfig | null;
+    /**
+     * Artifact / execution-graph namespace (Expansion E2). OFF by default —
+     * `enabled: false` (or absent) means the run/artifact SDK surface is inert,
+     * the exporter sends protocol v1 byte-identical to before, and zero new rows
+     * are written (spec §1.4). Set via `MODELRIG_ARTIFACTS=1`. Like `otlp`,
+     * `loadConfigFromEnv` ALWAYS resolves this so `/status` can answer
+     * "enabled|disabled" honestly; optional only so hand-built configs need not
+     * spell out the off case.
+     */
+    readonly artifacts?: ArtifactsConfig;
+}
+/** Scrub mode applied to content BEFORE upload (E2-C chunk B). Default `detect`
+ * when content custody is on. */
+export type ScrubMode = "off" | "detect" | "redact" | "block";
+/** Per-rig content-custody config (E2-C chunk A/B). Present ONLY when content
+ * custody is turned ON and the transport is configured; ABSENT (the default)
+ * means metadata + hash only — today's behaviour, unchanged. Consent, off by
+ * default (ruling 6). */
+export interface ArtifactContentConfig {
+    /** Full grant endpoint, e.g. https://server/v1/artifacts/uploads. */
+    readonly uploadsUrl: string;
+    /** `rig_sk_` key with the `artifact-write` scope (header only; never a URL — C2). */
+    readonly apiKey: string;
+    readonly scrub: ScrubMode;
+    /** Client-side ceiling short-circuit; the server enforces the real one. */
+    readonly maxBytes: number;
+}
+/** Resolved artifact-namespace config (E2 / E2-C). `enabled` is the E2 gate;
+ * `content` (E2-C) is present only when content custody is configured on. */
+export interface ArtifactsConfig {
+    readonly enabled: boolean;
+    readonly content?: ArtifactContentConfig;
 }
+/**
+ * Resolve the artifact config from raw env values (E2 / E2-C, default flip §2).
+ * Pure — env is read by the caller (the package's sole env-reader rule).
+ *   MODELRIG_ARTIFACTS unset                 → namespace ON when a control plane
+ *                                              is configured, OFF for local-only
+ *                                              (§2: metadata-on by default).
+ *   MODELRIG_ARTIFACTS=1|true|on             → force the namespace ON.
+ *   MODELRIG_ARTIFACTS=0|false|off           → force it OFF (the explicit opt-out).
+ *   MODELRIG_ARTIFACTS_CONTENT=on|1|true     → content custody ON (E2-C).
+ *   MODELRIG_CONTENT_UPLOAD_URL, MODELRIG_CONTENT_API_KEY → transport.
+ *   MODELRIG_ARTIFACTS_SCRUB=off|detect|redact|block → scrub mode (default detect).
+ *   MODELRIG_CONTENT_MAX_BYTES               → client ceiling (default 50MB).
+ * Content custody stays OFF (content absent) unless it is explicitly on AND the
+ * transport is fully configured — a half-configured custody is refused into the
+ * safe default (metadata only), never silently half-on. The metadata default
+ * flip does NOT flip content: content is its own gate (§2 "content unchanged").
+ */
+export declare function resolveArtifactsConfig(env: {
+    readonly artifacts?: string;
+    readonly content?: string;
+    readonly uploadsUrl?: string;
+    readonly apiKey?: string;
+    readonly scrub?: string;
+    readonly maxBytes?: string;
+}, 
+/** Is a cloud sink (api or direct) configured? Unset gate defaults ON when so,
+ * OFF otherwise. Defaults false so existing callers/tests keep local-only
+ * semantics (gate-only) unless they opt into the flip. */
+controlPlaneConfigured?: boolean): ArtifactsConfig;
+/** Resolved OTLP config (E1). Endpoint + sink-auth headers only; the emitter
+ * derives batch/interval + watermark from defaults + the source id. */
+export interface OtlpConfig {
+    /** OTLP/HTTP traces endpoint. NEVER logged/displayed — may embed a token (C2). */
+    readonly endpoint: string;
+    /** Sink auth headers from MODELRIG_OTLP_HEADERS (`k=v,k=v`). NEVER logged (C2). */
+    readonly headers: Record<string, string>;
+}
+/**
+ * Parse `MODELRIG_OTLP_HEADERS` ("k=v,k=v") into a header map (E1). Split on the
+ * FIRST `=` only, so a base64 Basic-auth value keeping its `=` padding survives.
+ * Blank/whitespace pairs and pairs with an empty key are dropped. Pure — env is
+ * read by the caller, this only shapes the string (keeps this file the sole
+ * env reader without smearing parsing into it).
+ */
+export declare function parseOtlpHeaders(raw: string | undefined): Record<string, string>;
+/**
+ * Resolve the OTLP config from raw env values (E1). Pure so it is testable
+ * without touching `process.env` (the package-invariants env-reader rule) —
+ * `loadConfigFromEnv` reads the two vars and hands them here. A blank/absent
+ * endpoint ⇒ `null` = off by default (spec §6a).
+ */
+export declare function resolveOtlpConfig(endpoint: string | undefined, headersRaw: string | undefined): OtlpConfig | null;
 interface ExportCommon {
     readonly sourceId?: string;
     readonly batchSize?: number;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -6,9 +6,94 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROVIDER_KEY_ENV = void 0;
+exports.resolveArtifactsConfig = resolveArtifactsConfig;
+exports.parseOtlpHeaders = parseOtlpHeaders;
+exports.resolveOtlpConfig = resolveOtlpConfig;
 exports.loadConfigFromEnv = loadConfigFromEnv;
 exports.directExportOf = directExportOf;
 const ingest_protocol_1 = require("./telemetry/ingest-protocol");
+const DEFAULT_SDK_CONTENT_MAX_BYTES = 52428800;
+function resolveScrubMode(raw, contentOn) {
+    const v = (raw ?? "").trim().toLowerCase();
+    if (v === "off" || v === "detect" || v === "redact" || v === "block")
+        return v;
+    // Default when content is on is `detect` — scan and count, upload verbatim.
+    return contentOn ? "detect" : "off";
+}
+/**
+ * Resolve the artifact config from raw env values (E2 / E2-C, default flip §2).
+ * Pure — env is read by the caller (the package's sole env-reader rule).
+ *   MODELRIG_ARTIFACTS unset                 → namespace ON when a control plane
+ *                                              is configured, OFF for local-only
+ *                                              (§2: metadata-on by default).
+ *   MODELRIG_ARTIFACTS=1|true|on             → force the namespace ON.
+ *   MODELRIG_ARTIFACTS=0|false|off           → force it OFF (the explicit opt-out).
+ *   MODELRIG_ARTIFACTS_CONTENT=on|1|true     → content custody ON (E2-C).
+ *   MODELRIG_CONTENT_UPLOAD_URL, MODELRIG_CONTENT_API_KEY → transport.
+ *   MODELRIG_ARTIFACTS_SCRUB=off|detect|redact|block → scrub mode (default detect).
+ *   MODELRIG_CONTENT_MAX_BYTES               → client ceiling (default 50MB).
+ * Content custody stays OFF (content absent) unless it is explicitly on AND the
+ * transport is fully configured — a half-configured custody is refused into the
+ * safe default (metadata only), never silently half-on. The metadata default
+ * flip does NOT flip content: content is its own gate (§2 "content unchanged").
+ */
+function resolveArtifactsConfig(env, 
+/** Is a cloud sink (api or direct) configured? Unset gate defaults ON when so,
+ * OFF otherwise. Defaults false so existing callers/tests keep local-only
+ * semantics (gate-only) unless they opt into the flip. */
+controlPlaneConfigured = false) {
+    const gate = (env.artifacts ?? "").trim().toLowerCase();
+    const explicitOn = gate === "1" || gate === "true" || gate === "on";
+    const explicitOff = gate === "0" || gate === "false" || gate === "off";
+    // §2 default flip: explicit wins; an unset gate follows the control plane.
+    const enabled = explicitOn || (!explicitOff && controlPlaneConfigured);
+    const contentGate = (env.content ?? "").trim().toLowerCase();
+    const contentOn = contentGate === "on" || contentGate === "1" || contentGate === "true";
+    const uploadsUrl = (env.uploadsUrl ?? "").trim();
+    const apiKey = (env.apiKey ?? "").trim();
+    const maxBytesRaw = env.maxBytes !== undefined && env.maxBytes !== "" ? Number(env.maxBytes) : NaN;
+    const maxBytes = Number.isInteger(maxBytesRaw) && maxBytesRaw > 0 ? maxBytesRaw : DEFAULT_SDK_CONTENT_MAX_BYTES;
+    // Content is on ONLY when the namespace is enabled, the gate is on, AND the
+    // transport is present. Missing transport → stays metadata-only (fail-safe).
+    const content = enabled && contentOn && uploadsUrl !== "" && apiKey !== ""
+        ? { uploadsUrl, apiKey, scrub: resolveScrubMode(env.scrub, true), maxBytes }
+        : undefined;
+    return { enabled, ...(content !== undefined ? { content } : {}) };
+}
+/**
+ * Parse `MODELRIG_OTLP_HEADERS` ("k=v,k=v") into a header map (E1). Split on the
+ * FIRST `=` only, so a base64 Basic-auth value keeping its `=` padding survives.
+ * Blank/whitespace pairs and pairs with an empty key are dropped. Pure — env is
+ * read by the caller, this only shapes the string (keeps this file the sole
+ * env reader without smearing parsing into it).
+ */
+function parseOtlpHeaders(raw) {
+    const out = {};
+    if (raw === undefined || raw.trim() === "")
+        return out;
+    for (const pair of raw.split(",")) {
+        const eq = pair.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = pair.slice(0, eq).trim();
+        const value = pair.slice(eq + 1).trim();
+        if (key === "")
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Resolve the OTLP config from raw env values (E1). Pure so it is testable
+ * without touching `process.env` (the package-invariants env-reader rule) —
+ * `loadConfigFromEnv` reads the two vars and hands them here. A blank/absent
+ * endpoint ⇒ `null` = off by default (spec §6a).
+ */
+function resolveOtlpConfig(endpoint, headersRaw) {
+    if (endpoint === undefined || endpoint.trim() === "")
+        return null;
+    return { endpoint: endpoint.trim(), headers: parseOtlpHeaders(headersRaw) };
+}
 /** Provider → the env var that keys it. One table so error surfaces can say
  * WHICH variable to set rather than "no key configured" (F1 / WS3: errors
  * that teach). `loadConfigFromEnv` below reads the same names. */
@@ -30,9 +115,28 @@ function loadConfigFromEnv(overrides) {
     const supabaseUrl = env.MODELRIG_SUPABASE_URL;
     const serviceRoleKey = env.MODELRIG_SUPABASE_SERVICE_ROLE_KEY;
     const apiKey = env.MODELRIG_API_KEY;
+    // OTLP span emission (E1) — off unless an endpoint is set. Additive to
+    // `export`; a rig may emit OTLP with no control-plane sink and vice-versa.
+    const otlp = resolveOtlpConfig(env.MODELRIG_OTLP_ENDPOINT, env.MODELRIG_OTLP_HEADERS);
+    // Artifact / execution-graph namespace (E2, default flip §2) — ON by default
+    // when a control plane is configured (api key OR the direct supabase pair),
+    // OFF for a pure local-only rig; MODELRIG_ARTIFACTS=0 is the explicit opt-out.
+    // Always resolved so /status + the boot banner answer honestly. Content
+    // custody (E2-C) stays its own gate — the metadata flip never flips content.
+    const controlPlaneConfigured = Boolean(apiKey) || Boolean(supabaseUrl && serviceRoleKey);
+    const artifacts = resolveArtifactsConfig({
+        artifacts: env.MODELRIG_ARTIFACTS,
+        content: env.MODELRIG_ARTIFACTS_CONTENT,
+        uploadsUrl: env.MODELRIG_CONTENT_UPLOAD_URL,
+        apiKey: env.MODELRIG_CONTENT_API_KEY ?? env.MODELRIG_API_KEY,
+        scrub: env.MODELRIG_ARTIFACTS_SCRUB,
+        maxBytes: env.MODELRIG_CONTENT_MAX_BYTES,
+    }, controlPlaneConfigured);
     const fromEnv = {
         routesDir: env.MODELRIG_ROUTES_DIR ?? DEFAULT_ROUTES_DIR,
         telemetryDbPath: env.MODELRIG_TELEMETRY_DB ?? DEFAULT_TELEMETRY_DB,
+        otlp,
+        artifacts,
         ...(env.MODELRIG_REGISTRY_PATH ? { registryPath: env.MODELRIG_REGISTRY_PATH } : {}),
         keys: {
             ...(env.GEMINI_API_KEY ? { gemini: env.GEMINI_API_KEY } : {}),

package/dist/deprecations.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Loud, one-time deprecation warnings (settings-plane §3).
+ *
+ * Two flags are on their way out now that governance lives in the control plane:
+ *   • YAML `capture:` — IGNORED when a control plane is configured; capture is a
+ *     task setting (console / API / MCP). Honored only for local-only rigs.
+ *   • the `direct` sink (MODELRIG_SUPABASE_*) — the supported path is api mode
+ *     (a `rig_sk_` key). Still works; will be removed (Matt's §0-row-5 decision).
+ *
+ * "Loud, never silent divergence" (spec §1.5): each warning fires ONCE per
+ * process (a module-level guard) so a user learns their YAML flag is being
+ * ignored, rather than quietly diverging from the console. The parked chunk-0.2
+ * commit carried no warn-once mechanism, so it is authored here from scratch.
+ */
+import type { RigConfig } from "./config";
+import type { RouteBundle } from "./types/route";
+/**
+ * Warn (once) that YAML `capture:` is ignored under a control plane. Fires only
+ * when a control plane is configured AND at least one loaded route still sets
+ * `capture: true` in YAML — a local-only rig keeps YAML as its mechanism and
+ * hears nothing.
+ */
+export declare function warnYamlCaptureDeprecated(routes: readonly RouteBundle[], controlPlaneConfigured: boolean): void;
+/**
+ * Warn (once) that the `direct` sink is deprecated, naming api mode as the path.
+ * Fires only for a rig actually configured in direct mode.
+ */
+export declare function warnDirectSinkDeprecated(config: RigConfig): void;
+/** Reset the once-per-process guards — TESTS ONLY, so warn-once cases are
+ * independent of run order. */
+export declare function __resetDeprecationWarningsForTest(): void;
+//# sourceMappingURL=deprecations.d.ts.map

package/dist/deprecations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecations.d.ts","sourceRoot":"","sources":["../src/deprecations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAKjD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,sBAAsB,EAAE,OAAO,GAC9B,IAAI,CAYN;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAShE;AAED;+BAC+B;AAC/B,wBAAgB,iCAAiC,IAAI,IAAI,CAGxD"}

package/dist/deprecations.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Loud, one-time deprecation warnings (settings-plane §3).
+ *
+ * Two flags are on their way out now that governance lives in the control plane:
+ *   • YAML `capture:` — IGNORED when a control plane is configured; capture is a
+ *     task setting (console / API / MCP). Honored only for local-only rigs.
+ *   • the `direct` sink (MODELRIG_SUPABASE_*) — the supported path is api mode
+ *     (a `rig_sk_` key). Still works; will be removed (Matt's §0-row-5 decision).
+ *
+ * "Loud, never silent divergence" (spec §1.5): each warning fires ONCE per
+ * process (a module-level guard) so a user learns their YAML flag is being
+ * ignored, rather than quietly diverging from the console. The parked chunk-0.2
+ * commit carried no warn-once mechanism, so it is authored here from scratch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warnYamlCaptureDeprecated = warnYamlCaptureDeprecated;
+exports.warnDirectSinkDeprecated = warnDirectSinkDeprecated;
+exports.__resetDeprecationWarningsForTest = __resetDeprecationWarningsForTest;
+let yamlCaptureWarned = false;
+let directSinkWarned = false;
+/**
+ * Warn (once) that YAML `capture:` is ignored under a control plane. Fires only
+ * when a control plane is configured AND at least one loaded route still sets
+ * `capture: true` in YAML — a local-only rig keeps YAML as its mechanism and
+ * hears nothing.
+ */
+function warnYamlCaptureDeprecated(routes, controlPlaneConfigured) {
+    if (yamlCaptureWarned || !controlPlaneConfigured)
+        return;
+    const withCapture = routes.filter((b) => b.capture).map((b) => b.route);
+    if (withCapture.length === 0)
+        return;
+    yamlCaptureWarned = true;
+    console.warn(`[modelrig] DEPRECATED: ${withCapture.length} route(s) set \`capture:\` in YAML ` +
+        `(${withCapture.join(", ")}). This flag is IGNORED when a control plane is configured — ` +
+        "capture is a task setting now. Set it in the console, the API " +
+        "(PATCH /v1/tasks/:task/settings), or via the MCP tool. YAML `capture:` is honored only " +
+        "for local-only rigs (no control plane).");
+}
+/**
+ * Warn (once) that the `direct` sink is deprecated, naming api mode as the path.
+ * Fires only for a rig actually configured in direct mode.
+ */
+function warnDirectSinkDeprecated(config) {
+    if (directSinkWarned || config.export?.mode !== "direct")
+        return;
+    directSinkWarned = true;
+    console.warn("[modelrig] DEPRECATED: the `direct` sink (MODELRIG_SUPABASE_URL + " +
+        "MODELRIG_SUPABASE_SERVICE_ROLE_KEY) is on its way out. The supported path is api mode — " +
+        "a `rig_sk_` key in MODELRIG_API_KEY, no database credentials in the client. Direct mode " +
+        "still works; migrate when convenient.");
+}
+/** Reset the once-per-process guards — TESTS ONLY, so warn-once cases are
+ * independent of run order. */
+function __resetDeprecationWarningsForTest() {
+    yamlCaptureWarned = false;
+    directSinkWarned = false;
+}

package/dist/gateway/http-protocol.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The HTTP gateway wire contract — G-1/G-5 (http-gateway spec §3, §4.3, §4.4).
+ *
+ * ONE definition of what a `/v1/chat/completions` request, response, and SSE
+ * chunk look like, plus the lane-disambiguation rule and the `x-modelrig-*`
+ * provenance headers. Both sides compile against it:
+ *
+ *   SDK (`packages/modelrig`)   — this repo; consumes the streaming/tool
+ *                                 surfaces the endpoint is built on.
+ *   `modelrig-server`           — separate repo (Phase B/C); implements the
+ *                                 endpoint and imports these types so the wire
+ *                                 shape cannot drift between the two.
+ *
+ * This mirrors `telemetry/ingest-protocol.ts`: a shared module is what makes
+ * "the two sides agree" enforceable rather than aspirational — a contract test
+ * round-trips the shapes on both sides instead of comparing two hand-written
+ * copies for similarity.
+ *
+ * TYPES + PURE FUNCTIONS ONLY. No transport, no auth, no I/O — the endpoint,
+ * SSE plumbing, and BYOK key resolution live server-side (spec §2).
+ */
+import type { ToolCall, ToolChoice, ToolDefinition } from "../types/provider";
+/** The endpoint path. Spelled once. */
+export declare const CHAT_COMPLETIONS_PATH = "/v1/chat/completions";
+/** The model-catalog path (routes + registry models) for SDK discovery. */
+export declare const MODELS_PATH = "/v1/models";
+/** Bumped only for a breaking change to the shapes below. */
+export declare const GATEWAY_PROTOCOL_VERSION = 1;
+export declare const MODELRIG_HEADERS: {
+    /** "slug" (verified pipeline) or "raw" (zero-margin BYOK passthrough). */
+    readonly lane: "x-modelrig-lane";
+    /** Phase D (spec §13.1 rule 4): where the slug lane resolved its bundle —
+     * "local" (this deployment's own routes, the self-host path) or "mirror" (the
+     * org-scoped `routes` mirror, the hosted path). A deployment serves ONE or the
+     * OTHER and SAYS WHICH; the two must never silently blend. Absent on the raw
+     * lane. */
+    readonly routeSource: "x-modelrig-route-source";
+    readonly provider: "x-modelrig-provider";
+    readonly model: "x-modelrig-model";
+    /** "true"/"false" — was the output schema-validated (slug lane only). */
+    readonly validated: "x-modelrig-validated";
+    /** "provider/model" that repaired the output, when repair fired. */
+    readonly repairedBy: "x-modelrig-repaired-by";
+    readonly costUsd: "x-modelrig-cost-usd";
+    /** The `rig.feedback()` handle (telemetry inference id). */
+    readonly inferenceId: "x-modelrig-inference-id";
+};
+export declare const MODELRIG_REQUEST_HEADERS: {
+    /** Per-run envelope key (budget). */
+    readonly envelope: "x-modelrig-envelope";
+    /** Named route variant to serve. */
+    readonly variant: "x-modelrig-variant";
+    /** "buffered" opts out of true streaming for validated-only output (§4.3). */
+    readonly stream: "x-modelrig-stream";
+};
+export type Lane = "slug" | "raw";
+/** The disambiguation verdict for a request's `model` field (spec §3.3). */
+export type LaneResolution = {
+    readonly lane: "slug";
+    readonly slug: string;
+} | {
+    readonly lane: "raw";
+    readonly provider: string;
+    readonly model: string;
+} | {
+    readonly lane: "unknown";
+    readonly reason: string;
+};
+/**
+ * The core routing rule (spec §3.3), as a pure function so both sides classify
+ * a `model` string identically:
+ *   1. `@rig/…` OR an exact known route slug  → slug lane (verified pipeline).
+ *   2. `^<providerId>/<model>$`, providerId ∈ PROVIDER_IDS → raw-model lane.
+ *   3. otherwise → unknown (the endpoint 404s; never silently guess).
+ *
+ * The namespaces don't collide: a route slug is a bare handle
+ * (`example.support_summarize`); a raw model always carries a known
+ * `provider/` prefix.
+ */
+export declare function classifyLane(model: string, knownRouteSlugs?: ReadonlySet<string>): LaneResolution;
+export interface ChatMessage {
+    readonly role: "system" | "user" | "assistant" | "tool";
+    readonly content: string | null;
+    /** Assistant turns that called tools carry them (echoed OpenAI shape). */
+    readonly tool_calls?: readonly ToolCall[];
+    /** `tool` role replies reference the call they answer. */
+    readonly tool_call_id?: string;
+    readonly name?: string;
+}
+export interface ChatCompletionRequest {
+    readonly model: string;
+    readonly messages: readonly ChatMessage[];
+    readonly stream?: boolean;
+    readonly temperature?: number;
+    readonly top_p?: number;
+    readonly max_tokens?: number;
+    readonly tools?: readonly ToolDefinition[];
+    readonly tool_choice?: ToolChoice;
+    /** OpenAI structured-output request; the slug lane maps it to the route. */
+    readonly response_format?: {
+        readonly type: "text";
+    } | {
+        readonly type: "json_object";
+    } | {
+        readonly type: "json_schema";
+        readonly json_schema: {
+            readonly name: string;
+            readonly schema: object;
+            readonly strict?: boolean;
+        };
+    };
+    /** ModelRig extensions may ride here instead of headers (spec §3.4). */
+    readonly modelrig?: {
+        readonly envelope?: string;
+        readonly variant?: string;
+        readonly stream?: "buffered";
+    };
+}
+export interface ChatCompletionUsage {
+    readonly prompt_tokens: number;
+    readonly completion_tokens: number;
+    readonly total_tokens: number;
+}
+export interface ChatCompletionChoice {
+    readonly index: number;
+    readonly message: {
+        readonly role: "assistant";
+        readonly content: string | null;
+        readonly tool_calls?: readonly ToolCall[];
+    };
+    readonly finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null;
+}
+export interface ChatCompletionResponse {
+    readonly id: string;
+    readonly object: "chat.completion";
+    readonly created: number;
+    readonly model: string;
+    readonly choices: readonly ChatCompletionChoice[];
+    readonly usage: ChatCompletionUsage;
+}
+export interface ChatCompletionChunkChoice {
+    readonly index: number;
+    readonly delta: {
+        readonly role?: "assistant";
+        readonly content?: string | null;
+        readonly tool_calls?: readonly ToolCall[];
+    };
+    readonly finish_reason: ChatCompletionChoice["finish_reason"];
+}
+export interface ChatCompletionChunk {
+    readonly id: string;
+    readonly object: "chat.completion.chunk";
+    readonly created: number;
+    readonly model: string;
+    readonly choices: readonly ChatCompletionChunkChoice[];
+}
+/**
+ * The structured-route terminal event (spec §4.3). Streamed bytes on a
+ * structured route are PRE-validation; the endpoint closes the stream with this
+ * authoritative event (as a chunk with a `modelrig` extension) before
+ * `data: [DONE]`. It carries the validation verdict and, when repair fired, the
+ * repaired final object.
+ */
+export interface TerminalValidationEvent {
+    readonly object: "modelrig.validation";
+    readonly validated: boolean;
+    /** The validated (and possibly repaired) output object. */
+    readonly output: unknown;
+    readonly repairedBy: string | null;
+    readonly inferenceId: string;
+    readonly errors?: readonly string[];
+}
+/** The SSE sentinel that closes an OpenAI-compatible stream. */
+export declare const SSE_DONE = "[DONE]";
+//# sourceMappingURL=http-protocol.d.ts.map

package/dist/gateway/http-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-protocol.d.ts","sourceRoot":"","sources":["../../src/gateway/http-protocol.ts"],"names":[],"mappings":"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"}

package/dist/gateway/http-protocol.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * The HTTP gateway wire contract — G-1/G-5 (http-gateway spec §3, §4.3, §4.4).
+ *
+ * ONE definition of what a `/v1/chat/completions` request, response, and SSE
+ * chunk look like, plus the lane-disambiguation rule and the `x-modelrig-*`
+ * provenance headers. Both sides compile against it:
+ *
+ *   SDK (`packages/modelrig`)   — this repo; consumes the streaming/tool
+ *                                 surfaces the endpoint is built on.
+ *   `modelrig-server`           — separate repo (Phase B/C); implements the
+ *                                 endpoint and imports these types so the wire
+ *                                 shape cannot drift between the two.
+ *
+ * This mirrors `telemetry/ingest-protocol.ts`: a shared module is what makes
+ * "the two sides agree" enforceable rather than aspirational — a contract test
+ * round-trips the shapes on both sides instead of comparing two hand-written
+ * copies for similarity.
+ *
+ * TYPES + PURE FUNCTIONS ONLY. No transport, no auth, no I/O — the endpoint,
+ * SSE plumbing, and BYOK key resolution live server-side (spec §2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSE_DONE = exports.MODELRIG_REQUEST_HEADERS = exports.MODELRIG_HEADERS = exports.GATEWAY_PROTOCOL_VERSION = exports.MODELS_PATH = exports.CHAT_COMPLETIONS_PATH = void 0;
+exports.classifyLane = classifyLane;
+const provider_1 = require("../types/provider");
+/** The endpoint path. Spelled once. */
+exports.CHAT_COMPLETIONS_PATH = "/v1/chat/completions";
+/** The model-catalog path (routes + registry models) for SDK discovery. */
+exports.MODELS_PATH = "/v1/models";
+/** Bumped only for a breaking change to the shapes below. */
+exports.GATEWAY_PROTOCOL_VERSION = 1;
+// ── Provenance headers (spec §3.4) ───────────────────────────────────────────
+// Response headers that make a completion auditable: which lane served it,
+// which provider/model actually ran, whether the output was verified, and the
+// feedback handle. Named once so the SDK, the server, and the console cannot
+// disagree about the spelling.
+exports.MODELRIG_HEADERS = {
+    /** "slug" (verified pipeline) or "raw" (zero-margin BYOK passthrough). */
+    lane: "x-modelrig-lane",
+    /** Phase D (spec §13.1 rule 4): where the slug lane resolved its bundle —
+     * "local" (this deployment's own routes, the self-host path) or "mirror" (the
+     * org-scoped `routes` mirror, the hosted path). A deployment serves ONE or the
+     * OTHER and SAYS WHICH; the two must never silently blend. Absent on the raw
+     * lane. */
+    routeSource: "x-modelrig-route-source",
+    provider: "x-modelrig-provider",
+    model: "x-modelrig-model",
+    /** "true"/"false" — was the output schema-validated (slug lane only). */
+    validated: "x-modelrig-validated",
+    /** "provider/model" that repaired the output, when repair fired. */
+    repairedBy: "x-modelrig-repaired-by",
+    costUsd: "x-modelrig-cost-usd",
+    /** The `rig.feedback()` handle (telemetry inference id). */
+    inferenceId: "x-modelrig-inference-id",
+};
+// Request-side extension headers (spec §3.4).
+exports.MODELRIG_REQUEST_HEADERS = {
+    /** Per-run envelope key (budget). */
+    envelope: "x-modelrig-envelope",
+    /** Named route variant to serve. */
+    variant: "x-modelrig-variant",
+    /** "buffered" opts out of true streaming for validated-only output (§4.3). */
+    stream: "x-modelrig-stream",
+};
+/**
+ * The core routing rule (spec §3.3), as a pure function so both sides classify
+ * a `model` string identically:
+ *   1. `@rig/…` OR an exact known route slug  → slug lane (verified pipeline).
+ *   2. `^<providerId>/<model>$`, providerId ∈ PROVIDER_IDS → raw-model lane.
+ *   3. otherwise → unknown (the endpoint 404s; never silently guess).
+ *
+ * The namespaces don't collide: a route slug is a bare handle
+ * (`example.support_summarize`); a raw model always carries a known
+ * `provider/` prefix.
+ */
+function classifyLane(model, knownRouteSlugs = new Set()) {
+    const trimmed = model.trim();
+    if (trimmed === "") {
+        return { lane: "unknown", reason: "empty model field" };
+    }
+    if (trimmed.startsWith("@rig/")) {
+        const slug = trimmed.slice("@rig/".length);
+        if (slug === "")
+            return { lane: "unknown", reason: "empty route slug after @rig/" };
+        return { lane: "slug", slug };
+    }
+    if (knownRouteSlugs.has(trimmed)) {
+        return { lane: "slug", slug: trimmed };
+    }
+    const slash = trimmed.indexOf("/");
+    if (slash > 0) {
+        const provider = trimmed.slice(0, slash);
+        const rest = trimmed.slice(slash + 1);
+        if (rest !== "" && provider_1.PROVIDER_IDS.includes(provider)) {
+            return { lane: "raw", provider, model: rest };
+        }
+    }
+    return {
+        lane: "unknown",
+        reason: `"${trimmed}" is neither a known route slug nor a <provider>/<model> for a supported provider`,
+    };
+}
+/** The SSE sentinel that closes an OpenAI-compatible stream. */
+exports.SSE_DONE = "[DONE]";