@oxyhq/contracts 0.28.0 → 0.30.0

package/dist/esm/inference/request.js

@@ -11,17 +11,23 @@
  *
  * 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';
 import { inferenceAttributionSchema } from './attribution.js';
 import { inferenceModalitySchema } from './catalogue.js';
 import { idempotencyKeySchema, inferenceTimestampSchema } from './identifiers.js';
-import { routingPolicyReferenceSchema, routingTargetSchema } from './routingPolicy.js';
+import { authorizedRouteSchema, routingPolicyReferenceSchema, routingTargetSchema, } from './routingPolicy.js';
 /* -------------------------------------------------------------------------- */
 /*  Input                                                                     */
 /* -------------------------------------------------------------------------- */
@@ -42,7 +48,38 @@ export const inferenceContentSourceSchema = z.discriminatedUnion('kind', [
     })
         .strict(),
 ]);
-/** 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 const inferenceContentPartSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('text'), text: z.string() }).strict(),
     z
@@ -61,6 +98,11 @@ export const inferenceContentPartSchema = z.discriminatedUnion('type', [
         filename: z.string().max(255).optional(),
     })
         .strict(),
+    /**
+     * A model's explanation for declining. Its own part, never a `text` one, so no
+     * renderer can present a refusal as the answer that was asked for.
+     */
+    z.object({ type: z.literal('refusal'), text: z.string() }).strict(),
 ]);
 /**
  * A tool call an assistant made, in the normalized form.
@@ -125,6 +167,20 @@ export const inferenceMessageSchema = z
             message: 'only an assistant message makes tool calls',
         });
     }
+    // Same rule as `toolCalls`, for the same reason: only the assistant can
+    // decline, so a refusal on any other role is a part every provider would
+    // silently ignore — and one a renderer might not.
+    if (message.role !== 'assistant') {
+        for (const [index, part] of message.content.entries()) {
+            if (part.type === 'refusal') {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['content', index, 'type'],
+                    message: 'only an assistant message carries a refusal',
+                });
+            }
+        }
+    }
 });
 /**
  * The request's input.
@@ -238,6 +294,17 @@ export const clientRequestMetadataSchema = z
 /* -------------------------------------------------------------------------- */
 /*  The envelope                                                              */
 /* -------------------------------------------------------------------------- */
+/**
+ * The model LINE a reference names, with any pinned revision dropped.
+ *
+ * Substitution is a question about the line — `anthropic/claude-opus-5` — never
+ * about the revision, so the comparisons below have to be made on it. Same split
+ * `resolveEdgeRoute` makes on the way in.
+ */
+const modelLineOf = (reference) => {
+    const at = reference.indexOf('@');
+    return at === -1 ? reference : reference.slice(0, at);
+};
 /**
  * The canonical internal request Oxy forwards to the data plane.
  *
@@ -265,6 +332,38 @@ export const inferenceRequestSchema = z
     idempotencyKey: idempotencyKeySchema.optional(),
     /** The exact policy revision this request is served under. */
     routingPolicy: routingPolicyReferenceSchema,
