@oxyhq/contracts 0.29.0 → 0.30.0

package/dist/esm/identity.js

@@ -204,6 +204,37 @@ export const exportAttestationSchema = z.object({
     signature: z.string(),
     signedAt: z.number(),
 });
+export const exportUsageReceiptSchema = z.object({
+    receiptId: z.string(),
+    requestId: z.string(),
+    settledAt: z.string(),
+    billedAmount: z.string(),
+    currency: z.string(),
+    outcome: z.string(),
+    resolvedModelReference: z.string(),
+    servingProvider: z.string(),
+    platformFeeOnly: z.boolean(),
+});
+export const exportLedgerEntrySchema = z.object({
+    entryId: z.string(),
+    kind: z.string(),
+    currency: z.string(),
+    createdAt: z.string(),
+});
+export const exportUsageReservationSchema = z.object({
+    reservationId: z.string(),
+    requestId: z.string(),
+    status: z.string(),
+    reservedAmount: z.string(),
+    currency: z.string(),
+    createdAt: z.string(),
+    expiresAt: z.string(),
+});
+export const exportFinancialSectionSchema = z.object({
+    receipts: z.array(exportUsageReceiptSchema),
+    ledgerEntries: z.array(exportLedgerEntrySchema),
+    reservations: z.array(exportUsageReservationSchema),
+});
 export const exportBundleSchema = z.object({
     '$schema': z.string(),
     exportedAt: z.string(),
@@ -218,6 +249,7 @@ export const exportBundleSchema = z.object({
         following: z.array(z.string()),
         followers: z.array(z.string()),
     }),
+    financial: exportFinancialSectionSchema,
     attestation: exportAttestationSchema.nullable(),
     proof: exportAttestationSchema.optional(),
 });

package/dist/esm/index.js

@@ -30,7 +30,7 @@ export {
 recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, appAffinityEventTypeSchema, appAffinityEventSchema, appAffinityEventsIngestSchema, } from './recommendations.js';
 export { 
 // Schemas
-verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportBundleSchema, } from './identity.js';
+verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportUsageReceiptSchema, exportLedgerEntrySchema, exportUsageReservationSchema, exportFinancialSectionSchema, exportBundleSchema, } from './identity.js';
 export { 
 // Schemas
 oxySignedRecordTypeSchema, } from './oxyRecordTypes.js';
