@sema-agent/core 7.51.1 → 7.52.0

package/dist/brain/open-responses.js

@@ -5,13 +5,14 @@ import { STREAM_TORN_WARNING, createRepetitionPoll, modelOutputInvalidOf, noteRe
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } 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 { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
+import { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
 import { resolveFetch } from "./transport.js";
+const OPEN_RESPONSES_KEY_HEADER = "authorization";
 const DEGENERATE_POLL_CHARS = 64;
 const MALFORMED_SAMPLE_CHARS = 160;
 const MALFORMED_ARGS_CHARS = 200;
@@ -239,20 +240,22 @@ export function createOpenResponsesBrain(given = {}) {
             maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl);
+                const routed = { id: model.id, baseUrl: model.baseUrl };
+                const { root, origin: rootOrigin } = resolveRequestRootOf(routed.baseUrl, config.baseUrl);
                 if (!root) {
                     throw new Error("createOpenResponsesBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
                 }
+                const modelHeaders = headerBagOnce(model.headers);
+                const optionsHeaders = headerBagOnce(options?.headers);
                 const routeCredential = resolveRouteCredential({
                     optionsApiKey: options?.apiKey,
-                    optionsHeaders: options?.headers,
-                    modelHeaders: model.headers,
+                    optionsHeaders,
+                    modelHeaders,
                     configApiKey: config.apiKey,
                     configHeaders: config.headers,
+                    keyHeader: OPEN_RESPONSES_KEY_HEADER,
                 });
-                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
-                if (!routeVerdict.ok)
-                    throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
+                const routeAdmission = admitRouteRequest(routed, routeCredential, { baseUrl: config.baseUrl });
                 const apiKey = routeCredential.apiKey;
                 if (options?.stop !== undefined && options.stop.length > 0) {
                     throw new Error("createOpenResponsesBrain: options.stop is not expressible in the Open Responses request (the wire form has no stop-sequence field); " +
@@ -285,11 +288,11 @@ export function createOpenResponsesBrain(given = {}) {
                 }
                 if (effort !== undefined)
                     body.reasoning = { effort };
-                const headers = mergeHeaders(model.headers, config.headers, options?.headers);
-                applyRouteCredentialHeaders(headers, routeCredential, { model: model.headers, options: options?.headers });
+                const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
+                applyRouteCredentialHeaders(headers, routeCredential);
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
-                    headers["authorization"] = `Bearer ${apiKey}`;
+                    lockHeader(headers, OPEN_RESPONSES_KEY_HEADER, `Bearer ${apiKey}`);
                 const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, RESPONSES_RESERVED);
                 return {
                     url: joinRequestUrl(root, "/responses"),
@@ -300,6 +303,7 @@ export function createOpenResponsesBrain(given = {}) {
                     outputCapTokens: effectiveOutputCap(wire, OUTPUT_CAP_KEYS.responses),
                     capDerivedPaths: OUTPUT_CAP_KEYS.responses,
                     onCommitted: () => {
+                        routeAdmission();
                         sentMaxTokens = builtMaxTokens;
                         sentMaxTokensLane = builtMaxTokensLane;
                         sentEffort = effort;
@@ -773,5 +777,5 @@ export function createOpenResponsesBrain(given = {}) {
             },
         });
     };
-    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
+    return { stream, adjudicateRoute: createBrainRouteJudge({ ...config, keyHeader: OPEN_RESPONSES_KEY_HEADER }) };
 }

package/dist/brain/openai.js

@@ -5,15 +5,16 @@ import { STREAM_TORN_WARNING, createRepetitionPoll, createStreamEndLedger, echoF
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } 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 } from "./request-params.js";
+import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
 import { BrainError, providerErrorWord } from "./errors.js";
 import { inBandProviderError } from "./provider-dialect.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
 import { resolveFetch } from "./transport.js";
+const OPENAI_KEY_HEADER = "authorization";
 function closeToolCallAccum(acc, responseIds, closed) {
     if (acc.closedTc)
         return acc.closedTc;
@@ -342,20 +343,22 @@ export function createOpenAIBrain(given = {}) {
             maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl);
+                const routed = { id: model.id, baseUrl: model.baseUrl };
+                const { root, origin: rootOrigin } = resolveRequestRootOf(routed.baseUrl, config.baseUrl);
                 if (!root) {
                     throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
                 }
+                const modelHeaders = headerBagOnce(model.headers);
+                const optionsHeaders = headerBagOnce(options?.headers);
                 const routeCredential = resolveRouteCredential({
                     optionsApiKey: options?.apiKey,
-                    optionsHeaders: options?.headers,
-                    modelHeaders: model.headers,
+                    optionsHeaders,
+                    modelHeaders,
                     configApiKey: config.apiKey,
                     configHeaders: config.headers,
+                    keyHeader: OPENAI_KEY_HEADER,
                 });
-                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
-                if (!routeVerdict.ok)
-                    throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
+                const routeAdmission = admitRouteRequest(routed, routeCredential, { baseUrl: config.baseUrl });
                 const apiKey = routeCredential.apiKey;
                 const body = {
                     model: model.id,
@@ -385,11 +388,11 @@ export function createOpenAIBrain(given = {}) {
                 if (options?.stop)
                     body.stop = options.stop;
                 applyThinking(body, model, options?.reasoning);
-                const headers = mergeHeaders(model.headers, config.headers, options?.headers);
-                applyRouteCredentialHeaders(headers, routeCredential, { model: model.headers, options: options?.headers });
+                const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
+                applyRouteCredentialHeaders(headers, routeCredential);
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
-                    headers["authorization"] = `Bearer ${apiKey}`;
+                    lockHeader(headers, OPENAI_KEY_HEADER, `Bearer ${apiKey}`);
                 const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, OPENAI_RESERVED);
                 return {
                     url: joinRequestUrl(root, "/chat/completions"),
@@ -400,6 +403,7 @@ export function createOpenAIBrain(given = {}) {
                     outputCapTokens: effectiveOutputCap(wire, OUTPUT_CAP_KEYS.openai),
                     capDerivedPaths: [mtField],
                     onCommitted: () => {
+                        routeAdmission();
                         sentMaxTokens = builtMaxTokens;
                         sentMaxTokensLane = builtMaxTokensLane;
                     },
@@ -749,5 +753,5 @@ export function createOpenAIBrain(given = {}) {
             },
         });
     };
-    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
+    return { stream, adjudicateRoute: createBrainRouteJudge({ ...config, keyHeader: OPENAI_KEY_HEADER }) };
 }

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

@@ -1,19 +1,3 @@
-/**
- * Request-parameter passthrough (design/40). A deployment can set official provider params it wants but
- * core doesn't model as first-class fields (OpenAI `frequency_penalty`/`presence_penalty`/`top_p`/`seed`/
- * `logit_bias`; Anthropic `top_k`/`top_p`/`stop_sequences`; …) via `Model.extraBody`, and core merges them
- * into the brain's request body. Anchored at the **Model** level (not per-turn) so the serialized body
- * stays byte-stable across turns → the prefix cache holds (design/9/31).
- *
- * Symmetric: each brain owns its structural + tuning keys (`reserved`) and ALWAYS wins — `extraBody` can
- * only supply the long tail, never clobber `messages`/`tools`/`temperature`/etc. Stripping is the safety
- * enforcement (the brains are standalone-usable), and a strip is never silent: {@link applyExtraBody}
- * RETURNS the keys it stripped, the brain reports them on the request it built
- * (`SSERequest.extraBodyDropped`), the stream engine reports them to the run's sink when it commits that
- * request (`reportExtraBodyDropped`), and the Runner announces them (`route.extra_body_reserved_dropped`).
- * One reading, at the one place the strip happens — so an `extraBody` a host brain swapped in for a single
- * request, or one on the compaction model, is said the same way the task's own model spec is.
- */
 /** OpenAI request-body keys core owns; `extraBody` cannot override these. */
 export declare const OPENAI_RESERVED: ReadonlySet<string>;
 /** Anthropic request-body keys core owns; `extraBody` cannot override these. (Note the asymmetry vs
@@ -43,16 +27,6 @@ export declare function applyExtraBody(body: Record<string, unknown>, extraBody:
     body: Record<string, unknown>;
     dropped: readonly string[];
 };
-/** 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
@@ -62,10 +36,11 @@ export declare const AUTH_CARRIER_NAMES: ReadonlySet<string>;
  * override silently defeated. A later bag's entry replaces an earlier case-variant instead; the
  * WINNER'S spelling and value survive (a single-spelling config is byte-identical on the wire).
  *
- * EXEMPT: the auth carriers (`authorization` / `x-api-key`, any case) pass through with plain
- * 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.
+ * EXEMPT: the credential headers ({@link isCredentialHeaderName}, the engine's one reading of which
+ * header carries a credential: `authorization`, `x-api-key`, `api-key`, `cookie`, …, any case) pass
+ * through with plain spread semantics (same-spelling override only, no case-fold dedup), so that the
+ * credential enforcement (`applyRouteCredentialHeaders`, route-adjudicator.ts) stays the ONE authority
+ * over credential spelling and this layer never becomes a second, subtly different one.
  *
  * The exemption is NOT what keeps a header-only `ANTHROPIC_AUTH_TOKEN` alive: dedup keeps the
  * winner's spelling, a lone `Authorization` has nothing to dedup against, and the credential
@@ -90,9 +65,9 @@ export declare const AUTH_CARRIER_NAMES: ReadonlySet<string>;
  * user-bag merge precisely so they "can NEVER be overridden" (council design/40) — and without the
  * delete a user bag carrying `Content-Type: text/plain` survives BESIDE the lowercase lock, the
  * platform `Headers` fold turning the pair into `text/plain, application/json` on the wire: a lock
- * that decides 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).
+ * that decides nothing. WHICH credential headers ride is the jurisdiction of `applyRouteCredentialHeaders`
+ * (route-adjudicator.ts); the key header a brain writes after it (`authorization` / `x-api-key`, from the
+ * apiKey knob) is a lock like any other — one value per name, whatever spelling a bag carried.
  */
 export declare function lockHeader(headers: Record<string, string>, lowerName: string, value: string): void;
 /**
@@ -103,6 +78,10 @@ export declare function lockHeader(headers: Record<string, string>, lowerName: s
  * losing the user's betas from the merge AND double-sending the header).
  */
 export declare function takeHeaderCasefold(headers: Record<string, string>, lowerName: string): string | undefined;
+/** A caller's header bag read ONCE, into a plain copy of its own enumerable entries — what a request build hands both
+ *  the route law (which credential rides, and its identity) and the merge (what goes on the wire), so a bag whose getters
+ *  or keys answer differently on a second read cannot be judged as one bag and sent as another. */
+export declare function headerBagOnce(bag: Readonly<Record<string, string>> | undefined): Record<string, string> | undefined;
 export declare function mergeHeaders(...bags: Array<Record<string, string> | undefined>): Record<string, string>;
 /**
  * The output-cap key(s) each lane's wire form uses. A lane's set is exactly the keys THAT lane's

package/dist/brain/request-params.js

@@ -1,3 +1,4 @@
+import { isCredentialHeaderName } from "../core/secret-env.js";
 export const OPENAI_RESERVED = new Set([
     "model",
     "messages",
@@ -52,7 +53,6 @@ export function applyExtraBody(body, extraBody, reserved) {
     }
     return { body: { ...passthrough, ...body }, dropped: dropped.length === 0 ? NO_KEYS : dropped };
 }
-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)
@@ -70,6 +70,9 @@ export function takeHeaderCasefold(headers, lowerName) {
     }
     return undefined;
 }
+export function headerBagOnce(bag) {
+    return bag === undefined ? undefined : { ...bag };
+}
 export function mergeHeaders(...bags) {
     const out = {};
     const spellingByFold = new Map();
@@ -78,7 +81,7 @@ export function mergeHeaders(...bags) {
             continue;
         for (const [name, value] of Object.entries(bag)) {
             const fold = name.toLowerCase();
-            if (AUTH_CARRIER_NAMES.has(fold)) {
+            if (isCredentialHeaderName(name)) {
                 out[name] = value;
                 continue;
             }

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

@@ -13,8 +13,8 @@
 import type { RouteCredential } from "../internal/llm.js";
 /** Where the credential a request would carry came from.
  *  - `"per-model"` — resolved FOR this model: a per-call key/headers from the per-model auth hook
- *    (`getApiKeyAndHeaders`), or an auth-bearing header declared on `Model.headers`. Paired by
- *    construction (the resolver was asked about THIS entry), so the adjudicator never refuses it.
+ *    (`getApiKeyAndHeaders`), or a credential header declared on `Model.headers`. Bound to the
+ *    origin of the first request sent carrying it; refused only on its way to another origin.
  *  - `"deployment-config"` — the brain construction-time fallback (`config.apiKey` / an auth header
  *    in `config.headers`). Paired only with the deployment's own root (`config.baseUrl`, else the lane's default).
  *  - `"absent"` — no credential anywhere. Legal for keyless gateways; refused only where an entry
@@ -40,8 +40,9 @@ export type RequestRootOrigin = (typeof REQUEST_ROOT_ORIGINS)[number];
  *  - `credentialSource` — {@link RouteCredentialSource}.
  *  - `carrier` — how the credential rode ({@link RouteCarrier}); absent exactly when `credentialSource` is `"absent"`.
  *  - `carrierBag` — the header bag whose auth header rode ({@link RouteCarrierBag}); present exactly when one did:
- *    with carrier `"header"`, and beside carrier `"apiKey"` in the deployment shape that sets both `config.apiKey`
- *    and an auth header in `config.headers` (both ride).
+ *    with carrier `"header"`, and beside carrier `"apiKey"` when one source sets both — the per-model hook's answer
+ *    (`apiKey` and an auth header in its `headers`) or the deployment (`config.apiKey` and an auth header in
+ *    `config.headers`); both ride.
  *  - `root` — which knob named the request's root ({@link RequestRootOrigin}).
  * The legal shapes are exactly the rows of {@link ROUTE_CREDENTIAL_PAIRING}.
  */
@@ -62,16 +63,16 @@ export interface RouteCredentialPairingRow {
     /** The knob(s) the credential is read from, in this engine's own spelling (`getApiKeyAndHeaders` is the per-model
      *  auth hook, whose answer reaches the brain as the per-call options). Empty for `"absent"`. */
     readonly credentialKnobs: readonly string[];
-    /** The root knob the credential is paired with: `"Model.baseUrl"` for a per-model credential (paired by
-     *  construction — it was resolved for this entry), `"config.baseUrl"` for the deployment credential (paired only
+    /** The root knob the credential is paired with: `"Model.baseUrl"` for a per-model credential (paired with the
+     *  ORIGIN that knob named the first time the credential was judged), `"config.baseUrl"` for the deployment credential (paired only
      *  when the request targets that root — or, undeclared, the lane's own default endpoint). Absent for
      *  `"absent"`. */
     readonly pairsWith?: "Model.baseUrl" | "config.baseUrl";
 }
 /**
  * The pairing law as a table — one row per route shape a request can carry, in resolution precedence (an earlier
- * row's source wins when several are configured; the three deployment rows are one rank, the deployment credential
- * judged as one). A consumer naming "which key was that" reads the row a {@link RequestRoute} lands on (same
+ * row's source wins when several are configured; one rank per source — the first three rows are the per-model hook's
+ * answer, the three deployment rows the deployment config, each source's credential judged as one). A consumer naming "which key was that" reads the row a {@link RequestRoute} lands on (same
  * `credentialSource` / `carrier` / `carrierBag`), never a sentence. The verdicts the law gives these shapes are the
  * conformance corpus's (`ROUTE_ADJUDICATION_CONFORMANCE_CORPUS`).
  */

package/dist/brain/request-route.js

@@ -14,6 +14,7 @@ export function requestRouteOf(credential, root) {
 }
 export const ROUTE_CREDENTIAL_PAIRING = Object.freeze([
     { credentialSource: "per-model", carrier: "apiKey", credentialKnobs: ["getApiKeyAndHeaders().apiKey"], pairsWith: "Model.baseUrl" },
+    { credentialSource: "per-model", carrier: "apiKey", carrierBag: "options", credentialKnobs: ["getApiKeyAndHeaders().apiKey", "getApiKeyAndHeaders().headers"], pairsWith: "Model.baseUrl" },
     { credentialSource: "per-model", carrier: "header", carrierBag: "options", credentialKnobs: ["getApiKeyAndHeaders().headers"], pairsWith: "Model.baseUrl" },
     { credentialSource: "per-model", carrier: "header", carrierBag: "model", credentialKnobs: ["Model.headers"], pairsWith: "Model.baseUrl" },
     { credentialSource: "deployment-config", carrier: "apiKey", credentialKnobs: ["config.apiKey"], pairsWith: "config.baseUrl" },

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

@@ -11,10 +11,19 @@
  * 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.
+ * The judgment, by credential source (see {@link RouteCredentialSource}). ONE law for both credential
+ * sources — **a credential has exactly one root** — differing only in where that root comes from:
+ *  - `per-model` → a per-model credential (auth hook or a credential header on `Model.headers`) is bound to the
+ *    ORIGIN (scheme + host + port) of the first request the engine SENT carrying it, in the engine's one
+ *    credential-origin table ({@link credentialOriginTable}) — written only by a brain's request gate when the request
+ *    goes out ({@link admitRouteRequest}), read by every judgment; a request carrying it to another origin is
+ *    refused (`route.credential_origin_mismatch`), a request to another path of the same origin is not. An
+ *    entry whose `baseUrl` moves to another host while its credential stays the same therefore sends
+ *    nothing: the credential belongs to the host it was first sent to, and a NEW credential (the entry's
+ *    credential reference changed with its address) is a new binding. The binding lasts for the process. Before any
+ *    origin is read, a per-model credential is ONE value per header: a request whose per-call `apiKey` is set beside a
+ *    header of the very name its lane writes that key in carries two values for one header, and is refused
+ *    (`route.credential_answer_conflict`) wherever it is going.
  *  - `deployment-config` → a deployment credential has exactly ONE root: the one its brain sends to when
  *    an entry names none — `config.baseUrl`, else the lane's own default endpoint
  *    (`RoutePairingConfig.laneDefault`). A request to that root is `"paired"`; a request to any other
@@ -32,13 +41,18 @@
  * Bad-value loudness (garbage / contradiction / absence / misplacement):
  *  - 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.
+ *  - contradiction — the torn pair refuses with `route.credential_mismatch` + both halves named; a bound
+ *    per-model credential sent elsewhere refuses with `route.credential_origin_mismatch` + both origins named; a
+ *    per-call key beside its own header refuses with `route.credential_answer_conflict` + both header names named.
+ *    Each is a VERDICT, one shape for every caller of the law ({@link adjudicateModelRoute}, which throws on garbage
+ *    alone): the request gate, a pre-flight, the read face and a failover chain read the same refusal.
  *  - absence — `route.credential_missing` with the fix hint, exactly where absence is a hole.
  *  - misplacement — a credential in the URL, or a non-http(s) root: {@link assertServableRequestRoot}.
  */
 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";
+import { BrainError } from "./errors.js";
 import type { RequestRootOrigin } from "./request-route.js";
 /** A base URL's ROUTE KEY — the value the pairing law COMPARES, folded to WIRE equivalence: the
  *  halves the wire itself treats as case-insensitive (scheme and host, RFC 9110) fold, the scheme's
@@ -119,25 +133,39 @@ export declare function resolveRequestRootOf(modelBaseUrl: string | undefined, c
     root: string;
     origin: RequestRootOrigin;
 };
-/** Whether a header bag carries an auth-bearing header (any case). */
+/** Whether a header bag carries a credential header (any case) — the engine's one reading of which header carries a
+ *  credential ({@link isCredentialHeaderName}: `Authorization`, `X-Api-Key`, Azure's `api-key`, `x-goog-api-key`,
+ *  `Cookie`, …), the same reading the withheld-value intake keeps. */
 export declare function hasAuthCarrier(headers: Record<string, string> | undefined): boolean;
+/** Test seam: empties the process's credential-origin table — every per-model credential is unbound again, as at a
+ *  process start. Never called by production code (a binding lasts as long as the process; restarting rebinds). A test
+ *  suite that sends one fixture credential to two local mock upstreams (two `listen(0)` ports are two origins) calls it
+ *  between cases, or gives each case its own fixture credential. */
+export declare function __resetCredentialOriginBindings(): void;
 /**
  * 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
+ * adjudication. One rank per SOURCE, most-specific wins; within a rank the apiKey knob and the rank's
+ * credential headers are ONE credential (they ride together and are bound together):
+ *   1. the per-model auth hook's answer — `options.apiKey` (presence, not truthiness: an empty string
+ *      is a present credential that fails closed at emit — no key header, no fallback to the
+ *      deployment's) and/or a credential header ({@link hasAuthCarrier}) in `options.headers` (a
+ *      gateway's own `Helicone-Auth` beside the key, or the key spelled as a header — not both: an `apiKey`
+ *      beside a header of the very name the lane writes the key in (`keyHeader`) is resolved all the same, with
+ *      that conflict recorded beside it for the law to refuse). The bag MUST be
+ *      per-model sourced (the hook's headers) — that provenance is what makes it a credential of THIS
+ *      entry, bound to its own origin below. A caller that folds run-wide headers into the per-call
+ *      options must strip credential headers 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
+ *   2. a credential header in `model.headers` (the ENTRY's own declared credential),
+ *   3. the deployment config (`config.apiKey` and/or a credential header in `config.headers` — the
+ *      documented gateway dual-auth shape, both riding 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`.
+ *   4. absent.
+ * 1–2 are `per-model`; 3 is `deployment-config`. A per-model credential that carries a secret leaves
+ * here with its identity beside it (a digest, held by this module and never a member of the returned
+ * object), which {@link adjudicateModelRoute} reads against the origin table and {@link admitRouteRequest}
+ * binds when its request is sent. Resolution does not judge the route: what it found — an identity, a key beside
+ * its own header — is the law's to rule on, in one verdict shape for every caller.
  */
 export declare function resolveRouteCredential(input: {
     optionsApiKey?: string;
@@ -145,10 +173,23 @@ export declare function resolveRouteCredential(input: {
     modelHeaders?: Record<string, string>;
     configApiKey?: string;
     configHeaders?: Record<string, string>;
+    /** The header the caller's lane writes a per-call `apiKey` in (`authorization`, `x-api-key`), when it has one. Per-call
+     *  options that carry an `apiKey` and a header of that name (any case) are two values for one header: the credential
+     *  is resolved with that conflict beside it, and the law refuses it (`route.credential_answer_conflict`) rather than
+     *  let the key win. Optional like every input here: a caller that does not know its lane leaves it out, and then no
+     *  conflict is recorded and none is refused. */
+    keyHeader?: 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.
+ * The pairing law (module note above). A READ: it judges against the engine's credential-origin table and writes
+ * nothing, so a pre-flight, the read face ({@link routePairingStatus}) and any consumer may call it freely — same
+ * inputs and same table, same verdict. A per-model credential {@link resolveRouteCredential} resolved with a key beside
+ * its own header is refused first (`route.credential_answer_conflict`, both header names in the fix — wherever the
+ * request goes, since the request itself is contradictory); otherwise it is judged against the origin it is bound to
+ * (refused when that is another one); one not bound yet, or built by hand (no resolution facts — the published corpus
+ * is such input), is servable. Every refusal is a verdict: the law throws on garbage alone. The table is written by one
+ * seat only: a first-party brain's request gate ({@link admitRouteRequest}), when the engine commits the request to be
+ * sent. The verdict reports nothing either: the request gate's refusal is {@link routeRefusalError}.
  */
 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
@@ -156,43 +197,77 @@ export declare function adjudicateModelRoute(model: Pick<Model, "id" | "baseUrl"
 export declare function routeRefusalText(verdict: Extract<RouteAdjudication, {
     ok: false;
 }>): string;
+/** The request gate's refusal — the ONE error a first-party brain throws when the pairing law refuses the request it is
+ *  building ({@link admitRouteRequest}). A credential-origin refusal is also reported to the run it happens in (the run
+ *  announces `route.credential_origin_mismatch`): here, at the request that is refused, and not in the law, whose other
+ *  callers only advise (a pre-flight, the read face) and leave the outcome to the seat that asked. */
+export declare function routeRefusalError(verdict: Extract<RouteAdjudication, {
+    ok: false;
+}>): BrainError;
 /**
- * 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).
+ * THE request gate of a first-party brain — the one seat that writes the credential-origin table. Judged while the
+ * request is built ({@link adjudicateModelRoute}, the same law the pre-flight and the read face read): a refusal is
+ * thrown here ({@link routeRefusalError}) before the body is built, and binds nothing — every refusal the law rules,
+ * a key beside its own header included, leaves as that one error (`<code>: <fix>`); the gate rules nothing of its
+ * own. An admitted request hands back its
+ * ADMISSION, which the brain runs from `SSERequest.onCommitted` — the engine's one point at which THIS request is the one
+ * that is sent: the law judged again and, admitted, the per-model credential bound to the request's origin, in ONE
+ * synchronous step; refused (the credential went out to another origin since the build — caller code runs while a body
+ * is built), the same refusal is thrown there, before anything is sent. A request built speculatively and declined (the
+ * context-overflow recovery's candidate), or one whose build fails after the gate, never reaches its admission and binds
+ * nothing. A credential is bound to the origin it was first SENT to, never to one it was only judged for. The request's
+ * halves (the entry's id and root, the brain's root and lane default) are read ONCE, here: both judgments and the binding
+ * are of the request this build is sending, whatever the caller's objects say by the time it is committed.
  */
-export declare function applyRouteCredentialHeaders(merged: Record<string, string>, credential: RouteCredential, bags: {
-    model?: Record<string, string>;
-    options?: Record<string, string>;
-}): void;
+export declare function admitRouteRequest(model: Pick<Model, "id" | "baseUrl">, credential: RouteCredential, config: RoutePairingConfig): () => 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.
+ * Enforce "the resolved credential is the request's ONLY credential" on an already-merged header
+ * bag — one source's credential rides, the other sources' credential headers do not:
+ *  - PER-MODEL winner → every credential header ({@link isCredentialHeaderName}) is stripped and the
+ *    winning bag's own credential headers written back — exactly the ones {@link resolveRouteCredential}
+ *    read and hashed ({@link ResolvedCredentialFacts}; the caller's bag is not read again): the hook's
+ *    answer (`options`) or the entry (`model`). The hook's answer is one credential — beside its apiKey,
+ *    which the brain then writes in its lane's key header (a request that also holds a header of that name
+ *    never gets here in a first-party brain: its request gate refused it first, `route.credential_answer_conflict`,
+ *    so the lock supersedes nothing the answer carried), its other credential headers ride (a gateway's `Helicone-Auth`); an
+ *    entry's credential survives a same- or variant-case deployment spelling that the plain merge order
+ *    would have let win. A credential header from any OTHER bag (the entry's under a hook answer, the
+ *    deployment's under either) never rides beside a per-model credential. Whether a header is stripped
+ *    is decided by its SOURCE, not its name.
+ *  - DEPLOYMENT-CONFIG winner → untouched. 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 shape — the
+ *    knob's lock write plus the surviving header, both on the wire.
+ *  - absent → untouched (no carriers exist).
  */
+export declare function applyRouteCredentialHeaders(merged: Record<string, string>, credential: RouteCredential): void;
 /** A brain's construction config, received ONCE by the engine's receipt law for caller objects
  *  ({@link receiveOwnProperties}: a plain object, every own member read once): the request gate and the pre-flight
  *  judge both read this frozen copy, so a config object mutated after construction moves neither and the two cannot
  *  disagree about the root a credential is paired with. The header bag is a caller object too: it is received by the
- *  same law from that one reading into a frozen bag of the copy's own. */
+ *  same law from that one reading into a frozen bag of the copy's own. The copy's credential — `apiKey` and the
+ *  credential headers — is a credential the engine now holds: no child spawned on this host inherits a variable whose
+ *  value equals it (`holdOwnCredentialValues`). */
 export declare function brainConfigSnapshot<T extends {
+    apiKey?: string;
     headers?: Record<string, string>;
 }>(given: T, subject: string): Readonly<T>;
+/**
+ * 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 agree on the same inputs. A refusal is
+ * always a verdict here, never a throw. The pre-flight sees the
+ * per-model auth it is handed, nothing later: a header a provider-request hook adds afterwards reaches
+ * the request build alone, which judges it by the same law.
+ */
 export declare function createBrainRouteJudge(config: {
     apiKey?: string;
     baseUrl?: string;
     headers?: Record<string, string>;
     /** The lane's own default endpoint (the brain's constant), when it has one. */
     laneDefault?: string;
+    /** The header the lane writes a per-call apiKey in ({@link resolveRouteCredential}'s `keyHeader`): the brain's own
+     *  constant, so the judge refuses the requests its request build refuses. */
+    keyHeader?: string;
 }): (model: Model, perModelAuth?: {
     apiKey?: string;
     headers?: Record<string, string>;
@@ -203,7 +278,7 @@ export declare function createBrainRouteJudge(config: {
  * `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 type RoutePairingStatus = `ok:${RoutePairingPosture}` | `broken:${"credential_mismatch" | "credential_missing" | "credential_origin_mismatch" | "credential_answer_conflict"}` | "unknown";
 export declare function routePairingStatus(brain: {
     adjudicateRoute?: (model: Model, perModelAuth?: {
         apiKey?: string;
@@ -294,8 +369,3 @@ export declare function unroutableSeatNotice(args: {
     sessionId?: string;
     runId?: string;
 }): 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;