@oxyhq/contracts 0.26.0 → 0.28.0

package/dist/cjs/inference/streamEvents.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Normalized stream events — what the data plane emits and the Oxy edge
+ * forwards as SSE.
+ *
+ * One discriminated union, seven shapes, all carrying `requestId` and a
+ * monotonic `sequence`. `requestId` is on EVERY event rather than only the
+ * first because a proxy that re-frames or a client that reconnects would
+ * otherwise be holding events it cannot attribute; `sequence` is what makes a
+ * redelivered event detectable as a duplicate rather than as new output.
+ *
+ * The events are versioned INDIVIDUALLY (see `version.ts`): a stream is a long
+ * sequence of small messages from a producer that may be redeployed mid-stream,
+ * so the alternative — one version for the whole union — would force every
+ * event to move whenever any one of them changed.
+ *
+ * `route_switch` is the customer-visible receipt for an allowed re-route, and
+ * its shape carries the invariant: a switch to a DIFFERENT model can only be
+ * expressed with `authorizedByPolicy: true`, so an unauthorized substitution is
+ * not a thing the contract can say.
+ *
+ * Decided in: docs/adr/0010-public-api-compatibility.md, docs/adr/0008-catalogue-concept-separation.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferenceStreamEventSchema = exports.inferenceStreamDoneEventSchema = exports.inferenceFinishReasonSchema = exports.inferenceStreamErrorEventSchema = exports.inferenceStreamRouteSwitchEventSchema = exports.inferenceRouteSwitchReasonSchema = exports.inferenceRouteSwitchDetailSchema = exports.inferenceStreamUsageEventSchema = exports.inferenceStreamToolCallEventSchema = exports.inferenceStreamDeltaEventSchema = exports.inferenceStreamStartEventSchema = void 0;
+const zod_1 = require("zod");
+const identifiers_1 = require("./identifiers");
+const errors_1 = require("./errors");
+const money_1 = require("./money");
+/**
+ * The first event of every stream: what was actually resolved.
+ *
+ * Names the revision-pinned model and the serving provider, so a customer who
+ * asked for `<publisher>/<model>` learns which revision answered without having
+ * to wait for the receipt. Carries no deployment health, no route id and no
+ * upstream cost.
+ */
+exports.inferenceStreamStartEventSchema = zod_1.z.object({
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    type: zod_1.z.literal('start'),
+    requestId: identifiers_1.requestIdSchema,
+    sequence: zod_1.z.number().int().nonnegative().safe(),
+    generationId: identifiers_1.generationIdSchema.optional(),
+    /** Always revision-pinned, even when the request named only the model. */
+    resolvedModelReference: identifiers_1.modelReferenceSchema,
+    servingProvider: identifiers_1.inferenceProviderSlugSchema,
+    startedAt: identifiers_1.inferenceTimestampSchema,
+});
+/**
+ * A chunk of output.
+ *
+ * `channel` separates visible output from reasoning and refusals, because a
+ * client that renders reasoning as answer text is a product bug, not a display
+ * preference.
+ */
+exports.inferenceStreamDeltaEventSchema = zod_1.z.object({
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    type: zod_1.z.literal('delta'),
+    requestId: identifiers_1.requestIdSchema,
+    sequence: zod_1.z.number().int().nonnegative().safe(),
+    /** Which output of a multi-output response this chunk belongs to. */
+    outputIndex: zod_1.z.number().int().nonnegative().safe(),
+    channel: zod_1.z.enum(['output_text', 'reasoning', 'refusal']),
+    text: zod_1.z.string(),
+});
+/**
+ * A tool call being streamed.
+ *
+ * `argumentsDelta` accumulates; `complete` marks the call finished so a client
+ * knows when the accumulated JSON text is worth parsing.
+ */
+exports.inferenceStreamToolCallEventSchema = zod_1.z.object({
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    type: zod_1.z.literal('tool_call'),
+    requestId: identifiers_1.requestIdSchema,
+    sequence: zod_1.z.number().int().nonnegative().safe(),
+    toolCallId: zod_1.z.string().min(1).max(128),
+    /** Present on the first event of a call. */
+    name: zod_1.z.string().min(1).max(128).optional(),
+    argumentsDelta: zod_1.z.string().optional(),
+    complete: zod_1.z.boolean(),
+});
+/**
+ * Metered units for the request so far.
+ *
+ * Units only — no money. What a customer is charged is the ledger's answer,
+ * derived from these units and a price version at settlement; a cost quoted by
+ * the data plane would be a second, unauthoritative answer to the same
+ * question.
+ */
+exports.inferenceStreamUsageEventSchema = zod_1.z.object({
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    type: zod_1.z.literal('usage'),
+    requestId: identifiers_1.requestIdSchema,
+    sequence: zod_1.z.number().int().nonnegative().safe(),
+    units: zod_1.z.array(money_1.usageQuantitySchema).min(1),
+    usageSource: money_1.usageSourceSchema,
+});
+/**
+ * What kind of re-route happened.
+ *
+ * `deployment` is same-model failover: the same revision, served somewhere else.
+ * `model` is a substitution, and is expressible ONLY with
+ * `authorizedByPolicy: true` — the routing policy's `authorizedCrossModel` list
+ * is the only thing that can produce one, so "a concrete model was silently
+ * replaced" has no representation in this contract.
+ */
+exports.inferenceRouteSwitchDetailSchema = zod_1.z.discriminatedUnion('scope', [
+    zod_1.z
+        .object({
+        scope: zod_1.z.literal('deployment'),
+        modelReference: identifiers_1.modelReferenceSchema,
+        toProvider: identifiers_1.inferenceProviderSlugSchema,
+        toDeploymentId: identifiers_1.deploymentIdSchema.optional(),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        scope: zod_1.z.literal('model'),
+        /**
+         * The UNPINNED model line the customer asked for (`<publisher>/<model>`,
+         * never `@revision`). A request that pinned a revision asked for exactly
+         * those weights and is served or refused, never substituted — so for such
+         * a request there is no value that satisfies this field, and the event
+         * cannot be constructed at all.
+         */
+        requestedModelId: identifiers_1.modelIdSchema,
+        fromModelReference: identifiers_1.modelReferenceSchema,
+        toModelReference: identifiers_1.modelReferenceSchema,
+        toProvider: identifiers_1.inferenceProviderSlugSchema,
+        /** Literal `true`: an unauthorized cross-model switch cannot be reported. */
+        authorizedByPolicy: zod_1.z.literal(true),
+    })
+        .strict(),
+]);
+/** Why a route changed mid-request. */
+exports.inferenceRouteSwitchReasonSchema = zod_1.z.enum([
+    'deployment_unavailable',
+    'provider_error',
+    'provider_timeout',
+    'provider_overloaded',
+    'rate_limited',
+    'capacity',
+    'policy_preference',
+]);
+/**
+ * The customer-visible notice that an allowed route switch occurred.
+ *
+ * Emitted in-stream rather than only recorded on the receipt, because a
+ * customer comparing two answers needs to know that the second one came from
+ * somewhere else while they are reading it.
+ */
+exports.inferenceStreamRouteSwitchEventSchema = zod_1.z.object({
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    type: zod_1.z.literal('route_switch'),
+    requestId: identifiers_1.requestIdSchema,
+    sequence: zod_1.z.number().int().nonnegative().safe(),
+    reason: exports.inferenceRouteSwitchReasonSchema,
+    detail: exports.inferenceRouteSwitchDetailSchema,
+    occurredAt: identifiers_1.inferenceTimestampSchema,
+});
+/**
+ * A terminal error. The stream ends here; no `done` follows, so a client that
+ * saw an error never also has to reconcile a success.
+ */
+exports.inferenceStreamErrorEventSchema = zod_1.z.object({
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    type: zod_1.z.literal('error'),
+    requestId: identifiers_1.requestIdSchema,
+    sequence: zod_1.z.number().int().nonnegative().safe(),
+    /** Carries its own `schemaVersion`: the same body is returned non-streaming. */
+    error: errors_1.inferenceErrorSchema,
+});
+/** Why generation stopped. */
+exports.inferenceFinishReasonSchema = zod_1.z.enum([
+    'stop',
+    'length',
+    'tool_calls',
+    'content_filter',
+    'cancelled',
+]);
+/**
+ * The successful terminal event.
+ *
+ * `receiptId` is present once settlement has produced one, giving a customer a
+ * direct handle on the exact amount charged rather than a telemetry estimate.
+ */
+exports.inferenceStreamDoneEventSchema = zod_1.z.object({
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: zod_1.z.literal(1),
+    type: zod_1.z.literal('done'),
+    requestId: identifiers_1.requestIdSchema,
+    sequence: zod_1.z.number().int().nonnegative().safe(),
+    generationId: identifiers_1.generationIdSchema.optional(),
+    finishReason: exports.inferenceFinishReasonSchema,
+    receiptId: zod_1.z.string().min(1).max(128).optional(),
+    completedAt: identifiers_1.inferenceTimestampSchema,
+});
+/**
+ * Every event a normalized stream can carry.
+ *
+ * Discriminated on `type`, so a consumer that meets an unknown event fails at
+ * the parse instead of falling into a default branch that treats it as output.
+ */
+exports.inferenceStreamEventSchema = zod_1.z.discriminatedUnion('type', [
+    exports.inferenceStreamStartEventSchema,
+    exports.inferenceStreamDeltaEventSchema,
+    exports.inferenceStreamToolCallEventSchema,
+    exports.inferenceStreamUsageEventSchema,
+    exports.inferenceStreamRouteSwitchEventSchema,
+    exports.inferenceStreamErrorEventSchema,
+    exports.inferenceStreamDoneEventSchema,
+]);

