@juno-ai/bind 1.0.0

package/routing/policy.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { type CanonicalModelId, type ProviderId } from "./canonical-model";
+/**
+ * Policy order and semantics are versioned; the version string travels into
+ * telemetry (LLM Provider Routing PRD §4.2) so a routing-behavior change is
+ * distinguishable from a configuration change after the fact.
+ */
+export declare const ROUTE_POLICY_VERSION = "provider-router-v1";
+export type RoutePolicyVersion = typeof ROUTE_POLICY_VERSION;
+/**
+ * `ordered` tries each listed provider in order, skipping unavailable or
+ * incapable endpoints. `only` is a hard fence: the marked canonical model is
+ * never attempted through another provider. A separately configured fallback
+ * model still expands under its own policy (PRD §4.2).
+ */
+export declare const providerPolicySchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    mode: z.ZodLiteral<"ordered">;
+    providers: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ProviderId", "out">>;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    mode: z.ZodLiteral<"only">;
+    provider: z.core.$ZodBranded<z.ZodString, "ProviderId", "out">;
+}, z.core.$strict>>], "mode">;
+export type ProviderPolicy = z.infer<typeof providerPolicySchema>;
+/**
+ * The checked-in route registry. It contains policy only — never endpoints,
+ * deployment names, credentials, prices, quota, or tenant-specific values.
+ *
+ * Naming note: the PRD draft called the bound default `azureBoundDefault`.
+ * The harness is provider-agnostic, so the registry generalizes it to
+ * `boundDefault`, applied when the host reports at least one provider
+ * binding for the model (see `resolveProviderPolicy`).
+ */
+export declare const modelRouteRegistrySchema: z.ZodReadonly<z.ZodObject<{
+    version: z.ZodLiteral<"provider-router-v1">;
+    /** Used when a model has no explicit policy and no provider binding. */
+    unboundDefault: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+        mode: z.ZodLiteral<"ordered">;
+        providers: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ProviderId", "out">>;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+        mode: z.ZodLiteral<"only">;
+        provider: z.core.$ZodBranded<z.ZodString, "ProviderId", "out">;
+    }, z.core.$strict>>], "mode">;
+    /** Used when a model has no explicit policy but has ≥1 provider binding. */
+    boundDefault: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+        mode: z.ZodLiteral<"ordered">;
+        providers: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ProviderId", "out">>;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+        mode: z.ZodLiteral<"only">;
+        provider: z.core.$ZodBranded<z.ZodString, "ProviderId", "out">;
+    }, z.core.$strict>>], "mode">;
+    /** Keys are canonical model ids; parsing rejects deployment names. */
+    models: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "CanonicalModelId", "out">, z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+        mode: z.ZodLiteral<"ordered">;
+        providers: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ProviderId", "out">>;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+        mode: z.ZodLiteral<"only">;
+        provider: z.core.$ZodBranded<z.ZodString, "ProviderId", "out">;
+    }, z.core.$strict>>], "mode">>;
+}, z.core.$strict>>;
+export type ModelRouteRegistry = z.infer<typeof modelRouteRegistrySchema>;
+/**
+ * Parse and freeze a checked-in registry object at module initialization.
+ * `satisfies` on the literal is not a runtime-validation substitute
+ * (PRD §4.2) — hosts must call this on their checked-in object.
+ */
+export declare function parseModelRouteRegistry(input: unknown): ModelRouteRegistry;
+/**
+ * Policy precedence (PRD §4.2): exact canonical-model entry, then the bound
+ * default when the host reports a provider binding for this model, then the
+ * unbound default. An explicit policy always wins — in particular, an
+ * explicit single-provider model does not become bound-first merely because
+ * a binding is later added.
+ *
+ * `boundProviders` is the host's report of which providers have an explicit
+ * binding for this model (e.g. an Azure deployment mapping). A catch-all
+ * transport that serves every model without per-model configuration should
+ * not be reported as a binding.
+ */
+export declare function resolveProviderPolicy(registry: ModelRouteRegistry, model: CanonicalModelId, boundProviders: ReadonlySet<ProviderId>): ProviderPolicy;
+/** The provider order a policy prescribes; `only` is a single-entry order. */
+export declare function policyProviderOrder(policy: ProviderPolicy): readonly ProviderId[];

