@oxyhq/contracts 0.26.0 → 0.27.0

package/dist/types/inference/version.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ *
+ * Decided in: docs/adr/0006-oxy-relay-boundary.md, docs/adr/0010-public-api-compatibility.md.
+ */
+/**
+ * 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.
+ */
+export declare const INFERENCE_CONTRACT_VERSION = "1.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/contracts",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "OxyHQ API contracts — single source of truth for request/response Zod schemas and inferred types, shared by the backend and the client SDKs",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",