@oxyhq/contracts 0.25.0 → 0.27.0

package/dist/esm/inference/identifiers.js

@@ -0,0 +1,186 @@
+/**
+ * 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 generated by the data plane. 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';

package/dist/esm/inference/money.js

@@ -0,0 +1,142 @@
+/**
+ * Money and usage units for the inference contracts.
+ *
+ * The non-negotiable invariant this file exists to make structural: **customer
+ * charges never use floating-point values as the financial source of truth.**
+ * A JS `number` cannot represent `0.1 + 0.2` exactly, and an inference ledger
+ * adds millions of small amounts, so a float total is wrong by construction
+ * rather than by accident.
+ *
+ * Every amount and every price is one representation: {@link exactDecimalSchema},
+ * an exact decimal STRING at the scale ADR 0009 declares. Amounts are not
+ * integer minor units, and that is the ADR's decision rather than an oversight:
+ * one token costs several orders of magnitude less than one cent, so rounding
+ * per request would make a customer's bill depend on how their client chunked
+ * its work. Rounding happens ONCE, at the invoice boundary, and is itself a
+ * ledger entry.
+ *
+ * A string is also what the driver hands back — `postgres.js` decodes `NUMERIC`
+ * as a string — so keeping it a string on the wire means accidental JS
+ * arithmetic fails loudly instead of silently losing precision. Money
+ * arithmetic happens in SQL or in a decimal type, never in a JS `number`.
+ *
+ * Units are carried separately from money in every shape: a receipt says both
+ * "204 output tokens" and "0.003060000000 USD", and neither is derived from the
+ * other at read time. That separation is what lets a price version change
+ * without rewriting settled history.
+ *
+ * Decided in: docs/adr/0009-usage-reservation-and-settlement.md.
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/*  Money                                                                     */
+/* -------------------------------------------------------------------------- */
+/** ISO 4217 alpha-3 currency code, e.g. `USD`. */
+export const currencyCodeSchema = z
+    .string()
+    .regex(/^[A-Z]{3}$/, 'currency must be an ISO 4217 alpha-3 code');
+/**
+ * The declared fractional scale of every amount and price in this contract, and
+ * of the `NUMERIC` columns the ledger stores them in.
+ *
+ * Twelve digits is sub-minor-unit precision by a wide margin: at $3 per million
+ * input tokens, one token costs `0.000003000000`, which this scale represents
+ * exactly. Amounts are compared and summed NUMERICALLY, never as text — `3.0`
+ * and `3.000000000000` are one amount written two ways.
+ */
+export const INFERENCE_MONEY_SCALE = 12;
+/**
+ * An exact non-negative decimal, carried as a STRING so no parse step can turn
+ * it into a float on the way past. Up to 18 integer digits and
+ * {@link INFERENCE_MONEY_SCALE} fractional digits.
+ *
+ * Non-negative: direction is carried by the SHAPE — a receipt debits, a refund
+ * credits — so a stray sign can never silently invert an entry.
+ *
+ * No exponent form: `1e-6` and `0.000001` are the same number, but only one of
+ * them survives a naive string comparison, a cache key or a log grep intact.
+ *
+ * Branded, so a bare `string` is not assignable and an amount cannot arrive
+ * from string concatenation that was never checked. Producers construct one
+ * with `exactDecimalSchema.parse(value)`.
+ */
+export const exactDecimalSchema = z
+    .string()
+    .regex(/^(?:0|[1-9][0-9]{0,17})(?:\.[0-9]{1,12})?$/, 'must be an exact non-negative decimal string without an exponent')
+    .brand();
+/**
+ * An amount of money: the exact decimal plus the currency it is in.
+ *
+ * `.strict()` so a payload carrying a convenience float beside the exact value
+ * (`{ amount: '18.06', amountFloat: 18.06 }`) is REJECTED rather than stripped.
+ * A stripped float is the more dangerous outcome: it disappears silently here
+ * and survives in the producer, where it is the value somebody eventually
+ * displays.
+ */
+export const moneySchema = z
+    .object({
+    amount: exactDecimalSchema,
+    currency: currencyCodeSchema,
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  Usage units                                                               */
+/* -------------------------------------------------------------------------- */
+/**
+ * The closed set of units inference is metered in.
+ *
+ * Time is carried in integer MILLISECONDS rather than seconds so that no unit
+ * quantity is ever fractional: a 12.5-second transcription is `12500`, exactly,
+ * and the "units are integers" rule holds for every modality instead of holding
+ * for tokens and being quietly broken by audio.
+ */
+export const USAGE_UNITS = [
+    'input_tokens',
+    'cached_input_tokens',
+    'output_tokens',
+    'reasoning_tokens',
+    'requests',
+    'images',
+    'audio_input_milliseconds',
+    'audio_output_milliseconds',
+    'video_milliseconds',
+    'characters',
+    'embeddings',
+];
+export const usageUnitSchema = z.enum(USAGE_UNITS);
+/**
+ * A metered quantity of ONE unit. Never money — a quantity carries no price and
+ * no currency, so a consumer cannot mistake a token count for an amount owed.
+ */
+export const usageQuantitySchema = z
+    .object({
+    unit: usageUnitSchema,
+    quantity: z.number().int().nonnegative().safe(),
+})
+    .strict();
+/**
+ * Where a metered quantity came from.
+ *
+ * Kept explicit because the three are not interchangeable when a charge is
+ * disputed: `provider_reported` is the upstream's own count, `oxy_measured` is
+ * counted by the platform (streamed bytes, wall-clock milliseconds), and
+ * `estimated` is a reconstruction used when a provider returned no usage at
+ * all. An estimate that is indistinguishable from a reported number is an
+ * estimate nobody can later reconcile or refund against.
+ */
+export const USAGE_SOURCES = ['provider_reported', 'oxy_measured', 'estimated'];
+export const usageSourceSchema = z.enum(USAGE_SOURCES);
+/**
+ * A price for one unit, as `amount` per `per` units — `per` because a price
+ * quoted per single token would need more fractional digits than it is worth
+ * ("$3.00 per 1000000 input_tokens" is how every provider quotes it, and how
+ * every customer reads it).
+ */
+export const unitPriceSchema = z
+    .object({
+    unit: usageUnitSchema,
+    amount: exactDecimalSchema,
+    per: z.number().int().positive().safe(),
+    currency: currencyCodeSchema,
+})
+    .strict();

package/dist/esm/inference/priceVersion.js

@@ -0,0 +1,107 @@
+/**
+ * Price versions — the immutable snapshots customer pricing is quoted and
+ * settled against.
+ *
+ * A price is never edited in place. A change publishes a NEW version that
+ * supersedes the old one, and every settled receipt keeps the id of the version
+ * it was priced with. That is what makes an invoice reproducible a year later:
+ * the receipt does not say "3.00 per million tokens", it says "priced under
+ * `pv_2026_08`", and that version still exists, unchanged, with its own
+ * effective window.
+ *
+ * Prices are exact decimal strings (see `money.ts`), never floats, and they are
+ * quoted per unit. The amount a customer owes is computed from them and is
+ * carried in the same exact form, so no step of the calculation passes through
+ * a representation that cannot hold the value.
+ *
+ * Decided in: docs/adr/0009-usage-reservation-and-settlement.md.
+ */
+import { z } from 'zod';
+import { inferenceTimestampSchema, modelReferenceSchema, inferenceProviderSlugSchema, } from './identifiers.js';
+import { currencyCodeSchema, unitPriceSchema } from './money.js';
+/**
+ * Lifecycle of a price version.
+ *
+ * `draft` is quotable in Console previews but may never price a receipt;
+ * `active` is what live requests are priced with; `superseded` priced receipts
+ * in the past and still resolves for them forever.
+ */
+export const priceVersionStatusSchema = z.enum(['draft', 'active', 'superseded']);
+/**
+ * A published set of customer prices for one model reference on one provider.
+ *
+ * Scoped to a `(modelReference, provider)` pair rather than to a model alone
+ * because the same model costs different amounts on different providers, and a
+ * receipt has to be reproducible against the route that actually served it.
+ */
+export const priceVersionSchema = z
+    .object({
+    /** See `version.ts`: served on its own by the catalogue, so it is versioned. */
+    schemaVersion: z.literal(1),
+    priceVersionId: z.string().min(1).max(128),
+    status: priceVersionStatusSchema,
+    modelReference: modelReferenceSchema,
+    provider: inferenceProviderSlugSchema,
+    currency: currencyCodeSchema,
+    unitPrices: z.array(unitPriceSchema).min(1),
+    effectiveFrom: inferenceTimestampSchema,
+    /** Absent while this version is the current one. */
+    effectiveUntil: inferenceTimestampSchema.optional(),
+    /** The version this one replaced, absent for the first version of a route. */
+    supersedesPriceVersionId: z.string().min(1).max(128).optional(),
+    createdAt: inferenceTimestampSchema,
+})
+    .superRefine((priceVersion, ctx) => {
+    const units = priceVersion.unitPrices.map((price) => price.unit);
+    if (new Set(units).size !== units.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['unitPrices'],
+            message: 'a unit may be priced only once per price version',
+        });
+    }
+    for (const [index, price] of priceVersion.unitPrices.entries()) {
+        if (price.currency !== priceVersion.currency) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['unitPrices', index, 'currency'],
+                message: 'every unit price must be quoted in the price version currency',
+            });
+        }
+    }
+    // Compared as instants, not as strings: `…T00:00:00Z` and `…T00:00:00.000Z`
+    // are the same moment and sort differently as text.
+    if (priceVersion.effectiveUntil !== undefined &&
+        Date.parse(priceVersion.effectiveUntil) <= Date.parse(priceVersion.effectiveFrom)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['effectiveUntil'],
+            message: 'a price version must stop applying after it started applying',
+        });
+    }
+    // A superseded version priced requests during a window that has closed. Left
+    // open, it is indistinguishable from the current one when a receipt is
+    // re-priced years later — which is the one job this record exists to do.
+    if (priceVersion.status === 'superseded' && priceVersion.effectiveUntil === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['effectiveUntil'],
+            message: 'a superseded price version must record when it stopped applying',
+        });
+    }
+});
+/**
+ * The price snapshot a settled receipt keeps.
+ *
+ * The unit prices are COPIED onto the receipt, not just referenced, so a receipt
+ * remains readable even if the price version record is later archived, and so
+ * that a mistake in the copy is visible as a disagreement with the version it
+ * names rather than silently invisible.
+ */
+export const priceSnapshotSchema = z
+    .object({
+    priceVersionId: z.string().min(1).max(128),
+    currency: currencyCodeSchema,
+    unitPrices: z.array(unitPriceSchema).min(1),
+})
+    .strict();

