@juno-ai/bind 1.0.0

package/routing/errors.js

@@ -0,0 +1,141 @@
+const PROPAGATE = Object.freeze({
+    sameEndpointRetry: false,
+    nextProvider: false,
+    fallbackModel: false,
+    breaker: "none",
+    propagate: true,
+});
+const DEFECT = Object.freeze({
+    sameEndpointRetry: true,
+    nextProvider: true,
+    fallbackModel: true,
+    breaker: "record_failure",
+    propagate: false,
+});
+const RETRIABLE_TRANSPORT = Object.freeze({
+    sameEndpointRetry: false,
+    nextProvider: true,
+    fallbackModel: true,
+    breaker: "record_failure",
+    propagate: false,
+});
+/**
+ * Request-shaped rejections (a 400, a moderation refusal): another provider
+ * may accept the request, so traverse — but the ENDPOINT is healthy, so the
+ * breaker must not count it. Otherwise one tenant's malformed/flagged prompt
+ * degrades the shared endpoint for everyone (see PRD §7.2).
+ */
+const REQUEST_SHAPED = Object.freeze({
+    sameEndpointRetry: false,
+    nextProvider: true,
+    fallbackModel: true,
+    breaker: "none",
+    propagate: false,
+});
+const CREDENTIAL_FAILURE = Object.freeze({
+    sameEndpointRetry: false,
+    nextProvider: true,
+    fallbackModel: true,
+    breaker: "open_immediately",
+    propagate: false,
+});
+/**
+ * The exhaustive failure → routing-behavior matrix (PRD §7.1). Pure; the
+ * executor applies it, the circuit breaker consumes its `breaker` effect.
+ */
+export function failureDisposition(error) {
+    switch (error.kind) {
+        case "aborted":
+            return PROPAGATE;
+        case "completion_defect":
+            return DEFECT;
+        case "network":
+            return RETRIABLE_TRANSPORT;
+        case "http":
+            switch (error.category) {
+                case "timeout":
+                case "rate_limit":
+                case "server_error":
+                    return RETRIABLE_TRANSPORT;
+                case "provider_bad_request":
+                    return REQUEST_SHAPED;
+                case "credential":
+                case "credits":
+                    return CREDENTIAL_FAILURE;
+                case "client_error":
+                    return PROPAGATE;
+                default: {
+                    const _exhaustive = error.category;
+                    throw new Error(`unknown http category: ${JSON.stringify(_exhaustive)}`);
+                }
+            }
+        default: {
+            const _exhaustive = error;
+            throw new Error(`unknown attempt error: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Default HTTP status → category mapping. A transport may override per
+ * provider (e.g. OpenRouter reports credit exhaustion as 402; another
+ * provider may use 403 with a body marker) — this is only the neutral
+ * baseline.
+ */
+export function categorizeHttpStatus(statusCode) {
+    if (statusCode === 408)
+        return "timeout";
+    if (statusCode === 429)
+        return "rate_limit";
+    if (statusCode >= 500)
+        return "server_error";
+    if (statusCode === 401 || statusCode === 403)
+        return "credential";
+    if (statusCode === 402)
+        return "credits";
+    if (statusCode === 400)
+        return "provider_bad_request";
+    return "client_error";
+}
+/**
+ * Whether a FRESH ATTEMPT LATER could plausibly succeed — the caller-facing
+ * "retriable" used to pick the most useful error when a whole plan fails
+ * (PRD §5.2 step 6: prefer a retriable primary-path error over a
+ * non-retriable stale fallback binding, so the host's queue-level retry
+ * still fires).
+ *
+ * Deliberately NOT the same notion as route-traversal eligibility: a
+ * provider-specific 400 traverses to the next provider (a different provider
+ * may accept the request shape — `failureDisposition`), but retrying the
+ * same exhausted plan later won't fix it, so it is not caller-retriable.
+ * Credential/credit failures likewise traverse but need operator action, not
+ * time.
+ */
+export function isRetriableAttemptError(error) {
+    switch (error.kind) {
+        case "aborted":
+            return false;
+        case "completion_defect":
+        case "network":
+            return true;
+        case "http":
+            switch (error.category) {
+                case "timeout":
+                case "rate_limit":
+                case "server_error":
+                    return true;
+                case "provider_bad_request":
+                case "credential":
+                case "credits":
+                case "client_error":
+                    return false;
+                default: {
+                    const _exhaustive = error.category;
+                    throw new Error(`unknown http category: ${JSON.stringify(_exhaustive)}`);
+                }
+            }
+        default: {
+            const _exhaustive = error;
+            throw new Error(`unknown attempt error: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}

package/routing/executor.d.ts

@@ -0,0 +1,64 @@
+import type { RouteCandidate, RoutePlan } from "./plan";
+import { type InferenceAttemptError, type RouteAttemptCursor } from "./errors";
+import type { RouteCircuitBreaker } from "./circuit-breaker";
+export type AttemptOutcome<T> = Readonly<{
+    kind: "success";
+    value: T;
+}> | Readonly<{
+    kind: "failure";
+    error: InferenceAttemptError;
+}>;
+/**
+ * One provider request. The host's transport adapter performs the network
+ * call, measures duration, and classifies any failure into
+ * `InferenceAttemptError` (transports classify facts; the executor owns
+ * route order — PRD §7.1).
+ */
+export type AttemptFn<T> = (candidate: RouteCandidate, cursor: RouteAttemptCursor) => Promise<AttemptOutcome<T>>;
+export type FallbackKind = "none" | "provider" | "model" | "provider_and_model";
+export interface ExecutePlanOptions<T> {
+    readonly plan: RoutePlan;
+    readonly attempt: AttemptFn<T>;
+    /** Stamped into cursors; the caller owns structured-output retry loops. */
+    readonly structuredOutputAttempt?: number;
+    /** Same-endpoint retry budget for completion defects. Default 2 (PRD §5.2). */
+    readonly completionDefectRetries?: number;
+    /** Optional per-endpoint circuit breaker (PRD §7.2). */
+    readonly breaker?: RouteCircuitBreaker | null;
+}
+export type RouteExecutionResult<T> = Readonly<{
+    ok: true;
+    value: T;
+    served: RouteCandidate;
+    cursor: RouteAttemptCursor;
+    fallbackKind: FallbackKind;
+    attemptCount: number;
+    failures: readonly InferenceAttemptError[];
+}> | Readonly<{
+    ok: false;
+    reason: "no_viable_endpoints";
+    attemptCount: 0;
+    failures: readonly [];
+}> | Readonly<{
+    ok: false;
+    reason: "attempts_exhausted";
+    error: InferenceAttemptError;
+    attemptCount: number;
+    failures: readonly InferenceAttemptError[];
+}>;
+/**
+ * Drive one structured-output attempt over a frozen route plan with the
+ * normative loop nesting (PRD §5.2): model stage → provider candidate →
+ * same-endpoint retry. Pure with respect to I/O — every request goes through
+ * `attempt`, every clock read through the injected breaker.
+ */
+export declare function executeRoutePlan<T>(options: ExecutePlanOptions<T>): Promise<RouteExecutionResult<T>>;
+/**
+ * Derive the fallback classification from an attempt cursor — the single
+ * shared derivation for hosts that attribute per-attempt (e.g. inference
+ * logging inside a transport adapter) before the executor returns.
+ */
+export declare function fallbackKindOfCursor(cursor: {
+    readonly stageIndex: number;
+    readonly candidateIndex: number;
+}): FallbackKind;

package/routing/executor.js

@@ -0,0 +1,173 @@
+import { failureDisposition, isRetriableAttemptError, } from "./errors";
+/**
+ * Drive one structured-output attempt over a frozen route plan with the
+ * normative loop nesting (PRD §5.2): model stage → provider candidate →
+ * same-endpoint retry. Pure with respect to I/O — every request goes through
+ * `attempt`, every clock read through the injected breaker.
+ */
+export async function executeRoutePlan(options) {
+    const structuredOutputAttempt = options.structuredOutputAttempt ?? 0;
+    const defectRetries = options.completionDefectRetries ?? 2;
+    const breaker = options.breaker ?? null;
+    const failures = [];
+    let attemptCount = 0;
+    let anyCandidateSeen = false;
+    for (let stageIndex = 0; stageIndex < options.plan.stages.length; stageIndex++) {
+        const stage = options.plan.stages[stageIndex];
+        if (stage === undefined)
+            continue;
+        for (let candidateIndex = 0; candidateIndex < stage.candidates.length; candidateIndex++) {
+            const candidate = stage.candidates[candidateIndex];
+            if (candidate === undefined)
+                continue;
+            anyCandidateSeen = true;
+            const breakerKey = {
+                providerId: candidate.providerId,
+                invocationModel: candidate.providerInvocationModel,
+                credentialSource: candidate.credentialSource,
+                credentialScope: candidate.breakerScope,
+            };
+            let halfOpenProbe = false;
+            if (breaker !== null) {
+                const admission = breaker.admit(breakerKey);
+                if (!admission.admitted)
+                    continue;
+                halfOpenProbe = admission.halfOpenProbe;
+            }
+            for (let endpointAttempt = 0; endpointAttempt <= defectRetries; endpointAttempt++) {
+                const cursor = Object.freeze({
+                    structuredOutputAttempt,
+                    stageIndex,
+                    candidateIndex,
+                    endpointAttempt,
+                });
+                attemptCount += 1;
+                const outcome = await options.attempt(candidate, cursor);
+                if (outcome.kind === "success") {
+                    breaker?.recordSuccess(breakerKey);
+                    return {
+                        ok: true,
+                        value: outcome.value,
+                        served: candidate,
+                        cursor,
+                        fallbackKind: fallbackKindFor(stage.kind, candidateIndex),
+                        attemptCount,
+                        failures,
+                    };
+                }
+                failures.push(outcome.error);
+                const disposition = failureDisposition(outcome.error);
+                switch (disposition.breaker) {
+                    case "none":
+                        // A breaker-invisible failure (abort, propagated client error)
+                        // must still resolve a half-open probe, or the probe slot stays
+                        // occupied forever and the endpoint is refused until restart.
+                        if (halfOpenProbe)
+                            breaker?.releaseProbe(breakerKey);
+                        break;
+                    case "record_failure":
+                        breaker?.recordFailure(breakerKey, {
+                            retryAfterMs: retryAfterOf(outcome.error),
+                        });
+                        break;
+                    case "open_immediately":
+                        breaker?.recordFailure(breakerKey, {
+                            openImmediately: true,
+                            retryAfterMs: retryAfterOf(outcome.error),
+                        });
+                        break;
+                    default: {
+                        const _exhaustive = disposition.breaker;
+                        throw new Error(`unknown breaker effect: ${JSON.stringify(_exhaustive)}`);
+                    }
+                }
+                if (disposition.propagate) {
+                    return {
+                        ok: false,
+                        reason: "attempts_exhausted",
+                        error: outcome.error,
+                        attemptCount,
+                        failures,
+                    };
+                }
+                if (disposition.sameEndpointRetry && endpointAttempt < defectRetries) {
+                    continue; // consume the same-endpoint defect budget
+                }
+                // ANTICIPATORY: unreachable under the current disposition matrix
+                // (every non-propagating disposition traverses fully — pinned by the
+                // matrix-invariant test in errors.test.ts). Kept so a future
+                // asymmetric disposition is honored without an executor change.
+                if (!disposition.nextProvider) {
+                    // The disposition matrix forbids trying another provider for this
+                    // model; move (at most) into the fallback-model stage.
+                    if (!disposition.fallbackModel) {
+                        const error = preferredFinalError(failures, options.plan.stages.length);
+                        if (error !== null) {
+                            return { ok: false, reason: "attempts_exhausted", error, attemptCount, failures };
+                        }
+                    }
+                    candidateIndex = stage.candidates.length; // exit the candidate loop
+                }
+                if (!disposition.fallbackModel) {
+                    stageIndex = options.plan.stages.length; // no fallback-model traversal
+                }
+                break; // leave the same-endpoint retry loop
+            }
+        }
+    }
+    if (!anyCandidateSeen && failures.length === 0) {
+        return { ok: false, reason: "no_viable_endpoints", attemptCount: 0, failures: [] };
+    }
+    const error = preferredFinalError(failures, options.plan.stages.length);
+    if (error === null) {
+        // Candidates existed but every one was skipped by the breaker.
+        return { ok: false, reason: "no_viable_endpoints", attemptCount: 0, failures: [] };
+    }
+    return { ok: false, reason: "attempts_exhausted", error, attemptCount, failures };
+}
+/**
+ * Derive the fallback classification from an attempt cursor — the single
+ * shared derivation for hosts that attribute per-attempt (e.g. inference
+ * logging inside a transport adapter) before the executor returns.
+ */
+export function fallbackKindOfCursor(cursor) {
+    if (cursor.stageIndex > 0) {
+        return cursor.candidateIndex > 0 ? "provider_and_model" : "model";
+    }
+    return cursor.candidateIndex > 0 ? "provider" : "none";
+}
+function fallbackKindFor(stageKind, candidateIndex) {
+    const providerFallback = candidateIndex > 0;
+    switch (stageKind) {
+        case "primary":
+            return providerFallback ? "provider" : "none";
+        case "fallback_model":
+            return providerFallback ? "provider_and_model" : "model";
+        default: {
+            const _exhaustive = stageKind;
+            throw new Error(`unknown stage kind: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+function retryAfterOf(error) {
+    return error.kind === "http" ? error.retryAfterMs : null;
+}
+/**
+ * PRD §5.2 step 6: when everything failed, prefer a retriable primary-stage
+ * error over a non-retriable error from the fallback stage (a stale fallback
+ * binding must not mask the actionable primary failure); otherwise report the
+ * final classified failure.
+ */
+function preferredFinalError(failures, stageCount) {
+    const last = failures.at(-1);
+    if (last === undefined)
+        return null;
+    if (stageCount < 2)
+        return last;
+    if (isRetriableAttemptError(last))
+        return last;
+    if (last.target.cursor.stageIndex === 0)
+        return last;
+    const primaryRetriable = failures.find((failure) => failure.target.cursor.stageIndex === 0 && isRetriableAttemptError(failure));
+    return primaryRetriable ?? last;
+}

package/routing/index.d.ts

@@ -0,0 +1,9 @@
+export { canonicalModelIdSchema, providerIdSchema, type CanonicalModelId, type ProviderId, } from "./canonical-model";
+export { ROUTE_POLICY_VERSION, providerPolicySchema, modelRouteRegistrySchema, parseModelRouteRegistry, resolveProviderPolicy, policyProviderOrder, type RoutePolicyVersion, type ProviderPolicy, type ModelRouteRegistry, } from "./policy";
+export { INFERENCE_CAPABILITIES, planIsEmpty, type InferenceCapability, type CredentialSource, type InferenceRequirements, type CachedTokenSemantics, type ProviderPricingBasis, type RouteCandidate, type RouteStage, type RoutePlan, type RouteSkip, } from "./plan";
+export { type TransportAvailability, type CandidateResolution, type PlannerTransport, } from "./transport";
+export { buildRoutePlan, type RoutePlanRequest, type RoutePlanResult } from "./planner";
+export { fallbackKindOfCursor } from "./executor";
+export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, type RouteAttemptCursor, type AttemptTarget, type HttpFailureCategory, type InferenceAttemptError, type FailureDisposition, type BreakerEffect, } from "./errors";
+export { createCircuitBreaker, type BreakerKey, type CircuitBreakerOptions, type EndpointAdmission, type RecordFailureOptions, type RouteCircuitBreaker, } from "./circuit-breaker";
+export { executeRoutePlan, type AttemptOutcome, type AttemptFn, type FallbackKind, type ExecutePlanOptions, type RouteExecutionResult, } from "./executor";

package/routing/index.js

@@ -0,0 +1,9 @@
+export { canonicalModelIdSchema, providerIdSchema, } from "./canonical-model";
+export { ROUTE_POLICY_VERSION, providerPolicySchema, modelRouteRegistrySchema, parseModelRouteRegistry, resolveProviderPolicy, policyProviderOrder, } from "./policy";
+export { INFERENCE_CAPABILITIES, planIsEmpty, } from "./plan";
+export {} from "./transport";
+export { buildRoutePlan } from "./planner";
+export { fallbackKindOfCursor } from "./executor";
+export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, } from "./errors";
+export { createCircuitBreaker, } from "./circuit-breaker";
+export { executeRoutePlan, } from "./executor";

package/routing/plan.d.ts

@@ -0,0 +1,98 @@
+import type { CanonicalModelId, ProviderId } from "./canonical-model";
+import type { ProviderPolicy, RoutePolicyVersion } from "./policy";
+/**
+ * Capabilities the planner checks before any network request (LLM Provider
+ * Routing PRD §5.1/§5.3). `max_completion_tokens` is modeled as a capability
+ * (a departure from the PRD draft, which listed the token-ceiling check in
+ * §5.3 prose but not in the union) so a ceiling violation produces the same
+ * `unsupported_capability` skip shape as any other mismatch.
+ */
+export declare const INFERENCE_CAPABILITIES: readonly ["chat_completions", "streaming", "tools", "structured_outputs", "image_input", "reasoning_effort", "file_parser_plugin", "service_tier", "max_completion_tokens"];
+export type InferenceCapability = (typeof INFERENCE_CAPABILITIES)[number];
+export type CredentialSource = "platform" | "tenant";
+export interface InferenceRequirements {
+    readonly capabilities: ReadonlySet<InferenceCapability>;
+    readonly requestedMaxCompletionTokens: number | null;
+}
+/**
+ * How a provider reports cached input tokens relative to `prompt_tokens`:
+ * `"subset"` — cached tokens are included in the prompt count (OpenAI);
+ * `"disjoint"` — cached tokens are reported alongside it and may exceed it
+ * (observed live on Grok served through Azure AI Foundry). Declared per
+ * binding, never inferred from the relative counts — a disjoint provider can
+ * legitimately report cached < prompt, which inference would misprice.
+ */
+export type CachedTokenSemantics = "subset" | "disjoint";
+export type ProviderPricingBasis = Readonly<{
+    kind: "provider_reported";
+}> | Readonly<{
+    kind: "configured_token_rates";
+    inputUsdPerM: number;
+    cachedInputUsdPerM: number;
+    outputUsdPerM: number;
+    cachedTokenSemantics: CachedTokenSemantics;
+}>;
+/**
+ * One concrete endpoint the executor may attempt. Secret-free by contract:
+ * no client, API key, base URL, prompt, or tenant secret — safe to inspect
+ * in tests and structured diagnostics (PRD §5.1).
+ */
+export interface RouteCandidate {
+    readonly providerId: ProviderId;
+    readonly canonicalModelId: CanonicalModelId;
+    readonly providerInvocationModel: string;
+    readonly credentialSource: CredentialSource;
+    readonly creditEligible: boolean;
+    readonly capabilities: ReadonlySet<InferenceCapability>;
+    /** null means the binding publishes no provider-side completion limit. */
+    readonly maxCompletionTokens: number | null;
+    readonly pricingBasis: ProviderPricingBasis;
+    /** Stable hash/version of non-secret binding data for diagnostics. */
+    readonly bindingFingerprint: string;
+    /**
+     * Optional non-secret credential identity used to scope circuit-breaker
+     * state beyond `credentialSource` (e.g. an opaque per-tenant tag for BYOK
+     * keys, so one tenant's revoked key never opens the circuit for other
+     * tenants). Never key material.
+     */
+    readonly breakerScope?: string;
+}
+export interface RouteStage {
+    readonly kind: "primary" | "fallback_model";
+    readonly canonicalModelId: CanonicalModelId;
+    readonly policy: ProviderPolicy;
+    readonly candidates: readonly RouteCandidate[];
+}
+/**
+ * The immutable, versioned route plan built once per logical call and reused
+ * across structured-output retries (PRD §5.1). Contains no secrets and no
+ * request content.
+ */
+export interface RoutePlan {
+    readonly policyVersion: RoutePolicyVersion;
+    readonly requirements: InferenceRequirements;
+    readonly stages: readonly RouteStage[];
+}
+/**
+ * A capability/configuration omission recorded at plan time. Skips are
+ * planner diagnostics, not failed network attempts (PRD §7.1); `reason` is a
+ * controlled internal string, never a raw provider/parser message.
+ */
+export type RouteSkip = Readonly<{
+    kind: "transport_unavailable";
+    providerId: ProviderId;
+    canonicalModelId: CanonicalModelId;
+    reason: string;
+}> | Readonly<{
+    kind: "unsupported_capability";
+    providerId: ProviderId;
+    canonicalModelId: CanonicalModelId;
+    capability: InferenceCapability;
+}> | Readonly<{
+    kind: "invalid_binding";
+    providerId: ProviderId;
+    canonicalModelId: CanonicalModelId;
+    reason: string;
+}>;
+/** True when no stage has an attemptable candidate. */
+export declare function planIsEmpty(plan: RoutePlan): boolean;

package/routing/plan.js

@@ -0,0 +1,22 @@
+/**
+ * Capabilities the planner checks before any network request (LLM Provider
+ * Routing PRD §5.1/§5.3). `max_completion_tokens` is modeled as a capability
+ * (a departure from the PRD draft, which listed the token-ceiling check in
+ * §5.3 prose but not in the union) so a ceiling violation produces the same
+ * `unsupported_capability` skip shape as any other mismatch.
+ */
+export const INFERENCE_CAPABILITIES = [
+    "chat_completions",
+    "streaming",
+    "tools",
+    "structured_outputs",
+    "image_input",
+    "reasoning_effort",
+    "file_parser_plugin",
+    "service_tier",
+    "max_completion_tokens",
+];
+/** True when no stage has an attemptable candidate. */
+export function planIsEmpty(plan) {
+    return plan.stages.every((stage) => stage.candidates.length === 0);
+}

package/routing/planner.d.ts

@@ -0,0 +1,36 @@
+import type { CanonicalModelId, ProviderId } from "./canonical-model";
+import { type ProviderPolicy } from "./policy";
+import type { InferenceRequirements, RoutePlan, RouteSkip } from "./plan";
+import type { PlannerTransport } from "./transport";
+export interface RoutePlanRequest {
+    readonly primaryModel: CanonicalModelId;
+    /** A distinct fallback canonical model, or null. Equal to primary is ignored. */
+    readonly fallbackModel: CanonicalModelId | null;
+    readonly requirements: InferenceRequirements;
+    /**
+     * Policy resolution per canonical model — typically
+     * `resolveProviderPolicy(registry, model, boundProviders)` partially
+     * applied by the host. Injected as a function so the planner never reads
+     * configuration itself.
+     */
+    readonly policyFor: (model: CanonicalModelId) => ProviderPolicy;
+    /**
+     * Composed transport registry. Map lookup by the provider ids the policy
+     * names — registration/iteration order never determines priority
+     * (PRD §4.3).
+     */
+    readonly transports: ReadonlyMap<ProviderId, PlannerTransport>;
+}
+export interface RoutePlanResult {
+    readonly plan: RoutePlan;
+    /** Configuration/capability omissions recorded while planning (PRD §7.1). */
+    readonly skips: readonly RouteSkip[];
+}
+/**
+ * Deterministically expand a canonical primary/fallback selection into an
+ * immutable, ordered route plan (LLM Provider Routing PRD §5.1). The only
+ * ordering inputs are the two model stages and each stage's policy provider
+ * order. Identical `(provider, invocation model)` endpoints are de-duplicated
+ * across the whole plan, first occurrence wins.
+ */
+export declare function buildRoutePlan(request: RoutePlanRequest): RoutePlanResult;

package/routing/planner.js

@@ -0,0 +1,102 @@
+import { ROUTE_POLICY_VERSION, policyProviderOrder, } from "./policy";
+/**
+ * Deterministically expand a canonical primary/fallback selection into an
+ * immutable, ordered route plan (LLM Provider Routing PRD §5.1). The only
+ * ordering inputs are the two model stages and each stage's policy provider
+ * order. Identical `(provider, invocation model)` endpoints are de-duplicated
+ * across the whole plan, first occurrence wins.
+ */
+export function buildRoutePlan(request) {
+    const skips = [];
+    const seenEndpoints = new Set();
+    const stageModels = request.fallbackModel !== null && request.fallbackModel !== request.primaryModel
+        ? [
+            { kind: "primary", model: request.primaryModel },
+            { kind: "fallback_model", model: request.fallbackModel },
+        ]
+        : [{ kind: "primary", model: request.primaryModel }];
+    const stages = [];
+    for (const { kind, model } of stageModels) {
+        const policy = request.policyFor(model);
+        const candidates = [];
+        for (const providerId of policyProviderOrder(policy)) {
+            const transport = request.transports.get(providerId);
+            if (transport === undefined) {
+                skips.push({
+                    kind: "transport_unavailable",
+                    providerId,
+                    canonicalModelId: model,
+                    reason: "no transport registered for provider",
+                });
+                continue;
+            }
+            const availability = transport.getAvailability();
+            if (!availability.available) {
+                skips.push({
+                    kind: "transport_unavailable",
+                    providerId,
+                    canonicalModelId: model,
+                    reason: availability.reason,
+                });
+                continue;
+            }
+            const resolution = transport.resolveCandidate(model, request.requirements);
+            switch (resolution.kind) {
+                case "unserved":
+                    continue;
+                case "skip":
+                    skips.push(resolution.skip);
+                    continue;
+                case "candidate":
+                    break;
+                default: {
+                    const _exhaustive = resolution;
+                    throw new Error(`unknown resolution: ${JSON.stringify(_exhaustive)}`);
+                }
+            }
+            const candidate = resolution.candidate;
+            const missing = capabilityGaps(candidate, request.requirements);
+            if (missing.length > 0) {
+                for (const capability of missing) {
+                    skips.push({
+                        kind: "unsupported_capability",
+                        providerId,
+                        canonicalModelId: model,
+                        capability,
+                    });
+                }
+                continue;
+            }
+            const endpointKey = `${candidate.providerId}\u0000${candidate.providerInvocationModel}`;
+            if (seenEndpoints.has(endpointKey))
+                continue;
+            seenEndpoints.add(endpointKey);
+            candidates.push(Object.freeze(candidate));
+        }
+        stages.push(Object.freeze({
+            kind,
+            canonicalModelId: model,
+            policy,
+            candidates: Object.freeze(candidates),
+        }));
+    }
+    const plan = Object.freeze({
+        policyVersion: ROUTE_POLICY_VERSION,
+        requirements: request.requirements,
+        stages: Object.freeze(stages),
+    });
+    return { plan, skips: Object.freeze(skips) };
+}
+function capabilityGaps(candidate, requirements) {
+    const missing = [];
+    for (const capability of requirements.capabilities) {
+        if (!candidate.capabilities.has(capability))
+            missing.push(capability);
+    }
+    if (requirements.requestedMaxCompletionTokens !== null &&
+        candidate.maxCompletionTokens !== null &&
+        requirements.requestedMaxCompletionTokens > candidate.maxCompletionTokens) {
+        missing.push("max_completion_tokens");
+    }
+    return missing;
+}