@sema-agent/core 5.55.0 → 5.57.0

package/dist/brain/openai.js

@@ -5,7 +5,9 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders } from "./request-params.js";
+import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
+import { BrainError } from "./errors.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function closeToolCallAccum(acc) {
@@ -270,7 +272,17 @@ export function createOpenAIBrain(config = {}) {
             httpLabel: "gateway",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const apiKey = options?.apiKey ?? config.apiKey;
+                const routeCredential = resolveRouteCredential({
+                    optionsApiKey: options?.apiKey,
+                    optionsHeaders: options?.headers,
+                    modelHeaders: model.headers,
+                    configApiKey: config.apiKey,
+                    configHeaders: config.headers,
+                });
+                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
+                if (!routeVerdict.ok)
+                    throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
+                const apiKey = routeCredential.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
                 if (!root) {
                     throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
@@ -304,8 +316,7 @@ export function createOpenAIBrain(config = {}) {
                     body.stop = options.stop;
                 applyThinking(body, model, options?.reasoning);
                 const headers = mergeHeaders(model.headers, config.headers, options?.headers);
-                if (options?.apiKey !== undefined)
-                    stripAuthHeaders(headers);
+                applyRouteCredentialHeaders(headers, routeCredential, { model: model.headers, options: options?.headers });
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
@@ -618,5 +629,5 @@ export function createOpenAIBrain(config = {}) {
             },
         });
     };
-    return { stream };
+    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
 }

package/dist/brain/request-params.d.ts

@@ -22,17 +22,16 @@ export declare function reservedFor(api: string): ReadonlySet<string>;
  * deployment with no `extraBody` is unaffected.
  */
 export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): Record<string, unknown>;
