@oxyhq/contracts 0.29.0 → 0.30.0

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. */

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
@@ -86,4 +99,4 @@
  * 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.1.0';
+export const INFERENCE_CONTRACT_VERSION = '1.2.0';