@kaana.ai/contracts 7.0.0 → 8.0.1

package/dist/public/realtime.js

@@ -4,6 +4,7 @@
  * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/realtime.ts`) by Kaana ADR 0002.
  */
 import { z } from 'zod';
+import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { realtimeAudioFormatSchema, realtimeOutputModalitySchema } from './audioFormats.js';
 import { realtimeSessionKindSchema, realtimeSessionTransportSchema, } from './catalogue.js';
 import { inferenceTimestampSchema, modelReferenceSchema, PADDED_BASE64_PATTERN, requestIdSchema, } from './identifiers.js';
@@ -36,15 +37,21 @@ export const MAX_REALTIME_RESUME_WINDOW_MS = 60_000;
  */
 export const MAX_REALTIME_ITEM_TEXT_CHARS = 1_048_576;
 /** A client-chosen command identity, unique within one session. */
-export const realtimeCommandIdSchema = z.string().min(1).max(128);
+export const realtimeCommandIdSchema = z
+    .string()
+    .check(minUtf16Length(1))
+    .check(maxUtf16Length(128));
 /** A conversation item's identity within one session. */
-export const realtimeItemIdSchema = z.string().min(1).max(128);
+export const realtimeItemIdSchema = z.string().check(minUtf16Length(1)).check(maxUtf16Length(128));
 /** A response's identity within one session. */
-export const realtimeResponseIdSchema = z.string().min(1).max(128);
+export const realtimeResponseIdSchema = z
+    .string()
+    .check(minUtf16Length(1))
+    .check(maxUtf16Length(128));
 const audioFrameSchema = z
     .string()
-    .min(4)
-    .max(MAX_REALTIME_AUDIO_FRAME_BASE64_LENGTH)
+    .check(minUtf16Length(4))
+    .check(maxUtf16Length(MAX_REALTIME_AUDIO_FRAME_BASE64_LENGTH))
     .regex(PADDED_BASE64_PATTERN);
 const sequenceSchema = z.number().int().nonnegative().safe();
 const milliseconds = z.number().int().nonnegative().safe();
@@ -106,16 +113,16 @@ export const realtimeInputTranscriptionSchema = z
      * the provider its spelling of that language, or none for the model to
      * detect; it is never refused.
      */
-    language: z.string().min(2).max(35).optional(),
+    language: z.string().check(minUtf16Length(2)).check(maxUtf16Length(35)).optional(),
     /** A hint — vocabulary or context — used where the model takes one. */
-    prompt: z.string().max(4_096).optional(),
+    prompt: z.string().check(maxUtf16Length(4_096)).optional(),
 })
     .strict();
 /** The target of a `translation` session. */
 export const realtimeTranslationSchema = z
     .object({
     /** A BCP 47 tag. */
-    targetLanguage: z.string().min(2).max(35),
+    targetLanguage: z.string().check(minUtf16Length(2)).check(maxUtf16Length(35)),
 })
     .strict();
 /**
@@ -134,9 +141,9 @@ export const realtimeToolDefinitionSchema = toolDefinitionSchema.omit({ strict:
  */
 export const realtimeSessionConfigSchema = z
     .object({
-    instructions: z.string().max(32_768).optional(),
+    instructions: z.string().check(maxUtf16Length(32_768)).optional(),
     outputModalities: z.array(realtimeOutputModalitySchema).min(1).max(2).optional(),
-    voice: z.string().min(1).max(64).optional(),
+    voice: z.string().check(minUtf16Length(1)).check(maxUtf16Length(64)).optional(),
     inputAudioFormat: realtimeAudioFormatSchema,
     outputAudioFormat: realtimeAudioFormatSchema.optional(),
     turnDetection: realtimeTurnDetectionSchema,
@@ -158,7 +165,7 @@ export const realtimeSessionConfigSchema = z
  */
 export const realtimeSessionConfigUpdateSchema = z
     .object({
-    instructions: z.string().max(32_768).optional(),
+    instructions: z.string().check(maxUtf16Length(32_768)).optional(),
     outputModalities: z.array(realtimeOutputModalitySchema).min(1).max(2).optional(),
     turnDetection: realtimeTurnDetectionSchema.optional(),
     inputAudioTranscription: realtimeInputTranscriptionSchema.optional(),
@@ -199,7 +206,10 @@ export const realtimeSessionLimitsSchema = z
  */
 export const realtimeContentPartSchema = z.discriminatedUnion('type', [
     z
-        .object({ type: z.literal('input_text'), text: z.string().max(MAX_REALTIME_ITEM_TEXT_CHARS) })
+        .object({
+        type: z.literal('input_text'),
+        text: z.string().check(maxUtf16Length(MAX_REALTIME_ITEM_TEXT_CHARS)),
+    })
         .strict(),
     z
         .object({
@@ -239,8 +249,8 @@ export const realtimeConversationItemSchema = z
         .object({
         type: z.literal('function_call'),
         itemId: realtimeItemIdSchema.optional(),
-        callId: z.string().min(1).max(128),
-        name: z.string().min(1).max(128),
+        callId: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)),
+        name: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)),
         arguments: z.string(),
     })
         .strict(),
@@ -248,8 +258,8 @@ export const realtimeConversationItemSchema = z
         .object({
         type: z.literal('function_call_output'),
         itemId: realtimeItemIdSchema.optional(),
-        callId: z.string().min(1).max(128),
-        output: z.string().max(MAX_REALTIME_ITEM_TEXT_CHARS),
+        callId: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)),
+        output: z.string().check(maxUtf16Length(MAX_REALTIME_ITEM_TEXT_CHARS)),
     })
         .strict(),
 ])
@@ -279,7 +289,7 @@ export const realtimeConversationItemSchema = z
 /** Per-response overrides for `response.create`. Absent fields keep the session's. */
 export const realtimeResponseParametersSchema = z
     .object({
-    instructions: z.string().max(32_768).optional(),
+    instructions: z.string().check(maxUtf16Length(32_768)).optional(),
     outputModalities: z.array(realtimeOutputModalitySchema).min(1).max(2).optional(),
     maxOutputTokens: z.number().int().positive().safe().optional(),
     toolChoice: toolChoiceSchema.optional(),
@@ -511,8 +521,8 @@ export const realtimeToolCallEventSchema = z.object({
     type: z.literal('tool_call'),
     responseId: realtimeResponseIdSchema,
     itemId: realtimeItemIdSchema,
-    toolCallId: z.string().min(1).max(128),
-    name: z.string().min(1).max(128).optional(),
+    toolCallId: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)),
+    name: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)).optional(),
     argumentsDelta: z.string().optional(),
     complete: z.boolean(),
 });
@@ -644,7 +654,7 @@ export const realtimeSessionOpenSchema = z
     config: realtimeSessionConfigSchema,
     limits: realtimeOpenLimitsSchema.optional(),
     /** The caller's own correlation id. */
-    clientSessionId: z.string().min(1).max(128).optional(),
+    clientSessionId: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)).optional(),
     labels: requestLabelsSchema.optional(),
 })
     .strict()

package/dist/public/responses.js

@@ -8,6 +8,7 @@
  * catalogue identities), and the response names no serving provider.
  */
 import { z } from 'zod';
+import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { powerLevelSchema } from './catalogue.js';
 import { generationIdSchema, modelReferenceSchema, requestIdSchema } from './identifiers.js';
 import { inferenceMessageSchema, inferenceReasoningSchema, requestLabelsSchema, responseFormatSchema, toolChoiceSchema, toolDefinitionSchema, } from './messages.js';
@@ -22,7 +23,10 @@ import { inferenceFinishReasonSchema } from './streamEvents.js';
  */
 export const modelTargetSchema = z.union([modelReferenceSchema, powerLevelSchema]);
 /** The message-or-text input `/v1/responses` accepts. */
-const responsesInputSchema = z.union([z.string().min(1), z.array(inferenceMessageSchema).min(1)]);
+const responsesInputSchema = z.union([
+    z.string().check(minUtf16Length(1)),
+    z.array(inferenceMessageSchema).min(1),
+]);
 /**
  * The request. `model` may be absent: the application's routing policy in Oxy
  * Console may name a default target, and the request is refused only when it
@@ -44,7 +48,10 @@ export const responsesRequestSchema = z
     frequencyPenalty: z.number().min(-2).max(2).optional(),
     presencePenalty: z.number().min(-2).max(2).optional(),
     seed: z.number().int().safe().optional(),
-    stopSequences: z.array(z.string().min(1).max(256)).max(8).optional(),
+    stopSequences: z
+        .array(z.string().check(minUtf16Length(1)).check(maxUtf16Length(256)))
+        .max(8)
+        .optional(),
     tools: z.array(toolDefinitionSchema).max(128).optional(),
     toolChoice: toolChoiceSchema.optional(),
     responseFormat: responseFormatSchema.optional(),
@@ -52,7 +59,7 @@ export const responsesRequestSchema = z
     reasoning: inferenceReasoningSchema.optional(),
     labels: requestLabelsSchema.optional(),
     /** The caller's own correlation id, echoed on the response. */
-    clientRequestId: z.string().min(1).max(128).optional(),
+    clientRequestId: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)).optional(),
 })
     .strict()
     .superRefine((request, ctx) => {

package/dist/public/streamEvents.js

@@ -5,6 +5,7 @@
  * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/streamEvents.ts`) by Kaana ADR 0002.
  */
 import { z } from 'zod';
