@adaptic/utils 0.0.1015 → 0.0.1016

package/dist/index.cjs

@@ -3290,7 +3290,7 @@ const MIN_WAKE_DELAY_MS = 1;
  * Number of whole tokens required to release a single queued request. The token
  * bucket consumes exactly one token per admitted request.
  */
-const TOKENS_PER_REQUEST = 1;
+const TOKENS_PER_REQUEST$1 = 1;
 /**
  * Token bucket rate limiter implementation
  *
@@ -3362,8 +3362,8 @@ class TokenBucketRateLimiter {
         // Require a WHOLE token: refill() accrues fractionally, and admitting on
         // any positive fraction would release a full request per accrual tick,
         // driving the bucket negative and overrunning the configured rate.
-        if (this.tokens >= TOKENS_PER_REQUEST) {
-            this.tokens -= TOKENS_PER_REQUEST;
+        if (this.tokens >= TOKENS_PER_REQUEST$1) {
+            this.tokens -= TOKENS_PER_REQUEST$1;
             logger.debug(`Rate limit token acquired for ${this.config.label}`, {
                 remainingTokens: this.tokens,
                 queueLength: this.queue.length,
@@ -3408,7 +3408,7 @@ class TokenBucketRateLimiter {
         if (this.wakeTimer !== null || this.queue.length === 0) {
             return;
         }
-        const tokensNeeded = Math.max(0, TOKENS_PER_REQUEST - this.tokens);
+        const tokensNeeded = Math.max(0, TOKENS_PER_REQUEST$1 - this.tokens);
         const deficitMs = Math.max(MIN_WAKE_DELAY_MS, Math.ceil((tokensNeeded / this.config.refillRate) * MS_PER_SECOND$1));
         const timer = setTimeout(() => {
             this.wakeTimer = null;
@@ -3460,8 +3460,8 @@ class TokenBucketRateLimiter {
         const logger = getLogger();
         try {
             // Whole-token admission — see the matching guard in acquire().
-            while (this.queue.length > 0 && this.tokens >= TOKENS_PER_REQUEST) {
-                this.tokens -= TOKENS_PER_REQUEST;
+            while (this.queue.length > 0 && this.tokens >= TOKENS_PER_REQUEST$1) {
+                this.tokens -= TOKENS_PER_REQUEST$1;
                 const next = this.queue.shift();
                 if (next) {
                     clearTimeout(next.timeoutHandle);
@@ -3543,7 +3543,7 @@ class TokenBucketRateLimiter {
  * await rateLimiters.alphaVantage.acquire();
  * ```
  */