package/dist/esm/inference/providerConnection.js

@@ -0,0 +1,139 @@
+/**
+ * BYOK provider connections — the metadata Oxy holds about a customer's own
+ * upstream provider credential.
+ *
+ * The credential itself is NOT here and cannot be put here. This shape carries
+ * a locator (`secretRef`) into Vault/KMS/managed secret storage, a prefix short
+ * enough to be useless, a fingerprint, and validation state. Two mechanisms
+ * make that structural rather than a convention somebody must remember:
+ *
+ *  - The object is `.strict()`. A producer that attaches `apiKey`, `secret`,
+ *    `token`, `privateKey` or `headers` fails the parse. Nothing is silently
+ *    stripped, because a stripped field is one that still exists upstream of
+ *    the parse, in a log line or an error report.
+ *  - `keyPrefix` is capped at 12 characters — shorter than any provider's
+ *    usable credential — so the one field designed to show part of a key cannot
+ *    be widened into showing all of it without changing the contract.
+ *
+ * BYOK does not move the billing relationship: the upstream provider bills the
+ * customer's own account directly, and Oxy charges only its platform fee. The
+ * record says so explicitly so a receipt against a BYOK route can be read
+ * correctly without consulting anything else.
+ *
+ * Decided in: issue #972 workstream 10.
+ */
+import { z } from 'zod';
+import { inferenceEnvironmentSchema, inferenceProviderSlugSchema, inferenceTimestampSchema, oxyAccountIdSchema, oxyApplicationIdSchema, } from './identifiers.js';
+/**
+ * How widely a connection applies.
+ *
+ * In the unified account graph a project IS an account, so `account` and
+ * `project` differ by INHERITANCE, not by id space: an `account` connection is
+ * inherited by every descendant project and application, a `project` one
+ * applies to that project account alone, and an `application` one to a single
+ * application. Recording which the customer chose is what makes a later
+ * "why did this app use that key" answerable.
+ */
+export const providerConnectionScopeSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('account'), accountId: oxyAccountIdSchema }).strict(),
+    z.object({ kind: z.literal('project'), accountId: oxyAccountIdSchema }).strict(),
+    z
+        .object({
+        kind: z.literal('application'),
+        accountId: oxyAccountIdSchema,
+        applicationId: oxyApplicationIdSchema,
+    })
+        .strict(),
+]);
+/**
+ * A locator for the credential in managed secret storage — never the credential.
+ *
+ * The scheme prefix is constrained to the stores Oxy actually uses, so a
+ * producer cannot pass a raw key through this field and have it look like a
+ * reference; whitespace is excluded for the same reason.
+ */
+export const providerSecretReferenceSchema = z
+    .string()
+    .max(512)
+    .regex(/^(?:vault|kms|ssm|secretsmanager):[A-Za-z0-9/_.:@-]{1,480}$/, 'a secret reference is a <store>:<locator> pointer, never credential material');
+/** Why a credential check failed, as a closed set the Console can render. */
+export const providerConnectionValidationSchema = z
+    .object({
+    state: z.enum(['unvalidated', 'valid', 'invalid', 'expired']),
+    lastValidatedAt: inferenceTimestampSchema.optional(),
+    /** Required when `invalid`: a failure nobody can act on is not a result. */
+    failureCode: z
+        .enum(['unauthorized', 'forbidden', 'not_found', 'rate_limited', 'network', 'unknown'])
+        .optional(),
+})
+    .strict();
+/** Lifecycle of a connection. `revoked` is terminal; `disabled` is reversible. */
+export const providerConnectionStatusSchema = z.enum([
+    'pending_validation',
+    'active',
+    'disabled',
+    'revoked',
+]);
+/**
+ * A customer's provider connection, without secrets.
+ *
+ * This is the whole of what Oxy stores, and the whole of what the data plane
+ * is given.
+ * Resolving `secretRef` to credential material happens in the secret store, at
+ * use time, in the data plane — never in a database row, an API response, a
+ * Console screen or a log line.
+ */
+export const providerConnectionSchema = z
+    .object({
+    /** See `version.ts`: exchanged with the data plane and rendered by Console. */
+    schemaVersion: z.literal(1),
+    connectionId: z.string().min(1).max(128),
+    provider: inferenceProviderSlugSchema,
+    /** The Oxy account that owns the connection and answers for its use. */
+    ownerAccountId: oxyAccountIdSchema,
+    scope: providerConnectionScopeSchema,
+    environment: inferenceEnvironmentSchema,
+    status: providerConnectionStatusSchema,
+    secretRef: providerSecretReferenceSchema,
+    /**
+     * The leading characters of the credential, for recognition only. Capped at
+     * 12 — long enough to tell two keys apart, far too short to be one.
+     */
+    keyPrefix: z.string().min(1).max(12),
+    /** SHA-256 of the credential, so rotation is verifiable without the key. */
+    fingerprint: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/, 'fingerprint must be 64 lowercase hex characters'),
+    validation: providerConnectionValidationSchema,
+    /**
+     * Always `true` for a BYOK connection: the provider bills the customer's own
+     * upstream account, and Oxy charges only its platform fee. Stated as data so
+     * a receipt against this route is readable without a second lookup.
+     */
+    upstreamBillsCustomerDirectly: z.literal(true),
+    /** Set when the provider's terms require a per-customer acknowledgement. */
+    termsAcknowledgedAt: inferenceTimestampSchema.optional(),
+    createdAt: inferenceTimestampSchema,
+    rotatedAt: inferenceTimestampSchema.optional(),
+})
+    .strict()
+    .superRefine((connection, ctx) => {
+    if (connection.validation.state === 'invalid' &&
+        connection.validation.failureCode === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['validation', 'failureCode'],
+            message: 'an invalid credential must record why the check failed',
+        });
+    }
+    // A credential the provider has rejected cannot be the one live requests are
+    // routed through: leaving it active turns every request on this route into a
+    // customer-visible upstream failure.
+    if (connection.status === 'active' && connection.validation.state === 'invalid') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['status'],
+            message: 'a connection whose credential failed validation cannot be active',
+        });
+    }
+});