@oxyhq/contracts 0.26.0 → 0.28.0

package/dist/esm/inference/entitlement.js

@@ -0,0 +1,214 @@
+/**
+ * Product entitlements — the interface a first-party product (Alia) queries to
+ * learn what an account is entitled to, WITHOUT learning anything it could
+ * mistake for a balance.
+ *
+ * ## The separation this file is
+ *
+ * #972 states the failure mode outright: confusing a product subscription with
+ * pay-as-you-go inference usage. So the two live in disjoint shapes here, and
+ * the separation is structural rather than documented:
+ *
+ *  - {@link productEntitlementSchema} carries PLAN and ALLOWANCES. Allowances
+ *    are whole integer counts of a product entitlement (API credits, included
+ *    requests) — `z.number().int()`, never `exactDecimalSchema`, so an allowance
+ *    is not even the same TYPE as money and cannot be added to one.
+ *  - `accountBalanceSchema` (in `accountBilling.ts`) carries MONEY, as exact
+ *    decimal strings.
+ *
+ * There is no field anywhere that is both, and no schema that sums them. A
+ * consumer wanting "what can this account do right now" reads both sections and
+ * presents both; a consumer that only wanted one is not handed the other in a
+ * form it can accidentally arithmetic.
+ *
+ * ## Allowances do not change what a request COSTS
+ *
+ * An Alia plan may include an allowance of inference. Oxy still records the
+ * exact underlying cost of every request against the account's ledger — the
+ * allowance is a PRODUCT-side entitlement that decides what Alia charges its
+ * user, not a discount applied to the receipt. That is why
+ * {@link productEntitlementSchema} names no price and no currency: a plan that
+ * could restate the cost of a request would be a second pricing authority, and
+ * a receipt has exactly one.
+ *
+ * ## Cost centres
+ *
+ * A first-party cost centre IS an Oxy project account — `users.kind` already has
+ * `project`, and an application's `ownerAccountId` already points at one. So a
+ * cost centre adds a LABEL and a slug to an account rather than a parallel
+ * hierarchy, which is the epic's "do not add a second organization model" rule
+ * applied to internal accounting.
+ *
+ * Decided in: docs/adr/0014-account-billing-and-entitlements.md.
+ */
+import { z } from 'zod';
+import { oxyAccountIdSchema } from './identifiers.js';
+import { billingModeSchema } from './accountBilling.js';
+import { currencyCodeSchema, exactDecimalSchema } from './money.js';
+/* -------------------------------------------------------------------------- */
+/*  Plans and allowances                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * The statuses a subscription may be mirrored in.
+ *
+ * All of the processor's, not just the ones this platform sells: a mirror that
+ * cannot represent what it mirrors freezes at its previous value, and a
+ * subscription the processor moved to `paused` would keep granting a plan
+ * nobody is paying for.
+ */
+export const PRODUCT_PLAN_STATUSES = [
+    'active',
+    'canceled',
+    'incomplete',
+    'incomplete_expired',
+    'past_due',
+    'paused',
+    'trialing',
+    'unpaid',
+];
+export const productPlanStatusSchema = z.enum(PRODUCT_PLAN_STATUSES);
+/**
+ * The statuses that mean the plan is LIVE.
+ *
+ * Exported because "is this entitlement in force" must have one answer across
+ * Oxy and every product consuming it — a consumer deriving its own list is how
+ * `past_due` comes to be honoured in one place and refused in another.
+ */
+export const LIVE_PRODUCT_PLAN_STATUSES = ['active', 'trialing'];
+/**
+ * One allowance included in a plan.
+ *
+ * `remaining` is optional and absent means "not metered against this allowance
+ * here" — NOT zero. A consumer that read an absent allowance as exhausted would
+ * refuse a user who has spent nothing.
+ */
+export const planAllowanceSchema = z
+    .object({
+    /** A stable machine name, e.g. `api_credits_per_month`. */
+    key: z.string().regex(/^[a-z][a-z0-9_]{0,62}$/),
+    /** Whole units included per period. Never money. */
+    included: z.number().int().nonnegative().safe(),
+    remaining: z.number().int().nonnegative().safe().optional(),
+})
+    .strict();
+/**
+ * The plan an account is on, if any.
+ *
+ * `price` is deliberately absent. What a customer pays for their plan is the
+ * processor's record and this platform's `billing_transactions`; restating it
+ * here would put a second price authority in the one interface whose whole job
+ * is to keep product pricing and inference cost apart.
+ */
+export const productPlanSchema = z
+    .object({
+    id: z.string().min(1).max(64),
+    name: z.string().min(1).max(120),
+    status: productPlanStatusSchema,
+    live: z.boolean(),
+    currentPeriodStart: z.string().datetime(),
+    currentPeriodEnd: z.string().datetime(),
+    cancelAtPeriodEnd: z.boolean(),
+    allowances: z.array(planAllowanceSchema),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Pay-as-you-go position                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * The account's inference-spend position, summarised for a product consumer.
+ *
+ * A REDUCTION of `accountBillingStateSchema`, not a copy: a product asking "may
+ * this account run another request" needs to know whether spending is possible
+ * and roughly how much room is left, and does not need the bucket breakdown.
+ * `promotionalBalance` and `purchasedBalance` are still separate — the rule that
+ * a grant and a purchase are never one number does not relax because the
+ * consumer is first-party.
+ */
+export const payAsYouGoEntitlementSchema = z
+    .object({
+    /** The account that actually pays — the nearest ancestor with a profile. */
+    billingAccountId: oxyAccountIdSchema,
+    currency: currencyCodeSchema,
+    billingMode: billingModeSchema,
+    purchasedBalance: exactDecimalSchema,
+    promotionalBalance: exactDecimalSchema,
+    availableToSpend: exactDecimalSchema,
+    /** False when the profile is suspended, closed, or out of room. */
+    canSpend: z.boolean(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Cost centres                                                              */
+/* -------------------------------------------------------------------------- */
+export const COST_CENTER_STATUSES = ['active', 'retired'];
+export const costCenterStatusSchema = z.enum(COST_CENTER_STATUSES);
+/**
+ * An internal cost centre — an Oxy account that first-party spend is attributed
+ * to, with a stable slug so a report can name it without an id.
+ *
+ * The account IS the cost centre; this shape only labels it. There is no
+ * `parentId` here for the same reason: the account graph already has one, and a
+ * second parent link would be a second hierarchy that can disagree with it.
+ */
+export const costCenterSchema = z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: z.literal(1),
+    accountId: oxyAccountIdSchema,
+    slug: z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
+    label: z.string().min(1).max(120),
+    status: costCenterStatusSchema,
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+})
+    .strict();
+/**
+ * What one cost centre spent over a window.
+ *
+ * `billedAmount` comes from settled receipts — the FINANCIAL ledger — never from
+ * telemetry sums, per #972 workstream 8. `requestCount` is a count of receipts,
+ * so the two are always about the same set of rows.
+ */
+export const costCenterSpendSchema = z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: z.literal(1),
+    costCenter: costCenterSchema,
+    currency: currencyCodeSchema,
+    periodStart: z.string().datetime(),
+    periodEnd: z.string().datetime(),
+    billedAmount: exactDecimalSchema,
+    requestCount: z.number().int().nonnegative().safe(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  The interface Alia queries                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Everything a product needs to decide what an account may do, in one read.
+ *
+ * The three sections never merge:
+ *
+ *  - `plan` + `allowances` — the product subscription.
+ *  - `payAsYouGo` — inference money. `null` when the account has no billing
+ *    profile anywhere up its ancestry, which is a REAL and distinct state from a
+ *    zero balance: nobody has decided who pays for this account yet.
+ *  - `costCenter` — where first-party spend is booked, `null` for a customer.
+ */
+export const productEntitlementSchema = z
+    .object({
+    /** See `version.ts`: this shape is served to Console and to Alia. */
+    schemaVersion: z.literal(1),
+    accountId: oxyAccountIdSchema,
+    plan: productPlanSchema.nullable(),
+    /**
+     * Allowances in force right now, whether they came from a plan or from the
+     * platform's own free tier. Whole counts; never money.
+     */
+    allowances: z.array(planAllowanceSchema),
+    payAsYouGo: payAsYouGoEntitlementSchema.nullable(),
+    costCenter: costCenterSchema.nullable(),
+    /** When this view was computed. Entitlements are eventually consistent. */
+    resolvedAt: z.string().datetime(),
+})
+    .strict();

package/dist/esm/inference/errors.js

@@ -0,0 +1,207 @@
+/**
+ * Inference errors and retryability.
+ *
+ * One closed set of codes, shared by the Oxy public edge, the data plane and
+ * every SDK.
+ * Closed because the alternative — a free-form `code` string — makes a client's
+ * error handling a guess about the producer's spelling, and makes "is this
+ * worth retrying" a decision every consumer re-derives from prose.
+ *
+ * Retryability is carried explicitly and is CONSTRAINED by the code: a code
+ * that can never succeed on a bare retry (an invalid request, a denied
+ * permission, an insufficient balance) cannot claim `retryable: true`. Without
+ * that constraint the field is advisory, and one producer setting it optimistically
+ * turns every client into a retry storm against a request that will never pass.
+ *
+ * The provider passthrough exists so a customer can see what the upstream said
+ * without Oxy having to interpret every provider's error vocabulary — but it is
+ * the single most likely place for an upstream credential to escape, because
+ * provider errors routinely echo the request that caused them. It is therefore
+ * a `.strict()` object of four fields with no room for headers or a request
+ * body, and its free text is refused if it looks like it contains a credential.
+ *
+ * Decided in: docs/adr/0010-public-api-compatibility.md.
+ */
+import { z } from 'zod';
+import { inferenceProviderSlugSchema, requestIdSchema } from './identifiers.js';
+/**
+ * The closed set of inference error codes.
+ *
+ * Grouped by who must act: the caller (`invalid_request` … `idempotency_conflict`),
+ * the account owner (`insufficient_balance`, `spending_limit_exceeded`,
+ * `quota_exceeded`, `byok_credential_invalid`), routing/permission policy
+ * (`policy_violation`, `commercial_permission_denied`, `no_route_available`),
+ * and the platform or its upstreams (everything from `deployment_unavailable`).
+ *
+ * The platform group is NOT uniformly retryable, and that is the point of
+ * `provider_credential_invalid` sitting in it: an upstream that refuses the
+ * PLATFORM's own credential fails every identical retry until an operator
+ * rotates a key, so classifying it as `provider_error` would send every client
+ * into a retry loop against a request that cannot succeed.
+ */
+export const INFERENCE_ERROR_CODES = [
+    'invalid_request',
+    'authentication_failed',
+    'permission_denied',
+    'insufficient_scope',
+    'model_not_found',
+    'unsupported_modality',
+    'context_length_exceeded',
+    'request_too_large',
+    'output_limit_exceeded',
+    'idempotency_conflict',
+    'insufficient_balance',
+    'spending_limit_exceeded',
+    'quota_exceeded',
+    'byok_credential_invalid',
+    'policy_violation',
+    'commercial_permission_denied',
+    'no_route_available',
+    'upstream_content_filtered',
+    'cancelled',
+    'rate_limited',
+    'deployment_unavailable',
+    'provider_error',
+    'provider_timeout',
+    'provider_overloaded',
+    'provider_credential_invalid',
+    'service_unavailable',
+    'internal_error',
+];
+export const inferenceErrorCodeSchema = z.enum(INFERENCE_ERROR_CODES);
+/**
+ * Codes for which an identical retried request cannot succeed.
+ *
+ * `rate_limited` and `quota_exceeded` sit on opposite sides of this line
+ * deliberately: a rate limit clears on its own within the window the response
+ * names, while a quota is an account-level ceiling that only a human raises.
+ * `cancelled` is here because the caller already withdrew the request; a client
+ * that retries it is contradicting its own cancellation.
+ *
+ * `byok_credential_invalid` and `provider_credential_invalid` are the same
+ * failure seen from the two sides of the BYOK boundary — the customer's own
+ * upstream credential and the platform's — and they are two codes rather than
+ * one because only the first names an action the customer can take. Both are
+ * non-retryable for the same reason: a credential an upstream has refused keeps
+ * being refused until somebody replaces it.
+ */
+export const NON_RETRYABLE_INFERENCE_ERROR_CODES = [
+    'invalid_request',
+    'authentication_failed',
+    'permission_denied',
+    'insufficient_scope',
+    'model_not_found',
+    'unsupported_modality',
+    'context_length_exceeded',
+    'request_too_large',
+    'output_limit_exceeded',
+    'idempotency_conflict',
+    'insufficient_balance',
+    'spending_limit_exceeded',
+    'quota_exceeded',
+    'byok_credential_invalid',
+    'policy_violation',
+    'commercial_permission_denied',
+    'no_route_available',
+    'upstream_content_filtered',
+    'cancelled',
+    'provider_credential_invalid',
+];
+const NON_RETRYABLE_CODE_SET = new Set(NON_RETRYABLE_INFERENCE_ERROR_CODES);
+/**
+ * Text that looks like it carries a credential.
+ *
+ * A deliberately narrow set of literal markers — the shapes upstream providers
+ * actually echo — rather than an entropy heuristic, which would reject
+ * legitimate error text (a request id, a base64 image fragment) and teach
+ * producers to strip messages until they pass.
+ */
+const CREDENTIAL_LIKE_TEXT = /(?:bearer\s+[a-z0-9._~+/=-]{8,}|authorization\s*[:=]|api[_-]?key\s*[:=]|\bsk-[a-z0-9_-]{8,}|\bsk_(?:live|test)_[a-z0-9]{8,})/i;
+/**
+ * Free text that is safe to hand a customer: bounded, and refused outright if a
+ * credential marker appears in it. Applied to BOTH the Oxy message and the
+ * upstream one — a leak is no less a leak for having been written by a provider.
+ */
+export const safeErrorTextSchema = z
+    .string()
+    .min(1)
+    .max(2000)
+    .refine((value) => !CREDENTIAL_LIKE_TEXT.test(value), 'error text must not contain credential-shaped material');
+/**
+ * A coarse classification of an upstream failure (ADR 0010's `upstreamCategory`).
+ *
+ * Distinct from {@link providerErrorPassthroughSchema}, which carries the
+ * upstream's OWN code and text: this is Oxy's reading of what kind of failure it
+ * was, in a vocabulary that is the same across every provider, so a client can
+ * branch on it without knowing who served the request.
+ */
+export const upstreamErrorCategorySchema = z.enum([
+    'rate_limit',
+    'quota',
+    'timeout',
+    'overloaded',
+    'server_error',
+    'content_filter',
+    'invalid_request',
+    'authentication',
+    'unknown',
+]);
+/**
+ * What the upstream provider said, reduced to the four fields a customer can
+ * act on.
+ *
+ * `.strict()` is the security control here, not a tidiness preference: it means
+ * a producer cannot widen this by attaching `requestHeaders`, `curl`, `body` or
+ * `raw` and have it silently pass. Adding a field is a contract change with a
+ * version bump and a review, which is the point.
+ */
+export const providerErrorPassthroughSchema = z
+    .object({
+    provider: inferenceProviderSlugSchema,
+    /** The upstream HTTP status, when the upstream spoke HTTP. */
+    status: z.number().int().min(100).max(599).optional(),
+    /** The upstream's own error code, verbatim and uninterpreted. */
+    code: z.string().max(128).optional(),
+    /** The upstream's message, subject to the same credential refusal. */
+    message: safeErrorTextSchema.optional(),
+})
+    .strict();
+/**
+ * The error body every inference surface returns and every stream error event
+ * carries.
+ *
+ * `requestId` is always present — an error a customer cannot correlate with a
+ * log line is an error they have to reproduce to report.
+ */
+export const inferenceErrorSchema = z
+    .object({
+    /** See `version.ts`: this shape appears alone on the wire, so it is versioned. */
+    schemaVersion: z.literal(1),
+    code: inferenceErrorCodeSchema,
+    message: safeErrorTextSchema,
+    retryable: z.boolean(),
+    requestId: requestIdSchema,
+    /** How long to wait before retrying. Only meaningful when `retryable`. */
+    retryAfterMs: z.number().int().nonnegative().safe().optional(),
+    /** The request field at fault, for `invalid_request`. */
+    param: z.string().max(128).optional(),
+    /** Present only when an upstream provider was reached and failed. */
+    upstreamCategory: upstreamErrorCategorySchema.optional(),
+    providerError: providerErrorPassthroughSchema.optional(),
+})
+    .superRefine((error, ctx) => {
+    if (error.retryable && NON_RETRYABLE_CODE_SET.has(error.code)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['retryable'],
+            message: `${error.code} can never succeed on an identical retry, so it cannot be retryable`,
+        });
+    }
+    if (error.retryAfterMs !== undefined && !error.retryable) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['retryAfterMs'],
+            message: 'retryAfterMs tells a client when to retry, so it requires retryable: true',
+        });
+    }
+});

