@oxyhq/contracts 0.28.0 → 0.30.0

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

@@ -22,7 +22,14 @@
  * 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.
+ * **The policy itself never crosses to the data plane.** What crosses is
+ * {@link authorizedRouteSchema} — the candidate routes that SURVIVED these
+ * controls, in preference order — plus {@link routingPolicyReferenceSchema} as
+ * provenance for the receipt. The data plane holds no control value and needs
+ * none: it fails over by taking the next entry. See ADR 0017.
+ *
+ * Decided in: docs/adr/0008-catalogue-concept-separation.md,
+ * docs/adr/0017-authorized-routes-in-the-envelope.md, issue #972 workstream 6.
  */
 import { z } from 'zod';
 /**
@@ -170,13 +177,13 @@ export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
         per: z.ZodNumber;
         currency: z.ZodString;
     }, "strict", z.ZodTypeAny, {
-        amount: string & z.BRAND<"ExactDecimal">;
         currency: string;
+        amount: string & z.BRAND<"ExactDecimal">;
         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;
+        amount: 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">>;
@@ -184,11 +191,11 @@ export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
         amount: z.ZodBranded<z.ZodString, "ExactDecimal">;
         currency: z.ZodString;
     }, "strict", z.ZodTypeAny, {
-        amount: string & z.BRAND<"ExactDecimal">;
         currency: string;
+        amount: string & z.BRAND<"ExactDecimal">;
     }, {
-        amount: string;
         currency: string;
+        amount: string;
     }>>;
     /** What to optimise for among the routes that qualify. */
     optimiseFor: z.ZodEnum<["price", "latency", "throughput", "balanced"]>;
@@ -237,8 +244,8 @@ export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
     requireZeroDataRetention: boolean;
     prohibitTrainingOnCustomerData: boolean;
     maxPricePerUnit: {
-        amount: string & z.BRAND<"ExactDecimal">;
         currency: string;
+        amount: string & z.BRAND<"ExactDecimal">;
         unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
         per: number;
     }[];
@@ -259,8 +266,8 @@ export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
         routingProfile: string;
     } | undefined;
     maxPricePerRequest?: {
-        amount: string & z.BRAND<"ExactDecimal">;
         currency: string;
+        amount: string & z.BRAND<"ExactDecimal">;
     } | undefined;
 }, {
     updatedAt: string;
@@ -299,14 +306,14 @@ export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
     allowedRegions?: string[] | undefined;
     deniedRegions?: string[] | undefined;
     maxPricePerUnit?: {
-        amount: string;
         currency: string;
+        amount: 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;
+        amount: string;
     } | undefined;
     allowedLicenseIds?: string[] | undefined;
 }>, {
@@ -331,8 +338,8 @@ export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
     requireZeroDataRetention: boolean;
     prohibitTrainingOnCustomerData: boolean;
     maxPricePerUnit: {
-        amount: string & z.BRAND<"ExactDecimal">;
         currency: string;
+        amount: string & z.BRAND<"ExactDecimal">;
         unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
         per: number;
     }[];
@@ -353,8 +360,8 @@ export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
         routingProfile: string;
     } | undefined;
     maxPricePerRequest?: {
-        amount: string & z.BRAND<"ExactDecimal">;
         currency: string;
+        amount: string & z.BRAND<"ExactDecimal">;
     } | undefined;
 }, {
     updatedAt: string;
@@ -393,14 +400,14 @@ export declare const routingPolicySchema: z.ZodEffects<z.ZodObject<{
     allowedRegions?: string[] | undefined;
     deniedRegions?: string[] | undefined;
     maxPricePerUnit?: {
-        amount: string;
         currency: string;
+        amount: 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;
+        amount: string;
     } | undefined;
     allowedLicenseIds?: string[] | undefined;
 }>;
@@ -419,8 +426,97 @@ export declare const routingPolicyReferenceSchema: z.ZodObject<{
     routingPolicyId: string;
     policyVersion: number;
 }>;
+/**
+ * One route the control plane has already authorized for one request.
+ *
+ * **Authorization is an ENTRY, never a boolean.** The same stance
+ * `inference_routing_policy_fallbacks` takes in storage: being allowed to serve
+ * a route IS appearing here, and every entry names its destination. A flag
+ * saying "substitution allowed" without naming the destination is exactly the
+ * silent substitution the platform forbids, and it invents a "flag set, list
+ * empty" state somebody then has to decide what to do with.
+ *
+ * Discriminated on `substitution`, relative to the FIRST entry — the primary
+ * route Oxy resolved:
+ *
+ *  - `same_model` serves the same model line as the primary. This is
+ *    availability failover between deployments of one model.
+ *  - `cross_model` serves a DIFFERENT model line, and is expressible only with
+ *    `authorizedByPolicy: true` as a literal. So "a model was substituted
+ *    without the customer authorizing it" is not a sentence this contract can
+ *    say — the same construction `inferenceRouteSwitchDetailSchema` uses to make
+ *    the resulting route-switch event unreportable.
+ */
+export declare const authorizedRouteSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"substitution", [z.ZodObject<{
+    deploymentId: z.ZodString;
+    modelReference: z.ZodString;
+    provider: z.ZodString;
+    regions: z.ZodArray<z.ZodString, "many">;
+    substitution: z.ZodLiteral<"same_model">;
+}, "strict", z.ZodTypeAny, {
+    provider: string;
+    modelReference: string;
+    regions: string[];
+    deploymentId: string;
+    substitution: "same_model";
+}, {
+    provider: string;
+    modelReference: string;
+    regions: string[];
+    deploymentId: string;
+    substitution: "same_model";
+}>, z.ZodObject<{
+    /** Literal `true`: an unauthorized substitution cannot be expressed. */
+    authorizedByPolicy: z.ZodLiteral<true>;
+    deploymentId: z.ZodString;
+    modelReference: z.ZodString;
+    provider: z.ZodString;
+    regions: z.ZodArray<z.ZodString, "many">;
+    substitution: z.ZodLiteral<"cross_model">;
+}, "strict", z.ZodTypeAny, {
+    provider: string;
+    modelReference: string;
+    regions: string[];
+    deploymentId: string;
+    substitution: "cross_model";
+    authorizedByPolicy: true;
+}, {
+    provider: string;
+    modelReference: string;
+    regions: string[];
+    deploymentId: string;
+    substitution: "cross_model";
+    authorizedByPolicy: true;
+}>]>, {
+    provider: string;
+    modelReference: string;
+    regions: string[];
+    deploymentId: string;
+    substitution: "same_model";
+} | {
+    provider: string;
+    modelReference: string;
+    regions: string[];
+    deploymentId: string;
+    substitution: "cross_model";
+    authorizedByPolicy: true;
+}, {
+    provider: string;
+    modelReference: string;
+    regions: string[];
+    deploymentId: string;
+    substitution: "same_model";
+} | {
+    provider: string;
+    modelReference: string;
+    regions: string[];
+    deploymentId: string;
+    substitution: "cross_model";
+    authorizedByPolicy: true;
+}>;
 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>;
+export type AuthorizedRoute = z.infer<typeof authorizedRouteSchema>;