+    /**
+     * 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.array(authorizedRouteSchema).min(1).optional(),
 })
     .superRefine((request, ctx) => {
     if (request.toolChoice !== undefined && request.tools.length === 0) {
@@ -282,4 +381,88 @@ export const inferenceRequestSchema = z
             message: 'tool names must be unique within one request',
         });
     }
+    const routes = request.authorizedRoutes;
+    // The emptiness is RE-CHECKED rather than assumed away by `.min(1)`. A
+    // failed `.min()` marks the parse dirty rather than aborting it, so zod runs
+    // this refinement with the empty array still in hand; `[]` is already
+    // refused above, and reading `routes[0]` here would throw instead.
+    if (routes === undefined || routes.length === 0)
+        return;
+    const primary = routes[0];
+    // The primary is not a substitution for itself, and every `substitution`
+    // value is read RELATIVE to it. A list whose first entry claims to be a
+    // cross-model substitute names no original to have substituted for.
+    if (primary.substitution !== 'same_model') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['authorizedRoutes', 0, 'substitution'],
+            message: 'the first authorized route is the primary and cannot be a substitution',
+        });
+    }
+    const primaryLine = modelLineOf(primary.modelReference);
+    // A request that named a concrete model is served or refused, never
+    // substituted, and one that PINNED a revision is served on exactly those
+    // weights. Both checks are on the primary, because a primary that already
+    // drifted makes every entry after it a substitution nobody labelled.
+    if (request.target.kind === 'model') {
+        const targetReference = request.target.modelReference;
+        const targetIsPinned = targetReference.includes('@');
+        if (targetIsPinned && primary.modelReference !== targetReference) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorizedRoutes', 0, 'modelReference'],
+                message: 'a pinned request is served on exactly the revision it pinned',
+            });
+        }
+        if (!targetIsPinned && primaryLine !== targetReference) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorizedRoutes', 0, 'modelReference'],
+                message: 'the primary authorized route must serve the model the request named',
+            });
+        }
+        if (targetIsPinned) {
+            for (const [index, route] of routes.entries()) {
+                if (route.substitution === 'cross_model') {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['authorizedRoutes', index, 'substitution'],
+                        message: 'a request that pinned a revision authorizes no cross-model substitute',
+                    });
+                }
+            }
+        }
+    }
+    for (const [index, route] of routes.entries()) {
+        const line = modelLineOf(route.modelReference);
+        // A mislabelled entry is the whole failure mode: `same_model` on a
+        // different model line is a substitution wearing the label that needs no
+        // authorization, and `cross_model` on the same line claims an
+        // authorization the customer never had to give.
+        if (route.substitution === 'same_model' && line !== primaryLine) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorizedRoutes', index, 'substitution'],
+                message: `route ${index} serves ${line}, not ${primaryLine}, so it is a cross-model substitute`,
+            });
+        }
+        if (route.substitution === 'cross_model' && line === primaryLine) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorizedRoutes', index, 'substitution'],
+                message: `route ${index} serves ${primaryLine}, so it is same-model failover`,
+            });
+        }
+    }
+    // Failing over to the deployment that just failed is not failover. The
+    // duplicate would also make `routeSwitches` count a switch that changed
+    // nothing.
+    const deployments = routes.map((route) => route.deploymentId);
+    if (new Set(deployments).size !== deployments.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['authorizedRoutes'],
+            message: 'each deployment appears at most once in the authorized route list',
+        });
+    }
 });

package/dist/esm/inference/routingPolicy.js

@@ -22,10 +22,17 @@
  * 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';
-import { inferenceProviderSlugSchema, inferenceRegionSchema, inferenceTimestampSchema, modelReferenceSchema, oxyAccountIdSchema, oxyApplicationIdSchema, routingProfileSlugSchema, } from './identifiers.js';
+import { deploymentIdSchema, inferenceProviderSlugSchema, inferenceRegionSchema, inferenceTimestampSchema, modelReferenceSchema, oxyAccountIdSchema, oxyApplicationIdSchema, routingProfileSlugSchema, } from './identifiers.js';
 import { exactDecimalSchema, currencyCodeSchema, unitPriceSchema } from './money.js';
 /**
  * What a policy resolves to when a caller names no model.
@@ -208,3 +215,75 @@ export const routingPolicyReferenceSchema = z
     policyVersion: z.number().int().positive().safe(),
 })
     .strict();
+/* -------------------------------------------------------------------------- */
+/*  Pre-authorized routes                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * What every authorized route carries, whichever kind it is.
+ *
+ * Exactly what EXECUTING a route needs, and nothing a policy could be
+ * re-derived from. There is no price, no data-retention flag, no licence id and
+ * no availability scope here: those are the values the control plane already
+ * evaluated to put this entry in the list, and repeating them would invite the
+ * data plane to evaluate them a second time — differently, in another language.
+ *
+ * `regions` is plural and matches `modelDeploymentSchema.regions`, because a
+ * deployment declares every region it MAY serve from and choosing among them is
+ * routing execution (ADR 0006). Oxy checked the whole set against the customer's
+ * residency controls as a SUBSET, so any region in this list is one the policy
+ * permits and the data plane's choice among them cannot escape it. Collapsing it
+ * to one region would make Oxy take a decision the boundary assigns elsewhere.
+ */
+const authorizedRouteFields = {
+    /** Which concrete endpoint. Opaque to customers; the data plane's own key. */
+    deploymentId: deploymentIdSchema,
+    /** Always revision-pinned: the entry names the exact weights to serve. */
+    modelReference: modelReferenceSchema,
+    provider: inferenceProviderSlugSchema,
+    regions: z.array(inferenceRegionSchema).min(1),
+};
+/**
+ * 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 const authorizedRouteSchema = z
+    .discriminatedUnion('substitution', [
+    z.object({ substitution: z.literal('same_model'), ...authorizedRouteFields }).strict(),
+    z
+        .object({
+        substitution: z.literal('cross_model'),
+        ...authorizedRouteFields,
+        /** Literal `true`: an unauthorized substitution cannot be expressed. */
+        authorizedByPolicy: z.literal(true),
+    })
+        .strict(),
+])
+    .superRefine((route, ctx) => {
+    // Same rule as `modelDeploymentSchema`: a route serves specific weights. An
+    // unpinned entry would leave the data plane choosing a revision, which is
+    // the one substitution the customer never authorized by naming a model.
+    if (!route.modelReference.includes('@')) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['modelReference'],
+            message: 'an authorized route must pin an immutable revision (<publisher>/<model>@<revision>)',
+        });
+    }
+});