@@ -113,7 +113,7 @@ export {
 // are branded apart so a delegated end user can never become the payer.
 oxyAccountIdSchema, delegatedUserIdSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, generationIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, 
 // Wire primitives
-inferenceTimestampSchema, inferenceDateSchema, inferenceHttpsUrlSchema, 
+inferenceTimestampSchema, inferenceDateSchema, inferenceHttpsUrlSchema, sha256DigestSchema, 
 // Catalogue references
 publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers.js';
 export { 
@@ -134,7 +134,12 @@ inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProve
 export { 
 // Routing policy: every control, plus the refinement that rejects a policy
 // no route could ever satisfy.
-routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, } from './inference/routingPolicy.js';
+routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, 
+// What the data plane actually receives: the routes the policy authorized.
+authorizedRouteSchema, } from './inference/routingPolicy.js';
+export { 
+// The signed Alia model release manifest (ingestion contract; no endpoint).
+aliaReleaseArtifactSchema, aliaReleaseSignatureSchema, aliaModelReleaseManifestSchema, } from './inference/aliaModelRelease.js';
 export { 
 // The normalized Oxy→data-plane request envelope.
 inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, } from './inference/request.js';

package/dist/esm/inference/aliaModelRelease.js

@@ -0,0 +1,247 @@
+/**
+ * The signed Alia model release manifest — the ingestion contract for a
+ * first-party model release.
+ *
+ * The catalogue already STORES everything such a manifest carries: the model
+ * card, the licence block, the provenance and base model, the evaluation table,
+ * the safety metadata, and an artifact digest with a `sha256:<64 hex>` CHECK.
+ * What did not exist was the manifest itself — a single document Alia SIGNS,
+ * asserting all of it at once — and that is the gap this shape closes. Nothing
+ * here re-declares a catalogue field; the manifest COMPOSES the published shapes
+ * so a manifest and the catalogue row it produces cannot describe a release
+ * differently.
+ *
+ * ## The manifest tightens the revision it carries
+ *
+ * `modelRevisionSchema` makes `modelCardUrl`, `artifactDigest`, `evaluations`
+ * and `safety` optional, because a third-party route legitimately has none of
+ * them — Oxy did not train those weights and cannot publish a card for them. A
+ * FIRST-PARTY release has no such excuse: the documentation trail is the reason
+ * a release manifest exists at all, and a model Alia ships without one is not a
+ * release, it is a deployment. So the refinement below requires all four,
+ * without changing the catalogue shape that a third-party entry still parses
+ * through.
+ *
+ * ## `.strict()` at the top level, and here that is forced rather than chosen
+ *
+ * The shapes exchanged with the data plane tolerate an unknown field, because
+ * refusing a producer one minor version ahead is a worse failure than ignoring
+ * its addition (`version.ts`). A SIGNED document inverts that: the signature is
+ * over the canonical bytes of the manifest, so a field silently stripped at this
+ * parse is a field missing from the bytes Oxy re-canonicalizes, and verification
+ * fails. A tolerant parse would therefore report "the signature is invalid" for
+ * what is really "this build does not understand this manifest" — the wrong
+ * diagnosis of the right problem. Strict says the true thing, and the cost is
+ * bounded: ingestion is a release-time operation an operator retries once Oxy
+ * takes the newer contract, not a served request that becomes unsettleable.
+ *
+ * ## What is deliberately NOT here
+ *
+ * **No HTTP write path.** The catalogue's emptiness is currently a safety
+ * property — `scripts/seed-inference-catalogue.ts` refuses to invent a licence
+ * or a retention flag because "a plausible invented value in a catalogue is
+ * worse than an absent one" — and a staff write path into it with nothing to
+ * ingest is an unexercised hazard. The schema lands; the endpoint waits for a
+ * real manifest to ingest.
+ *
+ * **No `payloadDigest` field.** The signature is over the canonical
+ * serialization of this manifest with `signatures` removed, and a verifier
+ * recomputes it. Storing the digest beside the document it digests would be a
+ * second source of truth for one fact, and a verifier that compared the
+ * signature against the DECLARED digest rather than the recomputed one would
+ * verify nothing at all.
+ *
+ * **No verification RESULT.** Whether a signature checked out is Oxy's finding
+ * about the document, not a claim the document makes about itself; a `verified`
+ * field inside a signed manifest is the signer asserting its own signature.
+ *
+ * ## The open owner decision this shape does not take
+ *
+ * **What signs, and what verifies, is not decided.** Oxy holds no Alia signing
+ * key, and whether to resolve `keyId` through the existing attestation machinery
+ * (`services/oxyVerificationResolver.ts`, the civic attestation code) or to
+ * introduce a dedicated Alia release key is a real choice with different
+ * custody, rotation and revocation consequences. So `keyId` is an OPAQUE
+ * identifier and this file names no registry that resolves it: either answer
+ * fits, and neither is presupposed. Until it is answered a manifest can be
+ * parsed and cannot be verified, which is the second reason no endpoint ships.
+ *
+ * Decided in: docs/adr/0008-catalogue-concept-separation.md,
+ * docs/adr/0017-authorized-routes-in-the-envelope.md, issue #972 §12.
+ */
+import { z } from 'zod';
+import { modelLicenseSchema, modelProvenanceSchema, modelRevisionSchema, } from './catalogue.js';
+import { inferenceTimestampSchema, RESERVED_ALIA_PUBLISHER, sha256DigestSchema, } from './identifiers.js';
+/**
+ * One artifact of a release, by path and digest.
+ *
+ * `sizeBytes` is required beside the digest so a verifier can refuse a stream
+ * that is the wrong length before reading it to the end, rather than only after.
+ */
+export const aliaReleaseArtifactSchema = z
+    .object({
+    /** Path within the release, e.g. `model-00001-of-00004.safetensors`. */
+    path: z.string().min(1).max(512),
+    digest: sha256DigestSchema,
+    sizeBytes: z.number().int().positive().safe(),
+    mediaType: z.string().min(1).max(255).optional(),
+})
+    .strict();
+/**
+ * One detached signature over the manifest.
+ *
+ * `algorithm` is a CLOSED enum with one member, and both halves of that are
+ * deliberate. Closed, because a verifier that trusts a document's own algorithm
+ * name accepts whatever that document nominates, `none` included. One member,
+ * because Ed25519 is the scheme ADR 0012 already chose for asymmetric
+ * verification on this platform, and naming a scheme nothing here can check
+ * would be advertising a capability that does not exist. A second member lands
+ * when a verifier for it does — which is a closed enum gaining a member, and
+ * therefore a MINOR contract-set change the handshake surfaces (`version.ts`).
+ *
+ * `keyId` is opaque on purpose: see the header. It identifies the public key
+ * without saying what resolves it.
+ *
+ * The signature covers the canonical serialization (RFC 8785 JCS) of the
+ * manifest with `signatures` removed. The canonicalization is NAMED rather than
+ * left implicit because a digest over "the manifest" is not verifiable by two
+ * implementations that serialize JSON differently; naming it is a mechanical
+ * necessity and is independent of the open question of which key signs.
+ */
+export const aliaReleaseSignatureSchema = z
+    .object({
+    algorithm: z.enum(['ed25519']),
+    canonicalization: z.enum(['jcs']),
+    /** Opaque identifier of the public key. Resolving it is undecided. */
+    keyId: z.string().min(1).max(256),
+    /**
+     * Unpadded base64url. Exactly 86 characters, which is a 64-byte Ed25519
+     * signature — the one algorithm above. A second algorithm moves this length
+     * into a refinement keyed on `algorithm`.
+     */
+    signature: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{86}$/, 'signature must be a 64-byte ed25519 signature in unpadded base64url'),
+    signedAt: inferenceTimestampSchema,
+})
+    .strict();
+/**
+ * A signed release of an `alia/*` model revision.
+ *
+ * `signatures` is a LIST rather than one signature, because "what signs" is
+ * undecided: a single field would presuppose one signer, while a list lets an
+ * Alia release key and an existing attestation co-sign the same document without
+ * either being retrofitted later.
+ */
+export const aliaModelReleaseManifestSchema = z
+    .object({
+    /** See `version.ts`: an ingestion payload is a whole message on the wire. */
+    schemaVersion: z.literal(1),
+    /** The release's own identity, so ingestion is idempotent on it. */
+    releaseId: z.string().min(1).max(128),
+    issuedAt: inferenceTimestampSchema,
+    /**
+     * The revision being released. Carries its OWN `schemaVersion`, like
+     * `billingProfileSchema` inside `accountBillingStateSchema`: the manifest's
+     * version governs the manifest and the revision's governs the revision,
+     * which is two versions of two things rather than two versions of one.
+     */
+    revision: modelRevisionSchema,
+    /** On the MODEL rather than the revision in the catalogue, so carried here. */
+    provenance: modelProvenanceSchema,
+    license: modelLicenseSchema,
+    artifacts: z.array(aliaReleaseArtifactSchema).min(1),
+    signatures: z.array(aliaReleaseSignatureSchema).min(1),
+})
+    .strict()
+    .superRefine((manifest, ctx) => {
+    // The same rule `catalogueModelSchema` enforces on a model, applied to the
+    // carrier that creates one: `alia/*` names models Alia actually owns or
+    // derived, and a manifest is the document that would launder somebody else's
+    // weights into the namespace.
+    const publisher = manifest.revision.modelId.slice(0, manifest.revision.modelId.indexOf('/'));
+    if (publisher !== RESERVED_ALIA_PUBLISHER) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'modelId'],
+            message: `an Alia release manifest releases a ${RESERVED_ALIA_PUBLISHER}/* model`,
+        });
+    }
+    if (manifest.provenance.releaseKind !== 'first_party_original' &&
+        manifest.provenance.releaseKind !== 'first_party_derived') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['provenance', 'releaseKind'],
+            message: 'an Alia release manifest describes a first-party release',
+        });
+    }
+    // A derived model's base is the licence-attribution trail. Recording the
+    // derivation without naming what it derives from loses exactly the fact
+    // attribution needs.
+    if (manifest.provenance.releaseKind === 'first_party_derived' &&
+        manifest.provenance.baseModelId === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['provenance', 'baseModelId'],
+            message: 'a derived release names the model it derives from',
+        });
+    }
+    // The four fields a third-party catalogue entry may omit and a first-party
+    // release may not. See the header.
+    if (manifest.revision.modelCardUrl === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'modelCardUrl'],
+            message: 'a first-party release publishes a model card',
+        });
+    }
+    if (manifest.revision.safety === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'safety'],
+            message: 'a first-party release publishes its safety metadata',
+        });
+    }
+    if (manifest.revision.evaluations.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'evaluations'],
+            message: 'a first-party release publishes at least one evaluation result',
+        });
+    }
+    // The digest the catalogue will serve has to be one of the digests this
+    // manifest signed. Otherwise the signature covers a set of artifacts that
+    // does not include the weights anybody runs.
+    if (manifest.revision.artifactDigest === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'artifactDigest'],
+            message: 'a first-party release names the digest of the artifact it serves',
+        });
+    }
+    else if (!manifest.artifacts.some((artifact) => artifact.digest === manifest.revision.artifactDigest)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision', 'artifactDigest'],
+            message: 'the served artifact digest must appear among the signed artifacts',
+        });
+    }
+    const paths = manifest.artifacts.map((artifact) => artifact.path);
+    if (new Set(paths).size !== paths.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['artifacts'],
+            message: 'each artifact path appears once in a release',
+        });
+    }
+    // Two signatures from one key are one signature written twice, and a
+    // duplicate would make a "two independent signers" check pass on one signer.
+    const keyIds = manifest.signatures.map((signature) => signature.keyId);
+    if (new Set(keyIds).size !== keyIds.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['signatures'],
+            message: 'each signing key signs a manifest once',
+        });
+    }
+});