+import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { generationIdSchema, inferenceTimestampSchema, modelReferenceSchema, PADDED_BASE64_PATTERN, requestIdSchema, } from './identifiers.js';
 import { publicErrorSchema } from './errors.js';
 import { usageQuantitySchema, usageSourceSchema } from './money.js';
@@ -51,7 +52,11 @@ export const inferenceStreamAudioEventSchema = z.object({
     sequence: z.number().int().nonnegative().safe(),
     outputIndex: z.number().int().nonnegative().safe(),
     mediaType: inferenceAudioMediaTypeSchema,
-    data: z.string().min(4).max(65536).regex(PADDED_BASE64_PATTERN),
+    data: z
+        .string()
+        .check(minUtf16Length(4))
+        .check(maxUtf16Length(65536))
+        .regex(PADDED_BASE64_PATTERN),
 });
 /**
  * A tool call being streamed.
@@ -65,9 +70,9 @@ export const inferenceStreamToolCallEventSchema = z.object({
     type: z.literal('tool_call'),
     requestId: requestIdSchema,
     sequence: z.number().int().nonnegative().safe(),
-    toolCallId: z.string().min(1).max(128),
+    toolCallId: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)),
     /** Present on the first event of a call. */
-    name: z.string().min(1).max(128).optional(),
+    name: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)).optional(),
     argumentsDelta: z.string().optional(),
     complete: z.boolean(),
 });