-const rateLimiters = {
+const rateLimiters$1 = {
     /**
      * Alpaca API rate limiter
      *
@@ -4149,7 +4149,7 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
             // bucket so concurrent callers (bar fetches, quotes, options, snapshots)
             // can't overrun Alpaca's server-side rate limit. Prior to this, parallel
             // historical-bar fan-out produced ~125 server-side 429s per minute.
-            await rateLimiters.alpaca.acquire();
+            await rateLimiters$1.alpaca.acquire();
             // Retry ONLY transient connection faults, and only on GET (every
             // market-data read here is idempotent). A non-2xx response is a real
             // answer from Alpaca and is never retried — that path still throws on
@@ -4195,7 +4195,7 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
                     await new Promise((resolve) => setTimeout(resolve, delayMs));
                     // Re-acquire the rate-limit token so a retry storm cannot overrun
                     // Alpaca's server-side limit.
-                    await rateLimiters.alpaca.acquire();
+                    await rateLimiters$1.alpaca.acquire();
                 }
             }
             if (!response) {
@@ -9902,7 +9902,7 @@ const fetchTickerInfo = async (symbol, options) => {
         apiKey,
     });
     return massiveLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(`${baseUrl}?${params.toString()}`, { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 1000);
             const data = await response.json();
@@ -10015,7 +10015,7 @@ const fetchLastTradeImpl = async (symbol, options) => {
         order: "desc",
     });
     return massiveLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(`${baseUrl}?${params.toString()}`, { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 1000);
             const data = (await response.json());
@@ -10086,7 +10086,7 @@ const fetchLastQuote = async (symbol, options) => {
         order: "desc",
     });
     return massiveLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(`${baseUrl}?${params.toString()}`, { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 1000);
             const data = (await response.json());
@@ -10175,7 +10175,7 @@ const fetchPrices = async (params, options) => {
             let aggregatedStatus = "OK";
             while (nextUrl) {
                 //getLogger().info(`Debug: Fetching ${nextUrl}`);
-                await rateLimiters.massive.acquire();
+                await rateLimiters$1.massive.acquire();
                 const response = await fetchWithRetry(nextUrl, { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 1000);
                 const data = await response.json();
                 if (!MASSIVE_VALID_STATUSES.has(data.status)) {
@@ -10362,7 +10362,7 @@ const fetchGroupedDaily = async (date, options) => {
         include_otc: options?.includeOTC ? "true" : "false",
     });
     return massiveLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(`${baseUrl}?${params.toString()}`, { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 1000);
             const data = await response.json();
@@ -10456,7 +10456,7 @@ symbol, date = new Date(), options) => {
         adjusted: (options?.adjusted ?? true).toString(),
     });
     return massiveLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(`${baseUrl}?${params.toString()}`, { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 1000);
             const data = await response.json();
@@ -10530,7 +10530,7 @@ const fetchTrades = async (symbol, options) => {
     if (options?.sort)
         params.append("sort", options.sort);
     return massiveLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         const url = `${baseUrl}?${params.toString()}`;
         try {
             logIfDebug(`Fetching trades for ${symbol} from ${url}`);
@@ -10613,7 +10613,7 @@ const fetchIndicesAggregates = async (params, options) => {
     }
     url.search = queryParams.toString();
     return massiveIndicesLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(url.toString(), { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 300);
             const data = await response.json();
@@ -10643,7 +10643,7 @@ const fetchIndicesPreviousClose = async (indicesTicker, options) => {
     queryParams.append("apiKey", apiKey);
     url.search = queryParams.toString();
     return massiveIndicesLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(url.toString(), { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 300);
             const data = await response.json();
@@ -10674,7 +10674,7 @@ const fetchIndicesDailyOpenClose = async (indicesTicker, date, options) => {
     queryParams.append("apiKey", apiKey);
     url.search = queryParams.toString();
     return massiveIndicesLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(url.toString(), { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 300);
             const data = await response.json();
@@ -10716,7 +10716,7 @@ const fetchIndicesSnapshot = async (params, options) => {
     }
     url.search = queryParams.toString();
     return massiveIndicesLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(url.toString(), { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 300);
             const data = await response.json();
@@ -10765,7 +10765,7 @@ const fetchUniversalSnapshot = async (tickers, options) => {
     }
     url.search = queryParams.toString();
     return massiveIndicesLimit(async () => {
-        await rateLimiters.massive.acquire();
+        await rateLimiters$1.massive.acquire();
         try {
             const response = await fetchWithRetry(url.toString(), { signal: createTimeoutSignal(DEFAULT_TIMEOUTS.MASSIVE_API) }, 3, 300);
             const data = await response.json();
@@ -52147,7 +52147,7 @@ class AlpacaClient {
      * @returns Result of the operation
      */
     async executeWithRateLimit(operation, label) {
-        await rateLimiters.alpaca.acquire();
+        await rateLimiters$1.alpaca.acquire();
         return withRetry(operation, {
             maxRetries: 2,
             baseDelayMs: 1000,
@@ -52206,7 +52206,7 @@ class AlpacaClient {
      * @returns Response data
      */
     async makeRequest(endpoint, method = "GET", body) {
-        await rateLimiters.alpaca.acquire();
+        await rateLimiters$1.alpaca.acquire();
         const url = `${this.apiBaseUrl}${endpoint}`;
         const options = {
             method,
@@ -62911,6 +62911,2764 @@ const alpaca = {
     streams: streams$1,
 };
 
+/**
+ * Per-route circuit breaker for the alias client.
+ *
+ * A provider that has just failed five calls will almost certainly fail the
+ * sixth, and every attempt spends latency budget the next leg of the chain
+ * needs. The breaker converts that repeated discovery into a decision made
+ * once: an unhealthy leg is skipped outright until it has had time to recover,
+ * so a chain reaches its working leg quickly instead of paying the full
+ * timeout of each dead one first.
+ *
+ * Breakers are keyed by chain POSITION, not by provider. Two consequences
+ * follow, and both are intended. Reverting an alias to a different model at the
+ * same position inherits that position's health rather than starting blind. And
+ * an isolated route never shares a breaker with the shared one, so isolated
+ * traffic can neither trip nor be tripped by traffic on the other side of the
+ * PD-9 boundary.
+ *
+ * The clock is injected. Breaker behaviour is entirely about elapsed time, and
+ * a test that must sleep to observe a cooldown is a test nobody runs.
+ *
+ * @module llm/circuit-breaker
+ */
+/**
+ * Tracks route health and decides whether a leg may be attempted.
+ */
+class CircuitBreakerRegistry {
+    records = new Map();
+    config;
+    now;
+    /**
+     * @param config Failure threshold, cooldown and half-open probe budget.
+     * @param now Clock, injected so cooldowns are testable without waiting.
+     */
+    constructor(config, now = Date.now) {
+        this.config = config;
+        this.now = now;
+    }
+    /**
+     * Current state of a route's breaker.
+     *
+     * The transition from open to half-open is computed from elapsed time at read
+     * time rather than scheduled with a timer. A timer would keep the process
+     * awake for every route that ever failed, and would drift whenever the
+     * process was busy — which is exactly when a breaker matters most.
+     *
+     * @param routeKey The route's stable key.
+     * @returns Its state.
+     */
+    stateOf(routeKey) {
+        const record = this.records.get(routeKey);
+        if (record === undefined || record.openedAtMs === null) {
+            return "closed";
+        }
+        const elapsed = this.now() - record.openedAtMs;
+        return elapsed >= this.config.cooldown_ms ? "half-open" : "open";
+    }
+    /**
+     * Whether a route may be attempted now.
+     *
+     * A half-open route admits a bounded number of probes at once. Letting the
+     * whole queue through the moment a cooldown expires would re-hammer a
+     * provider that is still recovering, which is how a breaker turns into a
+     * synchronised retry storm.
+     *
+     * @param routeKey The route's stable key.
+     * @returns Whether an attempt is permitted.
+     */
+    allows(routeKey) {
+        const state = this.stateOf(routeKey);
+        if (state === "closed") {
+            return true;
+        }
+        if (state === "open") {
+            return false;
+        }
+        const record = this.recordFor(routeKey);
+        return record.probesInFlight < this.config.half_open_probes;
+    }
+    /**
+     * Register that an attempt is starting, so half-open probes stay bounded.
+     *
+     * @param routeKey The route's stable key.
+     * @returns void
+     */
+    onAttemptStart(routeKey) {
+        if (this.stateOf(routeKey) === "half-open") {
+            this.recordFor(routeKey).probesInFlight += 1;
+        }
+    }
+    /**
+     * Record a success, closing the breaker.
+     *
+     * A single success closes it fully rather than decrementing the failure
+     * count. The breaker's question is "is this route working now", and one
+     * working call answers it; requiring several would keep a recovered provider
+     * excluded while the chain paid for slower legs.
+     *
+     * @param routeKey The route's stable key.
+     * @returns void
+     */
+    onSuccess(routeKey) {
+        this.records.set(routeKey, {
+            consecutiveFailures: 0,
+            openedAtMs: null,
+            probesInFlight: 0,
+        });
+    }
+    /**
+     * Record a failure, opening the breaker once the threshold is reached.
+     *
+     * A failure while half-open re-opens immediately without waiting to
+     * re-accumulate the threshold: the probe was the test, and it failed.
+     *
+     * @param routeKey The route's stable key.
+     * @returns void
+     */
+    onFailure(routeKey) {
+        const wasHalfOpen = this.stateOf(routeKey) === "half-open";
+        const record = this.recordFor(routeKey);
+        record.probesInFlight = 0;
+        record.consecutiveFailures += 1;
+        if (wasHalfOpen || record.consecutiveFailures >= this.config.failure_threshold) {
+            record.openedAtMs = this.now();
+        }
+    }
+    /**
+     * Inspect a route's breaker.
+     *
+     * @param routeKey The route's stable key.
+     * @returns A snapshot.
+     */
+    snapshot(routeKey) {
+        const record = this.records.get(routeKey) ?? {
+            consecutiveFailures: 0,
+            openedAtMs: null,
+            probesInFlight: 0,
+        };
+        return {
+            routeKey,
+            state: this.stateOf(routeKey),
+            consecutiveFailures: record.consecutiveFailures,
+            openedAtMs: record.openedAtMs,
+            probesInFlight: record.probesInFlight,
+        };
+    }
+    /**
+     * Every route the registry has observed.
+     *
+     * @returns Snapshots, sorted by route key for stable output.
+     */
+    snapshotAll() {
+        return [...this.records.keys()]
+            .sort()
+            .map((routeKey) => this.snapshot(routeKey));
+    }
+    /**
+     * Discard all breaker state.
+     *
+     * @returns void
+     */
+    reset() {
+        this.records.clear();
+    }
+    /**
+     * @param routeKey The route's stable key.
+     * @returns The mutable record, created on first use.
+     */
+    recordFor(routeKey) {
+        let record = this.records.get(routeKey);
+        if (record === undefined) {
+            record = { consecutiveFailures: 0, openedAtMs: null, probesInFlight: 0 };
+            this.records.set(routeKey, record);
+        }
+        return record;
+    }
+}
+
+/**
+ * Parameter normalisation across providers.
+ *
+ * A caller passes one option bag and the chain may serve it from any of three
+ * providers, so the same request has to be expressible to all of them. Vendors
+ * disagree about more than spelling: some reject a sampling parameter they do
+ * not support with a hard 400 rather than ignoring it, some name the output
+ * cap differently, and reasoning models take an effort knob that non-reasoning
+ * models refuse. Left unnormalised, a fallback would fail on the leg it fell
+ * back to — turning the mechanism that exists to survive an outage into a
+ * second way to fail.
+ *
+ * The rule throughout is that an unsupported parameter is OMITTED, never sent
+ * with a default. Sending a default asserts a value the caller did not choose;
+ * omitting it lets the provider apply its own, which is what "unsupported"
+ * actually means.
+ *
+ * @module llm/param-matrix
+ */
+/**
+ * Providers that name the output cap `max_tokens` rather than
+ * `max_completion_tokens`.
+ *
+ * The split is a wire-format fact about each API, so it is recorded as data
+ * next to the translation that uses it rather than inferred from a version
+ * number that will move.
+ */
+const MAX_TOKENS_PARAM_BY_API_STYLE = {
+    anthropic: "max_tokens",
+    "openai-compatible": "max_completion_tokens",
+};
+/** The response-format key an OpenAI-compatible provider expects. */
+const RESPONSE_FORMAT_KEY = "response_format";
+/**
+ * Normalise a caller's options into the exact parameter set one leg accepts.
+ *
+ * @param options The caller's options.
+ * @param route The leg the request is being prepared for.
+ * @param responseFormat The response shape the caller asked for.
+ * @returns Parameters ready to send verbatim.
+ */
+function normaliseParams(options, route, responseFormat) {
+    const params = {};
+    const capabilities = route.params;
+    // Temperature. A model that accepts only its default value returns a hard
+    // error for the parameter's mere presence, so support is checked before the
+    // caller's preference is consulted at all.
+    const temperature = options.temperature ?? capabilities.temperature ?? undefined;
+    if (capabilities.supports_temperature !== false && typeof temperature === "number") {
+        params.temperature = temperature;
+    }
+    // Output cap. The caller's value wins where present; the route's declared cap
+    // is the ceiling, because exceeding it is a provider error rather than a
+    // larger answer.
+    const routeCap = capabilities.max_output_tokens ?? undefined;
+    const requested = options.maxOutputTokens ?? routeCap;
+    if (typeof requested === "number") {
+        const capped = typeof routeCap === "number" ? Math.min(requested, routeCap) : requested;
+        const key = MAX_TOKENS_PARAM_BY_API_STYLE[route.provider.api_style] ?? "max_tokens";
+        params[key] = capped;
+    }
+    // Reasoning effort is meaningful only where the route declares it, and is
+    // dropped elsewhere rather than translated into a temperature.
+    const effort = options.reasoningEffort ?? capabilities.reasoning_effort ?? undefined;
+    if (typeof effort === "string" && capabilities.reasoning_effort !== undefined) {
+        params.reasoning_effort = effort;
+    }
+    const format = normaliseResponseFormat(responseFormat, route);
+    if (format !== undefined) {
+        params[RESPONSE_FORMAT_KEY] = format;
+    }
+    if (options.tools !== undefined && options.tools.length > 0) {
+        if (capabilities.supports_tools === false) {
+            throw new UnsupportedCapabilityError(route, "tools");
+        }
+        params.tools = [...options.tools];
+        // Parallel tool calls are off by default: a decision path that fans out
+        // tool calls concurrently reorders its own effects, and ordering is part
+        // of the meaning of a sequence of trading actions.
+        params.parallel_tool_calls = false;
+    }
+    if (options.metadata !== undefined) {
+        params.metadata = { ...options.metadata };
+    }
+    return params;
+}
+/**
+ * Translate the requested response shape into the parameter a route accepts.
+ *
+ * A strict JSON schema is a real capability, not a formatting preference: a
+ * route that cannot enforce one would return prose where the caller's parser
+ * expects an object. Rather than silently degrading to free JSON — which fails
+ * later, further from the cause — a route without the capability refuses the
+ * request so the chain advances to one that has it.
+ *
+ * @param responseFormat What the caller asked for.
+ * @param route The leg being prepared.
+ * @returns The provider-facing value, or undefined for plain text.
+ */
+function normaliseResponseFormat(responseFormat, route) {
+    if (responseFormat === "text") {
+        return undefined;
+    }
+    if (responseFormat === "json") {
+        return { type: "json_object" };
+    }
+    if (route.params.supports_json_schema === false) {
+        throw new UnsupportedCapabilityError(route, "json_schema");
+    }
+    return {
+        type: "json_schema",
+        json_schema: {
+            name: "structured_response",
+            strict: true,
+            schema: responseFormat.schema,
+        },
+    };
+}
+/**
+ * Thrown when a leg cannot honour a capability the caller requires.
+ *
+ * A distinct type rather than a generic error, because the chain treats it
+ * differently from a provider outage: the leg is not broken, it is simply the
+ * wrong leg for this request, and no retry against it will help.
+ */
+class UnsupportedCapabilityError extends Error {
+    /** The leg that cannot serve the request. */
+    routeKey;
+    /** The capability it lacks. */
+    capability;
+    /**
+     * @param route The leg.
+     * @param capability The missing capability.
+     */
+    constructor(route, capability) {
+        super(`route ${route.routeKey} (${route.providerName}/${route.modelId}) does not support ${capability}; ` +
+            "the chain advances rather than degrading the request, so the caller's contract is never silently weakened");
+        this.name = "UnsupportedCapabilityError";
+        this.routeKey = route.routeKey;
+        this.capability = capability;
+    }
+}
+/**
+ * Whether a leg can serve a request needing the given capabilities at all.
+ *
+ * Used to skip a leg before spending a network round trip on it. Checking
+ * up front rather than reacting to the provider's rejection keeps a
+ * capability mismatch from consuming the caller's latency budget.
+ *
+ * @param route The leg.
+ * @param needs Capabilities the request requires.
+ * @returns Whether the leg is a candidate.
+ */
+function routeSupports(route, needs) {
+    if (needs.tools === true && route.params.supports_tools === false) {
+        return false;
+    }
+    if (needs.jsonSchema === true && route.params.supports_json_schema === false) {
+        return false;
+    }
+    if (needs.vision === true && route.params.supports_vision !== true) {
+        return false;
+    }
+    if (needs.cacheControl === true && route.params.supports_cache_control !== true) {
+        return false;
+    }
+    return true;
+}
+
+var defaults$1 = {
+	_readme: "Applied to any provider whose published ceiling is unknown. Chosen to be comfortably below the slowest plausible published limit: being slower than necessary costs latency, while being faster than permitted costs 429s that the fallback chain will read as provider ill-health and use to open a circuit breaker. The asymmetry is what makes the conservative side the correct default.",
+	basis: "conservative-default",
+	requests_per_minute: 60,
+	max_concurrent: 4,
+	acquire_timeout_ms: 15000
+};
+var providers$1 = {
+	anthropic: {
+		basis: "conservative-default",
+		requests_per_minute: 50,
+		max_concurrent: 4,
+		acquire_timeout_ms: 15000,
+		source: null,
+		note: "Anthropic publishes tier-dependent limits; the account's tier is not recorded here. Transcribe the real ceiling from the console at W3-07 and set basis to published."
+	},
+	openai: {
+		basis: "conservative-default",
+		requests_per_minute: 60,
+		max_concurrent: 4,
+		acquire_timeout_ms: 15000,
+		source: null,
+		note: "Tier-dependent. No alias routes here today; the entry exists so a revert to an OpenAI incumbent inherits a bounded client rather than an unbounded one."
+	},
+	deepseek: {
+		basis: "conservative-default",
+		requests_per_minute: 60,
+		max_concurrent: 4,
+		acquire_timeout_ms: 30000,
+		source: null,
+		note: "Serves llm.extract, a batch-class alias, so a longer acquire timeout is appropriate: a batch caller can afford to queue where a hot-path caller cannot."
+	},
+	deepinfra: {
+		basis: "conservative-default",
+		requests_per_minute: 60,
+		max_concurrent: 4,
+		acquire_timeout_ms: 15000,
+		source: null,
+		note: "Awaiting W3-02. Transcribe the published ceiling then."
+	},
+	fireworks: {
+		basis: "conservative-default",
+		requests_per_minute: 60,
+		max_concurrent: 4,
+		acquire_timeout_ms: 15000,
+		source: null,
+		note: "The backlog calls out recording Fireworks' published RPM ceiling specifically (W3-03 -> W4-04). Do that at onboarding."
+	},
+	zai: {
+		basis: "conservative-default",
+		requests_per_minute: 60,
+		max_concurrent: 4,
+		acquire_timeout_ms: 15000,
+		source: null,
+		note: "Awaiting W3-04."
+	},
+	groq: {
+		basis: "conservative-default",
+		requests_per_minute: 30,
+		max_concurrent: 2,
+		acquire_timeout_ms: 10000,
+		source: null,
+		note: "Declared primary of the hot-path llm.fast alias but blocked on open item OI-01. Held tighter than the default because a hot-path caller cannot afford to queue: if the limit binds, failing fast into the chain beats waiting."
+	},
+	openrouter: {
+		basis: "conservative-default",
+		requests_per_minute: 30,
+		max_concurrent: 2,
+		acquire_timeout_ms: 15000,
+		source: null,
+		note: "Aggregator backstop, reached by explicit route only. Held tight because its own limits are a function of whichever upstream it selects, which the client cannot observe."
+	}
+};
+var limitsConfig = {
+	defaults: defaults$1,
+	providers: providers$1
+};
+
+/**
+ * Client-side rate and concurrency guards, per provider (W4-04).
+ *
+ * A provider's rate limit is enforced at the provider whether or not the client
+ * respects it. The reason to respect it here is what a 429 means once it
+ * arrives: to the fallback chain it is indistinguishable from provider
+ * ill-health, so a client that over-drives a healthy provider will open that
+ * provider's circuit breaker, fail over to a more expensive leg, and keep doing
+ * so — converting a self-inflicted pacing problem into a permanent routing
+ * change nobody chose. Pacing at the client is what keeps the breaker measuring
+ * the provider rather than measuring us.
+ *
+ * Two distinct bounds are applied because they fail differently. The rate bound
+ * (requests per minute) protects the provider's published ceiling. The
+ * concurrency bound protects the caller: a hundred simultaneous in-flight
+ * requests will each wait behind the other ninety-nine at the provider, so
+ * every one of them blows its latency budget and the fan-out produces a hundred
+ * timeouts instead of a queue.
+ *
+ * Limits live in `provider-limits.json`, not here. A rate limit discovered
+ * during an incident should be correctable by config, not by a release.
+ *
+ * @module llm/rate-guard
+ */
+/** Seconds in a minute, converting a published per-minute ceiling to a refill rate. */
+const SECONDS_PER_MINUTE = 60;
+/** One request consumes one token. */
+const TOKENS_PER_REQUEST = 1;
+const config$1 = limitsConfig;
+/**
+ * Resolve the limits that apply to a provider.
+ *
+ * An unregistered provider falls back to the conservative defaults rather than
+ * to no limit at all. Treating "unknown" as "unlimited" would make every newly
+ * onboarded provider the one most likely to be over-driven, which is exactly
+ * backwards: a new provider is the one whose real ceiling is least understood.
+ *
+ * @param provider The provider key.
+ * @returns Its limits.
+ */
+function limitsFor(provider) {
+    return config$1.providers[provider] ?? config$1.defaults;
+}
+/** Every provider with a recorded limit, plus whether it is published or a default. */
+function limitsInventory() {
+    return Object.keys(config$1.providers)
+        .sort()
+        .map((provider) => ({ provider, limits: config$1.providers[provider] }));
+}
+/**
+ * Thrown when a caller could not acquire a slot within its budget.
+ *
+ * Distinguished from a provider failure so the chain does not count it against
+ * route health: the provider was never asked, so nothing was learned about it.
+ */
+class RateGuardTimeoutError extends Error {
+    /** The provider whose guard could not admit the call. */
+    provider;
+    /** Which of the two bounds the caller waited on. */
+    bound;
+    /**
+     * @param provider The provider.
+     * @param bound Which bound was binding.
+     * @param waitedMs How long the caller waited.
+     */
+    constructor(provider, bound, waitedMs) {
+        super(`client-side ${bound} guard for provider "${provider}" did not admit the call within ${waitedMs} ms. ` +
+            "The provider was never contacted, so this says nothing about its health.");
+        this.name = "RateGuardTimeoutError";
+        this.provider = provider;
+        this.bound = bound;
+    }
+}
+/**
+ * A counting semaphore bounding simultaneous in-flight calls.
+ *
+ * Written here rather than pulled from a dependency because it is fifteen lines
+ * and because the waiting behaviour matters: a waiter that times out must be
+ * removed from the queue, or a burst of abandoned callers permanently consumes
+ * the permits that later callers need.
+ */
+class ConcurrencyGate {
+    inFlight = 0;
+    waiters = [];
+    limit;
+    provider;
+    /**
+     * @param provider The provider this gate guards.
+     * @param limit Maximum simultaneous in-flight calls.
+     */
+    constructor(provider, limit) {
+        this.provider = provider;
+        this.limit = limit;
+    }
+    /**
+     * Wait for a permit.
+     *
+     * @param timeoutMs How long the caller is willing to queue.
+     * @returns A release function the caller must invoke exactly once.
+     */
+    async acquire(timeoutMs) {
+        if (this.inFlight < this.limit) {
+            this.inFlight += 1;
+            return () => this.release();
+        }
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const index = this.waiters.findIndex((waiter) => waiter.timer === timer);
+                if (index !== -1) {
+                    this.waiters.splice(index, 1);
+                }
+                reject(new RateGuardTimeoutError(this.provider, "concurrency", timeoutMs));
+            }, timeoutMs);
+            this.waiters.push({ resolve, reject, timer });
+        });
+        this.inFlight += 1;
+        return () => this.release();
+    }
+    /**
+     * Return a permit and admit the next waiter.
+     *
+     * @returns void
+     */
+    release() {
+        this.inFlight -= 1;
+        const next = this.waiters.shift();
+        if (next !== undefined) {
+            clearTimeout(next.timer);
+            next.resolve();
+        }
+    }
+    /**
+     * @returns How many calls are currently in flight.
+     */
+    inFlightCount() {
+        return this.inFlight;
+    }
+    /**
+     * @returns How many callers are queued.
+     */
+    queueLength() {
+        return this.waiters.length;
+    }
+}
+/** Per-provider guards, created on first use and shared process-wide. */
+const rateLimiters = new Map();
+const concurrencyGates = new Map();
+/**
+ * The rate limiter for a provider.
+ *
+ * Shared process-wide rather than per-call-site, because the provider's ceiling
+ * applies to the process as a whole. Per-call-site limiters would each stay
+ * under the ceiling while their sum sailed past it.
+ *
+ * @param provider The provider key.
+ * @returns Its limiter.
+ */
+function rateLimiterFor(provider) {
+    let limiter = rateLimiters.get(provider);
+    if (limiter === undefined) {
+        const limits = limitsFor(provider);
+        limiter = new TokenBucketRateLimiter({
+            maxTokens: limits.requests_per_minute,
+            refillRate: limits.requests_per_minute / SECONDS_PER_MINUTE,
+            label: `llm:${provider}`,
+            timeoutMs: limits.acquire_timeout_ms,
+        });
+        rateLimiters.set(provider, limiter);
+    }
+    return limiter;
+}
+/**
+ * The concurrency gate for a provider.
+ *
+ * @param provider The provider key.
+ * @returns Its gate.
+ */
+function concurrencyGateFor(provider) {
+    let gate = concurrencyGates.get(provider);
+    if (gate === undefined) {
+        gate = new ConcurrencyGate(provider, limitsFor(provider).max_concurrent);
+        concurrencyGates.set(provider, gate);
+    }
+    return gate;
+}
+/**
+ * Run a call under a provider's rate and concurrency guards.
+ *
+ * The concurrency permit is taken AFTER the rate token. Taking it first would
+ * let callers hold scarce permits while idling in the rate queue, which
+ * throttles the provider twice over and turns a pacing bound into a deadlock
+ * shaped like slowness.
+ *
+ * `maxWaitMs` bounds how long a caller may queue. It exists because the queue
+ * spends the SAME budget the call itself does: a caller that waits out its whole
+ * deadline in a rate queue has failed just as completely as one that waited on
+ * the provider, and worse, it never reached the fallback chain that could have
+ * answered it. Passing the leg's own timeout keeps one clock governing the
+ * whole attempt.
+ *
+ * @param provider The provider key.
+ * @param call The work to run once admitted.
+ * @param maxWaitMs Ceiling on queue time; the configured guard timeout applies when lower.
+ * @returns The call's result.
+ * @throws {RateGuardTimeoutError} When neither bound admitted the call in time.
+ */
+async function withProviderGuards(provider, call, maxWaitMs) {
+    const limits = limitsFor(provider);
+    const waitBudgetMs = maxWaitMs === undefined
+        ? limits.acquire_timeout_ms
+        : Math.min(maxWaitMs, limits.acquire_timeout_ms);
+    try {
+        await rateLimiterFor(provider).acquire();
+    }
+    catch {
+        throw new RateGuardTimeoutError(provider, "rate", waitBudgetMs);
+    }
+    const release = await concurrencyGateFor(provider).acquire(waitBudgetMs);
+    try {
+        return await call();
+    }
+    finally {
+        // Released on every path. A permit leaked on the error path would shrink
+        // the effective limit by one on each failure until nothing could run — and
+        // failures cluster exactly when throughput matters most.
+        release();
+    }
+}
+/**
+ * Inspect the guards currently in use.
+ *
+ * @returns A snapshot per provider that has been used, sorted by provider.
+ */
+function guardSnapshots() {
+    const providers = new Set([...rateLimiters.keys(), ...concurrencyGates.keys()]);
+    return [...providers].sort().map((provider) => {
+        const limits = limitsFor(provider);
+        const limiter = rateLimiters.get(provider);
+        const gate = concurrencyGates.get(provider);
+        return {
+            provider,
+            basis: limits.basis,
+            requestsPerMinute: limits.requests_per_minute,
+            maxConcurrent: limits.max_concurrent,
+            inFlight: gate?.inFlightCount() ?? 0,
+            rateQueueLength: limiter?.getQueueLength() ?? 0,
+            concurrencyQueueLength: gate?.queueLength() ?? 0,
+            availableTokens: limiter?.getAvailableTokens() ?? limits.requests_per_minute * TOKENS_PER_REQUEST,
+        };
+    });
+}
+/**
+ * Discard all guard state.
+ *
+ * Exists so a test can start from a known position; a shared process-wide
+ * limiter is otherwise carried between tests and makes their order matter.
+ *
+ * @returns void
+ */
+function resetProviderGuards() {
+    for (const limiter of rateLimiters.values()) {
+        limiter.reset();
+    }
+    rateLimiters.clear();
+    concurrencyGates.clear();
+}
+
+/**
+ * Ordered execution of an alias's fallback chain (PD-3).
+ *
+ * Every call walks the chain primary -> secondary -> closed incumbent, and each
+ * leg runs under a hard timeout and a circuit breaker. Those three controls are
+ * one mechanism rather than three features: a chain without timeouts never
+ * reaches its second leg, a chain without a breaker pays a dead provider's full
+ * timeout on every call, and a timeout without a chain is just a slower
+ * failure. Timeout cascades are this system's known brown-out mode, which is
+ * why the budget is enforced here — at the only place that knows both the
+ * caller's deadline and how many legs are left to spend it on.
+ *
+ * Nothing here ever substitutes a value for an outcome. When every leg is
+ * exhausted the caller gets a typed error naming each leg and why it failed,
+ * because a default returned in place of an answer is a wrong answer that
+ * nobody is told about.
+ *
+ * @module llm/fallback-chain
+ */
+/** Zero-valued usage, used as the identity when summing across attempts. */
+const EMPTY_USAGE = {
+    prompt_tokens: 0,
+    completion_tokens: 0,
+    provider: "none",
+    model: "none",
+    cost: 0,
+};
+/**
+ * Thrown when every leg of a chain has been tried and none produced an answer.
+ *
+ * Carries the full attempt record rather than only the last error. The last
+ * error is usually the least informative one — the incumbent timing out says
+ * nothing about why the two legs before it were skipped — and an operator
+ * reading only that would go looking in the wrong place.
+ */
+class ChainExhaustedError extends Error {
+    /** The alias whose chain was exhausted. */
+    alias;
+    /** Every leg tried, in order, with its outcome. */
+    attempts;
+    /** Usage spent across the failed attempts, so the spend is still accounted for. */
+    totalUsage;
+    /**
+     * @param alias The alias.
+     * @param attempts The attempt record.
+     * @param totalUsage Usage spent across all attempts.
+     */
+    constructor(alias, attempts, totalUsage) {
+        const detail = attempts
+            .map((attempt) => `${attempt.role}(${attempt.provider}/${attempt.modelId}): ${attempt.outcome}` +
+            (attempt.reason === undefined ? "" : ` — ${attempt.reason}`))
+            .join("; ");
+        super(`LLM alias "${alias}" exhausted its fallback chain. Attempts: ${detail || "(no leg was servable)"}`);
+        this.name = "ChainExhaustedError";
+        this.alias = alias;
+        this.attempts = attempts;
+        this.totalUsage = totalUsage;
+    }
+}
+/**
+ * Add two usage records.
+ *
+ * Attribution keeps the LAST attempt's provider and model, because that is the
+ * one that produced the answer the caller is holding, while the token counts
+ * accumulate across every attempt. Charging only the successful attempt would
+ * understate spend by exactly the amount the failures cost — which is the
+ * amount a fallback chain is most likely to run up.
+ *
+ * @param a The running total.
+ * @param b The attempt to add, if any.
+ * @returns The combined usage.
+ */
+function sumUsage(a, b) {
+    if (b === undefined) {
+        return a;
+    }
+    return {
+        prompt_tokens: a.prompt_tokens + b.prompt_tokens,
+        completion_tokens: a.completion_tokens + b.completion_tokens,
+        reasoning_tokens: a.reasoning_tokens === undefined && b.reasoning_tokens === undefined
+            ? undefined
+            : (a.reasoning_tokens ?? 0) + (b.reasoning_tokens ?? 0),
+        cached_tokens: a.cached_tokens === undefined && b.cached_tokens === undefined
+            ? undefined
+            : (a.cached_tokens ?? 0) + (b.cached_tokens ?? 0),
+        provider: b.provider,
+        model: b.model,
+        cost: a.cost + b.cost,
+    };
+}
+/** Raised internally when a leg exceeds its budget. */
+class LegTimeoutError extends Error {
+    /**
+     * @param routeKey The leg that timed out.
+     * @param budgetMs Its budget in milliseconds.
+     */
+    constructor(routeKey, budgetMs) {
+        super(`route ${routeKey} exceeded its ${budgetMs} ms budget`);
+        this.name = "LegTimeoutError";
+    }
+}
+/**
+ * Run one leg under a hard timeout, honouring the caller's own cancellation.
+ *
+ * The timer is always cleared and the abort listener always removed, including
+ * on the success path. A long-lived process that leaked one timer per LLM call
+ * would accumulate them at exactly the rate it does useful work.
+ *
+ * @param leg The leg to run.
+ * @param params Normalised parameters for this leg.
+ * @param execution The call context.
+ * @returns The provider's answer.
+ */
+async function runLeg(leg, params, execution) {
+    const controller = new AbortController();
+    const budgetMs = leg.route.timeoutMs;
+    const timer = setTimeout(() => {
+        controller.abort(new LegTimeoutError(leg.route.routeKey, budgetMs));
+    }, budgetMs);
+    const forwardAbort = () => {
+        controller.abort(execution.callerSignal?.reason);
+    };
+    if (execution.callerSignal !== undefined) {
+        if (execution.callerSignal.aborted) {
+            forwardAbort();
+        }
+        else {
+            execution.callerSignal.addEventListener("abort", forwardAbort, { once: true });
+        }
+    }
+    try {
+        // The guards wrap the transport rather than the whole leg, so the per-leg
+        // timeout above still bounds the total wait: a caller queued behind the
+        // rate limiter is spending its budget just as surely as one waiting on the
+        // provider, and only one clock should govern both.
+        return await withProviderGuards(leg.route.providerName, () => leg.transport.execute({
+            route: leg.route,
+            content: execution.content,
+            responseFormat: execution.responseFormat,
+            params,
+            signal: controller.signal,
+            correlationId: execution.correlationId,
+        }), budgetMs);
+    }
+    finally {
+        clearTimeout(timer);
+        execution.callerSignal?.removeEventListener("abort", forwardAbort);
+    }
+}
+/**
+ * Classify why a leg failed.
+ *
+ * The distinction matters to the breaker: a timeout and a 5xx are evidence the
+ * provider is unhealthy, while the caller cancelling is not. Counting a
+ * cancellation as a provider failure would let a burst of user-cancelled
+ * requests open the breaker on a perfectly healthy route.
+ *
+ * @param error The thrown value.
+ * @param callerSignal The caller's cancellation signal, if any.
+ * @returns The outcome and whether it counts against route health.
+ */
+function classify(error, callerSignal) {
+    if (callerSignal !== undefined && callerSignal.aborted) {
+        return {
+            outcome: "skipped",
+            reason: "caller cancelled",
+            countsAgainstHealth: false,
+        };
+    }
+    if (error instanceof LegTimeoutError) {
+        return { outcome: "timeout", reason: error.message, countsAgainstHealth: true };
+    }
+    if (error instanceof UnsupportedCapabilityError) {
+        return { outcome: "skipped", reason: error.message, countsAgainstHealth: false };
+    }
+    if (error instanceof RateGuardTimeoutError) {
+        // Self-inflicted pacing, not provider ill-health. Counting it would let the
+        // client's own throttling open a breaker on a perfectly healthy provider
+        // and permanently reroute traffic nobody chose to reroute.
+        return { outcome: "skipped", reason: error.message, countsAgainstHealth: false };
+    }
+    const reason = error instanceof Error ? error.message : String(error);
+    if (/abort/i.test(reason)) {
+        return {
+            outcome: "timeout",
+            reason: `aborted: ${reason}`,
+            countsAgainstHealth: true,
+        };
+    }
+    return { outcome: "error", reason, countsAgainstHealth: true };
+}
+/**
+ * Whether the caller has stopped waiting.
+ *
+ * Read through a function rather than inline, because `AbortSignal.aborted` is
+ * a live getter: it can flip to true while a leg is in flight, but a compiler
+ * that narrowed it at the top of the loop would prove the later check
+ * unreachable and invite its removal. The check is not redundant — it is the
+ * only thing that stops the chain spending money on an answer nobody will read.
+ *
+ * @param signal The caller's signal, if any.
+ * @returns Whether the call has been cancelled.
+ */
+function isAborted$1(signal) {
+    return signal !== undefined && signal.aborted;
+}
+/**
+ * Walk a chain until a leg answers.
+ *
+ * @param alias The alias being served, for error attribution.
+ * @param execution The call context.
+ * @returns The first successful leg's answer, with the full attempt record.
+ * @throws {ChainExhaustedError} When no leg produced an answer.
+ */
+async function executeChain(alias, execution) {
+    const now = execution.now ?? Date.now;
+    const attempts = [];
+    let totalUsage = EMPTY_USAGE;
+    for (const leg of execution.legs) {
+        const { route } = leg;
+        if (isAborted$1(execution.callerSignal)) {
+            // The caller has stopped waiting. Continuing to walk the chain would
+            // spend money on an answer nobody will read.
+            break;
+        }
+        if (leg.params instanceof UnsupportedCapabilityError) {
+            const record = {
+                routeKey: route.routeKey,
+                role: route.role,
+                provider: route.providerName,
+                modelId: route.modelId,
+                outcome: "skipped",
+                durationMs: 0,
+                reason: leg.params.message,
+            };
+            attempts.push(record);
+            execution.onAttempt?.(record);
+            continue;
+        }
+        if (!execution.breakers.allows(route.routeKey)) {
+            const record = {
+                routeKey: route.routeKey,
+                role: route.role,
+                provider: route.providerName,
+                modelId: route.modelId,
+                outcome: "breaker-open",
+                durationMs: 0,
+                reason: `circuit breaker is ${execution.breakers.stateOf(route.routeKey)}`,
+            };
+            attempts.push(record);
+            execution.onAttempt?.(record);
+            continue;
+        }
+        const startedAt = now();
+        execution.breakers.onAttemptStart(route.routeKey);
+        try {
+            const response = await runLeg(leg, leg.params, execution);
+            execution.breakers.onSuccess(route.routeKey);
+            totalUsage = sumUsage(totalUsage, response.usage);
+            const record = {
+                routeKey: route.routeKey,
+                role: route.role,
+                provider: route.providerName,
+                modelId: route.modelId,
+                outcome: "ok",
+                durationMs: now() - startedAt,
+                usage: response.usage,
+            };
+            attempts.push(record);
+            execution.onAttempt?.(record);
+            return { response, servedBy: route, attempts, totalUsage };
+        }
+        catch (error) {
+            const { outcome, reason, countsAgainstHealth } = classify(error, execution.callerSignal);
+            if (countsAgainstHealth) {
+                execution.breakers.onFailure(route.routeKey);
+            }
+            const record = {
+                routeKey: route.routeKey,
+                role: route.role,
+                provider: route.providerName,
+                modelId: route.modelId,
+                outcome,
+                durationMs: now() - startedAt,
+                reason,
+            };
+            attempts.push(record);
+            execution.onAttempt?.(record);
+            if (outcome === "skipped" && isAborted$1(execution.callerSignal)) {
+                break;
+            }
+        }
+    }
+    throw new ChainExhaustedError(alias, attempts, totalUsage);
+}
+
+var schema_version = 1;
+var policy_source = "docs/llm-provider-migration.md#3-routing-policy (v1.1)";
+var revised = "2026-09-10";
+var defaults = {
+	request_timeout_ms: {
+		"hot-path": 30000,
+		background: 90000,
+		batch: 300000
+	},
+	retries_per_leg: 1,
+	circuit_breaker: {
+		failure_threshold: 5,
+		cooldown_ms: 60000,
+		half_open_probes: 1
+	}
+};
+var providers = {
+	anthropic: {
+		display_name: "Anthropic",
+		tier: "closed",
+		api_style: "anthropic",
+		base_url: null,
+		base_url_env: null,
+		api_key_env: "ANTHROPIC_API_KEY",
+		secret_path: "llm/anthropic/apiKey",
+		account_status: "live",
+		lumic_provider: "anthropic",
+		published_rpm: null,
+		published_tpm: null,
+		limits_source: null,
+		docs_url: "https://docs.claude.com/en/api/overview",
+		notes: "Permanent designated tier. Retained, keyed, budgeted and continuously exercised as the revert target of every alias (PD-11)."
+	},
+	openai: {
+		display_name: "OpenAI",
+		tier: "closed",
+		api_style: "openai-compatible",
+		base_url: null,
+		base_url_env: null,
+		api_key_env: "OPENAI_API_KEY",
+		secret_path: "llm/openai/apiKey",
+		account_status: "live",
+		lumic_provider: "openai",
+		published_rpm: null,
+		published_tpm: null,
+		limits_source: null,
+		docs_url: "https://platform.openai.com/docs/api-reference",
+		notes: "Permanent designated tier. No alias routes to it today; it stays keyed and budgeted so a per-alias revert to an OpenAI incumbent is a config change (PD-11)."
+	},
+	deepinfra: {
+		display_name: "DeepInfra",
+		tier: "open",
+		api_style: "openai-compatible",
+		base_url: "https://api.deepinfra.com/v1/openai",
+		base_url_env: "DEEPINFRA_BASE_URL",
+		api_key_env: "DEEPINFRA_API_KEY",
+		secret_path: "llm/deepinfra/apiKey",
+		account_status: "pending-onboarding",
+		lumic_provider: null,
+		published_rpm: null,
+		published_tpm: null,
+		limits_source: null,
+		docs_url: "https://deepinfra.com/docs",
+		notes: "Rate limits and exact model ids are transcribed from the provider console at W3-02, never guessed."
+	},
+	fireworks: {
+		display_name: "Fireworks AI",
+		tier: "open",
+		api_style: "openai-compatible",
+		base_url: "https://api.fireworks.ai/inference/v1",
+		base_url_env: "FIREWORKS_BASE_URL",
+		api_key_env: "FIREWORKS_API_KEY",
+		secret_path: "llm/fireworks/apiKey",
+		account_status: "pending-onboarding",
+		lumic_provider: null,
+		published_rpm: null,
+		published_tpm: null,
+		limits_source: null,
+		docs_url: "https://docs.fireworks.ai",
+		notes: "Onboarded as a capacity backstop. No alias routes to it until its published RPM ceiling is recorded in provider-limits (W4-04)."
+	},
+	zai: {
+		display_name: "Z.ai",
+		tier: "open",
+		api_style: "openai-compatible",
+		base_url: "https://api.z.ai/api/paas/v4",
+		base_url_env: "ZAI_BASE_URL",
+		api_key_env: "ZAI_API_KEY",
+		secret_path: "llm/zai/apiKey",
+		account_status: "pending-onboarding",
+		lumic_provider: null,
+		published_rpm: null,
+		published_tpm: null,
+		limits_source: null,
+		docs_url: "https://docs.z.ai",
+		notes: "First-party GLM host. Section 3 anchors first-party GLM below the converged multi-host price, so it is the primary leg for llm.reason."
+	},
+	deepseek: {
+		display_name: "DeepSeek",
+		tier: "open",
+		api_style: "openai-compatible",
+		base_url: "https://api.deepseek.com",
+		base_url_env: "DEEPSEEK_BASE_URL",
+		api_key_env: "DEEPSEEK_API_KEY",
+		secret_path: "llm/deepseek/apiKey",
+		account_status: "live",
+		lumic_provider: "deepseek",
+		published_rpm: null,
+		published_tpm: null,
+		limits_source: null,
+		docs_url: "https://api-docs.deepseek.com",
+		notes: "Already a registered lumic provider, so its legs can also be served by the degraded direct transport. Off-peak windows are captured in gateway config at W3-05 for batch scheduling."
+	},
+	groq: {
+		display_name: "Groq",
+		tier: "open",
+		api_style: "openai-compatible",
+		base_url: "https://api.groq.com/openai/v1",
+		base_url_env: "GROQ_BASE_URL",
+		api_key_env: "GROQ_API_KEY",
+		secret_path: "llm/groq/apiKey",
+		account_status: "not-in-scope",
+		lumic_provider: null,
+		published_rpm: null,
+		published_tpm: null,
+		limits_source: null,
+		docs_url: "https://console.groq.com/docs",
+		notes: "Section 3 names Groq or Cerebras as the llm.fast primary, but the W3 onboarding list does not include either. See open item OI-01: until an owner resolves it, llm.fast's primary leg is unreachable and the alias serves from its secondary and closed legs."
+	},
+	openrouter: {
+		display_name: "OpenRouter",
+		tier: "aggregator",
+		api_style: "openai-compatible",
+		base_url: "https://openrouter.ai/api/v1",
+		base_url_env: "OPENROUTER_BASE_URL",
+		api_key_env: "OPENROUTER_API_KEY",
+		secret_path: "llm/openrouter/apiKey",
+		account_status: "pending-onboarding",
+		lumic_provider: null,
+		published_rpm: null,
+		published_tpm: null,
+		limits_source: null,
+		docs_url: "https://openrouter.ai/docs",
+		notes: "Aggregator backstop. Reaches an open-weight model when its dedicated host is down, without a new account. Not a chain leg by default: an aggregator hides which upstream served a call, which defeats per-provider attribution."
+	}
+};
+var aliases = {
+	"llm.reason": {
+		workload: "Deep reasoning, audit loops, config tuning",
+		latency_class: "background",
+		criticality: "ops",
+		isolation_capable: true,
+		eval_gate: "free-text-judge",
+		budget: {
+			basis: "provisional-pre-baseline",
+			monthly_usd: 750,
+			alert_pct: [
+				50,
+				80,
+				100
+			]
+		},
+		routes: [
+			{
+				role: "primary",
+				provider: "zai",
+				model_id: null,
+				model_id_status: "pending-provider-confirmation",
+				model_id_source: null,
+				model_family: "GLM-5.3",
+				lumic_model: null,
+				params: {
+					temperature: null,
+					max_output_tokens: null,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: false,
+					supports_vision: false
+				},
+				price_per_mtok: {
+					input: 1.09,
+					output: 3.43,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 first-party GLM-5.3 anchor; re-verify at W2-02"
+				}
+			},
+			{
+				role: "secondary",
+				provider: "deepinfra",
+				model_id: null,
+				model_id_status: "pending-provider-confirmation",
+				model_id_source: null,
+				model_family: "DeepSeek V4 Pro",
+				lumic_model: null,
+				params: {
+					temperature: null,
+					max_output_tokens: null,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: false,
+					supports_vision: false
+				},
+				price_per_mtok: {
+					input: 1.3,
+					output: 2.6,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 DeepInfra anchor; re-verify at W2-02"
+				}
+			},
+			{
+				role: "closed_incumbent",
+				provider: "anthropic",
+				model_id: "claude-opus-4-7",
+				model_id_status: "confirmed",
+				model_id_source: "lumic-utils/src/types/openai-types.ts SUPPORTED_MODELS — already routed on in production",
+				model_family: "Opus-class",
+				lumic_model: "claude-opus-4-7",
+				params: {
+					temperature: null,
+					max_output_tokens: 128000,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: true,
+					context_window: 1000000
+				},
+				price_per_mtok: {
+					input: 5,
+					output: 25,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 Opus-class anchor; matches lumic-utils/src/functions/llm-config.ts"
+				}
+			}
+		]
+	},
+	"llm.agentic": {
+		workload: "Hardest long-horizon agentic work",
+		latency_class: "background",
+		criticality: "ops",
+		isolation_capable: true,
+		eval_gate: "tool-call",
+		policy_note: "Section 3 names the primary as Fable-class. The strongest Anthropic model registered in the lumic model registry — the table this codebase actually routes on — is claude-opus-4-7, so that is the configured id. Registering a Fable-class model in @adaptic/lumic-utils would change live model selection for every consumer of the advanced tier and is therefore a separate, evidence-gated decision, recorded as open item OI-02 rather than smuggled in here.",
+		budget: {
+			basis: "provisional-pre-baseline",
+			monthly_usd: 1500,
+			alert_pct: [
+				50,
+				80,
+				100
+			]
+		},
+		routes: [
+			{
+				role: "primary",
+				provider: "anthropic",
+				model_id: "claude-opus-4-7",
+				model_id_status: "confirmed",
+				model_id_source: "lumic-utils/src/types/openai-types.ts SUPPORTED_MODELS — already routed on in production",
+				model_family: "Fable-class (see policy_note)",
+				lumic_model: "claude-opus-4-7",
+				params: {
+					temperature: null,
+					max_output_tokens: 128000,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: true,
+					context_window: 1000000
+				},
+				price_per_mtok: {
+					input: 10,
+					output: 50,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 Fable-class anchor"
+				}
+			},
+			{
+				role: "secondary",
+				provider: "deepinfra",
+				model_id: null,
+				model_id_status: "pending-provider-confirmation",
+				model_id_source: null,
+				model_family: "Kimi K3",
+				lumic_model: null,
+				shadow_only: true,
+				params: {
+					temperature: null,
+					max_output_tokens: null,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: false,
+					supports_vision: false
+				},
+				price_per_mtok: {
+					input: 2.85,
+					output: 14.25,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 DeepInfra anchor; re-verify at W2-02"
+				},
+				notes: "Shadow-eval only per Section 3. Configured and scored, never served to a caller, so the hardest agentic path keeps its closed primary while the open candidate accrues evidence."
+			}
+		]
+	},
+	"llm.fast": {
+		workload: "Latency-critical paths",
+		latency_class: "hot-path",
+		criticality: "trading-adjacent",
+		isolation_capable: false,
+		eval_gate: "structured-output",
+		policy_note: "Trading-adjacent and hot-path, so under Section 7 this alias is the LAST to promote: no hot-path alias reaches LIVE until every background alias has completed W5-03 and held steady state for a week.",
+		budget: {
+			basis: "provisional-pre-baseline",
+			monthly_usd: 400,
+			alert_pct: [
+				50,
+				80,
+				100
+			]
+		},
+		routes: [
+			{
+				role: "primary",
+				provider: "groq",
+				model_id: null,
+				model_id_status: "pending-provider-confirmation",
+				model_id_source: null,
+				model_family: "gpt-oss-120B",
+				lumic_model: null,
+				params: {
+					temperature: null,
+					max_output_tokens: null,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: false,
+					supports_vision: false
+				},
+				price_per_mtok: {
+					input: 0.039,
+					output: 0.19,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 gpt-oss-120B anchor (DeepInfra price; Groq price unconfirmed pending OI-01)"
+				},
+				notes: "Unreachable until OI-01 is resolved — Groq is not on the W3 onboarding list."
+			},
+			{
+				role: "secondary",
+				provider: "deepinfra",
+				model_id: null,
+				model_id_status: "pending-provider-confirmation",
+				model_id_source: null,
+				model_family: "gpt-oss-120B",
+				lumic_model: null,
+				params: {
+					temperature: null,
+					max_output_tokens: null,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: false,
+					supports_vision: false
+				},
+				price_per_mtok: {
+					input: 0.039,
+					output: 0.19,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 DeepInfra anchor; re-verify at W2-02"
+				}
+			},
+			{
+				role: "closed_incumbent",
+				provider: "anthropic",
+				model_id: "claude-haiku-4-5",
+				model_id_status: "confirmed",
+				model_id_source: "lumic-utils/src/types/openai-types.ts SUPPORTED_MODELS — already routed on in production",
+				model_family: "Haiku-class",
+				lumic_model: "claude-haiku-4-5",
+				params: {
+					temperature: null,
+					max_output_tokens: 64000,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: true,
+					context_window: 200000
+				},
+				price_per_mtok: {
+					input: 1,
+					output: 5,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 Haiku-class anchor"
+				}
+			}
+		]
+	},
+	"llm.extract": {
+		workload: "High-volume extraction, classification, log analysis",
+		latency_class: "batch",
+		criticality: "internal",
+		isolation_capable: true,
+		eval_gate: "structured-output",
+		budget: {
+			basis: "provisional-pre-baseline",
+			monthly_usd: 300,
+			alert_pct: [
+				50,
+				80,
+				100
+			]
+		},
+		routes: [
+			{
+				role: "primary",
+				provider: "deepseek",
+				model_id: "deepseek-v4-flash",
+				model_id_status: "confirmed",
+				model_id_source: "lumic-utils/src/types/openai-types.ts SUPPORTED_MODELS — already routed on in production",
+				model_family: "DeepSeek V4 Flash",
+				lumic_model: "deepseek-v4-flash",
+				params: {
+					temperature: null,
+					max_output_tokens: 64000,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: false,
+					context_window: 1000000
+				},
+				price_per_mtok: {
+					input: 0.14,
+					output: 0.28,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 V4 Flash anchor; re-verify at W2-02"
+				}
+			},
+			{
+				role: "secondary",
+				provider: "zai",
+				model_id: null,
+				model_id_status: "pending-provider-confirmation",
+				model_id_source: null,
+				model_family: "GLM 5.3 Flash",
+				lumic_model: null,
+				params: {
+					temperature: null,
+					max_output_tokens: null,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: false,
+					supports_vision: false
+				},
+				price_per_mtok: {
+					input: 1.09,
+					output: 3.43,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 GLM first-party anchor; Flash-tier price unconfirmed, re-verify at W2-02"
+				}
+			},
+			{
+				role: "closed_incumbent",
+				provider: "anthropic",
+				model_id: "claude-haiku-4-5",
+				model_id_status: "confirmed",
+				model_id_source: "lumic-utils/src/types/openai-types.ts SUPPORTED_MODELS — already routed on in production",
+				model_family: "Haiku-class",
+				lumic_model: "claude-haiku-4-5",
+				params: {
+					temperature: null,
+					max_output_tokens: 64000,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: true,
+					context_window: 200000
+				},
+				price_per_mtok: {
+					input: 1,
+					output: 5,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 Haiku-class anchor"
+				}
+			}
+		]
+	},
+	"llm.judge": {
+		workload: "Eval judging only",
+		latency_class: "batch",
+		criticality: "internal",
+		isolation_capable: false,
+		pinned: true,
+		eval_gate: "none-pinned-judge",
+		policy_note: "PD-6: pinned and never auto-swapped, and deliberately carries no fallback. A judge that silently failed over would grade one model's output against another model's standard, which would corrupt every gate decided by it — so it fails loud instead.",
+		budget: {
+			basis: "provisional-pre-baseline",
+			monthly_usd: 150,
+			alert_pct: [
+				50,
+				80,
+				100
+			]
+		},
+		routes: [
+			{
+				role: "primary",
+				provider: "anthropic",
+				model_id: "claude-sonnet-4-6",
+				model_id_status: "confirmed",
+				model_id_source: "lumic-utils/src/types/openai-types.ts SUPPORTED_MODELS — already routed on in production",
+				model_family: "Sonnet-class",
+				lumic_model: "claude-sonnet-4-6",
+				params: {
+					temperature: 0,
+					max_output_tokens: 64000,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: true,
+					context_window: 1000000
+				},
+				price_per_mtok: {
+					input: 3,
+					output: 15,
+					as_of: "2026-09-10",
+					source: "lumic-utils/src/functions/llm-config.ts anthropicModelCosts"
+				}
+			}
+		]
+	}
+};
+var open_items = [
+	{
+		id: "OI-01",
+		question: "Section 3 makes Groq or Cerebras the llm.fast primary, but neither appears in the W3 onboarding provider list (DeepInfra, Fireworks, Z.ai, DeepSeek, aggregator). Which host serves llm.fast's primary leg, and is it added to W3?",
+		blocks: "llm.fast primary reachability; W5-03 canary for llm.fast",
+		owner: "CEO"
+	},
+	{
+		id: "OI-02",
+		question: "Section 3 names a Fable-class primary for llm.agentic, but the lumic model registry's strongest registered Anthropic model is claude-opus-4-7. Register a Fable-class model in @adaptic/lumic-utils, or accept opus-4-7 as the llm.agentic primary?",
+		blocks: "llm.agentic primary fidelity to Section 3",
+		owner: "CEO"
+	},
+	{
+		id: "OI-03",
+		question: "Every alias budget is provisional-pre-baseline because Section 9's baseline monthly spend is still FILL. Which caps apply once W1-03 produces the billing baseline?",
+		blocks: "PD-7 layer 3 calibration; Section 9 savings target measurement",
+		owner: "CEO"
+	},
+	{
+		id: "OI-04",
+		question: "llm.agentic's serving chain is one leg long because Section 3 makes its primary the closed incumbent and its only secondary shadow-eval-only. An Anthropic outage therefore leaves the alias with no configured fallback. Widen it (a second closed provider, or promoting the Kimi leg out of shadow), or accept the single leg?",
+		blocks: "llm.agentic availability under a primary-provider outage",
+		owner: "CEO"
+	}
+];
+var rawTable = {
+	schema_version: schema_version,
+	policy_source: policy_source,
+	revised: revised,
+	defaults: defaults,
+	providers: providers,
+	aliases: aliases,
+	open_items: open_items
+};
+
+/**
+ * Typed access to the canonical alias route table.
+ *
+ * The table is imported rather than fetched so an alias always resolves, even
+ * when the gateway is unreachable. A client that could only learn its routes
+ * from the gateway would have no way to fall back when the gateway itself is
+ * the thing that failed, which would make the mandatory fallback chain of PD-3
+ * conditional on the very component it exists to survive.
+ *
+ * Resolution is deliberately conservative in three ways. An unknown alias is an
+ * error rather than a default, because a typo silently served by whichever
+ * model happened to be configured is worse than a loud failure. A route whose
+ * vendor model id is unconfirmed is excluded, because a guessed id fails at the
+ * first live call rather than at review. And a shadow-only route is never
+ * served, because a candidate that can answer a live request has stopped being
+ * a candidate.
+ *
+ * @module llm/route-table
+ */
+/** Chain order, fixed by role rather than by authoring order in the file. */
+const ROLE_ORDER = ["primary", "secondary", "closed_incumbent"];
+/** Suffix naming an alias's research-isolated variant (PD-9). */
+const ISOLATED_SUFFIX = ".isolated";
+/**
+ * The canonical route table.
+ *
+ * Exposed as a readonly view so a consumer can inspect routing without being
+ * able to mutate it. A table that could be edited at runtime would let one
+ * caller change every other caller's routing.
+ */
+const routeTable = rawTable;
+/**
+ * Every alias the table defines.
+ *
+ * @returns The alias names, sorted for stable iteration.
+ */
+function listAliases() {
+    return Object.keys(routeTable.aliases).sort();
+}
+/**
+ * Look up an alias definition.
+ *
+ * @param alias The alias to resolve.
+ * @returns Its definition.
+ * @throws When the alias is not defined by the route table.
+ */
+function aliasDefinition(alias) {
+    const definition = routeTable.aliases[alias];
+    if (definition === undefined) {
+        throw new UnknownAliasError(alias, listAliases());
+    }
+    return definition;
+}
+/**
+ * Look up a provider registry entry.
+ *
+ * @param name The provider key.
+ * @returns Its registry entry.
+ * @throws When the provider is not registered.
+ */
+function providerEntry(name) {
+    const provider = routeTable.providers[name];
+    if (provider === undefined) {
+        throw new Error(`route table names provider "${name}", which is not in the provider registry`);
+    }
+    return provider;
+}
+/** Thrown when a caller names an alias the route table does not define. */
+class UnknownAliasError extends Error {
+    /** The alias that was requested. */
+    alias;
+    /** The aliases that do exist, so the message is actionable. */
+    known;
+    /**
+     * @param alias The unrecognised alias.
+     * @param known The aliases the table defines.
+     */
+    constructor(alias, known) {
+        super(`unknown LLM alias "${alias}". Known aliases: ${known.join(", ")}. ` +
+            "Application code names aliases only; adding one is a change to the route table.");
+        this.name = "UnknownAliasError";
+        this.alias = alias;
+        this.known = known;
+    }
+}
+/** Thrown when an alias exists but has no leg that can currently serve a caller. */
+class NoServableRouteError extends Error {
+    /** The alias that could not be served. */
+    alias;
+    /** Why each of its legs was excluded, in chain order. */
+    exclusions;
+    /**
+     * @param alias The alias.
+     * @param exclusions Per-leg reasons, in chain order.
+     */
+    constructor(alias, exclusions) {
+        super(`alias "${alias}" has no servable route. Legs excluded: ${exclusions.join("; ")}`);
+        this.name = "NoServableRouteError";
+        this.alias = alias;
+        this.exclusions = exclusions;
+    }
+}
+/**
+ * Order an alias's routes into the chain the client walks.
+ *
+ * @param definition The alias definition.
+ * @returns Routes ordered primary -> secondary -> closed incumbent.
+ */
+function orderedRoutes(definition) {
+    return [...definition.routes].sort((a, b) => ROLE_ORDER.indexOf(a.role) - ROLE_ORDER.indexOf(b.role));
+}
+/**
+ * Stable identity for one leg, used to key its circuit breaker and its metrics.
+ *
+ * Keyed by alias, isolation and role rather than by provider and model, because
+ * the breaker guards a position in a chain: reverting an alias to a different
+ * model at the same position should inherit that position's health rather than
+ * start blind, and the isolated variant must never share a breaker with the
+ * shared one.
+ *
+ * @param alias The alias.
+ * @param isolated Whether this is the isolated variant.
+ * @param role The leg's role.
+ * @returns The route key.
+ */
+function routeKeyFor(alias, isolated, role) {
+    return `${alias}${isolated ? ISOLATED_SUFFIX : ""}#${role}`;
+}
+/**
+ * Resolve an alias to the ordered chain of legs that can serve it today.
+ *
+ * Exclusions are returned rather than discarded so an exhausted chain can say
+ * why each leg was unavailable. "No route available" without that detail sends
+ * an operator to read config; with it, the answer is in the error.
+ *
+ * @param alias The alias to resolve.
+ * @param options Resolution options.
+ * @param options.isolated Route through the isolated variant (PD-9).
+ * @param options.timeoutMsOverride Per-leg budget override, never wider than the caller's own deadline.
+ * @returns The resolved chain.
+ * @throws {UnknownAliasError} When the alias is not defined.
+ */
+function resolveChain(alias, options = {}) {
+    const definition = aliasDefinition(alias);
+    const isolated = options.isolated === true;
+    if (isolated && !definition.isolation_capable) {
+        throw new Error(`alias "${alias}" is not isolation-capable, so it has no isolated variant. ` +
+            "PD-9 forbids serving isolated work from a shared route, so this fails rather than falling back.");
+    }
+    const timeoutMs = options.timeoutMsOverride ??
+        routeTable.defaults.request_timeout_ms[definition.latency_class];
+    const resolved = [];
+    const exclusions = [];
+    for (const route of orderedRoutes(definition)) {
+        const provider = providerEntry(route.provider);
+        if (route.shadow_only === true) {
+            exclusions.push({
+                role: route.role,
+                provider: route.provider,
+                reason: "shadow-only: configured and scored, never served to a caller",
+            });
+            continue;
+        }
+        if (route.model_id_status !== "confirmed" || route.model_id === null) {
+            exclusions.push({
+                role: route.role,
+                provider: route.provider,
+                reason: `model id unconfirmed (${route.model_family}); it is transcribed from the provider console at onboarding, never guessed`,
+            });
+            continue;
+        }
+        if (provider.account_status !== "live") {
+            exclusions.push({
+                role: route.role,
+                provider: route.provider,
+                reason: `provider account status is "${provider.account_status}"`,
+            });
+            continue;
+        }
+        resolved.push({
+            alias,
+            isolated,
+            role: route.role,
+            providerName: route.provider,
+            provider,
+            modelId: route.model_id,
+            lumicModel: route.lumic_model ?? null,
+            params: route.params ?? {},
+            routeKey: routeKeyFor(alias, isolated, route.role),
+            timeoutMs,
+            retriesPerLeg: routeTable.defaults.retries_per_leg,
+        });
+    }
+    return { alias, isolated, routes: resolved, exclusions };
+}
+/**
+ * The permanent closed-incumbent leg of an alias (PD-11).
+ *
+ * Found by provider tier rather than by role, because an alias whose primary is
+ * already a closed vendor has that primary as its revert target. Both shapes
+ * therefore hold the same guarantee: there is always a configured route that
+ * needs no new account and no code change to fall back to.
+ *
+ * @param chain A resolved chain.
+ * @returns The closed leg, or undefined when none is currently servable.
+ */
+function closedIncumbentLeg(chain) {
+    return chain.routes.find((route) => route.provider.tier === "closed");
+}
+/**
+ * The name the gateway knows a leg by.
+ *
+ * The head of a chain is addressed by the bare alias so a caller never learns a
+ * leg name; every other leg carries the derived name the renderer gives it.
+ * Keeping this derivation beside the resolver — rather than in the transport —
+ * is what stops the client and the gateway config from disagreeing about a name.
+ *
+ * @param route The resolved leg.
+ * @param chain The chain it belongs to.
+ * @returns The gateway `model_name`.
+ */
+function gatewayModelNameFor(route, chain) {
+    const base = `${route.alias}${route.isolated ? ISOLATED_SUFFIX : ""}`;
+    return chain.routes[0]?.routeKey === route.routeKey
+        ? base
+        : `${base}.fallback.${route.role}`;
+}
+
+/**
+ * Bounded validate-and-retry for structured output.
+ *
+ * A model asked for a schema-shaped answer sometimes returns something close
+ * but wrong. Feeding the validator's own complaint back once fixes most of
+ * those, because the model can see precisely what it got wrong. A second retry
+ * almost never helps: if the model is still wrong after being told exactly what
+ * was wrong, it is persistently wrong for this prompt, and further attempts
+ * spend budget and latency to arrive at the same place.
+ *
+ * The retry lives ahead of the fallback chain rather than inside it. A payload
+ * that fails validation is evidence about the PROMPT, not about the provider's
+ * health, so it must not open a circuit breaker or advance to the next leg —
+ * the next leg would receive the same prompt and be no likelier to satisfy it.
+ *
+ * Exhaustion throws. Returning a partial or defaulted object would hand the
+ * caller a well-typed value that no model ever produced, and the resulting
+ * decision would be made on invented data with nothing to show it.
+ *
+ * @module llm/schema-retry
+ */
+/** Attempts allowed: the first, plus exactly one feedback retry. */
+const MAX_ATTEMPTS = 2;
+/** Characters of an invalid payload echoed back to the model. */
+const PAYLOAD_EXCERPT = 2000;
+/**
+ * Thrown when both attempts failed validation.
+ *
+ * Carries both rejection reasons, because the pair is what distinguishes a
+ * flaky answer from a prompt the model cannot satisfy: two different complaints
+ * suggest instability, while the same complaint twice points at the prompt or
+ * the schema.
+ */
+class SchemaRetryExhaustedError extends Error {
+    /** Why the first attempt was rejected. */
+    firstReason;
+    /** Why the retry was rejected. */
+    secondReason;
+    /** Usage spent across both attempts, so the spend is still accounted for. */
+    totalUsage;
+    /**
+     * @param firstReason Validator's complaint about attempt one.
+     * @param secondReason Validator's complaint about attempt two.
+     * @param totalUsage Usage across both attempts.
+     */
+    constructor(firstReason, secondReason, totalUsage) {
+        super("LLM structured output failed validation twice. " +
+            `First: ${firstReason}. After feedback: ${secondReason}. ` +
+            "No value is returned: a defaulted object would be data no model produced.");
+        this.name = "SchemaRetryExhaustedError";
+        this.firstReason = firstReason;
+        this.secondReason = secondReason;
+        this.totalUsage = totalUsage;
+    }
+}
+/**
+ * Build the retry prompt.
+ *
+ * The rejected payload is echoed back alongside the complaint, because a model
+ * asked to "fix the error" without seeing what it produced will usually
+ * regenerate from scratch and reproduce the same mistake.
+ *
+ * @param originalPrompt The prompt that produced the invalid payload.
+ * @param rejected The payload that failed.
+ * @param reason The validator's complaint.
+ * @returns The retry prompt.
+ */
+function buildRetryPrompt(originalPrompt, rejected, reason) {
+    const excerpt = typeof rejected === "string"
+        ? rejected
+        : JSON.stringify(rejected, null, 2) ?? String(rejected);
+    return [
+        originalPrompt,
+        "",
+        "Your previous response was rejected by a schema validator.",
+        "",
+        "Previous response:",
+        excerpt.slice(0, PAYLOAD_EXCERPT),
+        "",
+        `Validator rejection: ${reason}`,
+        "",
+        "Return a corrected response that satisfies the schema. Return only the corrected response.",
+    ].join("\n");
+}
+/**
+ * Run a call with one validator-feedback retry.
+ *
+ * @param options Retry options.
+ * @param options.prompt The original prompt.
+ * @param options.validate Validator applied to each attempt's payload.
+ * @param options.call Executes one attempt with the given prompt.
+ * @returns The validated value with combined usage.
+ * @throws {SchemaRetryExhaustedError} When both attempts fail validation.
+ */
+async function callWithValidation(options) {
+    const first = await options.call(options.prompt);
+    const firstOutcome = options.validate(first.response);
+    if (firstOutcome.ok) {
+        return {
+            value: firstOutcome.value,
+            attempts: 1,
+            response: first,
+            totalUsage: first.usage,
+        };
+    }
+    const retryPrompt = buildRetryPrompt(options.prompt, first.response, firstOutcome.reason);
+    const second = await options.call(retryPrompt);
+    const combined = sumUsage(first.usage, second.usage);
+    const secondOutcome = options.validate(second.response);
+    if (secondOutcome.ok) {
+        return {
+            value: secondOutcome.value,
+            attempts: MAX_ATTEMPTS,
+            response: second,
+            totalUsage: combined,
+        };
+    }
+    throw new SchemaRetryExhaustedError(firstOutcome.reason, secondOutcome.reason, combined);
+}
+
+/**
+ * Degraded direct transport: the path used when the gateway itself is gone.
+ *
+ * Routing every call through one proxy concentrates a great deal of value — one
+ * place to swap a model, one place to bound spend, one place to see cost. It
+ * also concentrates risk: without this path, a gateway outage would take every
+ * LLM call in the system down at once, which is a worse failure than any of the
+ * provider outages the gateway exists to survive.
+ *
+ * Two constraints keep this a safety net rather than a second routing policy.
+ * It serves CLOSED-tier legs only, so the degraded path can never be the thing
+ * that silently promotes an open-weight model past its evaluation gates. And it
+ * resolves the model from the same route table the gateway is rendered from, so
+ * degraded traffic reaches the same model the gateway would have chosen.
+ *
+ * The provider SDK is reached through an injected caller, resolved lazily. A
+ * static import would make `@adaptic/utils` load a provider SDK for every
+ * consumer, including those that never make an LLM call, and would harden a
+ * package cycle that is currently only a declaration.
+ *
+ * @module llm/transports/direct
+ */
+/**
+ * Thrown when the degraded path is asked to serve a leg it must not serve.
+ *
+ * Refusing loudly rather than serving the leg anyway is the point: the whole
+ * value of restricting this path is lost if it quietly widens under pressure,
+ * and pressure is exactly when it runs.
+ */
+class DirectTransportRefusedError extends Error {
+    /**
+     * @param routeKey The leg that was refused.
+     * @param reason Why it cannot be served directly.
+     */
+    constructor(routeKey, reason) {
+        super(`the degraded direct transport refuses route ${routeKey}: ${reason}. ` +
+            "It exists so a gateway outage does not stop every LLM call, not as a second routing policy.");
+        this.name = "DirectTransportRefusedError";
+    }
+}
+/**
+ * Build the degraded direct transport.
+ *
+ * @param config Transport configuration.
+ * @returns A transport that reaches a closed-tier provider without the gateway.
+ */
+function createDirectTransport(config) {
+    return {
+        name: "direct",
+        async execute(request) {
+            const { route } = request;
+            if (route.provider.tier !== "closed") {
+                throw new DirectTransportRefusedError(route.routeKey, `provider "${route.providerName}" is ${route.provider.tier}-tier; only a closed incumbent may be served without the gateway, so a degraded call can never promote an open route past its evaluation gates`);
+            }
+            if (route.lumicModel === null) {
+                throw new DirectTransportRefusedError(route.routeKey, "the route names no lumic_model, so there is no registered model to call directly");
+            }
+            const call = await config.resolveCaller();
+            const result = await call(request.content, request.responseFormat, {
+                ...request.params,
+                model: route.lumicModel,
+                signal: request.signal,
+                timeout: route.timeoutMs,
+            });
+            return {
+                response: result.response,
+                usage: readUsage$1(result.usage, request),
+                tool_calls: Array.isArray(result.tool_calls)
+                    ? result.tool_calls
+                    : undefined,
+            };
+        },
+    };
+}
+/**
+ * Normalise the incumbent client's usage shape.
+ *
+ * Missing counts stay zero rather than being estimated, for the same reason
+ * they do on the gateway path: an invented token count flows straight into the
+ * budget accounting the spend controls depend on.
+ *
+ * @param usage The incumbent client's usage, if any.
+ * @param request The request it answers.
+ * @returns The normalised usage record.
+ */
+function readUsage$1(usage, request) {
+    return {
+        prompt_tokens: usage?.prompt_tokens ?? 0,
+        completion_tokens: usage?.completion_tokens ?? 0,
+        reasoning_tokens: usage?.reasoning_tokens,
+        cached_tokens: usage?.cached_tokens,
+        provider: usage?.provider ?? request.route.providerName,
+        model: usage?.model ?? request.route.modelId,
+        cost: usage?.cost ?? 0,
+    };
+}
+/**
+ * Package providing the default provider client, resolved at runtime.
+ *
+ * Assembled rather than written as a literal so the module specifier is opaque
+ * to the compiler and the bundler. That is not a trick to dodge a type error:
+ * this package is genuinely OPTIONAL. The stable lineage of `@adaptic/utils`
+ * does not depend on `@adaptic/lumic-utils` at all, the transport is injectable
+ * precisely so a consumer can supply its own, and the default exists only as a
+ * convenience for consumers that already have it installed. A static specifier
+ * would assert a dependency that does not exist and would harden the
+ * utils/lumic-utils package cycle from a declaration into a build-time fact.
+ */
+const DEFAULT_PROVIDER_CLIENT_PACKAGE = ["@adaptic", "lumic-utils"].join("/");
+/**
+ * The default caller: the incumbent client in `@adaptic/lumic-utils`.
+ *
+ * Resolved with a dynamic import so this module has no load-time dependency on
+ * that package. When it cannot be loaded the failure names the degraded path
+ * explicitly, because "cannot find module" during an outage is otherwise a
+ * confusing second mystery on top of the first — and a consumer that does not
+ * ship that package is expected to register its own transport rather than to
+ * discover this at the moment the gateway fails.
+ *
+ * @returns The provider-calling function.
+ */
+async function resolveDefaultDirectCaller() {
+    try {
+        const lumic = (await import(
+        /* @vite-ignore */ DEFAULT_PROVIDER_CLIENT_PACKAGE));
+        const call = lumic.lumic?.llm?.call;
+        if (typeof call !== "function") {
+            throw new Error(`${DEFAULT_PROVIDER_CLIENT_PACKAGE} exposes no lumic.llm.call`);
+        }
+        return call;
+    }
+    catch (error) {
+        throw new Error("the degraded direct transport could not load its provider client: " +
+            `${error instanceof Error ? error.message : String(error)}. ` +
+            "Register a direct transport explicitly via configureLlmClient() where the default is unavailable.");
+    }
+}
+
+/**
+ * Gateway transport: the normal path for every LLM call.
+ *
+ * The client sends an alias to the LiteLLM proxy and the proxy resolves it. The
+ * vendor model string therefore exists only in the gateway's configuration and
+ * never in application code (PD-5), which is what makes a model swap a config
+ * change rather than a deploy.
+ *
+ * The client still walks its own chain on top of the gateway's, and the
+ * duplication is deliberate. The gateway's fallbacks cover a provider being
+ * down; the client's cover the gateway being down. Only one of those two can
+ * cover the other, so the outer chain is the one that must exist.
+ *
+ * The gateway key is read from the environment by NAME at call time and never
+ * stored, logged, or included in an error (PD-2). Reading it per call rather
+ * than caching it at import means a rotation takes effect without a restart.
+ *
+ * @module llm/transports/gateway
+ */
+/** HTTP statuses that mean "try the next leg" rather than "this request is wrong". */
+const RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
+/** Maximum characters of an error body echoed into a message. */
+const ERROR_BODY_EXCERPT = 400;
+/**
+ * Thrown when the gateway itself is unreachable, as opposed to a provider
+ * behind it failing.
+ *
+ * The distinction is what licenses the degraded direct path: a 502 from a
+ * provider means try the next leg, while a connection refused from the proxy
+ * means the whole gateway is gone and the chain cannot be walked through it at
+ * all.
+ */
+class GatewayUnreachableError extends Error {
+    /**
+     * @param baseUrl The gateway that could not be reached.
+     * @param cause The underlying transport error.
+     */
+    constructor(baseUrl, cause) {
+        super(`LLM gateway at ${baseUrl} is unreachable: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "GatewayUnreachableError";
+    }
+}
+/** Thrown when the gateway answered, but with a failure. */
+class GatewayResponseError extends Error {
+    /** The HTTP status. */
+    status;
+    /** Whether advancing to the next leg could plausibly help. */
+    retryable;
+    /**
+     * @param status The HTTP status.
+     * @param body A bounded excerpt of the response body.
+     */
+    constructor(status, body) {
+        super(`LLM gateway returned ${status}: ${body.slice(0, ERROR_BODY_EXCERPT)}`);
+        this.name = "GatewayResponseError";
+        this.status = status;
+        this.retryable = RETRYABLE_STATUSES.has(status);
+    }
+}
+/**
+ * Read the gateway key from the environment by name.
+ *
+ * @param envVar The variable's NAME.
+ * @returns The key.
+ * @throws When the variable is unset, because an unauthenticated call would
+ *   reach the gateway as an anonymous caller and be rejected there anyway —
+ *   later, and with a less useful message.
+ */
+function readGatewayKey(envVar) {
+    const value = process.env[envVar];
+    if (value === undefined || value.length === 0) {
+        throw new Error(`${envVar} is unset, so the LLM gateway cannot be authenticated against. ` +
+            "Provision it from the secrets manager; it is never read from a file or a default.");
+    }
+    return value;
+}
+/**
+ * Extract usage from a chat-completion response.
+ *
+ * Absent counts stay zero rather than being estimated. A fabricated token count
+ * would flow straight into the budget accounting that the spend controls are
+ * built on, and a budget computed from invented numbers is worse than one that
+ * knows it is missing a call.
+ *
+ * @param payload The parsed response body.
+ * @param request The request it answers.
+ * @returns The usage record.
+ */
+function readUsage(payload, request) {
+    const usage = (payload.usage ?? {});
+    const details = (usage.prompt_tokens_details ?? {});
+    const cached = details.cached_tokens;
+    const reasoningDetails = (usage.completion_tokens_details ?? {});
+    const reasoning = reasoningDetails.reasoning_tokens;
+    return {
+        prompt_tokens: typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : 0,
+        completion_tokens: typeof usage.completion_tokens === "number" ? usage.completion_tokens : 0,
+        reasoning_tokens: typeof reasoning === "number" ? reasoning : undefined,
+        cached_tokens: typeof cached === "number" ? cached : undefined,
+        provider: request.route.providerName,
+        model: request.route.modelId,
+        cost: typeof usage.response_cost === "number" ? usage.response_cost : 0,
+    };
+}
+/**
+ * Build the gateway transport.
+ *
+ * @param config Transport configuration.
+ * @returns A transport that executes one leg through the proxy.
+ */
+function createGatewayTransport(config) {
+    const doFetch = config.fetchImpl ?? fetch;
+    return {
+        name: "gateway",
+        async execute(request) {
+            const messages = buildMessages(request);
+            const body = {
+                model: config.modelNameFor(request),
+                messages,
+                ...request.params,
+            };
+            let response;
+            try {
+                response = await doFetch(`${config.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${readGatewayKey(config.apiKeyEnv)}`,
+                        ...(request.correlationId === undefined
+                            ? {}
+                            : { "x-correlation-id": request.correlationId }),
+                    },
+                    body: JSON.stringify(body),
+                    signal: request.signal,
+                });
+            }
+            catch (error) {
+                // A transport-level throw means the proxy was never reached. Abort is
+                // re-thrown untouched so the chain's timeout classification stays
+                // accurate rather than being masked as a gateway outage.
+                if (request.signal.aborted) {
+                    throw error;
+                }
+                throw new GatewayUnreachableError(config.baseUrl, error);
+            }
+            if (!response.ok) {
+                throw new GatewayResponseError(response.status, await response.text());
+            }
+            const payload = (await response.json());
+            const choices = payload.choices;
+            const message = choices?.[0]?.message;
+            return {
+                response: parseContent(message?.content, request.responseFormat),
+                usage: readUsage(payload, request),
+                tool_calls: Array.isArray(message?.tool_calls)
+                    ? message.tool_calls
+                    : undefined,
+            };
+        },
+    };
+}
+/**
+ * Compose the message array for a request.
+ *
+ * @param request The request.
+ * @returns Chat messages.
+ */
+function buildMessages(request) {
+    const content = typeof request.content === "string" ? request.content : [...request.content];
+    return [{ role: "user", content }];
+}
+/**
+ * Interpret the model's content according to the requested format.
+ *
+ * A JSON format that does not parse is an error, not an empty object. Returning
+ * a default here would hand the caller a well-typed value that means nothing,
+ * and the failure would surface much later as a decision made on absent data.
+ *
+ * @param content The raw content.
+ * @param responseFormat The format the caller asked for.
+ * @returns The parsed value.
+ */
+function parseContent(content, responseFormat) {
+    const text = typeof content === "string" ? content : "";
+    if (responseFormat === "text") {
+        return text;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`LLM returned content that is not valid JSON for a ${typeof responseFormat === "string" ? responseFormat : "json_schema"} request: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+
+/**
+ * The alias-resolving LLM client.
+ *
+ * This is the only supported way to reach a language model from application
+ * code. Its signature mirrors the incumbent client's — content, response
+ * format, options — so migrating a call site is replacing a model string with
+ * an alias, and nothing else. That similarity is the point: a migration that
+ * required rewriting call sites would be a migration that stalls half-done,
+ * leaving some calls inside the timeout, breaker and fallback controls and
+ * some outside them, which is worse than either end state.
+ *
+ * There is deliberately no way to name a model. PD-5 makes vendor strings a CI
+ * failure in application code, and an option that accepted one would let a call
+ * site opt out of the routing policy without anyone noticing.
+ *
+ * Every call gets, in order: alias resolution against the canonical route
+ * table, per-provider parameter normalisation, a hard per-leg timeout, a
+ * per-route circuit breaker, an ordered fallback chain ending at the closed
+ * incumbent, and — where the caller supplies a validator — one schema-feedback
+ * retry ahead of the chain. None of them is optional, because a control that a
+ * caller can switch off is a control that will be off on the call that needed
+ * it.
+ *
+ * @module llm/alias-client
+ */
+/** Env var naming the gateway's base URL. */
+const GATEWAY_BASE_URL_ENV = "LLM_GATEWAY_BASE_URL";
+/** Env var NAME holding the gateway key. The key itself is never read here. */
+const DEFAULT_GATEWAY_KEY_ENV = "LLM_GATEWAY_API_KEY";
+/** Process-wide breaker registry, so route health is shared across call sites. */
+let breakers = new CircuitBreakerRegistry(routeTable.defaults.circuit_breaker);
+/** Active runtime wiring. */
+let config = {};
+/** Lazily built transports, rebuilt whenever configuration changes. */
+let gatewayTransport = null;
+let directTransport = null;
+/**
+ * Wire the client.
+ *
+ * Called once at process start. Transports are injectable so a consumer can
+ * supply its own instrumented client, and so tests can exercise the chain
+ * without a network — a fallback chain that could only be observed against live
+ * providers would in practice never be observed at all.
+ *
+ * @param next Runtime wiring; unspecified fields fall back to the environment.
+ * @returns void
+ */
+function configureLlmClient(next) {
+    config = { ...next };
+    gatewayTransport = null;
+    directTransport = null;
+    breakers = new CircuitBreakerRegistry(routeTable.defaults.circuit_breaker, next.now);
+}
+/**
+ * Inspect route health.
+ *
+ * @returns The live breaker registry.
+ */
+function llmBreakers() {
+    return breakers;
+}
+/**
+ * Resolve the gateway transport, building it on first use.
+ *
+ * @param chain The chain being served, used to derive each leg's gateway name.
+ * @returns The transport, or null when no gateway is configured.
+ */
+function gatewayFor(chain) {
+    if (config.gatewayTransport !== undefined) {
+        return config.gatewayTransport;
+    }
+    const baseUrl = config.gatewayBaseUrl ?? process.env[GATEWAY_BASE_URL_ENV];
+    if (baseUrl === undefined || baseUrl.length === 0) {
+        return null;
+    }
+    if (gatewayTransport === null) {
+        gatewayTransport = createGatewayTransport({
+            baseUrl,
+            apiKeyEnv: config.gatewayApiKeyEnv ?? DEFAULT_GATEWAY_KEY_ENV,
+            modelNameFor: (request) => gatewayModelNameFor(request.route, chain),
+        });
+    }
+    return gatewayTransport;
+}
+/**
+ * Resolve the degraded direct transport, building it on first use.
+ *
+ * @returns The transport.
+ */
+function directFor() {
+    if (config.directTransport !== undefined) {
+        return config.directTransport;
+    }
+    if (directTransport === null) {
+        directTransport = createDirectTransport({
+            resolveCaller: resolveDefaultDirectCaller,
+        });
+    }
+    return directTransport;
+}
+/**
+ * Prepare each leg, normalising parameters up front.
+ *
+ * Normalisation happens before the walk rather than inside it so a capability
+ * mismatch is known without spending a network round trip on it, and so a leg
+ * that cannot serve the request is recorded as skipped rather than counted
+ * against the provider's health.
+ *
+ * @param chain The resolved chain.
+ * @param options The caller's options.
+ * @param responseFormat The requested response shape.
+ * @param transport The transport to carry every leg.
+ * @returns Prepared legs, in chain order.
+ */
+function prepareLegs(chain, options, responseFormat, transport) {
+    return chain.routes.map((route) => {
+        try {
+            return {
+                route,
+                transport,
+                params: normaliseParams(options, route, responseFormat),
+            };
+        }
+        catch (error) {
+            if (error instanceof UnsupportedCapabilityError) {
+                return { route, transport, params: error };
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Call a language model by semantic alias.
+ *
+ * @param content The prompt, or multi-part content for a vision-capable route.
+ * @param responseFormat The response shape. Defaults to plain text.
+ * @param options Call options; `alias` is required and there is no model option.
+ * @returns The answer, with the routing decision and full attempt record attached.
+ * @throws {UnknownAliasError} When the alias is not in the route table.
+ * @throws {ChainExhaustedError} When no leg produced an answer.
+ * @throws {SchemaRetryExhaustedError} When a validated payload failed twice.
+ */
+async function callLLMByAlias(content, responseFormat = "text", options) {
+    const chain = resolveChain(options.alias, {
+        isolated: options.isolated,
+        timeoutMsOverride: options.timeoutMs,
+    });
+    if (chain.routes.length === 0) {
+        // Nothing is servable. The exclusions say why each leg was unavailable,
+        // which is the difference between an operator reading config and an
+        // operator reading the error.
+        throw new ChainExhaustedError(options.alias, chain.exclusions.map((exclusion) => ({
+            routeKey: `${options.alias}#${exclusion.role}`,
+            role: exclusion.role,
+            provider: exclusion.provider,
+            modelId: "(unresolved)",
+            outcome: "skipped",
+            durationMs: 0,
+            reason: exclusion.reason,
+        })), {
+            prompt_tokens: 0,
+            completion_tokens: 0,
+            provider: "none",
+            model: "none",
+            cost: 0,
+        });
+    }
+    const gateway = gatewayFor(chain);
+    const attemptLog = [];
+    /**
+     * Run the chain, falling back from the gateway to the degraded direct path
+     * only when the gateway itself is unreachable.
+     *
+     * @param prompt The prompt for this attempt.
+     * @returns The transport response and the routing facts about it.
+     */
+    const runOnce = async (prompt) => {
+        const boundContent = prompt;
+        if (gateway !== null) {
+            try {
+                const outcome = await executeChain(options.alias, {
+                    legs: prepareLegs(chain, options, responseFormat, gateway),
+                    content: boundContent,
+                    responseFormat,
+                    breakers,
+                    correlationId: options.correlationId,
+                    callerSignal: options.signal,
+                    now: config.now,
+                    onAttempt: (record) => attemptLog.push(record),
+                });
+                return { ...outcome, degraded: false };
+            }
+            catch (error) {
+                if (!isGatewayOutage(error)) {
+                    throw error;
+                }
+                // The proxy is gone, not a provider behind it. Walking the chain again
+                // through the gateway would repeat the same failure on every leg, so
+                // the degraded path takes over — restricted to the closed incumbent.
+            }
+        }
+        const direct = directFor();
+        const closedLegs = chain.routes.filter((route) => route.provider.tier === "closed");
+        if (closedLegs.length === 0) {
+            throw new ChainExhaustedError(options.alias, attemptLog, {
+                prompt_tokens: 0,
+                completion_tokens: 0,
+                provider: "none",
+                model: "none",
+                cost: 0,
+            });
+        }
+        const outcome = await executeChain(options.alias, {
+            legs: prepareLegs({ ...chain, routes: closedLegs }, options, responseFormat, direct),
+            content: boundContent,
+            responseFormat,
+            breakers,
+            correlationId: options.correlationId,
+            callerSignal: options.signal,
+            now: config.now,
+            onAttempt: (record) => attemptLog.push(record),
+        });
+        return { ...outcome, degraded: true };
+    };
+    if (options.validate === undefined) {
+        const outcome = await runOnce(content);
+        return {
+            response: outcome.response.response,
+            usage: outcome.response.usage,
+            tool_calls: outcome.response.tool_calls,
+            servedBy: outcome.servedBy,
+            attempts: attemptLog,
+            degraded: outcome.degraded,
+            totalUsage: outcome.totalUsage,
+        };
+    }
+    // A validator is only meaningful against a text prompt, because the retry has
+    // to be able to append the validator's complaint to it.
+    if (typeof content !== "string") {
+        throw new Error("a validator requires a string prompt: the feedback retry appends the validator's rejection to the original prompt");
+    }
+    let lastRouting = null;
+    const validated = await callWithValidation({
+        prompt: content,
+        validate: options.validate,
+        call: async (prompt) => {
+            const outcome = await runOnce(prompt);
+            lastRouting = {
+                servedBy: outcome.servedBy,
+                degraded: outcome.degraded,
+                totalUsage: outcome.totalUsage,
+            };
+            return outcome.response;
+        },
+    });
+    if (lastRouting === null) {
+        throw new Error("validated call completed without recording a routing decision");
+    }
+    const routing = lastRouting;
+    return {
+        response: validated.value,
+        usage: validated.response.usage,
+        tool_calls: validated.response.tool_calls,
+        servedBy: routing.servedBy,
+        attempts: attemptLog,
+        degraded: routing.degraded,
+        totalUsage: validated.totalUsage,
+    };
+}
+/**
+ * Whether an error means the gateway itself is gone.
+ *
+ * Only a transport-level failure to reach the proxy qualifies. A provider error
+ * relayed BY the proxy is a normal chain event and must not trigger the
+ * degraded path, or a single flaky provider would quietly move every call onto
+ * the closed incumbent — a fallback the routing policy reserves for last.
+ *
+ * @param error The error to classify.
+ * @returns Whether the gateway is unreachable.
+ */
+function isGatewayOutage(error) {
+    if (error instanceof GatewayUnreachableError) {
+        return true;
+    }
+    if (error instanceof ChainExhaustedError) {
+        return (error.attempts.length > 0 &&
+            error.attempts.every((attempt) => attempt.reason === undefined
+                ? false
+                : attempt.reason.includes("is unreachable")));
+    }
+    return false;
+}
+/**
+ * The aliases application code may name.
+ *
+ * @returns The alias names, sorted.
+ */
+function llmAliases() {
+    return Object.keys(routeTable.aliases).sort();
+}
+
+/**
+ * Streaming normalisation across provider wire formats.
+ *
+ * A caller that streams wants one thing — text as it arrives — but the wire
+ * formats disagree about how to say it. OpenAI-compatible providers emit
+ * server-sent events whose payload nests the increment under
+ * `choices[0].delta.content` and end with a literal `[DONE]` sentinel;
+ * Anthropic emits typed events where the increment is `delta.text` and the end
+ * is an explicit `message_stop`. A consumer written against one shape breaks on
+ * the other, which would make a fallback across providers fail precisely when
+ * the fallback was needed.
+ *
+ * The one behaviour that matters more than the format is how a stream ENDS. A
+ * stream cut short mid-answer looks exactly like a short answer: the consumer
+ * has already received and probably already acted on the text. So a stream
+ * that stops without its terminal event raises rather than returning what it
+ * had — a truncated answer accepted as complete is a wrong answer that nothing
+ * reports.
+ *
+ * @module llm/streaming
+ */
+/** SSE payload that marks the end of an OpenAI-compatible stream. */
+const SSE_DONE_SENTINEL = "[DONE]";
+/** Prefix carrying the payload on an SSE line. */
+const SSE_DATA_PREFIX = "data:";
+/** Anthropic event type carrying a text increment. */
+const ANTHROPIC_DELTA_EVENT = "content_block_delta";
+/** Anthropic event type marking the end of a message. */
+const ANTHROPIC_STOP_EVENT = "message_stop";
+/** Anthropic event type carrying a mid-stream error. */
+const ANTHROPIC_ERROR_EVENT = "error";
+/**
+ * Thrown when a stream ends without its terminal event.
+ *
+ * A distinct type because the caller's correct response differs from a normal
+ * failure: the partial text exists and may be worth logging for diagnosis, but
+ * it must never be treated as the answer.
+ */
+class StreamTruncatedError extends Error {
+    /** Text received before the stream stopped. Present for diagnosis only. */
+    partialText;
+    /**
+     * @param partialText What had arrived when the stream stopped.
+     * @param reason Why it stopped, when known.
+     */
+    constructor(partialText, reason) {
+        super(`LLM stream ended without a terminal event after ${partialText.length} characters: ${reason}. ` +
+            "The partial text is not returned as an answer: a truncated answer accepted as complete is a wrong answer nothing reports.");
+        this.name = "StreamTruncatedError";
+        this.partialText = partialText;
+    }
+}
+/** Thrown when a provider reports an error inside an already-open stream. */
+class StreamProviderError extends Error {
+    /** Text received before the error. */
+    partialText;
+    /**
+     * @param partialText What had arrived when the error appeared.
+     * @param detail The provider's message.
+     */
+    constructor(partialText, detail) {
+        super(`LLM stream failed mid-response: ${detail}`);
+        this.name = "StreamProviderError";
+        this.partialText = partialText;
+    }
+}
+/**
+ * Split a byte stream into complete lines.
+ *
+ * Chunk boundaries fall wherever the network puts them, not on line breaks, so
+ * a partial line is carried across chunks. Parsing each network chunk as if it
+ * were whole would drop or corrupt every event unlucky enough to be split.
+ *
+ * @param source The response body stream.
+ * @returns An async iterable of complete lines.
+ */
+async function* toLines(source) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for await (const chunk of source) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let newline = buffer.indexOf("\n");
+        while (newline !== -1) {
+            yield buffer.slice(0, newline).replace(/\r$/, "");
+            buffer = buffer.slice(newline + 1);
+            newline = buffer.indexOf("\n");
+        }
+    }
+    buffer += decoder.decode();
+    if (buffer.length > 0) {
+        yield buffer;
+    }
+}
+/**
+ * Normalise an OpenAI-compatible SSE stream.
+ *
+ * @param source The response body stream.
+ * @returns Normalised chunks.
+ * @throws {StreamTruncatedError} When the stream ends without `[DONE]`.
+ * @throws {StreamProviderError} When an error event appears mid-stream.
+ */
+async function* normaliseOpenAiStream(source) {
+    let text = "";
+    let sawDone = false;
+    for await (const line of toLines(source)) {
+        if (!line.startsWith(SSE_DATA_PREFIX)) {
+            continue;
+        }
+        const payload = line.slice(SSE_DATA_PREFIX.length).trim();
+        if (payload === SSE_DONE_SENTINEL) {
+            sawDone = true;
+            break;
+        }
+        if (payload.length === 0) {
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(payload);
+        }
+        catch (error) {
+            throw new StreamProviderError(text, `unparseable event: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (event.error !== undefined) {
+            throw new StreamProviderError(text, JSON.stringify(event.error));
+        }
+        const choices = event.choices;
+        const delta = choices?.[0]?.delta?.content;
+        if (typeof delta === "string" && delta.length > 0) {
+            text += delta;
+            yield { delta, text };
+        }
+    }
+    if (!sawDone) {
+        throw new StreamTruncatedError(text, "no [DONE] sentinel was received");
+    }
+}
+/**
+ * Normalise an Anthropic event stream.
+ *
+ * @param source The response body stream.
+ * @returns Normalised chunks.
+ * @throws {StreamTruncatedError} When the stream ends without `message_stop`.
+ * @throws {StreamProviderError} When an error event appears mid-stream.
+ */
+async function* normaliseAnthropicStream(source) {
+    let text = "";
+    let sawStop = false;
+    for await (const line of toLines(source)) {
+        if (!line.startsWith(SSE_DATA_PREFIX)) {
+            continue;
+        }
+        const payload = line.slice(SSE_DATA_PREFIX.length).trim();
+        if (payload.length === 0) {
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(payload);
+        }
+        catch (error) {
+            throw new StreamProviderError(text, `unparseable event: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const type = event.type;
+        if (type === ANTHROPIC_ERROR_EVENT) {
+            throw new StreamProviderError(text, JSON.stringify(event.error ?? event));
+        }
+        if (type === ANTHROPIC_STOP_EVENT) {
+            sawStop = true;
+            break;
+        }
+        if (type === ANTHROPIC_DELTA_EVENT) {
+            const delta = event.delta?.text;
+            if (typeof delta === "string" && delta.length > 0) {
+                text += delta;
+                yield { delta, text };
+            }
+        }
+    }
+    if (!sawStop) {
+        throw new StreamTruncatedError(text, "no message_stop event was received");
+    }
+}
+/**
+ * Normalise a stream according to the wire format its provider speaks.
+ *
+ * Selecting on the route's declared API style rather than sniffing the payload
+ * keeps the decision with the route table, which is the thing that actually
+ * knows which provider is answering.
+ *
+ * @param apiStyle The provider's wire format.
+ * @param source The response body stream.
+ * @returns Normalised chunks, identical in shape across providers.
+ */
+function normaliseStream(apiStyle, source) {
+    return apiStyle === "anthropic"
+        ? normaliseAnthropicStream(source)
+        : normaliseOpenAiStream(source);
+}
+/**
+ * Drain a normalised stream into its complete text.
+ *
+ * @param stream A normalised stream.
+ * @returns The full text.
+ * @throws Whatever the stream raises; a truncated stream never resolves to text.
+ */
+async function collectStream(stream) {
+    let text = "";
+    for await (const chunk of stream) {
+        text = chunk.text;
+    }
+    return text;
+}
+
 /**
  * @module LRUCache
  */
@@ -72035,7 +74793,7 @@ const adaptic = {
     },
     rateLimiter: {
         TokenBucketRateLimiter,
-        limiters: rateLimiters,
+        limiters: rateLimiters$1,
     },
 };
 const adptc = adaptic;
@@ -72070,6 +74828,8 @@ exports.AssetAllocationEngine = AssetAllocationEngine;
 exports.AuthenticationError = AuthenticationError;
 exports.BTC_PAIRS = BTC_PAIRS;
 exports.BarError = BarError;
+exports.ChainExhaustedError = ChainExhaustedError;
+exports.CircuitBreakerRegistry = CircuitBreakerRegistry;
 exports.CircuitOpenError = CircuitOpenError;
 exports.CryptoDataError = CryptoDataError;
 exports.CryptoOrderError = CryptoOrderError;
@@ -72078,7 +74838,10 @@ exports.DEFAULT_RISK_FREE_RATE = DEFAULT_RISK_FREE_RATE;
 exports.DEFAULT_TIMEOUTS = DEFAULT_TIMEOUTS;
 exports.DEFAULT_TRADING_POLICY = DEFAULT_TRADING_POLICY;
 exports.DataFormatError = DataFormatError;
+exports.DirectTransportRefusedError = DirectTransportRefusedError;
 exports.DuplicateClientOrderIdError = DuplicateClientOrderIdError;
+exports.GatewayResponseError = GatewayResponseError;
+exports.GatewayUnreachableError = GatewayUnreachableError;
 exports.HttpClientError = HttpClientError;
 exports.HttpServerError = HttpServerError;
 exports.KEEP_ALIVE_DEFAULTS = KEEP_ALIVE_DEFAULTS;
@@ -72095,13 +74858,18 @@ exports.MassiveTradeZodSchema = MassiveTradeSchema;
 exports.MassiveTradesResponseSchema = MassiveTradesResponseSchema;
 exports.NetworkError = NetworkError;
 exports.NewsError = NewsError;
+exports.NoServableRouteError = NoServableRouteError;
 exports.OptionStrategyError = OptionStrategyError;
 exports.OptionsDataError = OptionsDataError;
 exports.QuoteError = QuoteError;
 exports.RISK_FREE_RATE_TTL_MS = RISK_FREE_RATE_TTL_MS;
+exports.RateGuardTimeoutError = RateGuardTimeoutError;
 exports.RateLimitError = RateLimitError;
 exports.RawMassivePriceDataSchema = RawMassivePriceDataSchema;
+exports.SchemaRetryExhaustedError = SchemaRetryExhaustedError;
 exports.StampedeProtectedCache = StampedeProtectedCache;
+exports.StreamProviderError = StreamProviderError;
+exports.StreamTruncatedError = StreamTruncatedError;
 exports.TRADING_API = TRADING_API;
 exports.TimeoutError = TimeoutError;
 exports.TokenBucketRateLimiter = TokenBucketRateLimiter;
@@ -72110,7 +74878,9 @@ exports.TrailingStopValidationError = TrailingStopValidationError;
 exports.USDC_PAIRS = USDC_PAIRS;
 exports.USDT_PAIRS = USDT_PAIRS;
 exports.USD_PAIRS = USD_PAIRS;
+exports.UnknownAliasError = UnknownAliasError;
 exports.UnsupportedBrokerError = UnsupportedBrokerError;
+exports.UnsupportedCapabilityError = UnsupportedCapabilityError;
 exports.ValidationError = ValidationError;
 exports.ValidationResponseError = ValidationResponseError;
 exports.WEBSOCKET_STREAMS = WEBSOCKET_STREAMS;
@@ -72125,6 +74895,7 @@ exports.atr = atrNs;
 exports.bracketOrders = bracketOrders;
 exports.buildOCCSymbol = buildOCCSymbol;
 exports.buildOptionSymbol = buildOptionSymbol;
+exports.buildRetryPrompt = buildRetryPrompt;
 exports.buyCryptoNotional = buyCryptoNotional;
 exports.buyToClose = buyToClose;
 exports.buyToOpen = buyToOpen;
@@ -72135,6 +74906,8 @@ exports.calculateOrderValue = calculateOrderValue;
 exports.calculatePeriodPerformance = calculatePeriodPerformance;
 exports.calculatePutCallRatio = calculatePutCallRatio;
 exports.calculateTotalFilledValue = calculateTotalFilledValue;
+exports.callLLMByAlias = callLLMByAlias;
+exports.callWithValidation = callWithValidation;
 exports.cancelAllCryptoOrders = cancelAllCryptoOrders;
 exports.cancelOCOOrder = cancelOCOOrder;
 exports.cancelOTOOrder = cancelOTOOrder;
@@ -72145,6 +74918,9 @@ exports.clearClientCache = clearClientCache;
 exports.clock = clock;
 exports.closeAllOptionPositions = closeAllOptionPositions;
 exports.closeOptionPosition = closeOptionPosition;
+exports.closedIncumbentLeg = closedIncumbentLeg;
+exports.collectStream = collectStream;
+exports.configureLlmClient = configureLlmClient;
 exports.createAlpacaClient = createAlpacaClient;
 exports.createAlpacaMarketDataAPI = createAlpacaMarketDataAPI;
 exports.createAlpacaTradingAPI = createAlpacaTradingAPI;
@@ -72158,7 +74934,9 @@ exports.createCryptoMarketOrder = createCryptoMarketOrder;
 exports.createCryptoOrder = createCryptoOrder;
 exports.createCryptoStopLimitOrder = createCryptoStopLimitOrder;
 exports.createCryptoStopOrder = createCryptoStopOrder;
+exports.createDirectTransport = createDirectTransport;
 exports.createExecutorFromTradingAPI = createExecutorFromTradingAPI;
+exports.createGatewayTransport = createGatewayTransport;
 exports.createIronCondor = createIronCondor$1;
 exports.createIronCondorAdvanced = createIronCondor;
 exports.createMultiLegOptionOrder = createMultiLegOptionOrder;
@@ -72192,6 +74970,7 @@ exports.findNearestExpiration = findNearestExpiration;
 exports.findOptionsByDelta = findOptionsByDelta;
 exports.formatOrderForLog = formatOrderForLog;
 exports.formatOrderSummary = formatOrderSummary;
+exports.gatewayModelNameFor = gatewayModelNameFor;
 exports.generateOptimalAllocation = generateOptimalAllocation;
 exports.getAccountConfiguration = getAccountConfiguration;
 exports.getAccountDetails = getAccountDetails;
@@ -72278,6 +75057,7 @@ exports.getTradingWebSocketUrl = getTradingWebSocketUrl;
 exports.getTrailingStopHWM = getTrailingStopHWM;
 exports.groupOrdersByStatus = groupOrdersByStatus;
 exports.groupOrdersBySymbol = groupOrdersBySymbol;
+exports.guardSnapshots = guardSnapshots;
 exports.hasActiveTrailingStop = hasActiveTrailingStop;
 exports.hasOptionLiquidity = hasGoodLiquidity;
 exports.hasStockLiquidity = hasGoodLiquidity$1;
@@ -72299,21 +75079,37 @@ exports.isSupportedCryptoPair = isSupportedCryptoPair;
 exports.isTransientNetworkError = isTransientNetworkError;
 exports.legacyApi = index$1;
 exports.limitBuyWithTakeProfit = limitBuyWithTakeProfit;
+exports.limitsFor = limitsFor;
+exports.limitsInventory = limitsInventory;
+exports.listAliases = listAliases;
+exports.llmAliases = llmAliases;
+exports.llmBreakers = llmBreakers;
+exports.normaliseAnthropicStream = normaliseAnthropicStream;
+exports.normaliseOpenAiStream = normaliseOpenAiStream;
+exports.normaliseParams = normaliseParams;
+exports.normaliseStream = normaliseStream;
 exports.ocoOrders = ocoOrders;
 exports.orderUtils = orderUtils;
+exports.orderedRoutes = orderedRoutes;
 exports.otoOrders = otoOrders;
 exports.paginate = paginate;
 exports.paginateAll = paginateAll;
 exports.parseOCCSymbol = parseOCCSymbol;
 exports.protectLongPosition = protectLongPosition;
 exports.protectShortPosition = protectShortPosition;
-exports.rateLimiters = rateLimiters;
+exports.rateLimiters = rateLimiters$1;
 exports.resetLogger = resetLogger;
+exports.resetProviderGuards = resetProviderGuards;
 exports.resetRiskFreeRateCache = resetRiskFreeRateCache;
+exports.resolveChain = resolveChain;
+exports.resolveDefaultDirectCaller = resolveDefaultDirectCaller;
 exports.risk = riskNs;
 exports.rollOptionPosition = rollOptionPosition;
 exports.roundPriceForAlpaca = roundPriceForAlpaca$3;
 exports.roundPriceForAlpacaNumber = roundPriceForAlpacaNumber;
+exports.routeKeyFor = routeKeyFor;
+exports.routeSupports = routeSupports;
+exports.routeTable = routeTable;
 exports.safeValidateResponse = safeValidateResponse;
 exports.searchNews = searchNews;
 exports.sellAllCrypto = sellAllCrypto;
@@ -72325,6 +75121,7 @@ exports.setRiskFreeRate = setRiskFreeRate;
 exports.shortWithStopLoss = shortWithStopLoss;
 exports.sortOrdersByDate = sortOrdersByDate;
 exports.strategy = strategyNs;
+exports.sumUsage = sumUsage;
 exports.tradingPolicy = index;
 exports.trailingStops = trailingStops;
 exports.updateAccountConfiguration = updateAccountConfiguration;
@@ -72337,6 +75134,7 @@ exports.validateResponse = validateResponse;
 exports.verifyFetchKeepAlive = verifyFetchKeepAlive;
 exports.volatility = volatilityNs;
 exports.waitForOrderFill = waitForOrderFill;
+exports.withProviderGuards = withProviderGuards;
 exports.withRetry = withRetry;
 exports.withTimeout = withTimeout;
 //# sourceMappingURL=index.cjs.map