@oxyhq/contracts 0.29.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>;

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

@@ -43,19 +43,19 @@ export declare const inferenceStreamStartEventSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "start";
     requestId: string;
-    schemaVersion: 1;
-    sequence: number;
     resolvedModelReference: string;
     servingProvider: string;
+    schemaVersion: 1;
+    sequence: number;
     startedAt: string;
     generationId?: string | undefined;
 }, {
     type: "start";
     requestId: string;
-    schemaVersion: 1;
-    sequence: number;
     resolvedModelReference: string;
     servingProvider: string;
+    schemaVersion: 1;
+    sequence: number;
     startedAt: string;
     generationId?: string | undefined;
 }>;
@@ -77,7 +77,7 @@ export declare const inferenceStreamDeltaEventSchema: z.ZodObject<{
     channel: z.ZodEnum<["output_text", "reasoning", "refusal"]>;
     text: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    channel: "reasoning" | "output_text" | "refusal";
+    channel: "reasoning" | "refusal" | "output_text";
     type: "delta";
     requestId: string;
     schemaVersion: 1;
@@ -85,7 +85,7 @@ export declare const inferenceStreamDeltaEventSchema: z.ZodObject<{
     sequence: number;
     outputIndex: number;
 }, {
-    channel: "reasoning" | "output_text" | "refusal";
+    channel: "reasoning" | "refusal" | "output_text";
     type: "delta";
     requestId: string;
     schemaVersion: 1;
@@ -136,6 +136,33 @@ export declare const inferenceStreamToolCallEventSchema: z.ZodObject<{
  * derived from these units and a price version at settlement; a cost quoted by
  * the data plane would be a second, unauthoritative answer to the same
  * question.
+ *
+ * ## This event is MEASUREMENT EVIDENCE, never a settleable record
+ *
+ * `normalizedUsageReportSchema` is the only shape a settlement is written from,
+ * and this event is deliberately NOT a subset of it that could be widened into
+ * one. It carries units and a source; a report additionally carries the
+ * attribution block, the outcome, the resolved route, the route-switch count and
+ * the two timestamps. Every one of those is knowable only by one END of the
+ * request rather than by the frame: the outcome only by the edge, which is the
+ * only party that knows whether the CLIENT cancelled, and the route record only
+ * by the data plane.
+ *
+ * So the event is not widened, and that is a decision rather than an omission.
+ * Adding the route record and the attribution block here would repeat both on
+ * EVERY usage frame of every stream, and each repetition is one more place two
+ * frames of one stream could disagree about which route served it — a second
+ * source of truth per frame, for fields no consumer of a progress signal reads.
+ *
+ * **What the edge may do with it, and what it may not.** The units are exact and
+ * may be settled; the record around them may not be inferred. When no terminal
+ * report arrives — the ordinary case for a client disconnect, since the report
+ * frame can no longer be delivered to a connection that is gone — the edge
+ * settles the units from the last such event and takes the OUTCOME from itself,
+ * never from the event. Its outcome is then `cancelled`, `partial` or `failed`;
+ * it is never `completed`, because nothing here can witness that the customer
+ * received the whole answer. Zero units marked `estimated` is the arm for no
+ * evidence at ALL, not for a disconnect that reported some.
  */
 export declare const inferenceStreamUsageEventSchema: z.ZodObject<{
     /** See `version.ts`: each stream event is a whole message on the wire. */
@@ -216,18 +243,18 @@ export declare const inferenceRouteSwitchDetailSchema: z.ZodDiscriminatedUnion<"
     authorizedByPolicy: z.ZodLiteral<true>;
 }, "strict", z.ZodTypeAny, {
     scope: "model";
+    authorizedByPolicy: true;
     toProvider: string;
     requestedModelId: string;
     fromModelReference: string;
     toModelReference: string;
-    authorizedByPolicy: true;
 }, {
     scope: "model";
+    authorizedByPolicy: true;
     toProvider: string;
     requestedModelId: string;
     fromModelReference: string;
     toModelReference: string;
-    authorizedByPolicy: true;
 }>]>;
 /** Why a route changed mid-request. */
 export declare const inferenceRouteSwitchReasonSchema: z.ZodEnum<["deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "rate_limited", "capacity", "policy_preference"]>;
@@ -277,18 +304,18 @@ export declare const inferenceStreamRouteSwitchEventSchema: z.ZodObject<{
         authorizedByPolicy: z.ZodLiteral<true>;
     }, "strict", z.ZodTypeAny, {
         scope: "model";
+        authorizedByPolicy: true;
         toProvider: string;
         requestedModelId: string;
         fromModelReference: string;
         toModelReference: string;
-        authorizedByPolicy: true;
     }, {
         scope: "model";
+        authorizedByPolicy: true;
         toProvider: string;
         requestedModelId: string;
         fromModelReference: string;
         toModelReference: string;
-        authorizedByPolicy: true;
     }>]>;
     occurredAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -304,11 +331,11 @@ export declare const inferenceStreamRouteSwitchEventSchema: z.ZodObject<{
         toDeploymentId?: string | undefined;
     } | {
         scope: "model";
+        authorizedByPolicy: true;
         toProvider: string;
         requestedModelId: string;
         fromModelReference: string;
         toModelReference: string;
-        authorizedByPolicy: true;
     };
     sequence: number;
 }, {
@@ -324,11 +351,11 @@ export declare const inferenceStreamRouteSwitchEventSchema: z.ZodObject<{
         toDeploymentId?: string | undefined;
     } | {
         scope: "model";
+        authorizedByPolicy: true;
         toProvider: string;
         requestedModelId: string;
         fromModelReference: string;
         toModelReference: string;
-        authorizedByPolicy: true;
     };
     sequence: number;
 }>;
@@ -506,8 +533,8 @@ export declare const inferenceStreamDoneEventSchema: z.ZodObject<{
     sequence: number;
     finishReason: "length" | "cancelled" | "content_filter" | "refusal" | "stop" | "tool_calls";
     completedAt: string;
-    generationId?: string | undefined;
     receiptId?: string | undefined;
+    generationId?: string | undefined;
 }, {
     type: "done";
     requestId: string;
@@ -515,8 +542,8 @@ export declare const inferenceStreamDoneEventSchema: z.ZodObject<{
     sequence: number;
     finishReason: "length" | "cancelled" | "content_filter" | "refusal" | "stop" | "tool_calls";
     completedAt: string;
-    generationId?: string | undefined;
     receiptId?: string | undefined;
+    generationId?: string | undefined;
 }>;
 /**
  * Every event a normalized stream can carry.
@@ -538,19 +565,19 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
 }, "strip", z.ZodTypeAny, {
     type: "start";
     requestId: string;
-    schemaVersion: 1;
-    sequence: number;
     resolvedModelReference: string;
     servingProvider: string;
+    schemaVersion: 1;
+    sequence: number;
     startedAt: string;
     generationId?: string | undefined;
 }, {
     type: "start";
     requestId: string;
-    schemaVersion: 1;
-    sequence: number;
     resolvedModelReference: string;
     servingProvider: string;
+    schemaVersion: 1;
+    sequence: number;
     startedAt: string;
     generationId?: string | undefined;
 }>, z.ZodObject<{
@@ -564,7 +591,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
     channel: z.ZodEnum<["output_text", "reasoning", "refusal"]>;
     text: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    channel: "reasoning" | "output_text" | "refusal";
+    channel: "reasoning" | "refusal" | "output_text";
     type: "delta";
     requestId: string;
     schemaVersion: 1;
@@ -572,7 +599,7 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
     sequence: number;
     outputIndex: number;
 }, {
-    channel: "reasoning" | "output_text" | "refusal";
+    channel: "reasoning" | "refusal" | "output_text";
     type: "delta";
     requestId: string;
     schemaVersion: 1;
@@ -684,18 +711,18 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
         authorizedByPolicy: z.ZodLiteral<true>;
     }, "strict", z.ZodTypeAny, {
         scope: "model";
+        authorizedByPolicy: true;
         toProvider: string;
         requestedModelId: string;
         fromModelReference: string;
         toModelReference: string;
-        authorizedByPolicy: true;
     }, {
         scope: "model";
+        authorizedByPolicy: true;
         toProvider: string;
         requestedModelId: string;
         fromModelReference: string;
         toModelReference: string;
-        authorizedByPolicy: true;
     }>]>;
     occurredAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -711,11 +738,11 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
         toDeploymentId?: string | undefined;
     } | {
         scope: "model";
+        authorizedByPolicy: true;
         toProvider: string;
         requestedModelId: string;
         fromModelReference: string;
         toModelReference: string;
-        authorizedByPolicy: true;
     };
     sequence: number;
 }, {
@@ -731,11 +758,11 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
         toDeploymentId?: string | undefined;
     } | {
         scope: "model";
+        authorizedByPolicy: true;
         toProvider: string;
         requestedModelId: string;
         fromModelReference: string;
         toModelReference: string;
-        authorizedByPolicy: true;
     };
     sequence: number;
 }>, z.ZodObject<{
@@ -890,8 +917,8 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
     sequence: number;
     finishReason: "length" | "cancelled" | "content_filter" | "refusal" | "stop" | "tool_calls";
     completedAt: string;
-    generationId?: string | undefined;
     receiptId?: string | undefined;
+    generationId?: string | undefined;
 }, {
     type: "done";
     requestId: string;
@@ -899,8 +926,8 @@ export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type",
     sequence: number;
     finishReason: "length" | "cancelled" | "content_filter" | "refusal" | "stop" | "tool_calls";
     completedAt: string;
-    generationId?: string | undefined;
     receiptId?: string | undefined;
+    generationId?: string | undefined;
 }>]>;
 export type InferenceStreamStartEvent = z.infer<typeof inferenceStreamStartEventSchema>;
 export type InferenceStreamDeltaEvent = z.infer<typeof inferenceStreamDeltaEventSchema>;