package/dist/esm/inference/identifiers.js

@@ -0,0 +1,194 @@
+/**
+ * Identifiers, references and wire primitives shared by every Oxy↔data-plane
+ * inference contract.
+ *
+ * Two kinds of identifier live here, and the difference matters:
+ *
+ *  - **Principal identifiers** owned by Oxy (`accountId`, `applicationId`,
+ *    `credentialId`, the optional delegated `userId`). The data plane may store
+ *    them as immutable references; it never owns, mints or mutates them.
+ *  - **Catalogue references** (`<publisher>/<model>`, `<publisher>/<model>@<revision>`,
+ *    a routing-profile slug). These are the strings a customer types, so their
+ *    grammar is part of the public contract, not an implementation detail.
+ *
+ * Platform-agnostic — zod only. Every regex here is plain ASCII: this package
+ * is imported by React Native apps running on Hermes, which rejects Unicode
+ * property escapes (`\p{…}`) at runtime.
+ *
+ * Decided in: docs/adr/0007-canonical-request-attribution.md, docs/adr/0008-catalogue-concept-separation.md.
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/*  Principal identifiers                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * An Oxy account id — the account that owns the workload and is financially
+ * responsible for it.
+ *
+ * Branded, and that brand is load-bearing rather than decorative: it is the
+ * type-level half of the rule that a delegated end-user identity can never
+ * become the billing identity (see {@link delegatedUserIdSchema} and
+ * `billingPrincipalSchema`). A plain `string` — and therefore any id read out
+ * of a header, a JWT claim or a request body — is not assignable to it; the
+ * only way to obtain one is to parse a value through this schema.
+ */
+export const oxyAccountIdSchema = z.string().min(1).max(64).brand();
+/**
+ * A delegated end-user identity (Alia's `X-Oxy-User-Id`), branded with a
+ * DIFFERENT brand from {@link oxyAccountIdSchema} so the two cannot be
+ * substituted for one another in either direction, in any consumer, without a
+ * cast that review would catch.
+ *
+ * It exists for attribution and product-side personalisation only. It is never
+ * a billing principal, never an access-control principal, and its presence
+ * never changes which account is charged.
+ */
+export const delegatedUserIdSchema = z.string().min(1).max(64).brand();
+/**
+ * An Oxy `Application._id`. Not branded: no invariant in this contract turns on
+ * confusing it with another id, and brand inflation costs every producer a
+ * parse call for no safety. The two ids above are branded because ADR 0007's
+ * rule is exactly that they must not be interchangeable.
+ */
+export const oxyApplicationIdSchema = z.string().min(1).max(64);
+/** An Oxy `ApplicationCredential._id` — the credential used for this request. */
+export const oxyCredentialIdSchema = z.string().min(1).max(64);
+/**
+ * A request id allocated by the Oxy EDGE, at admission and BEFORE
+ * authentication, so that a request rejected for a bad credential is as
+ * 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.
+ *
+ * Correlates the Oxy edge, the data plane, the financial ledger and the
+ * customer-visible receipt, so it appears on every stream event and every
+ * ledger record.
+ */
+export const requestIdSchema = z.string().min(1).max(128);
+/**
+ * A generation id generated by the data plane, present when a request produced
+ * a generation that can be looked up later (`GET /v1/generations/:id`).
+ */
+export const generationIdSchema = z.string().min(1).max(128);
+/**
+ * A caller-supplied idempotency key. Every reserve/settle/refund call is keyed
+ * on one so a retry, a redelivered event or a duplicated webhook can never
+ * charge twice.
+ */
+export const idempotencyKeySchema = z.string().min(1).max(255);
+/** Credential environments. A credential is issued into exactly one of them. */
+export const inferenceEnvironmentSchema = z.enum(['development', 'staging', 'production']);
+/* -------------------------------------------------------------------------- */
+/*  Wire primitives                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * An instant, as an ISO 8601 string in UTC (`2026-08-15T09:41:00.000Z`).
+ *
+ * Validated rather than left free-form — unlike the session contracts, which
+ * carry legacy expiry strings no consumer interprets, every instant here is
+ * read: a reservation expires, a price version starts applying, a receipt is
+ * settled. One canonical spelling (UTC, `Z`) so two records that describe the
+ * same moment compare and sort as equal, which a mix of offsets would not.
+ */
+export const inferenceTimestampSchema = z.string().datetime();
+/**
+ * A calendar DATE with no instant attached (`2026-05-01`) — a knowledge cutoff
+ * or a release date, which are published as days and become wrong when a
+ * timezone is invented for them.
+ */
+export const inferenceDateSchema = z
+    .string()
+    .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/, 'must be an ISO 8601 calendar date (YYYY-MM-DD)');
+/** An absolute https URL, for model cards, licenses and provider documentation. */
+export const inferenceHttpsUrlSchema = z
+    .string()
+    .max(2048)
+    .regex(/^https:\/\/[^\s]+$/, 'must be an absolute https URL');
+/* -------------------------------------------------------------------------- */
+/*  Catalogue references                                                      */
+/* -------------------------------------------------------------------------- */
+/** One path segment of a canonical model id: a lowercase, URL-safe slug. */
+const SLUG_PATTERN = '[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?';
+/** A revision label. Case-preserving, because upstream revisions often are. */
+const REVISION_PATTERN = '[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?';
+/** A publisher slug, e.g. `openai`, `anthropic`, `meta`, `alia`. */
+export const publisherSlugSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'publisher must be a lowercase URL-safe slug');
+/** A model slug within its publisher's namespace, e.g. `gpt-5`, `llama-3.1-70b`. */
+export const modelSlugSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'model must be a lowercase URL-safe slug');
+/**
+ * A canonical model id, `<publisher>/<model>`. This names a MODEL — a
+ * long-lived product identity whose behaviour changes as revisions ship. It
+ * does not name a revision, a deployment or a provider.
+ */
+export const modelIdSchema = z
+    .string()
+    .max(129)
+    .regex(new RegExp(`^${SLUG_PATTERN}/${SLUG_PATTERN}$`), 'model id must be <publisher>/<model>');
+/** An immutable revision label, unique within its model, e.g. `2026-05-01`. */
+export const modelRevisionLabelSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${REVISION_PATTERN}$`), 'revision must be a URL-safe label');
+/**
+ * A model reference as a customer writes it: `<publisher>/<model>` (the model's
+ * current revision, chosen by Oxy) or `<publisher>/<model>@<revision>` (an
+ * immutable revision the customer pinned).
+ *
+ * Both forms name a CONCRETE MODEL. Neither can name a routing profile — see
+ * {@link routingProfileSlugSchema} — which is what makes "a request for a
+ * concrete model is never silently replaced with a different model" a
+ * distinction the type system can carry rather than a convention.
+ */
+export const modelReferenceSchema = z
+    .string()
+    .max(194)
+    .regex(new RegExp(`^${SLUG_PATTERN}/${SLUG_PATTERN}(?:@${REVISION_PATTERN})?$`), 'model reference must be <publisher>/<model> or <publisher>/<model>@<revision>');
+/**
+ * A routing-profile slug, e.g. `auto`, `fast`, `quality`.
+ *
+ * Deliberately refuses a `/`, so a profile can never be written in the shape of
+ * a model id and no caller can be confused about whether they asked for a
+ * concrete model or for Oxy to choose one. Modes like `auto`/`fast`/`quality`
+ * are profiles or product presets; they are never model objects.
+ */
+export const routingProfileSlugSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'routing profile must be a lowercase URL-safe slug');
+/** An inference provider slug, e.g. `openai`, `bedrock`, `oxy-hosted`. */
+export const inferenceProviderSlugSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'provider must be a lowercase URL-safe slug');
+/**
+ * A deployment/endpoint id. Opaque to customers: which concrete endpoint served
+ * a request is the data plane's operational detail, and only the customer-safe
+ * subset of it is ever attributed back (see the catalogue's serving-boundary
+ * rules).
+ */
+export const deploymentIdSchema = z.string().min(1).max(128);
+/**
+ * A region identifier, e.g. `us-west-2`, `eu-central-1`. Free-form rather than
+ * a closed enum because the set is provider-defined and grows without any
+ * contract change; residency policies match on exact strings.
+ */
+export const inferenceRegionSchema = z
+    .string()
+    .max(64)
+    .regex(new RegExp(`^${SLUG_PATTERN}$`), 'region must be a lowercase URL-safe slug');
+/**
+ * The publisher namespace reserved for models Alia actually owns or derives.
+ *
+ * `alia/*` is never a re-badged third-party route and never a prompt preset —
+ * enforcing that is the job of `modelSchema`'s provenance refinement, which
+ * this constant exists to be checked against.
+ */
+export const RESERVED_ALIA_PUBLISHER = 'alia';