package/dist/esm/inference/catalogue.js

@@ -27,7 +27,7 @@
  * Decided in: docs/adr/0008-catalogue-concept-separation.md.
  */
 import { z } from 'zod';
-import { deploymentIdSchema, inferenceDateSchema, inferenceHttpsUrlSchema, inferenceProviderSlugSchema, inferenceRegionSchema, inferenceTimestampSchema, modelIdSchema, modelReferenceSchema, modelRevisionLabelSchema, modelSlugSchema, publisherSlugSchema, RESERVED_ALIA_PUBLISHER, routingProfileSlugSchema, } from './identifiers.js';
+import { deploymentIdSchema, inferenceDateSchema, inferenceHttpsUrlSchema, inferenceProviderSlugSchema, inferenceRegionSchema, inferenceTimestampSchema, modelIdSchema, modelReferenceSchema, modelRevisionLabelSchema, modelSlugSchema, publisherSlugSchema, RESERVED_ALIA_PUBLISHER, routingProfileSlugSchema, sha256DigestSchema, } from './identifiers.js';
 import { priceSnapshotSchema } from './priceVersion.js';
 /* -------------------------------------------------------------------------- */
 /*  Shared catalogue vocabulary                                               */
@@ -279,10 +279,7 @@ export const modelRevisionSchema = z
     releasedAt: inferenceTimestampSchema,
     retiredAt: inferenceTimestampSchema.optional(),
     /** Digest of the served artifact, where Oxy hosts the weights itself. */
