@oxyhq/contracts 0.26.0 → 0.27.0

package/dist/esm/accountGraph.js

@@ -14,9 +14,10 @@ import { z } from 'zod';
  * `db/schema/users.ts` mirrors to keep the `users_kind_check` CHECK honest.
  *
  * Deriving the union from the array instead would cost nothing here and be paid
- * by consumers: `kind` travels into `@oxyhq/services` through
- * `SwitchableAccount`, where an indexed-access type is materially more
- * expensive to check than a literal union.
+ * by consumers: `kind` travels into `@oxyhq/services` on every device-directory
+ * context (`deviceContextSchema.kind` → `DeviceContext` → the switcher rows),
+ * and an indexed-access type is materially more expensive to check there than a
+ * literal union.
  */
 export const ACCOUNT_KINDS = [
     'personal',

package/dist/esm/index.js

@@ -102,3 +102,48 @@ devicePairingStatusSchema, deviceTransferInitRequestSchema, deviceTransferInitRe
 export { 
 // Schemas — transparency log (checkpoints + inclusion proofs)
 transparencyCheckpointSignatureSchema, transparencyAnchorSchema, transparencyCheckpointSchema, transparencyInclusionProofSchema, transparencyCheckpointListSchema, } from './transparency.js';
+/* -------------------------------------------------------------------------- */
+/*  Inference (Oxy↔data-plane) — issue #972                                        */
+/* -------------------------------------------------------------------------- */
+export { 
+// The version of the contract SET; per-shape versions live in the data.
+INFERENCE_CONTRACT_VERSION, } from './inference/version.js';
+export { 
+// Principal identifiers. `oxyAccountIdSchema` and `delegatedUserIdSchema`
+// 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, 
+// Catalogue references
+publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers.js';
+export { 
+// Exact money and metered units — never floats, units never money.
+currencyCodeSchema, INFERENCE_MONEY_SCALE, exactDecimalSchema, moneySchema, USAGE_UNITS, usageUnitSchema, USAGE_SOURCES, usageSourceSchema, usageQuantitySchema, unitPriceSchema, } from './inference/money.js';
+export { 
+// Canonical attribution: who pays, which app, which credential, which user.
+INFERENCE_SCOPES, inferenceScopeSchema, billingPrincipalSchema, authenticatedPrincipalSchema, inferenceAttributionSchema, } from './inference/attribution.js';
+export { 
+// Closed error vocabulary + retryability + a leak-proof provider passthrough.
+INFERENCE_ERROR_CODES, NON_RETRYABLE_INFERENCE_ERROR_CODES, inferenceErrorCodeSchema, upstreamErrorCategorySchema, safeErrorTextSchema, providerErrorPassthroughSchema, inferenceErrorSchema, } from './inference/errors.js';
+export { 
+// Price versions and the snapshot a settled receipt keeps.
+priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion.js';
+export { 
+// The six distinct catalogue objects + the customer-safe projection.
+inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
+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';
+export { 
+// The normalized Oxy→data-plane request envelope.
+inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, } from './inference/request.js';
+export { 
+// Normalized SSE events.
+inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents.js';
+export { 
+// Reserve → settle → refund.
+usageReservationRequestSchema, usageReservationStatusSchema, usageReservationSchema, inferenceRequestOutcomeSchema, normalizedUsageReportSchema, usageReceiptSchema, usageRefundSubjectSchema, usageRefundReasonSchema, usageRefundSchema, } from './inference/usage.js';
+export { 
+// BYOK connection metadata that structurally cannot carry a secret.
+providerConnectionScopeSchema, providerSecretReferenceSchema, providerConnectionValidationSchema, providerConnectionStatusSchema, providerConnectionSchema, } from './inference/providerConnection.js';

package/dist/esm/inference/attribution.js

@@ -0,0 +1,98 @@
+/**
+ * Canonical attribution for an inference request.
+ *
+ * Every accepted request resolves to an Oxy account, an Oxy application, the
+ * Oxy credential that authenticated it, an optional delegated end user, and the
+ * ids that correlate it across the edge, the data plane and the ledger. The
+ * data plane may store these as immutable references; it never owns or mutates
+ * them, and it never mints a customer identity of its own.
+ *
+ * The rule this file encodes structurally, rather than restating in prose:
+ * **the delegated `userId` can never be the billing identity.** Two independent
+ * mechanisms enforce it, one at compile time and one at parse time, because a
+ * delegated identity being charged for somebody else's workload is the kind of
+ * mistake that produces a correct-looking invoice for the wrong customer:
+ *
+ *  1. `accountId` and `userId` carry DIFFERENT brands, so neither is assignable
+ *     to the other in any consumer without a cast.
+ *  2. {@link billingPrincipalSchema} is `.strict()` and holds exactly one field,
+ *     so a payload that smuggles `userId` into the billing block is rejected at
+ *     the parse rather than stripped and forgotten.
+ *
+ * These shapes are EMBEDDED — they ride inside a request envelope, a receipt or
+ * a ledger record and inherit its `schemaVersion`. Versioning them separately
+ * would let one message claim two versions.
+ *
+ * Decided in: docs/adr/0007-canonical-request-attribution.md.
+ */
+import { z } from 'zod';
+import { delegatedUserIdSchema, generationIdSchema, inferenceEnvironmentSchema, oxyAccountIdSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, } from './identifiers.js';
+/**
+ * The inference capability scopes the data plane needs to know about.
+ *
+ * A credential may carry many other Oxy scopes; only these cross the boundary,
+ * because the data plane's authorization questions are exactly "may this caller
+ * invoke", "may it read the catalogue", "may it read usage", "may it read or
+ * write routing", "may it read or write provider connections". Everything else
+ * is the control plane's business and is not the data plane's to hold.
+ */
+export const INFERENCE_SCOPES = [
+    'inference:invoke',
+    'inference:models:read',
+    'inference:usage:read',
+    'inference:routing:read',
+    'inference:routing:write',
+    'inference:providers:read',
+    'inference:providers:write',
+];
+export const inferenceScopeSchema = z.enum(INFERENCE_SCOPES);
+/**
+ * The financially responsible principal, and the ONLY identity a charge may be
+ * booked against.
+ *
+ * It is its own type — not a field on a larger principal object — precisely so
+ * that a function taking "who pays" cannot be handed a user, a session, a
+ * device or an application. It cannot be constructed from a delegated user id:
+ * the brands differ, and this object accepts no other key.
+ */
+export const billingPrincipalSchema = z
+    .object({
+    accountId: oxyAccountIdSchema,
+})
+    .strict();
+/**
+ * Who authenticated, as resolved by the Oxy edge before a request is forwarded.
+ *
+ * Mirrors what a verified Oxy service token carries (`appId`, `credentialId`,
+ * `ownerAccountId`, `environment`, effective scopes) so that the two
+ * authentication paths — a machine API key and a first-party service token —
+ * produce one shape downstream. The data plane authorizes against this
+ * envelope; it does not re-derive access from its own database, because it has
+ * no account graph to re-derive it from.
+ */
+export const authenticatedPrincipalSchema = z.object({
+    billing: billingPrincipalSchema,
+    applicationId: oxyApplicationIdSchema,
+    credentialId: oxyCredentialIdSchema,
+    environment: inferenceEnvironmentSchema,
+    inferenceScopes: z.array(inferenceScopeSchema),
+});
+/**
+ * The attribution block carried by every request, receipt and ledger record.
+ *
+ * `userId` is the OPTIONAL delegated end user — Alia's `X-Oxy-User-Id`. It is
+ * attribution only: it never changes which account is charged, never grants
+ * access, and lives outside {@link billingPrincipalSchema} so that no code path
+ * can read it as the payer.
+ *
+ * `requestId` is generated by the data plane and always present; `generationId`
+ * is present
+ * once a generation exists, which is why it is optional on a request and
+ * expected on a receipt.
+ */
+export const inferenceAttributionSchema = z.object({
+    principal: authenticatedPrincipalSchema,
+    userId: delegatedUserIdSchema.optional(),
+    requestId: requestIdSchema,
+    generationId: generationIdSchema.optional(),
+});

package/dist/esm/inference/catalogue.js

@@ -0,0 +1,479 @@
+/**
+ * The canonical model catalogue.
+ *
+ * Six things are kept DISTINCT here, because collapsing any pair of them is how
+ * a catalogue starts lying to customers:
+ *
+ *  1. **Publisher** — who released the model (`openai`, `meta`, `alia`).
+ *  2. **Model** — a long-lived product identity, `<publisher>/<model>`. Its
+ *     behaviour changes over time as revisions ship.
+ *  3. **Model revision** — an IMMUTABLE point in that history,
+ *     `<publisher>/<model>@<revision>`. This is what an evaluation result, a
+ *     model card and an artifact digest actually describe.
+ *  4. **Inference provider** — who runs the weights (a third party, Oxy's own
+ *     hosting, or the customer's own account under BYOK).
+ *  5. **Deployment/endpoint** — one concrete servable route: a revision, on a
+ *     provider, in a region, under a data policy, with a commercial permission.
+ *  6. **Routing profile** — a named strategy for CHOOSING among routes
+ *     (`auto`, `fast`, `quality`). A profile is not a model; it has no weights,
+ *     no revision and no license, and it is never written in the shape of a
+ *     model id.
+ *
+ * `modelCatalogueEntrySchema` is the customer-safe projection Oxy serves from
+ * `GET /v1/models`: it repeats the customer-facing fields rather than embedding
+ * the operational descriptors, so internal deployment ids, upstream wholesale
+ * costs and route health can never reach it by accident of nesting.
+ *
+ * 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 { priceSnapshotSchema } from './priceVersion.js';
+/* -------------------------------------------------------------------------- */
+/*  Shared catalogue vocabulary                                               */
+/* -------------------------------------------------------------------------- */
+/** The modalities a model can consume or produce. */
+export const inferenceModalitySchema = z.enum([
+    'text',
+    'image',
+    'audio',
+    'video',
+    'embedding',
+]);
+/**
+ * What a model can do, in the terms a caller has to decide against before
+ * sending a request: can it call tools, does it accept images, will it honour a
+ * JSON schema, how much context does it take, how much can it emit.
+ */
+export const modelCapabilitiesSchema = z
+    .object({
+    inputModalities: z.array(inferenceModalitySchema).min(1),
+    outputModalities: z.array(inferenceModalitySchema).min(1),
+    tools: z.boolean(),
+    parallelToolCalls: z.boolean(),
+    structuredOutput: z.boolean(),
+    jsonMode: z.boolean(),
+    reasoning: z.boolean(),
+    streaming: z.boolean(),
+    promptCaching: z.boolean(),
+    maxContextTokens: z.number().int().positive().safe(),
+    maxOutputTokens: z.number().int().positive().safe(),
+})
+    .strict();
+/**
+ * License terms, including the two questions that decide whether Oxy may serve
+ * a model to third parties at all: is commercial use permitted, and must the
+ * base model be attributed.
+ */
+export const modelLicenseSchema = z
+    .object({
+    /** SPDX identifier where one exists, otherwise the publisher's own name. */
+    licenseId: z.string().min(1).max(128),
+    displayName: z.string().min(1).max(200),
+    url: inferenceHttpsUrlSchema.optional(),
+    commercialUseAllowed: z.boolean(),
+    requiresAttribution: z.boolean(),
+    acceptableUsePolicyUrl: inferenceHttpsUrlSchema.optional(),
+})
+    .strict();
+/**
+ * How a model came to exist.
+ *
+ * `releaseKind` is what stops `alia/*` from becoming a re-badging namespace:
+ * a first-party namespace may only carry models Alia actually trained or
+ * derived, never a third-party route wearing an Oxy name.
+ */
+export const modelProvenanceSchema = z
+    .object({
+    releaseKind: z.enum([
+        'first_party_original',
+        'first_party_derived',
+        'open_weight',
+        'third_party_hosted',
+    ]),
+    /** The model this one was derived/fine-tuned from, where there is one. */
+    baseModelId: modelIdSchema.optional(),
+    trainingOrganization: z.string().min(1).max(200).optional(),
+})
+    .strict();
+/**
+ * What happens to the customer's prompts and responses on a given route.
+ *
+ * Every field here is enforceable by a routing policy, which is the reason they
+ * are structured rather than a prose paragraph on a docs page.
+ */
+export const inferenceDataPolicySchema = z
+    .object({
+    retainsPayloads: z.boolean(),
+    /** Zero when nothing is retained. */
+    retentionDays: z.number().int().nonnegative().max(3650),
+    trainsOnCustomerData: z.boolean(),
+    zeroDataRetentionAvailable: z.boolean(),
+    /** Named subprocessors a payload may pass through, for compliance review. */
+    subprocessors: z.array(z.string().min(1).max(200)).default([]),
+    policyUrl: inferenceHttpsUrlSchema.optional(),
+})
+    .strict()
+    .superRefine((policy, ctx) => {
+    if (!policy.retainsPayloads && policy.retentionDays > 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['retentionDays'],
+            message: 'a route that retains no payloads cannot have a retention window',
+        });
+    }
+    // Training requires having the data to train on. A route claiming both is
+    // reporting one of the two fields wrongly, and a routing policy that
+    // prohibits training would be enforced against a value that is not true.
+    if (!policy.retainsPayloads && policy.trainsOnCustomerData) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['trainsOnCustomerData'],
+            message: 'a route that retains no payloads cannot train on customer data',
+        });
+    }
+});
+/**
+ * Who a route may be served to. Availability inside Alia never implies
+ * permission to resell the same provider/model publicly, which is why this is
+ * an explicit scope on the route rather than a boolean derived from "it works".
+ */
+export const availabilityScopeSchema = z.enum([
+    'internal_alia',
+    'public_payg',
+    'enterprise',
+    'byok_only',
+    'oxy_hosted',
+]);
+/** The commercial basis on which Oxy may serve a route. */
+export const commercialPermissionSchema = z.enum([
+    'standard_application_use',
+    'public_resale_approved',
+    'wholesale_contract',
+    'customer_byok',
+    'open_weight_hosting',
+]);
+/** Deprecation state, with the replacement a customer should migrate to. */
+export const modelDeprecationSchema = z
+    .object({
+    status: z.enum(['active', 'deprecated', 'retired']),
+    replacementModelReference: modelReferenceSchema.optional(),
+    announcedAt: inferenceTimestampSchema.optional(),
+    sunsetAt: inferenceTimestampSchema.optional(),
+})
+    .strict()
+    .superRefine((deprecation, ctx) => {
+    if (deprecation.status === 'active' && deprecation.sunsetAt !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['sunsetAt'],
+            message: 'an active model has no sunset date; announce the deprecation first',
+        });
+    }
+});
+/** One published evaluation result for a revision. */
+export const modelEvaluationResultSchema = z
+    .object({
+    suite: z.string().min(1).max(128),
+    metric: z.string().min(1).max(128),
+    /** Kept as a string: an eval score is published text, not arithmetic. */
+    score: z.string().min(1).max(64),
+    evaluatedAt: inferenceTimestampSchema.optional(),
+    reportUrl: inferenceHttpsUrlSchema.optional(),
+})
+    .strict();
+/**
+ * Safety metadata a downstream developer needs, and the EU AI Act / GPAI
+ * documentation trail expects to find beside a served model.
+ */
+export const modelSafetyMetadataSchema = z
+    .object({
+    safetyCardUrl: inferenceHttpsUrlSchema.optional(),
+    contentFilteringDefault: z.enum(['none', 'provider_default', 'strict']),
+    knownLimitations: z.array(z.string().min(1).max(500)).default([]),
+    /** Content-provenance marking the modality requires, where it requires one. */
+    provenanceMarking: z.enum(['none', 'visible_watermark', 'invisible_watermark', 'c2pa']),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  1. Publisher                                                              */
+/* -------------------------------------------------------------------------- */
+/** Who released a model. Never a provider, and never a routing profile. */
+export const modelPublisherSchema = z.object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: z.literal(1),
+    publisherId: z.string().min(1).max(128),
+    slug: publisherSlugSchema,
+    displayName: z.string().min(1).max(200),
+    description: z.string().max(2000).optional(),
+    websiteUrl: inferenceHttpsUrlSchema.optional(),
+});
+/* -------------------------------------------------------------------------- */
+/*  2. Model                                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * A model: the long-lived product identity `<publisher>/<model>`.
+ *
+ * Carries no provider, no region, no price and no availability — those belong
+ * to a DEPLOYMENT, because the same model is served on several routes whose
+ * answers to those questions differ.
+ */
+export const catalogueModelSchema = z
+    .object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: z.literal(1),
+    modelId: modelIdSchema,
+    publisher: publisherSlugSchema,
+    slug: modelSlugSchema,
+    displayName: z.string().min(1).max(200),
+    description: z.string().max(4000).optional(),
+    capabilities: modelCapabilitiesSchema,
+    license: modelLicenseSchema,
+    provenance: modelProvenanceSchema,
+    knowledgeCutoff: inferenceDateSchema.optional(),
+    releasedOn: inferenceDateSchema.optional(),
+    /** The revision served when a caller names the model without pinning one. */
+    currentRevision: modelRevisionLabelSchema,
+    deprecation: modelDeprecationSchema,
+})
+    .superRefine((model, ctx) => {
+    if (model.modelId !== `${model.publisher}/${model.slug}`) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['modelId'],
+            message: 'modelId must be exactly <publisher>/<model>',
+        });
+    }
+    // `alia/*` is reserved for models Alia actually owns or derived. A provider
+    // alias published under it would make an Oxy-branded model id mean nothing,
+    // and would put an Oxy name on somebody else's weights and license.
+    if (model.publisher === RESERVED_ALIA_PUBLISHER &&
+        model.provenance.releaseKind !== 'first_party_original' &&
+        model.provenance.releaseKind !== 'first_party_derived') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['provenance', 'releaseKind'],
+            message: `the ${RESERVED_ALIA_PUBLISHER}/* namespace is reserved for first-party releases`,
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  3. Model revision                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * An immutable revision of a model.
+ *
+ * `reference` is the exact string a customer pins (`<publisher>/<model>@<revision>`)
+ * and is checked against its parts, so a record cannot claim a reference that
+ * resolves elsewhere. Evaluation and safety metadata hang here rather than on
+ * the model, because they describe specific weights.
+ */
+export const modelRevisionSchema = z
+    .object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: z.literal(1),
+    revisionId: z.string().min(1).max(128),
+    modelId: modelIdSchema,
+    revision: modelRevisionLabelSchema,
+    reference: modelReferenceSchema,
+    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(),
+    modelCardUrl: inferenceHttpsUrlSchema.optional(),
+    evaluations: z.array(modelEvaluationResultSchema).default([]),
+    safety: modelSafetyMetadataSchema.optional(),
+})
+    .superRefine((revision, ctx) => {
+    if (revision.reference !== `${revision.modelId}@${revision.revision}`) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['reference'],
+            message: 'reference must be exactly <modelId>@<revision>',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  4. Inference provider                                                     */
+/* -------------------------------------------------------------------------- */
+/** Who runs the weights for a route. */
+export const inferenceProviderSchema = z.object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: z.literal(1),
+    providerId: z.string().min(1).max(128),
+    slug: inferenceProviderSlugSchema,
+    displayName: z.string().min(1).max(200),
+    /**
+     * `customer_byok` means the customer's own upstream account is billed
+     * directly by the provider and Oxy charges only its platform fee.
+     */
+    kind: z.enum(['third_party', 'oxy_hosted', 'customer_byok']),
+    websiteUrl: inferenceHttpsUrlSchema.optional(),
+    statusPageUrl: inferenceHttpsUrlSchema.optional(),
+    regions: z.array(inferenceRegionSchema).default([]),
+    dataPolicy: inferenceDataPolicySchema,
+});
+/* -------------------------------------------------------------------------- */
+/*  5. Deployment / endpoint                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * One concrete servable route: a revision, on a provider, in some regions,
+ * under a data policy, with an availability scope and a commercial permission.
+ *
+ * This is the object a routing policy filters and a route switch names — never
+ * a model. Two deployments of the SAME revision are what same-model failover
+ * moves between; moving to a deployment of a different revision or model is a
+ * cross-model fallback and needs explicit authorization.
+ */
+export const modelDeploymentSchema = z
+    .object({
+    /** See `version.ts`: exchanged with the data plane on its own. */
+    schemaVersion: z.literal(1),
+    deploymentId: deploymentIdSchema,
+    provider: inferenceProviderSlugSchema,
+    /** Always revision-pinned: a deployment serves specific weights. */
+    modelReference: modelReferenceSchema,
+    regions: z.array(inferenceRegionSchema).min(1),
+    dataPolicy: inferenceDataPolicySchema,
+    availabilityScope: availabilityScopeSchema,
+    commercialPermission: commercialPermissionSchema,
+    status: z.enum(['active', 'degraded', 'disabled', 'retired']),
+    /** Reserved capacity for one enterprise account rather than shared. */
+    dedicatedCapacity: z.boolean(),
+    /** The price version customers are charged under on this route. */
+    priceVersionId: z.string().min(1).max(128).optional(),
+})
+    .superRefine((deployment, ctx) => {
+    if (!deployment.modelReference.includes('@')) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['modelReference'],
+            message: 'a deployment must pin an immutable revision (<publisher>/<model>@<revision>)',
+        });
+    }
+    // A technically callable route is not automatically publicly resellable.
+    // Publishing one to pay-as-you-go customers requires a permission state that
+    // says somebody reviewed the right to resell it, not merely that it answers.
+    if (deployment.availabilityScope === 'public_payg' &&
+        deployment.commercialPermission !== 'public_resale_approved' &&
+        deployment.commercialPermission !== 'wholesale_contract' &&
+        deployment.commercialPermission !== 'open_weight_hosting') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['commercialPermission'],
+            message: 'a public pay-as-you-go route requires an approved resale permission',
+        });
+    }
+    if (deployment.availabilityScope === 'byok_only' &&
+        deployment.commercialPermission !== 'customer_byok') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['commercialPermission'],
+            message: 'a BYOK-only route is served under the customer’s own provider terms',
+        });
+    }
+    // Pricing is what Oxy charges. A BYOK route bills the customer upstream and
+    // carries only a platform fee, which is not a per-unit model price.
+    if (deployment.priceVersionId !== undefined && deployment.availabilityScope === 'byok_only') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['priceVersionId'],
+            message: 'a BYOK-only route has no customer model price; the platform fee is separate',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  6. Routing profile                                                        */
+/* -------------------------------------------------------------------------- */
+/** One candidate a profile may resolve to, and how strongly it is preferred. */
+export const routingProfileCandidateSchema = z
+    .object({
+    modelReference: modelReferenceSchema,
+    /** Lower sorts first. Ties are broken by the profile's optimisation target. */
+    priority: z.number().int().nonnegative().max(1000),
+})
+    .strict();
+/**
+ * A named strategy for choosing among routes — `auto`, `fast`, `quality`.
+ *
+ * Not a model: it has no publisher, no revision, no license and no weights, and
+ * its slug cannot be written as `<publisher>/<model>`. A request that names a
+ * profile is asking Oxy to choose; a request that names a model is not, which is
+ * the distinction the "never silently substituted" invariant rests on.
+ */
+export const routingProfileSchema = z.object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: z.literal(1),
+    routingProfileId: z.string().min(1).max(128),
+    slug: routingProfileSlugSchema,
+    displayName: z.string().min(1).max(200),
+    description: z.string().max(2000).optional(),
+    /** What the profile optimises for when several candidates qualify. */
+    optimiseFor: z.enum(['price', 'latency', 'throughput', 'quality', 'balanced']),
+    candidates: z.array(routingProfileCandidateSchema).min(1),
+    /** A product preset (Alia's "fast" toggle) rather than a customer's own profile. */
+    isProductPreset: z.boolean(),
+});
+/* -------------------------------------------------------------------------- */
+/*  Customer-safe catalogue projection                                        */
+/* -------------------------------------------------------------------------- */
+/** The publisher fields a customer sees beside a model. */
+export const cataloguePublisherSummarySchema = z
+    .object({
+    slug: publisherSlugSchema,
+    displayName: z.string().min(1).max(200),
+    websiteUrl: inferenceHttpsUrlSchema.optional(),
+})
+    .strict();
+/**
+ * A serving provider as a customer may see it: who ran the request and where.
+ *
+ * Deliberately has no deployment id, no route id, no health score and no
+ * upstream cost — the customer-safe half of the serving boundary, so that
+ * exposing attribution can never leak operational topology.
+ */
+export const catalogueServingProviderSummarySchema = z
+    .object({
+    slug: inferenceProviderSlugSchema,
+    displayName: z.string().min(1).max(200),
+    regions: z.array(inferenceRegionSchema).default([]),
+    dataPolicy: inferenceDataPolicySchema,
+})
+    .strict();
+/**
+ * One entry of the customer-facing catalogue (`GET /v1/models`).
+ *
+ * A projection, not a container: it repeats the customer-facing fields instead
+ * of embedding the operational descriptors, so no internal identifier can reach
+ * a customer by being nested one level deeper than anybody looked.
+ */
+export const modelCatalogueEntrySchema = z.object({
+    /** See `version.ts`: this is the public catalogue response shape. */
+    schemaVersion: z.literal(1),
+    modelId: modelIdSchema,
+    publisher: cataloguePublisherSummarySchema,
+    displayName: z.string().min(1).max(200),
+    description: z.string().max(4000).optional(),
+    currentRevision: modelRevisionLabelSchema,
+    /** Revisions a customer may pin today, newest first. */
+    availableRevisions: z.array(modelRevisionLabelSchema).min(1),
+    capabilities: modelCapabilitiesSchema,
+    license: modelLicenseSchema,
+    provenance: modelProvenanceSchema,
+    knowledgeCutoff: inferenceDateSchema.optional(),
+    releasedOn: inferenceDateSchema.optional(),
+    regions: z.array(inferenceRegionSchema).default([]),
+    servingProviders: z.array(catalogueServingProviderSummarySchema).default([]),
+    dataPolicy: inferenceDataPolicySchema,
+    /** Absent for routes a customer cannot buy per-unit (BYOK-only, internal). */
+    pricing: priceSnapshotSchema.optional(),
+    availabilityScope: availabilityScopeSchema,
+    commercialPermission: commercialPermissionSchema,
+    deprecation: modelDeprecationSchema,
+    evaluations: z.array(modelEvaluationResultSchema).default([]),
+    safety: modelSafetyMetadataSchema.optional(),
+    modelCardUrl: inferenceHttpsUrlSchema.optional(),
+});