package/routing/policy.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { canonicalModelIdSchema, providerIdSchema, } from "./canonical-model";
+/**
+ * Policy order and semantics are versioned; the version string travels into
+ * telemetry (LLM Provider Routing PRD §4.2) so a routing-behavior change is
+ * distinguishable from a configuration change after the fact.
+ */
+export const ROUTE_POLICY_VERSION = "provider-router-v1";
+const orderedPolicySchema = z
+    .strictObject({
+    mode: z.literal("ordered"),
+    providers: z
+        .array(providerIdSchema)
+        .min(1)
+        .refine((providers) => new Set(providers).size === providers.length, "duplicate provider ids in ordered policy"),
+})
+    .readonly();
+const onlyPolicySchema = z
+    .strictObject({
+    mode: z.literal("only"),
+    provider: providerIdSchema,
+})
+    .readonly();
+/**
+ * `ordered` tries each listed provider in order, skipping unavailable or
+ * incapable endpoints. `only` is a hard fence: the marked canonical model is
+ * never attempted through another provider. A separately configured fallback
+ * model still expands under its own policy (PRD §4.2).
+ */
+export const providerPolicySchema = z.discriminatedUnion("mode", [
+    orderedPolicySchema,
+    onlyPolicySchema,
+]);
+/**
+ * The checked-in route registry. It contains policy only — never endpoints,
+ * deployment names, credentials, prices, quota, or tenant-specific values.
+ *
+ * Naming note: the PRD draft called the bound default `azureBoundDefault`.
+ * The harness is provider-agnostic, so the registry generalizes it to
+ * `boundDefault`, applied when the host reports at least one provider
+ * binding for the model (see `resolveProviderPolicy`).
+ */
+export const modelRouteRegistrySchema = z
+    .strictObject({
+    version: z.literal(ROUTE_POLICY_VERSION),
+    /** Used when a model has no explicit policy and no provider binding. */
+    unboundDefault: providerPolicySchema,
+    /** Used when a model has no explicit policy but has ≥1 provider binding. */
+    boundDefault: providerPolicySchema,
+    /** Keys are canonical model ids; parsing rejects deployment names. */
+    models: z.record(canonicalModelIdSchema, providerPolicySchema),
+})
+    .readonly();
+/**
+ * Parse and freeze a checked-in registry object at module initialization.
+ * `satisfies` on the literal is not a runtime-validation substitute
+ * (PRD §4.2) — hosts must call this on their checked-in object.
+ */
+export function parseModelRouteRegistry(input) {
+    const registry = modelRouteRegistrySchema.parse(input);
+    for (const policy of Object.values(registry.models)) {
+        if (policy.mode === "ordered")
+            Object.freeze(policy.providers);
+        Object.freeze(policy);
+    }
+    Object.freeze(registry.models);
+    return Object.freeze(registry);
+}
+/**
+ * Policy precedence (PRD §4.2): exact canonical-model entry, then the bound
+ * default when the host reports a provider binding for this model, then the
+ * unbound default. An explicit policy always wins — in particular, an
+ * explicit single-provider model does not become bound-first merely because
+ * a binding is later added.
+ *
+ * `boundProviders` is the host's report of which providers have an explicit
+ * binding for this model (e.g. an Azure deployment mapping). A catch-all
+ * transport that serves every model without per-model configuration should
+ * not be reported as a binding.
+ */
+export function resolveProviderPolicy(registry, model, boundProviders) {
+    const explicit = registry.models[model];
+    if (explicit !== undefined)
+        return explicit;
+    return boundProviders.size > 0 ? registry.boundDefault : registry.unboundDefault;
+}
+/** The provider order a policy prescribes; `only` is a single-entry order. */
+export function policyProviderOrder(policy) {
+    switch (policy.mode) {
+        case "ordered":
+            return policy.providers;
+        case "only":
+            return [policy.provider];
+        default: {
+            const _exhaustive = policy;
+            throw new Error(`unknown policy mode: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}

package/routing/transport.d.ts

@@ -0,0 +1,40 @@
+import type { CanonicalModelId, ProviderId } from "./canonical-model";
+import type { InferenceRequirements, RouteCandidate, RouteSkip } from "./plan";
+export type TransportAvailability = Readonly<{
+    available: true;
+}> | Readonly<{
+    available: false;
+    reason: string;
+}>;
+/**
+ * What a transport reports when the planner asks it for an endpoint:
+ * - `candidate` — a concrete, attemptable endpoint.
+ * - `skip` — the transport knows about the model but cannot serve it
+ *   (malformed binding, capability gap it detects itself); recorded as a
+ *   plan diagnostic.
+ * - `unserved` — the transport has no knowledge of this model (e.g. no Azure
+ *   deployment mapping). Omitted silently, matching PRD §5.1's "wholly
+ *   absent configuration is omitted" behavior.
+ */
+export type CandidateResolution = Readonly<{
+    kind: "candidate";
+    candidate: RouteCandidate;
+}> | Readonly<{
+    kind: "skip";
+    skip: RouteSkip;
+}> | Readonly<{
+    kind: "unserved";
+}>;
+/**
+ * The planner-facing surface of an inference transport. This is the harness
+ * subset of the PRD's `InferenceTransportContribution` (§4.3): request
+ * construction (`createClient` / `buildRequest`) and provider error
+ * classification stay with the host's transport adapters, because they
+ * depend on the wire client. The planner needs only availability and
+ * endpoint resolution.
+ */
+export interface PlannerTransport {
+    readonly id: ProviderId;
+    getAvailability(): TransportAvailability;
+    resolveCandidate(model: CanonicalModelId, requirements: InferenceRequirements): CandidateResolution;
+}

package/routing/transport.js

@@ -0,0 +1 @@
+export {};