-/**
- * Per-call auth REPLACES construction-time auth: drop every auth-bearing header
- * (case-insensitive `authorization` / `x-api-key`) from an already-merged header bag. Called by a
- * brain's buildRequest ONLY when a per-call `options.apiKey` is present — the brain then re-emits
- * the credential in its own wire posture (anthropic `x-api-key`, openai `Bearer`), making the
- * per-call key the request's single credential. Case-insensitivity matters twice: a
- * construction-time `Authorization` (capital A) is what boot env tokens ship, and a case-variant
- * duplicate would otherwise ride the wire alongside the hard-locked lowercase form (fetch Headers
- * folds duplicates into one comma-joined value — broken auth both ways).
- */
-export declare function stripAuthHeaders(headers: Record<string, string>): void;
+/** The auth-bearing header names (case-fold), single-sourced for the credential enforcement
+ *  (`applyRouteCredentialHeaders`, route-adjudicator.ts — the ONE authority over auth spelling: a
+ *  per-model winner strips every carrier, any case, and re-asserts the winning bag's own),
+ *  {@link mergeHeaders} (which EXEMPTS them — see there), and the route credential resolver (which
+ *  reads carrier PRESENCE per bag to classify a headers-borne credential). The former per-call
+ *  strip helper that lived here (`stripAuthHeaders` — "per-call auth replaces construction-time
+ *  auth", triggered on `options.apiKey` presence) is retired: the three brains now run the
+ *  route-credential resolution instead, whose per-model arm strips a strict superset of what the
+ *  helper did. */
+export declare const AUTH_CARRIER_NAMES: ReadonlySet<string>;
 /**
  * #343 — the shared USER-HEADER merge layer (`model.headers` → construction `config.headers` →
  * per-call `options.headers`, later bag wins), CASE-FOLD deduplicated: HTTP header field names are
@@ -45,26 +44,29 @@ export declare function stripAuthHeaders(headers: Record<string, string>): void;
  * deployment — is byte-identical on the wire).
  *
  * EXEMPT: the auth carriers (`authorization` / `x-api-key`, any case) pass through with the exact
- * legacy spread semantics (same-spelling override only, no case-fold dedup), so that
- * {@link stripAuthHeaders} stays the ONE authority over auth spelling and this layer never becomes a
- * second, subtly different one.
+ * legacy spread semantics (same-spelling override only, no case-fold dedup), so that the credential
+ * enforcement (`applyRouteCredentialHeaders`, route-adjudicator.ts) stays the ONE authority over
+ * auth spelling and this layer never becomes a second, subtly different one.
  *
  * RE-RULED, because the exemption used to be justified by a reason that does not hold: the
  * note claimed it protected "the header-only ANTHROPIC_AUTH_TOKEN shape, which must survive under its
  * own capital-A spelling". Dedup would not endanger that shape — it keeps the WINNER'S spelling, and a
  * lone `Authorization` has nothing to be deduped against, so it survives either way; nor does the
- * per-call-replaces flow depend on the exemption, since {@link stripAuthHeaders} already deletes every
- * spelling present. Measured, not reasoned: `mergeHeaders({Authorization:A},{authorization:B})` keeps
- * BOTH, and the platform `Headers` fold sends `authorization: A, B`.
+ * credential-replaces flow depend on the exemption, since the enforcement already deletes every
+ * spelling present when a per-model credential wins. Measured, not reasoned:
+ * `mergeHeaders({Authorization:A},{authorization:B})` keeps BOTH, and the platform `Headers` fold
+ * sends `authorization: A, B`.
  *
- * STATED RESIDUAL (deliberately not fixed here): a deployment that spells the SAME auth carrier two
- * ways across two layers therefore ships both, comma-folded — the very disease this function fixed
- * for every other header. It is held, not denied, on severity: no server accepts a comma-joined
- * credential, so the failure is a LOUD 401 attributable to the misconfiguration, whereas the
- * non-auth case this function exists for produced a silently WRONG value (`X-Tenant: a, b` — neither
- * writer's, the later layer's documented override defeated). Tightening it changes which credential
- * reaches the wire, so it belongs in a window that discloses an auth-face behavior change, not in one
- * whose subject is the reasoning knob.
+ * STATED RESIDUAL (deliberately not fixed here), NARROWED by the credential enforcement: where a
+ * PER-MODEL credential wins (an options- or entry-bag carrier), every carrier is stripped and only
+ * the winning bag's re-asserted, so a cross-layer double spelling now folds to the winner. What
+ * remains is the DEPLOYMENT-CONFIG arm — its bytes ride untouched by design — so a config bag that
+ * itself spells the SAME auth carrier two ways still ships both, comma-folded. It is held, not
+ * denied, on severity: no server accepts a comma-joined credential, so the failure is a LOUD 401
+ * attributable to the misconfiguration, whereas the non-auth case this function exists for produced
+ * a silently WRONG value (`X-Tenant: a, b` — neither writer's, the later layer's documented
+ * override defeated). Tightening it changes which credential reaches the wire, so it belongs in a
+ * window that discloses an auth-face behavior change.
  */
 /**
  * #343 (review r4) — assign a STRUCTURAL locked header under its canonical lowercase name, deleting
@@ -72,8 +74,9 @@ export declare function stripAuthHeaders(headers: Record<string, string>): void;
  * the user-bag merge precisely so they "can NEVER be overridden" (council design/40) — but a valid
  * user bag carrying `Content-Type: text/plain` survived BESIDE the lowercase lock, and the platform
  * `Headers` fold turns the pair into `text/plain, application/json` on the wire: the lock decided
- * nothing. Auth carriers are deliberately NOT routed through here (per-call replacement + the
- * header-only boot flow are {@link stripAuthHeaders}' pinned jurisdiction).
+ * nothing. Auth carriers are deliberately NOT routed through here (credential replacement + the
+ * header-only boot flow are the pinned jurisdiction of `applyRouteCredentialHeaders`,
+ * route-adjudicator.ts).
  */
 export declare function lockHeader(headers: Record<string, string>, lowerName: string, value: string): void;
 /**

package/dist/brain/request-params.js

@@ -54,13 +54,7 @@ export function applyExtraBody(body, extraBody, reserved) {
     }
     return { ...passthrough, ...body };
 }
-const AUTH_CARRIER_NAMES = new Set(["authorization", "x-api-key"]);
-export function stripAuthHeaders(headers) {
-    for (const k of Object.keys(headers)) {
-        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
-            delete headers[k];
-    }
-}
+export const AUTH_CARRIER_NAMES = new Set(["authorization", "x-api-key"]);
 export function lockHeader(headers, lowerName, value) {
     for (const k of Object.keys(headers)) {
         if (k !== lowerName && k.toLowerCase() === lowerName)

package/dist/brain/route-adjudicator.d.ts

@@ -0,0 +1,190 @@
+/**
+ * key↔URL route pairing adjudication — the SINGLE source of the pairing law.
+ *
+ * The invariant: **the credential a request carries must belong to the URL the request targets.**
+ * A request's URL half is per-ENTRY (`Model.baseUrl`, a required field) while the historical
+ * credential fallback was per-BRAIN-INSTANCE (`options.apiKey ?? config.apiKey`): with more than one
+ * entry flowing through one brain, the deployment credential silently followed EVERY entry's URL —
+ * including a third-party host it was never meant for. This module is what the three first-party
+ * brains now consult before shaping a request, what the brain decorators re-walk per hop (each
+ * hop/route re-resolves the three credential states for ITS model against ITS config), and what
+ * external consumers (a server annotating a model roster, a conformance suite) import so there is
+ * exactly one implementation of the law.
+ *
+ * The judgment, by credential source (see {@link RouteCredentialSource}):
+ *  - `per-model` → OK always. A per-model credential was resolved FOR this entry (auth hook or an
+ *    auth header on `Model.headers`); it is paired by construction, so the per-model lane pays no
+ *    new cost.
+ *  - `deployment-config` → OK only where the pairing is verifiable-and-true: the deployment DECLARED
+ *    its credential's URL half (`config.baseUrl`) and the request targets exactly that root.
+ *    A declared root with a diverging entry URL is the torn pair this module exists to stop
+ *    (`route.credential_mismatch`). An UNDECLARED root (`config.apiKey` with no `config.baseUrl`)
+ *    stays allowed as the `"unpinned"` posture — that is the documented single-endpoint quick-start
+ *    shape (key on config, URL on the model) and refusing it would break every deployment built from
+ *    it; the posture is surfaced so read faces can annotate the unverifiable pairing instead.
+ *  - `absent` → OK for keyless deployments (nothing to protect); refused as
+ *    `route.credential_missing` only where an entry declares its OWN URL away from a DECLARED
+ *    deployment root — a distinct endpoint with no credential route is a configuration hole, and a
+ *    loud refusal with a fix hint beats an unauthenticated request to a third-party host.
+ *
+ * Fail-closed direction: "no credential leak" outranks "silently works". A deployment that only
+ * worked because the gateway key HAPPENED to be valid at another entry's host now refuses loudly,
+ * and every refusal names the entry, both URL halves, and a one-line fix.
+ *
+ * Bad-value loudness (garbage / contradiction / absence):
+ *  - garbage — non-string URL/credential inputs throw a `TypeError` here (a programmer error must
+ *    not be laundered into a polite verdict); whitespace-only URLs normalize to "" (undeclared).
+ *  - contradiction — the torn pair refuses with `route.credential_mismatch` + both halves named.
+ *  - absence — `route.credential_missing` with the fix hint, exactly where absence is a hole.
+ */
+import type { Model } from "../internal/llm.js";
+import type { RouteAdjudication, RouteCredential, RoutePairingConfig, RoutePairingPosture } from "../internal/llm.js";
+import type { Brain, EngineNotice } from "../core/types.js";
+/** Normalize a base URL for pairing comparison, to WIRE equivalence: trim + strip trailing
+ *  slashes, then — for a string that parses as a URL — fold the halves the wire itself treats as
+ *  case-insensitive (scheme and host, RFC 9110) and elide the scheme's default port, while keeping
+ *  the PATH byte-preserved (paths are case-sensitive; folding them would compare two genuinely
+ *  different endpoints equal — a widening of exactly the leak this module exists to stop). Two
+ *  spellings that resolve to the same origin+path on the wire therefore compare equal, and a
+ *  refusal can never be minted over a spelling difference the wire cannot see. A value that does
+ *  not parse as a URL keeps the raw trimmed spelling — the same fail-closed raw comparison as
+ *  before. Non-string input throws — see the module note on garbage. */
+export declare function normalizeBaseUrl(url: string | undefined): string;
+/** Whether a header bag carries an auth-bearing header (any case). */
+export declare function hasAuthCarrier(headers: Record<string, string> | undefined): boolean;
+/**
+ * Resolve WHICH credential a request would carry, tagged with its source — the input half of the
+ * adjudication. Precedence (most-specific wins):
+ *   1. `options.apiKey` (per-call, from the per-model auth hook — presence, not truthiness: an
+ *      empty string is a present credential that fails closed at emit),
+ *   2. an auth carrier in `options.headers` (per-call headers-borne). The bag MUST be per-model
+ *      sourced (the per-model auth hook's headers) — that provenance is what licenses the
+ *      "paired by construction" verdict below. A caller that folds run-wide headers into the
+ *      per-call options must strip auth carriers first (the harness merge does), or a deployment
+ *      credential would ride here and be judged per-model,
+ *   3. an auth carrier in `model.headers` (the ENTRY's own declared credential),
+ *   4. the deployment config (`config.apiKey` and/or an auth carrier in `config.headers` —
+ *      deliberately ONE rank, not two: a config carrying BOTH forms is the documented gateway
+ *      dual-auth escape shape, and both ride exactly as they always have; the pairing gate judges
+ *      the pair as one deployment credential),
+ *   5. absent.
+ * 1–3 are `per-model`; 4 is `deployment-config`.
+ */
+export declare function resolveRouteCredential(input: {
+    optionsApiKey?: string;
+    optionsHeaders?: Record<string, string>;
+    modelHeaders?: Record<string, string>;
+    configApiKey?: string;
+    configHeaders?: Record<string, string>;
+}): RouteCredential;
+/**
+ * The pairing law (module note above). Pure and deterministic: same inputs, same verdict — safe to
+ * call both at a resolution seat (pre-flight) and again inside a brain's request build.
+ */
+export declare function adjudicateModelRoute(model: Pick<Model, "id" | "baseUrl">, credential: RouteCredential, config: RoutePairingConfig): RouteAdjudication;
+/** Render a refusal as the one-line detail text the brains put in their thrown error (the machine
+ *  code leads so log/transcript consumers can grep it; the fix hint closes it). */
+export declare function routeRefusalText(verdict: Extract<RouteAdjudication, {
+    ok: false;
+}>): string;
+/**
+ * Enforce "the resolved credential is the request's ONLY credential" on an already-merged header
+ * bag — the per-call-auth-replaces rule, generalized to the per-model sources:
+ *  - PER-MODEL apiKey-form winner → every auth carrier is stripped; the brain then emits the key in
+ *    its own wire posture, the single credential on the wire (the pre-existing per-call rule).
+ *  - PER-MODEL headers-borne winner (per-call or entry bag) → carriers are stripped and the winning
+ *    bag's own carriers re-asserted (an entry-declared credential must survive a same- or
+ *    variant-case deployment spelling that the plain merge order would have let win).
+ *  - DEPLOYMENT-CONFIG winner → untouched. The historical bytes stand exactly: a header-only config
+ *    keeps its own spelling, and a config carrying BOTH the apiKey knob and an auth header is the
+ *    documented gateway dual-auth escape shape — the knob's hard-lock write plus the surviving
+ *    header, both on the wire, as they always were.
+ *  - absent → untouched (no carriers exist).
+ */
+export declare function applyRouteCredentialHeaders(merged: Record<string, string>, credential: RouteCredential, bags: {
+    model?: Record<string, string>;
+    options?: Record<string, string>;
+}): void;
+/**
+ * The first-party brains' `adjudicateRoute` face, closed over the brain's construction config —
+ * EXACTLY the resolution + judgment the brain's own request build runs (single source, two call
+ * sites), so a pre-flight verdict and the request-time verdict can never disagree.
+ */
+export declare function createBrainRouteJudge(config: {
+    apiKey?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+}): (model: Model, perModelAuth?: {
+    apiKey?: string;
+    headers?: Record<string, string>;
+}) => RouteAdjudication;
+/**
+ * Per-entry pairing status — the read-face predicate a roster/diagnostic surface annotates entries
+ * with, so a torn pair is visible at configuration time instead of on the first real request.
+ * `judge` is a brain's optional `adjudicateRoute` face; absent ⇒ `"unknown"` (a custom brain core
+ * cannot see into — never guessed at).
+ */
+export type RoutePairingStatus = `ok:${RoutePairingPosture}` | `broken:${"credential_mismatch" | "credential_missing"}` | "unknown";
+export declare function routePairingStatus(brain: {
+    adjudicateRoute?: (model: Model, perModelAuth?: {
+        apiKey?: string;
+        headers?: Record<string, string>;
+    }) => RouteAdjudication | undefined;
+}, model: Model, perModelAuth?: {
+    apiKey?: string;
+    headers?: Record<string, string>;
+}): RoutePairingStatus;
+/**
+ * Pre-flight a DERIVED-leg model (one the engine resolved from a role/tier/system default rather
+ * than an explicit caller `model`) against the deployment brain's pairing judge. The two-leg
+ * disposition for a broken pairing:
+ *  - a NAMED model (explicit in the spec) refuses loudly at the brain's request gate — the caller
+ *    asked for that exact route and gets the refusal + fix hint;
+ *  - a DERIVED model must not sink the main-model task it serves — the seat falls back to the
+ *    primary model and announces `route.fallback_to_primary` (the notice IS the loudness; a silent
+ *    swap would hide the misconfiguration this whole surface exists to expose).
+ * Returns the verdict, or `undefined` when no judgment is possible (the brain has no judge face,
+ * the judge itself threw, or the auth hook threw or outran the advisory bound — in which case the
+ * seat proceeds unchanged and the failure/latency surfaces at its own request-time call site
+ * exactly as before).
+ *
+ * The hook call is BOUNDED. The pre-flight is advisory (the request gate re-runs the same law), so
+ * it must never widen a slow secret manager's blast radius from "the derived call is slow" to "task
+ * preparation is wedged": past the bound the pre-flight simply abstains. The eventual request still
+ * resolves the hook itself (the pre-flight result is never reused as a credential — same-inputs
+ * determinism of the law is what keeps the two calls' verdicts aligned, not a cached secret).
+ */
+export declare const DERIVED_ROUTE_PREFLIGHT_HOOK_BOUND_MS = 5000;
+export declare function adjudicateDerivedRoute(args: {
+    brain: Brain;
+    model: Model;
+    getApiKeyAndHeaders?: ((model: Model) => Promise<{
+        apiKey?: string;
+        headers?: Record<string, string>;
+    } | undefined> | {
+        apiKey?: string;
+        headers?: Record<string, string>;
+    } | undefined) | undefined;
+}): Promise<RouteAdjudication | undefined>;
+/**
+ * Whether two resolved models denote the SAME route for pre-flight purposes: identical wire id AND
+ * identical normalized entry URL. `Model.id` alone is NOT route identity — two catalog entries can
+ * legitimately share a wire id (the same model served from two endpoints), and a same-id guard
+ * would silently skip the pre-flight for exactly the split the pairing law exists to judge.
+ */
+export declare function sameRouteIdentity(a: Pick<Model, "id" | "baseUrl">, b: Pick<Model, "id" | "baseUrl">): boolean;
+/** The `route.fallback_to_primary` announcement — one shared shape for every derived-leg seat, so
+ *  a consumer can rely on `detail.{seat, from, to, cause}` regardless of which seat fell back. */
+export declare function fallbackToPrimaryNotice(args: {
+    seat: string;
+    from: string;
+    to: string;
+    verdict: Extract<RouteAdjudication, {
+        ok: false;
+    }>;
+}): EngineNotice;
+/** The auth carriers of a header bag, canonicalized (case-fold name → value, sorted) — the
+ *  Model-visible credential fingerprint used by catalog-change disclosure (a same-name entry whose
+ *  URL moved while this fingerprint did not is the "address changed, credential reference did not"
+ *  shape worth announcing). */
+export declare function authCarrierFingerprint(headers: Record<string, string> | undefined): string;

