@sema-agent/core 5.56.0 → 5.58.0

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[];

package/dist/brain/route-conformance.js

@@ -0,0 +1,136 @@
+export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
+    {
+        name: "per-model-on-root",
+        intent: "a per-model credential is paired by construction, on the deployment root",
+        model: { id: "m-main", baseUrl: "https://gw.example.com" },
+        credential: { source: "per-model", apiKey: "k-main" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "per-model" },
+    },
+    {
+        name: "per-model-off-root",
+        intent: "a per-model credential is paired by construction even off the deployment root (the resolver was asked about THIS entry)",
+        model: { id: "m-third", baseUrl: "https://third-party.example.net/v1" },
+        credential: { source: "per-model", apiKey: "k-third" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "per-model" },
+    },
+    {
+        name: "per-model-headers-borne",
+        intent: "an entry-declared auth header is a per-model credential (headers-borne)",
+        model: { id: "m-hdr", baseUrl: "https://third-party.example.net" },
+        credential: { source: "per-model", headersBorne: true, carrierBag: "model" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "per-model" },
+    },
+    {
+        name: "per-model-empty-string-key",
+        intent: "an empty-string per-model key is a PRESENT credential (fails closed at emit, never falls to the deployment key)",
+        model: { id: "m-degraded", baseUrl: "https://third-party.example.net" },
+        credential: { source: "per-model", apiKey: "" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "per-model" },
+    },
+    {
+        name: "deployment-paired",
+        intent: "the main-gateway pass: entry URL === declared config root, deployment credential allowed",
+        model: { id: "m-main", baseUrl: "https://gw.example.com" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "paired" },
+    },
+    {
+        name: "deployment-paired-empty-entry",
+        intent: "an entry with an empty baseUrl targets the config root — deployment credential paired",
+        model: { id: "m-implicit", baseUrl: "" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "paired" },
+    },
+    {
+        name: "deployment-paired-slash-normalized",
+        intent: "trailing slashes do not break the pairing (both halves normalize before compare)",
+        model: { id: "m-main", baseUrl: "https://gw.example.com/" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: true, posture: "paired" },
+    },
+    {
+        name: "deployment-mismatch",
+        intent: "THE torn pair: deployment credential + entry URL off the declared root = refusal, not a silently-followed key",
+        model: { id: "m-third", baseUrl: "https://third-party.example.net/v1" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
+    },
+    {
+        name: "deployment-mismatch-path-differs",
+        intent: "a differing path is a differing root (no prefix leniency — the credential goes to the exact declared root only)",
+        model: { id: "m-path", baseUrl: "https://gw.example.com/other" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com/v1" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
+    },
+    {
+        name: "deployment-mismatch-derived-leg",
+        intent: "the same torn pair on a DERIVED model: same verdict; the engine disposes of it as fallback-to-primary + notice",
+        model: { id: "m-summarize", baseUrl: "https://third-party.example.net" },
+        credential: { source: "deployment-config", apiKey: "k-gw" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "derived",
+    },
+    {
+        name: "deployment-headers-borne-mismatch",
+        intent: "a deployment auth HEADER is the same fallback arm: off the declared root it is refused, not sent",
+        model: { id: "m-third", baseUrl: "https://third-party.example.net" },
+        credential: { source: "deployment-config", headersBorne: true, carrierBag: "config" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_mismatch" },
+        leg: "named",
+    },
+    {
+        name: "deployment-unpinned",
+        intent: "the quick-start posture: config key with NO declared config root stays allowed (single-endpoint form: key on config, URL on the model) — surfaced as unpinned, not refused",
+        model: { id: "m-quickstart", baseUrl: "https://api.example.com/v1" },
+        credential: { source: "deployment-config", apiKey: "k-quickstart" },
+        config: {},
+        expect: { ok: true, posture: "unpinned" },
+    },
+    {
+        name: "absent-keyless-on-root",
+        intent: "a keyless deployment on its own root has nothing to protect — allowed",
+        model: { id: "m-local", baseUrl: "http://127.0.0.1:8000/v1" },
+        credential: { source: "absent" },
+        config: { baseUrl: "http://127.0.0.1:8000/v1" },
+        expect: { ok: true, posture: "keyless" },
+    },
+    {
+        name: "absent-keyless-undeclared",
+        intent: "keyless with no declared config root (URL only on the model) — allowed",
+        model: { id: "m-local", baseUrl: "http://127.0.0.1:8000/v1" },
+        credential: { source: "absent" },
+        config: {},
+        expect: { ok: true, posture: "keyless" },
+    },
+    {
+        name: "absent-missing-off-root",
+        intent: "an entry declaring its OWN URL away from a DECLARED deployment root with no credential anywhere is a configuration hole — loud refusal beats an unauthenticated request to a third-party host",
+        model: { id: "m-third", baseUrl: "https://third-party.example.net" },
+        credential: { source: "absent" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_missing" },
+        leg: "named",
+    },
+    {
+        name: "absent-missing-derived-leg",
+        intent: "the same hole on a DERIVED model: same verdict; engine disposition is fallback-to-primary + notice",
+        model: { id: "m-summarize", baseUrl: "https://third-party.example.net" },
+        credential: { source: "absent" },
+        config: { baseUrl: "https://gw.example.com" },
+        expect: { ok: false, code: "route.credential_missing" },
+        leg: "derived",
+    },
+];

package/dist/brain/routing.js

@@ -15,13 +15,17 @@ function errorMessage(model, text) {
 }
 export function createRoutingBrain(routes, opts = {}) {
     const by = opts.by ?? "provider";
-    const stream = (model, context, options) => {
+    const resolveTarget = (model) => {
         const key = by === "api" ? model.api : model.provider;
         const routed = Object.hasOwn(routes, key) ? routes[key] : undefined;
         const matched = routed !== null && typeof routed === "object" && typeof routed.stream === "function"
             ? routed
             : undefined;
-        const target = matched ?? opts.fallback;
+        return matched ?? opts.fallback;
+    };
+    const stream = (model, context, options) => {
+        const key = by === "api" ? model.api : model.provider;
+        const target = resolveTarget(model);
         if (!target) {
             const out = createAssistantMessageEventStream();
             out.push({
@@ -33,5 +37,6 @@ export function createRoutingBrain(routes, opts = {}) {
         }
         return target.stream(model, context, options);
     };
-    return { stream };
+    const adjudicateRoute = (model, perModelAuth) => resolveTarget(model)?.adjudicateRoute?.(model, perModelAuth);
+    return { stream, adjudicateRoute };
 }

package/dist/brain/status-sink.d.ts

@@ -18,7 +18,7 @@ export declare function runWithStatusSink<T>(emit: (s: BrainStatus) => void, fn:
  */
 export declare function emitBrainStatus(status: BrainStatus): void;
 /**
- * Silent-fallback telemetry (service [398] C1/C4/C5/C6) — the brain→runner TELEMETRY channel, a
+ * Silent-fallback telemetry (C1/C4/C5/C6) — the brain→runner TELEMETRY channel, a
  * SECOND ALS sink parallel to the status one. Statuses are user-facing liveness frames (wire
  * `status` events); telemetry is operator-facing fallback accounting the Runner bridges to trace
  * events (`brain.failover` / `breaker.transition` / `brain.retry` / `vision.placeholder`). Kept
@@ -52,7 +52,7 @@ export type BrainTelemetry = {
 }
 /** PDF read: a `document` content block was substituted with a text placeholder because the serving
  *  API/model cannot take native document input (openai brain always; anthropic brain when the model
- *  declares no vision). Silent quality loss → frame (same [398] C4 discipline as vision_placeholder). */
+ *  declares no vision). Silent quality loss → frame (same C4 discipline as vision_placeholder). */
  | {
     kind: "document_placeholder";
     count: number;

package/dist/brain/stream-shared.d.ts

@@ -35,7 +35,7 @@ export interface RepetitionPoll {
     readonly spared: RepetitionEvent[];
 }
 /**
- * Repetition telemetry (clay 2026-07-10): the cut event + allowance-spared hits for THIS stream.
+ * Repetition telemetry (2026-07-10): the cut event + allowance-spared hits for THIS stream.
  * Polls re-inspect the same growing text every ~64 chars — dedupe spared by rule+segment so one
  * boot block doesn't log once per poll. Attached to the final message as `repetition`.
  */

package/dist/config/catalog.d.ts

@@ -1,5 +1,5 @@
 /**
- * Config catalog (clay ruling 2026-07-19) — the SINGLE machine-readable source for the engineering
+ * Config catalog (ruled 2026-07-19) — the SINGLE machine-readable source for the engineering
  * configuration scale across every client (server / cli / TB harness / future shells).
  *
  * Why this exists: the same knob was found carrying FIVE different values across layers (maxTurns:
@@ -12,8 +12,8 @@
  *      nothing) or overrides it and DECLARES the override (`TaskSpec.configOverrides`, with a
  *      reason). Declared overrides ride the `config.assembled` trace, so every run self-reports its
  *      true knobs and their provenance — "who set 80" becomes a trace read, not archaeology.
- *   3. **Announced change discipline** (clay): the recommendations are a living baseline — any repo
- *      changing one (or overriding persistently) posts the change to the shared blackboard so the
+ *   3. **Announced change discipline**: the recommendations are a living baseline — any repo
+ *      changing one (or overriding persistently) posts the change to the shared config record so the
  *      scale evolves deliberately, together.
  *
  * v1 scope: the cross-client TASK-LAUNCH knobs (the chaos surface). Internal engine tuning
@@ -62,12 +62,12 @@ export interface EffectiveConfigField {
     value: number | boolean | string | null;
     provenance: ConfigProvenance;
 }
-/** Declaration bounds (codex): host strings ride the trace stream — bounded and sanitized, never
+/** Declaration bounds: host strings ride the trace stream — bounded and sanitized, never
  *  free-form. Beyond `MAX_OVERRIDE_DECLARATIONS` entries are dropped (count-capped, first-N kept). */
 export declare const MAX_OVERRIDE_DECLARATIONS = 32;
 /**
  * Build the effective task-launch config + provenance from a spec's launch fields. Pure. The
- * manifest must mirror ENGINE truth, not the spec's surface (codex): `maxOutputTokens` falls back
+ * manifest must mirror ENGINE truth, not the spec's surface: `maxOutputTokens` falls back
  * to the model's own cap (provenance `derived`) before "provider default".
  */
 export declare function resolveEffectiveConfig(spec: {