@oxyhq/contracts 0.29.0 → 0.30.0

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

@@ -11,11 +11,17 @@
  *
  * What the envelope carries that a provider request does not: the resolved
  * attribution block (who pays, which application, which credential, which
- * delegated user), the exact routing policy reference and the customer's
- * idempotency key. Those are the fields that make a request billable and
- * explainable, and they are resolved BEFORE the request enters the data plane.
+ * delegated user), the exact routing policy reference, the routes that policy
+ * has already authorized, and the customer's idempotency key. Those are the
+ * fields that make a request billable and explainable, and they are resolved
+ * BEFORE the request enters the data plane.
  *
- * Decided in: docs/adr/0010-public-api-compatibility.md.
+ * The policy VALUES never travel. `routingPolicy` is a reference — provenance
+ * for the receipt — and `authorizedRoutes` is the result of applying the policy,
+ * in preference order, so the data plane needs no policy semantics to fail over.
+ *
+ * Decided in: docs/adr/0010-public-api-compatibility.md,
+ * docs/adr/0017-authorized-routes-in-the-envelope.md.
  */
 import { z } from 'zod';
 /**
@@ -47,7 +53,38 @@ export declare const inferenceContentSourceSchema: z.ZodDiscriminatedUnion<"kind
     data: string;
     mediaType: string;
 }>]>;
-/** One part of a message's content. A message is always a list of parts. */
+/**
+ * One part of a message's content. A message is always a list of parts.
+ *
+ * ## `refusal` is a member and `reasoning` is not, and the asymmetry is the point
+ *
+ * A model that DECLINES says why, and those words are meant for the customer:
+ * they are the difference between "rephrase this" and "stop asking". Before this
+ * member existed there was nowhere in an {@link InferenceMessage} to put them, so
+ * a non-streaming fold kept `finishReason: 'refusal'` and dropped the sentence —
+ * the customer learned they were refused and not why, while a streaming caller of
+ * the same request got the whole explanation on the `refusal` delta channel.
+ *
+ * Reasoning is the opposite case and stays absent. It is the model's private
+ * working, and a `text` part is where somebody would put it — which renders
+ * private reasoning to the customer AS the answer, the product bug the delta
+ * channels exist to prevent. An opaque per-block reasoning blob crossing this
+ * boundary needs a home nobody has chosen yet, and inventing one here would
+ * choose it by accident.
+ *
+ * Both public dialects can carry a refusal, which is what separates the two
+ * cases at the boundary as well as in principle: `refusal` is OpenAI's OWN field
+ * in both of its shapes (`delta.refusal` streaming, `message.refusal`
+ * non-streaming), while reasoning has no OpenAI field at all — the
+ * `reasoning_content`/`reasoning` spellings an OpenAI-compatible provider emits
+ * are provider extensions. So carrying the refusal costs no dialect its
+ * standard-client parseability, and carrying reasoning would.
+ *
+ * The part is a MEMBER rather than a field because a refusal need not have text:
+ * an Anthropic `stop_reason: "refusal"` maps to the finish reason and separates
+ * no words from the answer, while an OpenAI-compatible `refusal` does. A required
+ * field would force the first provider to invent a sentence.
+ */
 export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
@@ -196,6 +233,15 @@ export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<"type",
         mediaType: string;
     };
     filename?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"refusal">;
+    text: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "refusal";
+    text: string;
+}, {
+    type: "refusal";
+    text: string;
 }>]>;
 /**
  * A tool call an assistant made, in the normalized form.
@@ -376,6 +422,15 @@ export declare const inferenceMessageSchema: z.ZodEffects<z.ZodObject<{
             mediaType: string;
         };
         filename?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"refusal">;
+        text: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: "refusal";
+        text: string;
+    }, {
+        type: "refusal";
+        text: string;
     }>]>, "many">;
     /** Participant name, where the dialect supports naming participants. */
     name: z.ZodOptional<z.ZodString>;
@@ -431,6 +486,9 @@ export declare const inferenceMessageSchema: z.ZodEffects<z.ZodObject<{
             mediaType: string;
         };
         filename?: string | undefined;
+    } | {
+        type: "refusal";
+        text: string;
     })[];
     role: "system" | "user" | "developer" | "assistant" | "tool";
     name?: string | undefined;