package/dist/cjs/inference/usage.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * The reserve → settle → refund protocol.
+ *
+ * Four records, in the order they happen:
+ *
+ *  1. **Reservation** — before a request enters the data plane, Oxy holds the
+ *     MAXIMUM the request could cost (input units + maximum output + the
+ *     allowed route's price ceiling). A request whose account cannot cover that
+ *     hold is rejected before anything is spent upstream.
+ *  2. **Usage report** — the data plane's technical account of what was
+ *     consumed. Units and route, never money: the data plane measures, the
+ *     control plane prices.
+ *  3. **Receipt** — the immutable settlement. Carries the exact units, a COPY
+ *     of the prices they were charged at, and the amount booked. It is never
+ *     edited afterwards.
+ *  4. **Refund/reversal** — an equally immutable entry that releases an unused
+ *     hold or reverses a settled charge. Settled history is compensated, never
+ *     rewritten, because an invoice a customer already received must remain
+ *     reconstructible.
+ *
+ * Every one of them is keyed by an idempotency key, so a retried call, a
+ * redelivered event or a duplicated webhook produces the same record rather than
+ * a second charge.
+ *
+ * Money is an exact decimal string throughout (ADR 0009 — never integer minor
+ * units, never a float), and unit counts are carried separately from it (see
+ * `money.ts`).
+ *
+ * Decided in: docs/adr/0009-usage-reservation-and-settlement.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usageRefundSchema = exports.usageRefundReasonSchema = exports.usageRefundSubjectSchema = exports.usageReceiptSchema = exports.normalizedUsageReportSchema = exports.inferenceRequestOutcomeSchema = exports.usageReservationSchema = exports.usageReservationStatusSchema = exports.usageReservationRequestSchema = void 0;
+const zod_1 = require("zod");
+const attribution_1 = require("./attribution");
+const identifiers_1 = require("./identifiers");
+const money_1 = require("./money");
+const priceVersion_1 = require("./priceVersion");
+/* -------------------------------------------------------------------------- */
+/*  1. Reservation                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Ask the ledger to hold the maximum a request could cost.
+ *
+ * `maxAmount` is the number the balance check is made against, and it is
+ * computed from the three inputs beside it rather than guessed: the units
+ * already known (the prompt), the ceiling on units still to come
+ * (`maxOutputTokens`), and the most expensive route the policy allows. Sizing a
+ * hold from a typical response rather than the worst allowed one is how a
+ * balance goes negative on a long generation.
+ */
+exports.usageReservationRequestSchema = zod_1.z.object({
+    /** See `version.ts`: exchanged between the edge and the ledger on its own. */
+    schemaVersion: zod_1.z.literal(1),
+    idempotencyKey: identifiers_1.idempotencyKeySchema,
+    attribution: attribution_1.inferenceAttributionSchema,
+    /** Units already determined by the request itself, e.g. input tokens. */
+    knownUnits: zod_1.z.array(money_1.usageQuantitySchema).default([]),
+    /** The ceiling on generated output, when the request set one. */
+    maxOutputTokens: zod_1.z.number().int().positive().safe().optional(),
+    /** The price version of the most expensive route the policy permits. */
+    ceilingPriceVersionId: zod_1.z.string().min(1).max(128),
+    maxAmount: money_1.exactDecimalSchema,
+    currency: money_1.currencyCodeSchema,
+    expiresInSeconds: zod_1.z.number().int().positive().max(86400),
+});
+/** Lifecycle of a hold. Terminal states are `settled`, `released`, `expired`. */
+exports.usageReservationStatusSchema = zod_1.z.enum([
+    'held',
+    'settled',
+    'released',
+    'expired',
+]);
+/**
+ * A hold placed against an account's balance.
+ *
+ * Reserved amounts are shown to customers distinctly from settled charges: a
+ * reservation is not money spent, and presenting the two as one number makes a
+ * balance appear to drop and then recover for every request.
+ */
+exports.usageReservationSchema = zod_1.z
+    .object({
+    /** See `version.ts`: read back by the edge and the Console on its own. */
+    schemaVersion: zod_1.z.literal(1),
+    reservationId: zod_1.z.string().min(1).max(128),
+    idempotencyKey: identifiers_1.idempotencyKeySchema,
+    attribution: attribution_1.inferenceAttributionSchema,
+    status: exports.usageReservationStatusSchema,
+    reservedAmount: money_1.exactDecimalSchema,
+    currency: money_1.currencyCodeSchema,
+    ceilingPriceVersionId: zod_1.z.string().min(1).max(128),
+    createdAt: identifiers_1.inferenceTimestampSchema,
+    expiresAt: identifiers_1.inferenceTimestampSchema,
+    /** The receipt that consumed this hold. Present exactly when `settled`. */
+    settledReceiptId: zod_1.z.string().min(1).max(128).optional(),
+})
+    .superRefine((reservation, ctx) => {
+    if (reservation.status === 'settled' && reservation.settledReceiptId === undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['settledReceiptId'],
+            message: 'a settled reservation must name the receipt that settled it',
+        });
+    }
+    if (reservation.status !== 'settled' && reservation.settledReceiptId !== undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['settledReceiptId'],
+            message: 'only a settled reservation has a settling receipt',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  2. Usage report (data plane → Oxy)                                        */
+/* -------------------------------------------------------------------------- */
+/** How a request ended, from the data plane's point of view. */
+exports.inferenceRequestOutcomeSchema = zod_1.z.enum([
+    'completed',
+    'partial',
+    'cancelled',
+    'failed',
+]);
+/**
+ * The data plane's technical account of one request.
+ *
+ * No money and no price: the data plane measures units and names the route it
+ * used, and the control plane decides what that costs. Keeping the two apart is
+ * what allows a price to be corrected after the fact without re-running or
+ * re-measuring anything.
+ *
+ * `usageSource` is load-bearing when a provider returns no usage at all: the
+ * report still arrives, marked `estimated`, so settlement can apply the
+ * estimation policy knowingly instead of treating a reconstruction as fact.
+ *
+ * `units` is a PARTITION of what the request consumed, not a set of totals with
+ * details hanging off them — see `USAGE_UNITS` in `money.ts`. Reporting a provider's
+ * nested `prompt_tokens`/`completion_tokens` verbatim charges the cached and
+ * reasoning tokens twice, so subtracting the children out is part of what
+ * "normalized" means in this shape's name.
+ */
+exports.normalizedUsageReportSchema = zod_1.z
+    .object({
+    /** See `version.ts`: emitted by the data plane as a whole message. */
+    schemaVersion: zod_1.z.literal(1),
+    requestId: identifiers_1.requestIdSchema,
+    generationId: identifiers_1.generationIdSchema.optional(),
+    attribution: attribution_1.inferenceAttributionSchema,
+    outcome: exports.inferenceRequestOutcomeSchema,
+    units: zod_1.z.array(money_1.usageQuantitySchema),
+    usageSource: money_1.usageSourceSchema,
+    resolvedModelReference: identifiers_1.modelReferenceSchema,
+    servingProvider: identifiers_1.inferenceProviderSlugSchema,
+    deploymentId: identifiers_1.deploymentIdSchema.optional(),
+    /** How many allowed route switches occurred while serving this request. */
+    routeSwitches: zod_1.z.number().int().nonnegative().max(100),
+    startedAt: identifiers_1.inferenceTimestampSchema,
+    completedAt: identifiers_1.inferenceTimestampSchema,
+    timeToFirstTokenMs: zod_1.z.number().int().nonnegative().safe().optional(),
+})
+    .superRefine((report, ctx) => {
+    // Compared as instants: two spellings of one moment sort differently as text.
+    if (Date.parse(report.completedAt) < Date.parse(report.startedAt)) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['completedAt'],
+            message: 'a request cannot complete before it started',
+        });
+    }
+    const units = report.units.map((quantity) => quantity.unit);
+    if (new Set(units).size !== units.length) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['units'],
+            message: 'each unit is reported once, as a total',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  3. Receipt (settlement)                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * The immutable record of what a request was actually charged.
+ *
+ * `priceSnapshot` is a COPY of the unit prices applied, not just the id of the
+ * price version they came from, so the arithmetic on this receipt can be
+ * checked years later without depending on any other record still existing.
+ *
+ * `platformFeeOnly` marks a BYOK request: the upstream provider billed the
+ * customer's own account directly, and `billedAmount` is Oxy's service fee
+ * rather than the cost of the tokens. Without the flag, the two look identical
+ * and a BYOK customer appears to have been charged twice for one request.
+ */
+exports.usageReceiptSchema = zod_1.z
+    .object({
+    /** See `version.ts`: returned to customers by `GET /v1/generations/:id`. */
+    schemaVersion: zod_1.z.literal(1),
+    receiptId: zod_1.z.string().min(1).max(128),
+    /** The hold this settled against. Absent for a charge with no reservation. */
+    reservationId: zod_1.z.string().min(1).max(128).optional(),
+    idempotencyKey: identifiers_1.idempotencyKeySchema,
+    attribution: attribution_1.inferenceAttributionSchema,
+    outcome: exports.inferenceRequestOutcomeSchema,
+    units: zod_1.z.array(money_1.usageQuantitySchema).min(1),
+    usageSource: money_1.usageSourceSchema,
+    priceSnapshot: priceVersion_1.priceSnapshotSchema,
+    billedAmount: money_1.exactDecimalSchema,
+    currency: money_1.currencyCodeSchema,
+    platformFeeOnly: zod_1.z.boolean(),
+    resolvedModelReference: identifiers_1.modelReferenceSchema,
+    servingProvider: identifiers_1.inferenceProviderSlugSchema,
+    settledAt: identifiers_1.inferenceTimestampSchema,
+})
+    .superRefine((receipt, ctx) => {
+    if (receipt.currency !== receipt.priceSnapshot.currency) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['priceSnapshot', 'currency'],
+            message: 'a receipt must be settled in the currency it was priced in',
+        });
+    }
+    const units = receipt.units.map((quantity) => quantity.unit);
+    if (new Set(units).size !== units.length) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['units'],
+            message: 'each unit is settled once, as a total',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  4. Refund / reversal                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * What a reversal acts on: an unused hold, or a settled charge.
+ *
+ * A discriminated union, so "release the rest of the hold" and "give back money
+ * already booked" can never be confused for one another — they hit different
+ * ledger accounts and only the second one is visible on an invoice.
+ */
+exports.usageRefundSubjectSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z
+        .object({ kind: zod_1.z.literal('reservation'), reservationId: zod_1.z.string().min(1).max(128) })
+        .strict(),
+    zod_1.z.object({ kind: zod_1.z.literal('receipt'), receiptId: zod_1.z.string().min(1).max(128) }).strict(),
+]);
+/** Why money was given back or a hold was released. */
+exports.usageRefundReasonSchema = zod_1.z.enum([
+    'unused_reservation',
+    'client_cancelled',
+    'upstream_failure',
+    'partial_stream',
+    'usage_unavailable',
+    'billing_correction',
+    'duplicate_charge',
+]);
+/** Reasons that can only ever act on a settled charge. */
+const RECEIPT_ONLY_REFUND_REASONS = new Set([
+    'billing_correction',
+    'duplicate_charge',
+]);
+/**
+ * An immutable reversal entry.
+ *
+ * `amount` is non-negative like every other amount in this contract: the
+ * direction is carried by the record being a refund, not by a sign that a
+ * consumer could read the wrong way round. Idempotent by key, so a retried
+ * refund releases the same money once.
+ */
+exports.usageRefundSchema = zod_1.z
+    .object({
+    /** See `version.ts`: a ledger record read back on its own. */
+    schemaVersion: zod_1.z.literal(1),
+    refundId: zod_1.z.string().min(1).max(128),
+    idempotencyKey: identifiers_1.idempotencyKeySchema,
+    attribution: attribution_1.inferenceAttributionSchema,
+    subject: exports.usageRefundSubjectSchema,
+    reason: exports.usageRefundReasonSchema,
+    amount: money_1.exactDecimalSchema,
+    currency: money_1.currencyCodeSchema,
+    createdAt: identifiers_1.inferenceTimestampSchema,
+})
+    .superRefine((refund, ctx) => {
+    if (refund.reason === 'unused_reservation' && refund.subject.kind !== 'reservation') {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['reason'],
+            message: 'an unused reservation is released against the reservation, not a receipt',
+        });
+    }
+    if (RECEIPT_ONLY_REFUND_REASONS.has(refund.reason) && refund.subject.kind !== 'receipt') {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['reason'],
+            message: `${refund.reason} reverses a settled charge, so it acts on a receipt`,
+        });
+    }
+});