package/dist/esm/inference/streamEvents.js

@@ -87,6 +87,33 @@ export const inferenceStreamToolCallEventSchema = z.object({
  * 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 const inferenceStreamUsageEventSchema = z.object({
     /** See `version.ts`: each stream event is a whole message on the wire. */
@@ -174,12 +201,22 @@ export const inferenceStreamErrorEventSchema = z.object({
     /** Carries its own `schemaVersion`: the same body is returned non-streaming. */
     error: inferenceErrorSchema,
 });
-/** Why generation stopped. */
+/**
+ * Why generation stopped.
+ *
+ * `refusal` and `content_filter` are separate members because they are separate
+ * events: the MODEL declining to answer is a property of the answer, while a
+ * filter is an upstream system removing one. The delta channels already carry
+ * that distinction (`channel: 'refusal'` beside the filter's own error code),
+ * so collapsing it here would have made the terminal event less specific than
+ * the stream that produced it.
+ */
 export const inferenceFinishReasonSchema = z.enum([
     'stop',
     'length',
     'tool_calls',
     'content_filter',
+    'refusal',
     'cancelled',
 ]);
 /**

package/dist/esm/inference/usage.js

@@ -118,7 +118,13 @@ export const inferenceRequestOutcomeSchema = z.enum([
     'failed',
 ]);
 /**
- * The data plane's technical account of one request.
+ * The data plane's technical account of one request, and the ONLY shape a
+ * settlement is written from.
+ *
+ * `inferenceStreamUsageEventSchema` is not a narrower version of this one that
+ * could be widened into it — see that event's own comment. Its units are exact
+ * and settleable; the record around them is not inferable, so an edge settling
+ * from a stream event supplies the outcome itself and never promotes the event.
  *
  * No money and no price: the data plane measures units and names the route it
  * used, and the control plane decides what that costs. Keeping the two apart is
@@ -134,6 +140,24 @@ export const inferenceRequestOutcomeSchema = z.enum([
  * nested `prompt_tokens`/`completion_tokens` verbatim charges the cached and
  * reasoning tokens twice, so subtracting the children out is part of what
  * "normalized" means in this shape's name.
+ *
+ * **A `completed` report carries at least one unit, and the other outcomes need
+ * not.** `completed` is the one outcome that asserts the customer received the
+ * whole answer, so "delivered in full, consumed nothing measurable" is a
+ * contradiction — and it is one that BILLS NOTHING: settlement prices every
+ * reported unit and sums, so an empty list is a free request produced by a
+ * provider that simply omitted its usage block. The refinement makes that shape
+ * unparseable, and the policy behind it is refuse-and-release: the report is
+ * rejected and the hold is released, never estimated and charged.
+ *
+ * The three other outcomes legitimately carry none, which is why the rule is
+ * conditional rather than a `.min(1)` on the field. In the reference data plane
+ * `failed` is DERIVED from having no units — `outcomeFor` in
+ * `internal/relay/executor.go` returns `partial` when units exist and `failed`
+ * when they do not — and `cancelled` is reported for a client that stopped
+ * before anything was measured. An unconditional minimum would refuse those
+ * reports, and a refused report is a request that ran, cost money upstream and
+ * can never be settled or refunded.
  */
 export const normalizedUsageReportSchema = z
     .object({
@@ -171,6 +195,13 @@ export const normalizedUsageReportSchema = z
             message: 'each unit is reported once, as a total',
         });
     }
+    if (report.outcome === 'completed' && report.units.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['units'],
+            message: 'a completed request consumed something; report at least one unit',
+        });
+    }
 });
 /* -------------------------------------------------------------------------- */
 /*  3. Receipt (settlement)                                                   */