@@ -476,6 +534,9 @@ export declare const inferenceMessageSchema: z.ZodEffects<z.ZodObject<{
             mediaType: string;
         };
         filename?: string | undefined;
+    } | {
+        type: "refusal";
+        text: string;
     })[];
     role: "system" | "user" | "developer" | "assistant" | "tool";
     name?: string | undefined;
@@ -521,6 +582,9 @@ export declare const inferenceMessageSchema: z.ZodEffects<z.ZodObject<{
             mediaType: string;
         };
         filename?: string | undefined;
+    } | {
+        type: "refusal";
+        text: string;
     })[];
     role: "system" | "user" | "developer" | "assistant" | "tool";
     name?: string | undefined;
@@ -566,6 +630,9 @@ export declare const inferenceMessageSchema: z.ZodEffects<z.ZodObject<{
             mediaType: string;
         };
         filename?: string | undefined;
+    } | {
+        type: "refusal";
+        text: string;
     })[];
     role: "system" | "user" | "developer" | "assistant" | "tool";
     name?: string | undefined;
@@ -736,6 +803,15 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<"format", [z.
                 mediaType: string;
             };
             filename?: string | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"refusal">;
+            text: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            type: "refusal";
+            text: string;
+        }, {
+            type: "refusal";
+            text: string;
         }>]>, "many">;
         /** Participant name, where the dialect supports naming participants. */
         name: z.ZodOptional<z.ZodString>;
@@ -791,6 +867,9 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<"format", [z.
                 mediaType: string;
             };
             filename?: string | undefined;
+        } | {
+            type: "refusal";
+            text: string;
         })[];
         role: "system" | "user" | "developer" | "assistant" | "tool";
         name?: string | undefined;
@@ -836,6 +915,9 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<"format", [z.
                 mediaType: string;
             };
             filename?: string | undefined;
+        } | {
+            type: "refusal";
+            text: string;
         })[];
         role: "system" | "user" | "developer" | "assistant" | "tool";
         name?: string | undefined;
@@ -881,6 +963,9 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<"format", [z.
                 mediaType: string;
             };
             filename?: string | undefined;
+        } | {
+            type: "refusal";
+            text: string;
         })[];
         role: "system" | "user" | "developer" | "assistant" | "tool";
         name?: string | undefined;
@@ -926,6 +1011,9 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<"format", [z.
                 mediaType: string;
             };
             filename?: string | undefined;
+        } | {
+            type: "refusal";
+            text: string;
         })[];
         role: "system" | "user" | "developer" | "assistant" | "tool";
         name?: string | undefined;
@@ -974,6 +1062,9 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<"format", [z.
                 mediaType: string;
             };
             filename?: string | undefined;
+        } | {
+            type: "refusal";
+            text: string;
         })[];
         role: "system" | "user" | "developer" | "assistant" | "tool";
         name?: string | undefined;
@@ -1022,6 +1113,9 @@ export declare const inferenceInputSchema: z.ZodDiscriminatedUnion<"format", [z.
                 mediaType: string;
             };
             filename?: string | undefined;
+        } | {
+            type: "refusal";
+            text: string;
         })[];
         role: "system" | "user" | "developer" | "assistant" | "tool";
         name?: string | undefined;
@@ -1421,6 +1515,15 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"refusal">;
+                text: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                type: "refusal";
+                text: string;
+            }, {
+                type: "refusal";
+                text: string;
             }>]>, "many">;
             /** Participant name, where the dialect supports naming participants. */
             name: z.ZodOptional<z.ZodString>;
@@ -1476,6 +1579,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -1521,6 +1627,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -1566,6 +1675,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -1611,6 +1723,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -1659,6 +1774,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -1707,6 +1825,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -1857,6 +1978,103 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
         routingPolicyId: string;
         policyVersion: number;
     }>;
