@oxyhq/contracts 0.26.0 → 0.27.0

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

package/dist/cjs/inference/errors.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferenceErrorSchema = exports.providerErrorPassthroughSchema = exports.upstreamErrorCategorySchema = exports.safeErrorTextSchema = exports.NON_RETRYABLE_INFERENCE_ERROR_CODES = exports.inferenceErrorCodeSchema = exports.INFERENCE_ERROR_CODES = void 0;
+const zod_1 = require("zod");
+const identifiers_1 = require("./identifiers");
+/**
+ * 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`).
+ */
+exports.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',
+    'service_unavailable',
+    'internal_error',
+];
+exports.inferenceErrorCodeSchema = zod_1.z.enum(exports.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.
+ */
+exports.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',
+];
+const NON_RETRYABLE_CODE_SET = new Set(exports.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.
+ */
+exports.safeErrorTextSchema = zod_1.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.
+ */
+exports.upstreamErrorCategorySchema = zod_1.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.
+ */
+exports.providerErrorPassthroughSchema = zod_1.z
+    .object({
+    provider: identifiers_1.inferenceProviderSlugSchema,
+    /** The upstream HTTP status, when the upstream spoke HTTP. */
+    status: zod_1.z.number().int().min(100).max(599).optional(),
+    /** The upstream's own error code, verbatim and uninterpreted. */
+    code: zod_1.z.string().max(128).optional(),
+    /** The upstream's message, subject to the same credential refusal. */
+    message: exports.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.
+ */
+exports.inferenceErrorSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this shape appears alone on the wire, so it is versioned. */
+    schemaVersion: zod_1.z.literal(1),
+    code: exports.inferenceErrorCodeSchema,
+    message: exports.safeErrorTextSchema,
+    retryable: zod_1.z.boolean(),
+    requestId: identifiers_1.requestIdSchema,
+    /** How long to wait before retrying. Only meaningful when `retryable`. */
+    retryAfterMs: zod_1.z.number().int().nonnegative().safe().optional(),
+    /** The request field at fault, for `invalid_request`. */
+    param: zod_1.z.string().max(128).optional(),
+    /** Present only when an upstream provider was reached and failed. */
+    upstreamCategory: exports.upstreamErrorCategorySchema.optional(),
+    providerError: exports.providerErrorPassthroughSchema.optional(),
+})
+    .superRefine((error, ctx) => {
+    if (error.retryable && NON_RETRYABLE_CODE_SET.has(error.code)) {
+        ctx.addIssue({
+            code: zod_1.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: zod_1.z.ZodIssueCode.custom,
+            path: ['retryAfterMs'],
+            message: 'retryAfterMs tells a client when to retry, so it requires retryable: true',
+        });
+    }
+});