package/dist/cjs/inference/version.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Version rule for the Oxy↔data-plane inference contracts.
+ *
+ * Oxy is the control plane; the inference data plane is a separate service.
+ * They are deployed independently, in different repositories, possibly in
+ * different languages.
+ * Every shape they exchange therefore carries its version IN THE PARSED DATA,
+ * never as a comment or an out-of-band assumption, so a producer running ahead
+ * of a consumer fails loudly at the parse instead of being silently reinterpreted.
+ *
+ * The rule, enforced by `src/__tests__/inference.compatibility.test.ts`:
+ *
+ *  - A schema carries `schemaVersion: z.literal(<n>)` **if and only if** it can
+ *    appear on the wire as a whole message — a request envelope, a stream event,
+ *    a catalogue descriptor, a ledger record, an error body.
+ *  - A schema that only ever appears EMBEDDED inside such a message (the
+ *    attribution block, one message part, one usage quantity, a data-retention
+ *    policy) carries no version of its own: it inherits the version of the
+ *    envelope it rides in. Versioning it separately would create two versions
+ *    that can disagree about one byte stream.
+ *  - A shape that is BOTH — `inferenceErrorSchema` is returned as an HTTP body
+ *    and also rides inside the stream's error event — keeps its own version.
+ *    The envelope's version then governs the envelope and the payload's governs
+ *    the payload, which is two versions of two things rather than two versions
+ *    of one.
+ *  - Every exported object schema in `src/inference/` must fall into exactly one
+ *    of those groups. The compatibility test holds both lists as exact
+ *    equalities, so a new shape that is in neither fails the build rather than
+ *    quietly shipping unversioned.
+ *
+ * A shape's own version is bumped when its meaning changes in a way a consumer
+ * pinned to the previous version would misread — a field removed, a field's
+ * units changed, a closed enum's member given a new meaning. Adding an OPTIONAL
+ * field is additive and does not bump it, because a consumer on the previous
+ * version parses the message correctly and simply does not read the new field.
+ *
+ * ## Which shapes reject an unknown field
+ *
+ * That last rule is why the shapes EXCHANGED WITH THE DATA PLANE are not
+ * `.strict()` at their top level — the request envelope, the four usage records,
+ * the stream events, the error body, the catalogue descriptors, the price
+ * version. The split is a decision rather than an omission: `.strict()` and
+ * "adding an optional field is additive" cannot both hold on one shape, because
+ * a producer one minor version ahead would have its whole message REFUSED
+ * rather than its new field ignored. For a usage report that means a request
+ * already served upstream can never be settled and Oxy absorbs its cost, which
+ * is a worse failure than the one strictness would have caught.
+ *
+ * Their LEAVES are strict, and that is where the protection lives: a stripped
+ * field is the worse outcome exactly where it would be a leak or a second
+ * source of truth, because it disappears at this parse and survives in the
+ * producer, which is where somebody eventually reads it. So
+ * `clientRequestMetadataSchema` (no IP, ever), `moneySchema` (no convenience
+ * float beside the exact decimal), `providerErrorPassthroughSchema` (no
+ * upstream request or headers beside the message), `usageQuantitySchema` and
+ * `unitPriceSchema` all refuse an unknown field, while the envelope carrying
+ * them tolerates an additive one.
+ *
+ * A shape Oxy does NOT exchange with the data plane is strict at its top level
+ * too, since nothing there can run ahead of this package:
+ * `providerConnectionSchema`, where an unknown field is how a BYOK credential
+ * escapes, and the billing and entitlement records, where one is a second
+ * number beside an exact amount.
+ *
+ * Decided in: docs/adr/0006-oxy-relay-boundary.md, docs/adr/0010-public-api-compatibility.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INFERENCE_CONTRACT_VERSION = void 0;
+/**
+ * Version of the contract SET as a whole — the value the control plane and the
+ * data plane exchange in a startup/health handshake to establish that they were built against
+ * compatible definitions before a single inference request is served.
+ *
+ * MAJOR is bumped when any individual shape's `schemaVersion` increments (at
+ * least one message is now read differently by the two sides); MINOR when a
+ * shape or an optional field is added; PATCH for documentation-only changes
+ * that leave every parsed byte identical.
+ *
+ * This constant is deliberately NOT embedded in the request envelope. Pinning a
+ * request to the version of the whole set would make an unrelated additive
+ * change to, say, the catalogue reject every in-flight inference request; the
+ * per-shape `schemaVersion` is what a message is validated against.
+ */
+exports.INFERENCE_CONTRACT_VERSION = '1.0.0';