-    artifactDigest: z
-        .string()
-        .regex(/^sha256:[a-f0-9]{64}$/, 'artifact digest must be sha256:<64 lowercase hex>')
-        .optional(),
+    artifactDigest: sha256DigestSchema.optional(),
     modelCardUrl: inferenceHttpsUrlSchema.optional(),
     evaluations: z.array(modelEvaluationResultSchema).default([]),
     safety: modelSafetyMetadataSchema.optional(),

package/dist/esm/inference/identifiers.js

@@ -59,8 +59,16 @@ export const oxyCredentialIdSchema = z.string().min(1).max(64);
  * traceable as one that was served (ADR 0007, and step 1 of ADR 0010's edge
  * order). It is required on the inbound envelope, which is what makes the data
  * plane a consumer of this id rather than its source: the data plane echoes it
- * on every stream event, on the usage report and on anything it can be asked
- * about later.
+ * on every stream event, on the usage report, in its response header and on
+ * anything it can be asked about later. It never mints one for a request it
+ * received.
+ *
+ * The one case that is NOT an exception to that: an envelope the data plane
+ * cannot read or authenticate carries no id to echo, so its rejection is
+ * labelled with an id of the data plane's own — visibly local, and never
+ * correlated with an Oxy request, because there is no Oxy request it belongs to.
+ * Saying so is what stops "consumer, not source" from being read as forbidding
+ * the only id such a rejection could have.
  *
  * Correlates the Oxy edge, the data plane, the financial ledger and the
  * customer-visible receipt, so it appears on every stream event and every
@@ -106,6 +114,18 @@ export const inferenceHttpsUrlSchema = z
     .string()
     .max(2048)
     .regex(/^https:\/\/[^\s]+$/, 'must be an absolute https URL');
+/**
+ * A content digest, `sha256:<64 lowercase hex>`.
+ *
+ * ONE spelling, because a digest is compared for equality and nothing else: an
+ * uppercase or unprefixed variant of the same hash is a different string, so two
+ * records describing the same bytes would not match. Lowercase hex with the
+ * algorithm prefix is what the `inference_model_revisions` CHECK stores and what
+ * every artifact registry emits.
+ */
+export const sha256DigestSchema = z
+    .string()
+    .regex(/^sha256:[a-f0-9]{64}$/, 'digest must be sha256:<64 lowercase hex>');
 /* -------------------------------------------------------------------------- */
 /*  Catalogue references                                                      */
 /* -------------------------------------------------------------------------- */

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',
+        });
+    }
 });