+    /**
+     * The routes the control plane has already authorized for this request, in
+     * PREFERENCE ORDER. The first entry is the primary route Oxy resolved; the
+     * data plane fails over by taking the next one.
+     *
+     * This is what closes the gap ADR 0010's amendment left open. That amendment
+     * assigns the data plane "failover within the destinations the policy
+     * authorized" — and the envelope named no destinations, so a data plane could
+     * only fail over by re-deriving the customer's policy from values it does not
+     * have. Enumerating the survivors instead means a route switch outside the
+     * policy is impossible BY CONSTRUCTION rather than by two enforcement engines
+     * agreeing in two languages.
+     *
+     * **Absent means no failover is authorized, never "choose freely."** It is
+     * the state every envelope built before this field existed is in, and the
+     * behaviour a data plane that reads no list must already have: resolve the
+     * `target` and serve it or fail. Permission is granted by an ENTRY, so its
+     * absence can only ever narrow, and there is no reading of an absent list
+     * that widens what may be served.
+     *
+     * An EMPTY list is refused rather than treated as that state. `[]` would say
+     * "no route is authorized at all", which contradicts an envelope that was
+     * built to be served, and it is exactly the "permission granted, destination
+     * unnamed" shape `authorizedRouteSchema` exists to make unrepresentable.
+     *
+     * No price rides here. Oxy sized the hold against the most expensive route
+     * the policy permits (`usageReservationRequestSchema.ceilingPriceVersionId`),
+     * and every entry is one that policy permitted, so no failover among them can
+     * exceed it. A per-route price would also be a second authority for ranking,
+     * beside the order this list already carries.
+     */
+    authorizedRoutes: z.ZodOptional<z.ZodArray<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<{
+        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;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     attribution: {
         requestId: string;
@@ -1926,6 +2144,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -1980,6 +2201,20 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
         strict: boolean;
         schema: Record<string, unknown>;
     } | undefined;
+    authorizedRoutes?: ({
+        provider: string;
+        modelReference: string;
+        regions: string[];
+        deploymentId: string;
+        substitution: "same_model";
+    } | {
+        provider: string;
+        modelReference: string;
+        regions: string[];
+        deploymentId: string;
+        substitution: "cross_model";
+        authorizedByPolicy: true;
+    })[] | undefined;
 }, {
     attribution: {
         requestId: string;
@@ -2042,6 +2277,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -2103,6 +2341,20 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
         strict: boolean;
         schema: Record<string, unknown>;
     } | undefined;
+    authorizedRoutes?: ({
+        provider: string;
+        modelReference: string;
+        regions: string[];
+        deploymentId: string;
+        substitution: "same_model";
+    } | {
+        provider: string;
+        modelReference: string;
+        regions: string[];
+        deploymentId: string;
+        substitution: "cross_model";
+        authorizedByPolicy: true;
+    })[] | undefined;
 }>, {
     attribution: {
         requestId: string;
@@ -2172,6 +2424,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -2226,6 +2481,20 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
         strict: boolean;
         schema: Record<string, unknown>;
     } | undefined;
+    authorizedRoutes?: ({
+        provider: string;
+        modelReference: string;
+        regions: string[];
+        deploymentId: string;
+        substitution: "same_model";
+    } | {
+        provider: string;
+        modelReference: string;
+        regions: string[];
+        deploymentId: string;
+        substitution: "cross_model";
+        authorizedByPolicy: true;
+    })[] | undefined;
 }, {
     attribution: {
         requestId: string;
@@ -2288,6 +2557,9 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
                     mediaType: string;
                 };
                 filename?: string | undefined;
+            } | {
+                type: "refusal";
+                text: string;
             })[];
             role: "system" | "user" | "developer" | "assistant" | "tool";
             name?: string | undefined;
@@ -2349,6 +2621,20 @@ export declare const inferenceRequestSchema: z.ZodEffects<z.ZodObject<{
         strict: boolean;
         schema: Record<string, unknown>;
     } | undefined;
+    authorizedRoutes?: ({
+        provider: string;
+        modelReference: string;
+        regions: string[];
+        deploymentId: string;
+        substitution: "same_model";
+    } | {
+        provider: string;
+        modelReference: string;
+        regions: string[];
+        deploymentId: string;
+        substitution: "cross_model";
+        authorizedByPolicy: true;
+    })[] | undefined;
 }>;
 export type InferenceContentSource = z.infer<typeof inferenceContentSourceSchema>;
 export type InferenceContentPart = z.infer<typeof inferenceContentPartSchema>;