@oxyhq/contracts 0.26.0 → 0.28.0

package/dist/cjs/inference/attribution.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferenceAttributionSchema = exports.authenticatedPrincipalSchema = exports.billingPrincipalSchema = exports.inferenceScopeSchema = exports.INFERENCE_SCOPES = void 0;
+const zod_1 = require("zod");
+const identifiers_1 = require("./identifiers");
+/**
+ * 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.
+ */
+exports.INFERENCE_SCOPES = [
+    'inference:invoke',
+    'inference:models:read',
+    'inference:usage:read',
+    'inference:routing:read',
+    'inference:routing:write',
+    'inference:providers:read',
+    'inference:providers:write',
+];
+exports.inferenceScopeSchema = zod_1.z.enum(exports.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.
+ */
+exports.billingPrincipalSchema = zod_1.z
+    .object({
+    accountId: identifiers_1.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.
+ */
+exports.authenticatedPrincipalSchema = zod_1.z.object({
+    billing: exports.billingPrincipalSchema,
+    applicationId: identifiers_1.oxyApplicationIdSchema,
+    credentialId: identifiers_1.oxyCredentialIdSchema,
+    environment: identifiers_1.inferenceEnvironmentSchema,
+    inferenceScopes: zod_1.z.array(exports.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 OXY EDGE, on admission and before
+ * authentication completes, and is always present (ADR 0007). Not by the data
+ * plane: a data plane that minted the correlation key could not correlate a
+ * request it never received, and the requests rejected at the edge are exactly
+ * the ones an operator most needs to find.
+ *
+ * `generationId` is present once a generation exists, which is why it is
+ * optional on a request and expected on a receipt. That one IS the data plane's,
+ * because only the data plane knows how many outputs a request produced.
+ */
+exports.inferenceAttributionSchema = zod_1.z.object({
+    principal: exports.authenticatedPrincipalSchema,
+    userId: identifiers_1.delegatedUserIdSchema.optional(),
+    requestId: identifiers_1.requestIdSchema,
+    generationId: identifiers_1.generationIdSchema.optional(),
+});

package/dist/cjs/inference/catalogue.js

@@ -0,0 +1,482 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelCatalogueEntrySchema = exports.catalogueServingProviderSummarySchema = exports.cataloguePublisherSummarySchema = exports.routingProfileSchema = exports.routingProfileCandidateSchema = exports.modelDeploymentSchema = exports.inferenceProviderSchema = exports.modelRevisionSchema = exports.catalogueModelSchema = exports.modelPublisherSchema = exports.modelSafetyMetadataSchema = exports.modelEvaluationResultSchema = exports.modelDeprecationSchema = exports.commercialPermissionSchema = exports.availabilityScopeSchema = exports.inferenceDataPolicySchema = exports.modelProvenanceSchema = exports.modelLicenseSchema = exports.modelCapabilitiesSchema = exports.inferenceModalitySchema = void 0;
+const zod_1 = require("zod");
+const identifiers_1 = require("./identifiers");
+const priceVersion_1 = require("./priceVersion");
+/* -------------------------------------------------------------------------- */
+/*  Shared catalogue vocabulary                                               */
+/* -------------------------------------------------------------------------- */
+/** The modalities a model can consume or produce. */
+exports.inferenceModalitySchema = zod_1.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.
+ */
+exports.modelCapabilitiesSchema = zod_1.z
+    .object({
+    inputModalities: zod_1.z.array(exports.inferenceModalitySchema).min(1),
+    outputModalities: zod_1.z.array(exports.inferenceModalitySchema).min(1),
+    tools: zod_1.z.boolean(),
+    parallelToolCalls: zod_1.z.boolean(),
+    structuredOutput: zod_1.z.boolean(),
+    jsonMode: zod_1.z.boolean(),
+    reasoning: zod_1.z.boolean(),
+    streaming: zod_1.z.boolean(),
+    promptCaching: zod_1.z.boolean(),
+    maxContextTokens: zod_1.z.number().int().positive().safe(),
+    maxOutputTokens: zod_1.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.
+ */
+exports.modelLicenseSchema = zod_1.z
+    .object({
+    /** SPDX identifier where one exists, otherwise the publisher's own name. */
+    licenseId: zod_1.z.string().min(1).max(128),
+    displayName: zod_1.z.string().min(1).max(200),
+    url: identifiers_1.inferenceHttpsUrlSchema.optional(),
+    commercialUseAllowed: zod_1.z.boolean(),
+    requiresAttribution: zod_1.z.boolean(),
+    acceptableUsePolicyUrl: identifiers_1.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.
+ */
+exports.modelProvenanceSchema = zod_1.z
+    .object({
+    releaseKind: zod_1.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: identifiers_1.modelIdSchema.optional(),
+    trainingOrganization: zod_1.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.
+ */
+exports.inferenceDataPolicySchema = zod_1.z
+    .object({
+    retainsPayloads: zod_1.z.boolean(),
+    /** Zero when nothing is retained. */
+    retentionDays: zod_1.z.number().int().nonnegative().max(3650),
+    trainsOnCustomerData: zod_1.z.boolean(),
+    zeroDataRetentionAvailable: zod_1.z.boolean(),
+    /** Named subprocessors a payload may pass through, for compliance review. */
+    subprocessors: zod_1.z.array(zod_1.z.string().min(1).max(200)).default([]),
+    policyUrl: identifiers_1.inferenceHttpsUrlSchema.optional(),
+})
+    .strict()
+    .superRefine((policy, ctx) => {
+    if (!policy.retainsPayloads && policy.retentionDays > 0) {
+        ctx.addIssue({
+            code: zod_1.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: zod_1.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".
+ */
+exports.availabilityScopeSchema = zod_1.z.enum([
+    'internal_alia',
+    'public_payg',
+    'enterprise',
+    'byok_only',
+    'oxy_hosted',
+]);
+/** The commercial basis on which Oxy may serve a route. */
+exports.commercialPermissionSchema = zod_1.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. */
+exports.modelDeprecationSchema = zod_1.z
+    .object({
+    status: zod_1.z.enum(['active', 'deprecated', 'retired']),
+    replacementModelReference: identifiers_1.modelReferenceSchema.optional(),
+    announcedAt: identifiers_1.inferenceTimestampSchema.optional(),
+    sunsetAt: identifiers_1.inferenceTimestampSchema.optional(),
+})
+    .strict()
+    .superRefine((deprecation, ctx) => {
+    if (deprecation.status === 'active' && deprecation.sunsetAt !== undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['sunsetAt'],
+            message: 'an active model has no sunset date; announce the deprecation first',
+        });
+    }
+});
+/** One published evaluation result for a revision. */
+exports.modelEvaluationResultSchema = zod_1.z
+    .object({
+    suite: zod_1.z.string().min(1).max(128),
+    metric: zod_1.z.string().min(1).max(128),
+    /** Kept as a string: an eval score is published text, not arithmetic. */
+    score: zod_1.z.string().min(1).max(64),
+    evaluatedAt: identifiers_1.inferenceTimestampSchema.optional(),
+    reportUrl: identifiers_1.inferenceHttpsUrlSchema.optional(),
+})
+    .strict();
+/**
+ * Safety metadata a downstream developer needs, and the EU AI Act / GPAI
+ * documentation trail expects to find beside a served model.
+ */
+exports.modelSafetyMetadataSchema = zod_1.z
+    .object({
+    safetyCardUrl: identifiers_1.inferenceHttpsUrlSchema.optional(),
+    contentFilteringDefault: zod_1.z.enum(['none', 'provider_default', 'strict']),
+    knownLimitations: zod_1.z.array(zod_1.z.string().min(1).max(500)).default([]),
+    /** Content-provenance marking the modality requires, where it requires one. */
+    provenanceMarking: zod_1.z.enum(['none', 'visible_watermark', 'invisible_watermark', 'c2pa']),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  1. Publisher                                                              */
+/* -------------------------------------------------------------------------- */
+/** Who released a model. Never a provider, and never a routing profile. */
+exports.modelPublisherSchema = zod_1.z.object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: zod_1.z.literal(1),
+    publisherId: zod_1.z.string().min(1).max(128),
+    slug: identifiers_1.publisherSlugSchema,
+    displayName: zod_1.z.string().min(1).max(200),
+    description: zod_1.z.string().max(2000).optional(),
+    websiteUrl: identifiers_1.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.
+ */
+exports.catalogueModelSchema = zod_1.z
+    .object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: zod_1.z.literal(1),
+    modelId: identifiers_1.modelIdSchema,
+    publisher: identifiers_1.publisherSlugSchema,
+    slug: identifiers_1.modelSlugSchema,
+    displayName: zod_1.z.string().min(1).max(200),
+    description: zod_1.z.string().max(4000).optional(),
+    capabilities: exports.modelCapabilitiesSchema,
+    license: exports.modelLicenseSchema,
+    provenance: exports.modelProvenanceSchema,
+    knowledgeCutoff: identifiers_1.inferenceDateSchema.optional(),
+    releasedOn: identifiers_1.inferenceDateSchema.optional(),
+    /** The revision served when a caller names the model without pinning one. */
+    currentRevision: identifiers_1.modelRevisionLabelSchema,
+    deprecation: exports.modelDeprecationSchema,
+})
+    .superRefine((model, ctx) => {
+    if (model.modelId !== `${model.publisher}/${model.slug}`) {
+        ctx.addIssue({
+            code: zod_1.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 === identifiers_1.RESERVED_ALIA_PUBLISHER &&
+        model.provenance.releaseKind !== 'first_party_original' &&
+        model.provenance.releaseKind !== 'first_party_derived') {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['provenance', 'releaseKind'],
+            message: `the ${identifiers_1.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.
+ */
+exports.modelRevisionSchema = zod_1.z
+    .object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: zod_1.z.literal(1),
+    revisionId: zod_1.z.string().min(1).max(128),
+    modelId: identifiers_1.modelIdSchema,
+    revision: identifiers_1.modelRevisionLabelSchema,
+    reference: identifiers_1.modelReferenceSchema,
+    releasedAt: identifiers_1.inferenceTimestampSchema,
+    retiredAt: identifiers_1.inferenceTimestampSchema.optional(),
+    /** Digest of the served artifact, where Oxy hosts the weights itself. */
+    artifactDigest: zod_1.z
+        .string()
+        .regex(/^sha256:[a-f0-9]{64}$/, 'artifact digest must be sha256:<64 lowercase hex>')
+        .optional(),
+    modelCardUrl: identifiers_1.inferenceHttpsUrlSchema.optional(),
+    evaluations: zod_1.z.array(exports.modelEvaluationResultSchema).default([]),
+    safety: exports.modelSafetyMetadataSchema.optional(),
+})
+    .superRefine((revision, ctx) => {
+    if (revision.reference !== `${revision.modelId}@${revision.revision}`) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['reference'],
+            message: 'reference must be exactly <modelId>@<revision>',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  4. Inference provider                                                     */
+/* -------------------------------------------------------------------------- */
+/** Who runs the weights for a route. */
+exports.inferenceProviderSchema = zod_1.z.object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: zod_1.z.literal(1),
+    providerId: zod_1.z.string().min(1).max(128),
+    slug: identifiers_1.inferenceProviderSlugSchema,
+    displayName: zod_1.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: zod_1.z.enum(['third_party', 'oxy_hosted', 'customer_byok']),
+    websiteUrl: identifiers_1.inferenceHttpsUrlSchema.optional(),
+    statusPageUrl: identifiers_1.inferenceHttpsUrlSchema.optional(),
+    regions: zod_1.z.array(identifiers_1.inferenceRegionSchema).default([]),
+    dataPolicy: exports.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.
+ */
+exports.modelDeploymentSchema = zod_1.z
+    .object({
+    /** See `version.ts`: exchanged with the data plane on its own. */
+    schemaVersion: zod_1.z.literal(1),
+    deploymentId: identifiers_1.deploymentIdSchema,
+    provider: identifiers_1.inferenceProviderSlugSchema,
+    /** Always revision-pinned: a deployment serves specific weights. */
+    modelReference: identifiers_1.modelReferenceSchema,
+    regions: zod_1.z.array(identifiers_1.inferenceRegionSchema).min(1),
+    dataPolicy: exports.inferenceDataPolicySchema,
+    availabilityScope: exports.availabilityScopeSchema,
+    commercialPermission: exports.commercialPermissionSchema,
+    status: zod_1.z.enum(['active', 'degraded', 'disabled', 'retired']),
+    /** Reserved capacity for one enterprise account rather than shared. */
+    dedicatedCapacity: zod_1.z.boolean(),
+    /** The price version customers are charged under on this route. */
+    priceVersionId: zod_1.z.string().min(1).max(128).optional(),
+})
+    .superRefine((deployment, ctx) => {
+    if (!deployment.modelReference.includes('@')) {
+        ctx.addIssue({
+            code: zod_1.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: zod_1.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: zod_1.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: zod_1.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. */
+exports.routingProfileCandidateSchema = zod_1.z
+    .object({
+    modelReference: identifiers_1.modelReferenceSchema,
+    /** Lower sorts first. Ties are broken by the profile's optimisation target. */
+    priority: zod_1.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.
+ */
+exports.routingProfileSchema = zod_1.z.object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: zod_1.z.literal(1),
+    routingProfileId: zod_1.z.string().min(1).max(128),
+    slug: identifiers_1.routingProfileSlugSchema,
+    displayName: zod_1.z.string().min(1).max(200),
+    description: zod_1.z.string().max(2000).optional(),
+    /** What the profile optimises for when several candidates qualify. */
+    optimiseFor: zod_1.z.enum(['price', 'latency', 'throughput', 'quality', 'balanced']),
+    candidates: zod_1.z.array(exports.routingProfileCandidateSchema).min(1),
+    /** A product preset (Alia's "fast" toggle) rather than a customer's own profile. */
+    isProductPreset: zod_1.z.boolean(),
+});
+/* -------------------------------------------------------------------------- */
+/*  Customer-safe catalogue projection                                        */
+/* -------------------------------------------------------------------------- */
+/** The publisher fields a customer sees beside a model. */
+exports.cataloguePublisherSummarySchema = zod_1.z
+    .object({
+    slug: identifiers_1.publisherSlugSchema,
+    displayName: zod_1.z.string().min(1).max(200),
+    websiteUrl: identifiers_1.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.
+ */
+exports.catalogueServingProviderSummarySchema = zod_1.z
+    .object({
+    slug: identifiers_1.inferenceProviderSlugSchema,
+    displayName: zod_1.z.string().min(1).max(200),
+    regions: zod_1.z.array(identifiers_1.inferenceRegionSchema).default([]),
+    dataPolicy: exports.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.
+ */
+exports.modelCatalogueEntrySchema = zod_1.z.object({
+    /** See `version.ts`: this is the public catalogue response shape. */
+    schemaVersion: zod_1.z.literal(1),
+    modelId: identifiers_1.modelIdSchema,
+    publisher: exports.cataloguePublisherSummarySchema,
+    displayName: zod_1.z.string().min(1).max(200),
+    description: zod_1.z.string().max(4000).optional(),
+    currentRevision: identifiers_1.modelRevisionLabelSchema,
+    /** Revisions a customer may pin today, newest first. */
+    availableRevisions: zod_1.z.array(identifiers_1.modelRevisionLabelSchema).min(1),
+    capabilities: exports.modelCapabilitiesSchema,
+    license: exports.modelLicenseSchema,
+    provenance: exports.modelProvenanceSchema,
+    knowledgeCutoff: identifiers_1.inferenceDateSchema.optional(),
+    releasedOn: identifiers_1.inferenceDateSchema.optional(),
+    regions: zod_1.z.array(identifiers_1.inferenceRegionSchema).default([]),
+    servingProviders: zod_1.z.array(exports.catalogueServingProviderSummarySchema).default([]),
+    dataPolicy: exports.inferenceDataPolicySchema,
+    /** Absent for routes a customer cannot buy per-unit (BYOK-only, internal). */
+    pricing: priceVersion_1.priceSnapshotSchema.optional(),
+    availabilityScope: exports.availabilityScopeSchema,
+    commercialPermission: exports.commercialPermissionSchema,
+    deprecation: exports.modelDeprecationSchema,
+    evaluations: zod_1.z.array(exports.modelEvaluationResultSchema).default([]),
+    safety: exports.modelSafetyMetadataSchema.optional(),
+    modelCardUrl: identifiers_1.inferenceHttpsUrlSchema.optional(),
+});