package/dist/brain/route-adjudicator.js

@@ -0,0 +1,189 @@
+import { AUTH_CARRIER_NAMES } from "./request-params.js";
+export function normalizeBaseUrl(url) {
+    if (url === undefined)
+        return "";
+    if (typeof url !== "string") {
+        throw new TypeError(`route pairing: baseUrl must be a string (got ${typeof url})`);
+    }
+    const raw = url.trim().replace(/\/+$/, "");
+    if (raw === "")
+        return "";
+    try {
+        const u = new URL(raw);
+        return `${u.protocol}//${u.host}${u.pathname}${u.search}`.replace(/\/+$/, "");
+    }
+    catch {
+        return raw;
+    }
+}
+export function hasAuthCarrier(headers) {
+    if (!headers)
+        return false;
+    for (const k of Object.keys(headers)) {
+        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
+            return true;
+    }
+    return false;
+}
+export function resolveRouteCredential(input) {
+    const { optionsApiKey, optionsHeaders, modelHeaders, configApiKey, configHeaders } = input;
+    if (optionsApiKey !== undefined) {
+        if (typeof optionsApiKey !== "string")
+            throw new TypeError(`route pairing: apiKey must be a string (got ${typeof optionsApiKey})`);
+        return { source: "per-model", apiKey: optionsApiKey };
+    }
+    if (hasAuthCarrier(optionsHeaders))
+        return { source: "per-model", headersBorne: true, carrierBag: "options" };
+    if (hasAuthCarrier(modelHeaders))
+        return { source: "per-model", headersBorne: true, carrierBag: "model" };
+    const configHeadersBorne = hasAuthCarrier(configHeaders);
+    if (configApiKey !== undefined || configHeadersBorne) {
+        if (configApiKey !== undefined && typeof configApiKey !== "string") {
+            throw new TypeError(`route pairing: apiKey must be a string (got ${typeof configApiKey})`);
+        }
+        return {
+            source: "deployment-config",
+            ...(configApiKey !== undefined ? { apiKey: configApiKey } : {}),
+            ...(configHeadersBorne ? { headersBorne: true, carrierBag: "config" } : {}),
+        };
+    }
+    return { source: "absent" };
+}
+export function adjudicateModelRoute(model, credential, config) {
+    const entry = normalizeBaseUrl(model.baseUrl);
+    const declared = normalizeBaseUrl(config.baseUrl);
+    const request = entry || declared;
+    if (credential.source === "per-model")
+        return { ok: true, posture: "per-model" };
+    if (credential.source === "deployment-config") {
+        if (declared === "")
+            return { ok: true, posture: "unpinned" };
+        if (request === declared)
+            return { ok: true, posture: "paired" };
+        return {
+            ok: false,
+            code: "route.credential_mismatch",
+            detail: {
+                modelId: model.id,
+                entryBaseUrl: entry,
+                requestBaseUrl: request,
+                configBaseUrl: declared,
+                fixHint: `model "${model.id}" targets ${request} but the deployment credential is paired with ${declared}: ` +
+                    `give the model its own credential (a per-model key via getApiKeyAndHeaders, or an auth header on Model.headers), ` +
+                    `or serve it through a brain whose config.baseUrl is ${request}`,
+            },
+        };
+    }
+    if (declared === "" || entry === "" || request === declared)
+        return { ok: true, posture: "keyless" };
+    return {
+        ok: false,
+        code: "route.credential_missing",
+        detail: {
+            modelId: model.id,
+            entryBaseUrl: entry,
+            requestBaseUrl: request,
+            configBaseUrl: declared,
+            fixHint: `model "${model.id}" targets ${request} but no credential is configured for that endpoint ` +
+                `(the deployment credential root is ${declared}): supply a per-model credential ` +
+                `(getApiKeyAndHeaders, or an auth header on Model.headers), or serve it through a brain constructed for ${request}`,
+        },
+    };
+}
+export function routeRefusalText(verdict) {
+    return `${verdict.code}: ${verdict.detail.fixHint}`;
+}
+export function applyRouteCredentialHeaders(merged, credential, bags) {
+    if (credential.source !== "per-model")
+        return;
+    for (const k of Object.keys(merged)) {
+        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
+            delete merged[k];
+    }
+    if (credential.headersBorne !== true)
+        return;
+    const winner = credential.carrierBag === "options" ? bags.options : bags.model;
+    if (!winner)
+        return;
+    for (const [k, v] of Object.entries(winner)) {
+        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
+            merged[k] = v;
+    }
+}
+export function createBrainRouteJudge(config) {
+    return (model, perModelAuth) => {
+        const credential = resolveRouteCredential({
+            optionsApiKey: perModelAuth?.apiKey,
+            optionsHeaders: perModelAuth?.headers,
+            modelHeaders: model.headers,
+            configApiKey: config.apiKey,
+            configHeaders: config.headers,
+        });
+        return adjudicateModelRoute(model, credential, { baseUrl: config.baseUrl });
+    };
+}
+export function routePairingStatus(brain, model, perModelAuth) {
+    const verdict = brain.adjudicateRoute?.(model, perModelAuth);
+    if (verdict === undefined)
+        return "unknown";
+    if (verdict.ok)
+        return `ok:${verdict.posture}`;
+    return verdict.code === "route.credential_mismatch" ? "broken:credential_mismatch" : "broken:credential_missing";
+}
+export const DERIVED_ROUTE_PREFLIGHT_HOOK_BOUND_MS = 5_000;
+export async function adjudicateDerivedRoute(args) {
+    const judge = args.brain.adjudicateRoute;
+    if (judge === undefined)
+        return undefined;
+    let auth;
+    if (args.getApiKeyAndHeaders !== undefined) {
+        let timer;
+        const ABSTAIN = Symbol("preflight-abstain");
+        try {
+            const bound = new Promise((resolve) => {
+                timer = setTimeout(() => resolve(ABSTAIN), DERIVED_ROUTE_PREFLIGHT_HOOK_BOUND_MS);
+            });
+            const hookResult = Promise.resolve(args.getApiKeyAndHeaders(args.model));
+            hookResult.catch(() => { });
+            const raced = await Promise.race([hookResult, bound]);
+            if (raced === ABSTAIN)
+                return undefined;
+            auth = raced;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    try {
+        return judge(args.model, auth);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function sameRouteIdentity(a, b) {
+    return a.id === b.id && normalizeBaseUrl(a.baseUrl) === normalizeBaseUrl(b.baseUrl);
+}
+export function fallbackToPrimaryNotice(args) {
+    return {
+        code: "route.fallback_to_primary",
+        message: `derived model "${args.from}" (${args.seat}) is not routable (${args.verdict.code}) — ` +
+            `falling back to the primary model "${args.to}". ${args.verdict.detail.fixHint}`,
+        detail: { seat: args.seat, from: args.from, to: args.to, cause: args.verdict.code, fixHint: args.verdict.detail.fixHint },
+    };
+}
+export function authCarrierFingerprint(headers) {
+    if (!headers)
+        return "";
+    const rows = [];
+    for (const [k, v] of Object.entries(headers)) {
+        const fold = k.toLowerCase();
+        if (AUTH_CARRIER_NAMES.has(fold))
+            rows.push(`${fold}=${v}`);
+    }
+    return rows.sort().join("\n");
+}

package/dist/brain/route-conformance.d.ts

@@ -0,0 +1,55 @@
+import type { RouteAdjudication, RouteCredential, RoutePairingConfig } from "../internal/llm.js";
+/**
+ * The PUBLISHED golden conformance corpus for the key↔URL pairing adjudicator
+ * ({@link import("./route-adjudicator.js").adjudicateModelRoute}).
+ *
+ * THE SEAM. The pairing law has exactly ONE implementation — core's `adjudicateModelRoute` — and
+ * every consumer that surfaces routing verdicts (a server annotating its model roster, a brain
+ * degradation leg replacing a hand-rolled check) MUST delegate to it rather than re-derive
+ * "does this key belong to this URL". This corpus is the anti-drift anchor between codebases
+ * (the gold-corpus discipline):
+ *  - CORE runs it as a regression test (`test/route-adjudication.test.ts`): every vector's `expect`
+ *    MUST equal `adjudicateModelRoute(model, credential, config)` on the `ok`/`posture`/`code`
+ *    axes. A change to the law fails the test and updates the corpus in lockstep with the engine
+ *    version, so the published contract can never silently drift from the implementation.
+ *  - A CONSUMER imports this corpus from `@sema-agent/core` and runs it as a CONTRACT test against
+ *    whatever face it wired the adjudicator into: for each vector, its surface's
+ *    allow/annotate/refuse of the described route MUST match `expect.ok` (and forward
+ *    `expect.code` verbatim on refusals). That proves the surface actually routes through core's
+ *    predicate.
+ *
+ * ⚠️ CONSUMER CONTRACT: depend on `expect.ok` + `expect.code` (+ `expect.posture` if the surface
+ * annotates postures). `fixHint` wording is core-internal and may be reworded without notice.
+ *
+ * `leg` is ADVISORY: how the refusal is DISPOSED of in the engine's two-leg discipline — a
+ * `"named"` (caller-explicit) model surfaces the refusal loudly at the request gate; a `"derived"`
+ * (role/tier/system-default) model falls back to the primary model with a
+ * `route.fallback_to_primary` notice. The verdict itself is leg-independent (same law both legs).
+ */
+export interface RouteAdjudicationVector {
+    /** Stable case id (appears in test output + the published contract). */
+    name: string;
+    /** What this vector proves. */
+    intent: string;
+    model: {
+        id: string;
+        baseUrl: string;
+    };
+    credential: RouteCredential;
+    config: RoutePairingConfig;
+    /** The `ok` / `posture` / `code` axes of the expected {@link RouteAdjudication}. */
+    expect: {
+        ok: true;
+        posture: Extract<RouteAdjudication, {
+            ok: true;
+        }>["posture"];
+    } | {
+        ok: false;
+        code: Extract<RouteAdjudication, {
+            ok: false;
+        }>["code"];
+    };
+    /** Advisory: how the engine's two-leg discipline disposes of this shape (see module note). */
+    leg?: "named" | "derived";
+}
+export declare const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS: readonly RouteAdjudicationVector[];