@@ -103,7 +108,7 @@ export const inferenceStreamDoneEventSchema = z.object({
     sequence: z.number().int().nonnegative().safe(),
     generationId: generationIdSchema.optional(),
     finishReason: inferenceFinishReasonSchema,
-    receiptId: z.string().min(1).max(128).optional(),
+    receiptId: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)).optional(),
     completedAt: inferenceTimestampSchema,
 });
 /* -------------------------------------------------------------------------- */

package/dist/public/version.d.ts

@@ -100,7 +100,7 @@
  * 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 = "7.0.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.0.0";
 /**
  * Contract set 4.0.0 (Kaana ADR 0002) is the first published as
  * `@kaana.ai/contracts`. MAJOR because the set changed hands and split in two:

package/dist/public/version.js

@@ -100,7 +100,7 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export const INFERENCE_CONTRACT_VERSION = '7.0.0';
+export const INFERENCE_CONTRACT_VERSION = '8.0.0';
 /**
  * Contract set 4.0.0 (Kaana ADR 0002) is the first published as
  * `@kaana.ai/contracts`. MAJOR because the set changed hands and split in two:

package/dist/stringBounds.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+/**
+ * Kaana's frozen wire contract measures strings in UTF-16 code units, as Go's
+ * utf16Length does. Zod >=4.5 measures its built-in string bounds in code points.
+ * These per-schema checks retain the standard bound metadata used by the Go
+ * descriptor and JSON Schema generators, with the contract's explicit measure.
+ * No Zod constructor, prototype, shared check or array validation is changed.
+ */
+export declare function minUtf16Length(minimum: number): z.core.$ZodCheck<string>;
+export declare function maxUtf16Length(maximum: number): z.core.$ZodCheck<string>;
+export declare function utf16Length(length: number): z.core.$ZodCheck<string>;

