@oxyhq/contracts 0.25.0 → 0.27.0

package/dist/types/inference/routingPolicy.d.ts

@@ -0,0 +1,426 @@
+/**
+ * Routing policy — the customer-facing routing configuration.
+ *
+ * Stored under an Oxy account or application (the control plane owns it),
+ * executed by the data plane, which owns execution. Every request records the
+ * exact `{routingPolicyId, policyVersion}` it was served under, so a route
+ * decision months old can be explained against the policy that was in force,
+ * not against the policy that exists now.
+ *
+ * Two rules shape the fallback controls:
+ *
+ *  - **Same-model deployment failover is not cross-model fallback.** Moving
+ *    between two deployments of the SAME revision is an availability decision
+ *    and is on by default; serving a DIFFERENT model is a substitution the
+ *    customer must have authorized by name.
+ *  - **A request for a concrete model is never silently replaced.** Cross-model
+ *    fallback is an explicit list of references, and a switch that uses it emits
+ *    a customer-visible route-switch event.
+ *
+ * The controls are flat and independent, matching what Console renders — which
+ * means contradictory combinations are EXPRESSIBLE and must therefore be
+ * REJECTED, rather than being quietly resolved by whichever field the executor
+ * happens to read first. That rejection is `routingPolicySchema`'s refinement.
+ *
+ * Decided in: docs/adr/0008-catalogue-concept-separation.md, issue #972 workstream 6.
+ */
+import { z } from 'zod';
+/**
+ * What a policy resolves to when a caller names no model.
+ *
+ * A discriminated union rather than two optional fields, so "which one did the
+ * customer configure" is never a question about which field is non-null.
+ */
+export declare const routingTargetSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"model">;
+    modelReference: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "model";
+    modelReference: string;
+}, {
+    kind: "model";
+    modelReference: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"routing_profile">;
+    routingProfile: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "routing_profile";
+    routingProfile: string;
+}, {
+    kind: "routing_profile";
+    routingProfile: string;
+}>]>;
+/**
+ * Which account or application a policy governs.
+ *
+ * Application-scoped policies are the common case; an account-scoped policy is
+ * the floor its applications inherit, and inheritance is resolved by the control
+ * plane before a policy reaches the data plane.
+ */
+export declare const routingPolicyScopeSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"account">;
+    accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+}, "strict", z.ZodTypeAny, {
+    kind: "account";
+    accountId: string & z.BRAND<"OxyAccountId">;
+}, {
+    kind: "account";
+    accountId: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"application">;
+    accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    applicationId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "application";
+    accountId: string & z.BRAND<"OxyAccountId">;
+    applicationId: string;
+}, {
+    kind: "application";
+    accountId: string;
+    applicationId: string;
+}>]>;
+/**
+ * The fallback controls, kept together so a reviewer sees all three at once.
+ *
+ * `authorizedCrossModel` is a list of model references the customer has
+ * explicitly permitted as substitutes — never a boolean, because "allow
+ * fallback" without naming the destination is exactly the silent substitution
+ * the invariant forbids.
+ */
+export declare const routingFallbackPolicySchema: z.ZodObject<{
+    disabled: z.ZodBoolean;
+    sameModelDeployment: z.ZodBoolean;
+    authorizedCrossModel: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    disabled: boolean;
+    sameModelDeployment: boolean;
+    authorizedCrossModel: string[];
+}, {
+    disabled: boolean;
+    sameModelDeployment: boolean;
+    authorizedCrossModel?: string[] | undefined;
+}>;
+/**
+ * A versioned routing policy.
+ *
+ * `policyVersion` is the CUSTOMER's revision of their own configuration and is
+ * unrelated to `schemaVersion`, which is the version of this wire shape. They
+ * are two different clocks: a customer edits their policy without any contract
+ * change, and a contract change does not renumber anybody's policy.
+ */
+export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
+    /** See `version.ts`: exchanged with the data plane on its own. */
+    schemaVersion: z.ZodLiteral<1>;
+    routingPolicyId: z.ZodString;
+    policyVersion: z.ZodNumber;
+    scope: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"account">;
+        accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    }, "strict", z.ZodTypeAny, {
+        kind: "account";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    }, {
+        kind: "account";
+        accountId: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"application">;
+        accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+        applicationId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "application";
+        accountId: string & z.BRAND<"OxyAccountId">;
+        applicationId: string;
+    }, {
+        kind: "application";
+        accountId: string;
+        applicationId: string;
+    }>]>;
+    /** Absent when every request must name its own model. */
+    defaultTarget: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"model">;
+        modelReference: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "model";
+        modelReference: string;
+    }, {
+        kind: "model";
+        modelReference: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"routing_profile">;
+        routingProfile: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "routing_profile";
+        routingProfile: string;
+    }, {
+        kind: "routing_profile";
+        routingProfile: string;
+    }>]>>;
+    /** Empty means "no allowlist" — every provider qualifies unless denied. */
+    providerAllowlist: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    providerDenylist: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Empty means "no residency constraint". */
+    allowedRegions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    deniedRegions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    requireZeroDataRetention: z.ZodBoolean;
+    prohibitTrainingOnCustomerData: z.ZodBoolean;
+    /** Ceilings on what a route may cost the customer, quoted like catalogue prices. */
+    maxPricePerUnit: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+        amount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+        per: z.ZodNumber;
+        currency: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }, {
+        amount: string;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }>, "many">>;
+    maxPricePerRequest: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodBranded<z.ZodString, "ExactDecimal">;
+        currency: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+    }, {
+        amount: string;
+        currency: string;
+    }>>;
+    /** What to optimise for among the routes that qualify. */
+    optimiseFor: z.ZodEnum<["price", "latency", "throughput", "balanced"]>;
+    /** Serve only from Oxy's own hosting of open-weight models. */
+    oxyHostedOnly: z.ZodBoolean;
+    /** License / usage-right constraints. Empty license list means unconstrained. */
+    allowedLicenseIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    requireCommercialUseRights: z.ZodBoolean;
+    fallback: z.ZodObject<{
+        disabled: z.ZodBoolean;
+        sameModelDeployment: z.ZodBoolean;
+        authorizedCrossModel: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        disabled: boolean;
+        sameModelDeployment: boolean;
+        authorizedCrossModel: string[];
+    }, {
+        disabled: boolean;
+        sameModelDeployment: boolean;
+        authorizedCrossModel?: string[] | undefined;
+    }>;
+    /** Whether the customer's own provider credentials may or must be used. */
+    byokPreference: z.ZodEnum<["disabled", "prefer", "require"]>;
+    /** Enterprise reserved capacity rather than shared endpoints. */
+    dedicatedCapacity: z.ZodEnum<["disabled", "prefer", "require"]>;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: string;
+    scope: {
+        kind: "account";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    } | {
+        kind: "application";
+        accountId: string & z.BRAND<"OxyAccountId">;
+        applicationId: string;
+    };
+    schemaVersion: 1;
+    dedicatedCapacity: "disabled" | "prefer" | "require";
+    optimiseFor: "price" | "latency" | "throughput" | "balanced";
+    routingPolicyId: string;
+    policyVersion: number;
+    providerAllowlist: string[];
+    providerDenylist: string[];
+    allowedRegions: string[];
+    deniedRegions: string[];
+    requireZeroDataRetention: boolean;
+    prohibitTrainingOnCustomerData: boolean;
+    maxPricePerUnit: {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[];
+    oxyHostedOnly: boolean;
+    allowedLicenseIds: string[];
+    requireCommercialUseRights: boolean;
+    fallback: {
+        disabled: boolean;
+        sameModelDeployment: boolean;
+        authorizedCrossModel: string[];
+    };
+    byokPreference: "disabled" | "prefer" | "require";
+    defaultTarget?: {
+        kind: "model";
+        modelReference: string;
+    } | {
+        kind: "routing_profile";
+        routingProfile: string;
+    } | undefined;
+    maxPricePerRequest?: {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+    } | undefined;
+}, {
+    updatedAt: string;
+    scope: {
+        kind: "account";
+        accountId: string;
+    } | {
+        kind: "application";
+        accountId: string;
+        applicationId: string;
+    };
+    schemaVersion: 1;
+    dedicatedCapacity: "disabled" | "prefer" | "require";
+    optimiseFor: "price" | "latency" | "throughput" | "balanced";
+    routingPolicyId: string;
+    policyVersion: number;
+    requireZeroDataRetention: boolean;
+    prohibitTrainingOnCustomerData: boolean;
+    oxyHostedOnly: boolean;
+    requireCommercialUseRights: boolean;
+    fallback: {
+        disabled: boolean;
+        sameModelDeployment: boolean;
+        authorizedCrossModel?: string[] | undefined;
+    };
+    byokPreference: "disabled" | "prefer" | "require";
+    defaultTarget?: {
+        kind: "model";
+        modelReference: string;
+    } | {
+        kind: "routing_profile";
+        routingProfile: string;
+    } | undefined;
+    providerAllowlist?: string[] | undefined;
+    providerDenylist?: string[] | undefined;
+    allowedRegions?: string[] | undefined;
+    deniedRegions?: string[] | undefined;
+    maxPricePerUnit?: {
+        amount: string;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[] | undefined;
+    maxPricePerRequest?: {
+        amount: string;
+        currency: string;
+    } | undefined;
+    allowedLicenseIds?: string[] | undefined;
+}>, {
+    updatedAt: string;
+    scope: {
+        kind: "account";
+        accountId: string & z.BRAND<"OxyAccountId">;
+    } | {
+        kind: "application";
+        accountId: string & z.BRAND<"OxyAccountId">;
+        applicationId: string;
+    };
+    schemaVersion: 1;
+    dedicatedCapacity: "disabled" | "prefer" | "require";
+    optimiseFor: "price" | "latency" | "throughput" | "balanced";
+    routingPolicyId: string;
+    policyVersion: number;
+    providerAllowlist: string[];
+    providerDenylist: string[];
+    allowedRegions: string[];
+    deniedRegions: string[];
+    requireZeroDataRetention: boolean;
+    prohibitTrainingOnCustomerData: boolean;
+    maxPricePerUnit: {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[];
+    oxyHostedOnly: boolean;
+    allowedLicenseIds: string[];
+    requireCommercialUseRights: boolean;
+    fallback: {
+        disabled: boolean;
+        sameModelDeployment: boolean;
+        authorizedCrossModel: string[];
+    };
+    byokPreference: "disabled" | "prefer" | "require";
+    defaultTarget?: {
+        kind: "model";
+        modelReference: string;
+    } | {
+        kind: "routing_profile";
+        routingProfile: string;
+    } | undefined;
+    maxPricePerRequest?: {
+        amount: string & z.BRAND<"ExactDecimal">;
+        currency: string;
+    } | undefined;
+}, {
+    updatedAt: string;
+    scope: {
+        kind: "account";
+        accountId: string;
+    } | {
+        kind: "application";
+        accountId: string;
+        applicationId: string;
+    };
+    schemaVersion: 1;
+    dedicatedCapacity: "disabled" | "prefer" | "require";
+    optimiseFor: "price" | "latency" | "throughput" | "balanced";
+    routingPolicyId: string;
+    policyVersion: number;
+    requireZeroDataRetention: boolean;
+    prohibitTrainingOnCustomerData: boolean;
+    oxyHostedOnly: boolean;
+    requireCommercialUseRights: boolean;
+    fallback: {
+        disabled: boolean;
+        sameModelDeployment: boolean;
+        authorizedCrossModel?: string[] | undefined;
+    };
+    byokPreference: "disabled" | "prefer" | "require";
+    defaultTarget?: {
+        kind: "model";
+        modelReference: string;
+    } | {
+        kind: "routing_profile";
+        routingProfile: string;
+    } | undefined;
+    providerAllowlist?: string[] | undefined;
+    providerDenylist?: string[] | undefined;
+    allowedRegions?: string[] | undefined;
+    deniedRegions?: string[] | undefined;
+    maxPricePerUnit?: {
+        amount: string;
+        currency: string;
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        per: number;
+    }[] | undefined;
+    maxPricePerRequest?: {
+        amount: string;
+        currency: string;
+    } | undefined;
+    allowedLicenseIds?: string[] | undefined;
+}>;
+/**
+ * The reference a request records: which policy, at which of the customer's own
+ * revisions. Embedded in the request envelope and in the settled receipt, so a
+ * charge can be explained against the exact configuration that produced it.
+ */
+export declare const routingPolicyReferenceSchema: z.ZodObject<{
+    routingPolicyId: z.ZodString;
+    policyVersion: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    routingPolicyId: string;
+    policyVersion: number;
+}, {
+    routingPolicyId: string;
+    policyVersion: number;
+}>;
+export type RoutingTarget = z.infer<typeof routingTargetSchema>;
+export type RoutingPolicyScope = z.infer<typeof routingPolicyScopeSchema>;
+export type RoutingFallbackPolicy = z.infer<typeof routingFallbackPolicySchema>;
+export type RoutingPolicy = z.infer<typeof routingPolicySchema>;
+export type RoutingPolicyReference = z.infer<typeof routingPolicyReferenceSchema>;