package/dist/esm/inference/version.js

@@ -62,7 +62,20 @@
  * escapes, and the billing and entitlement records, where one is a second
  * number beside an exact amount.
  *
- * Decided in: docs/adr/0006-oxy-relay-boundary.md, docs/adr/0010-public-api-compatibility.md.
+ * A SIGNED document is strict at its top level for a third reason, and there it
+ * is forced rather than chosen. `aliaModelReleaseManifestSchema` carries
+ * signatures over its own canonical bytes, so a field stripped at this parse is a
+ * field missing from the bytes a verifier re-canonicalizes: a tolerant parse
+ * would report an invalid SIGNATURE where the truth is that this build does not
+ * understand the DOCUMENT. Its producer can run ahead of this package — Alia's
+ * release tooling is deployed independently — so the usual argument applies here
+ * and is outweighed, because the refusal costs an operator one retry after Oxy
+ * takes the newer contract, while the tolerant parse costs a misdiagnosis of a
+ * cryptographic failure.
+ *
+ * Decided in: docs/adr/0006-oxy-relay-boundary.md,
+ * docs/adr/0010-public-api-compatibility.md,
+ * docs/adr/0017-authorized-routes-in-the-envelope.md.
  */
 /**
  * Version of the contract SET as a whole — the value the control plane and the
@@ -71,12 +84,19 @@
  *
  * MAJOR is bumped when any individual shape's `schemaVersion` increments (at
  * least one message is now read differently by the two sides); MINOR when a
- * shape or an optional field is added; PATCH for documentation-only changes
- * that leave every parsed byte identical.
+ * shape or an optional field is added, when a CLOSED ENUM gains a member, or
+ * when a refinement changes which bytes parse; PATCH for documentation-only
+ * changes that leave every parsed byte identical.
+ *
+ * The last two are MINOR rather than PATCH because both produce the same
+ * failure: a producer on the newer set emits something the older set refuses,
+ * with no `schemaVersion` difference to explain it. A new enum member and a
+ * loosened refinement are exactly what the handshake exists to surface — a
+ * skew the per-message version cannot express.
  *
  * This constant is deliberately NOT embedded in the request envelope. Pinning a
  * request to the version of the whole set would make an unrelated additive
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export const INFERENCE_CONTRACT_VERSION = '1.0.0';
+export const INFERENCE_CONTRACT_VERSION = '1.2.0';