package/dist/stringBounds.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/**
+ * Kaana's frozen wire contract measures strings in UTF-16 code units, as Go's
+ * utf16Length does. Zod >=4.5 measures its built-in string bounds in code points.
+ * These per-schema checks retain the standard bound metadata used by the Go
+ * descriptor and JSON Schema generators, with the contract's explicit measure.
+ * No Zod constructor, prototype, shared check or array validation is changed.
+ */
+export function minUtf16Length(minimum) {
+    const check = z.minLength(minimum);
+    check._zod.check = (payload) => {
+        if (payload.value.length >= minimum)
+            return;
+        payload.issues.push({
+            origin: 'string',
+            code: 'too_small',
+            minimum,
+            inclusive: true,
+            input: payload.value,
+            inst: check,
+            continue: true,
+        });
+    };
+    return check;
+}
+export function maxUtf16Length(maximum) {
+    const check = z.maxLength(maximum);
+    check._zod.check = (payload) => {
+        if (payload.value.length <= maximum)
+            return;
+        payload.issues.push({
+            origin: 'string',
+            code: 'too_big',
+            maximum,
+            inclusive: true,
+            input: payload.value,
+            inst: check,
+            continue: true,
+        });
+    };
+    return check;
+}
+export function utf16Length(length) {
+    const check = z.length(length);
+    check._zod.check = (payload) => {
+        if (payload.value.length === length)
+            return;
+        payload.issues.push({
+            origin: 'string',
+            ...(payload.value.length > length
+                ? { code: 'too_big', maximum: length }
+                : { code: 'too_small', minimum: length }),
+            inclusive: true,
+            exact: true,
+            input: payload.value,
+            inst: check,
+            continue: true,
+        });
+    };
+    return check;
+}

package/dist/timestampCheck.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+/** Preserve the existing UTC wire spelling, including minute precision. */
+export declare function utcTimestampCheck(): z.core.$ZodCheck<string>;

package/dist/timestampCheck.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/** Preserve the existing UTC wire spelling, including minute precision. */
+export function utcTimestampCheck() {
+    // Zod >=4.6 requires seconds on a qualified datetime. Compose its calendar
+    // and time validators explicitly to retain the contract's previous grammar,
+    // without accepting offsets, local datetimes or invalid calendar dates.
+    const date = z.regexes.date.source.slice(1, -1);
+    const time = z.regexes.time({}).source.slice(1, -1);
+    return new z.core.$ZodISODateTime({
+        type: 'string',
+        format: 'datetime',
+        check: 'string_format',
+        offset: false,
+        local: false,
+        precision: null,
+        pattern: new RegExp(`^${date}T(?:${time}(?:Z))$`),
+    });
+}

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "7.0.0",
+    "version": "8.0.0",
     "description": "Kaana inference API. Generated from @kaana.ai/contracts; the Zod source is the authority. Accounts, applications, oxy_sk_ keys, limits and billing are managed in Oxy Console: https://console.oxy.so"
   },
   "servers": [
@@ -1388,13 +1388,9 @@
                 "minLength": 1
               },
               "param": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
+                "type": [
+                  "string",
+                  "null"
                 ]
               },
               "code": {
@@ -1542,13 +1538,9 @@
                       "const": "assistant"
                     },
                     "content": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
+                      "type": [
+                        "string",
+                        "null"
                       ]
                     },
                     "audio": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaana.ai/contracts",
-  "version": "7.0.0",
+  "version": "8.0.1",
   "description": "Kaana inference contract: the Zod schemas of the public API at https://kaana.ai/v1 and, under /internal, of the Oxy-Kaana grant, settlement and signed lane.",
   "type": "module",
   "sideEffects": false,
@@ -38,10 +38,9 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "bun test src",
-    "prepublishOnly": "bun run typecheck && bun run test && bun run build && make -C ../.. contract-generate"
+    "test": "bun test src"
   },
   "dependencies": {
-    "zod": ">=4.4.3 <4.5.0"
+    "zod": ">=4.6.7 <5.0.0"
   }
 }