@kaana.ai/contracts 8.11.0 → 8.13.0

package/dist/internal/catalogue.d.ts

@@ -314,10 +314,10 @@ export declare const routingProfileSchema: z.ZodObject<{
     displayName: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     optimiseFor: z.ZodEnum<{
+        quality: "quality";
         price: "price";
         latency: "latency";
         throughput: "throughput";
-        quality: "quality";
         balanced: "balanced";
     }>;
     candidates: z.ZodArray<z.ZodObject<{

package/dist/internal/identity.d.ts

@@ -0,0 +1,141 @@
+/** Identity facts only. Kaana owns admission, routing and economic policy. */
+import { z } from 'zod';
+export declare const IDENTITY_SIGNATURE_DOMAIN = "oxy-kaana-identity:v1";
+export declare const IDENTITY_VALIDITY_WINDOW_MS = 60000;
+export declare const OXY_KAANA_IDENTITIES_ENDPOINT = "/internal/kaana/v1/identities";
+/** The exact bytes of this request, not inference content, are signed by hash. */
+export declare const kaanaIdentityRequestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"identity">;
+    requestId: z.ZodString;
+    audience: z.ZodLiteral<"kaana.ai">;
+    credential: z.ZodString;
+    onBehalfOfUserId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "DelegatedUserId", "out">>;
+}, z.core.$strict>;
+export declare const kaanaIdentityLaneSchema: z.ZodEnum<{
+    machine_credential: "machine_credential";
+    service_token: "service_token";
+}>;
+export declare const kaanaIdentityApplicationClassSchema: z.ZodEnum<{
+    system: "system";
+    first_party: "first_party";
+    third_party: "third_party";
+    internal: "internal";
+}>;
+export declare const kaanaIdentityPrincipalSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    authority: z.ZodLiteral<"first_party">;
+    ownerAccountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+    applicationId: z.ZodString;
+    credentialId: z.ZodString;
+    environment: z.ZodEnum<{
+        development: "development";
+        staging: "staging";
+        production: "production";
+    }>;
+    lane: z.ZodEnum<{
+        machine_credential: "machine_credential";
+        service_token: "service_token";
+    }>;
+    applicationClass: z.ZodEnum<{
+        system: "system";
+        first_party: "first_party";
+        third_party: "third_party";
+        internal: "internal";
+    }>;
+    applicationIsInternal: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    authority: z.ZodLiteral<"external">;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "inference:invoke": "inference:invoke";
+        "inference:models:read": "inference:models:read";
+        "inference:usage:read": "inference:usage:read";
+        "inference:routing:read": "inference:routing:read";
+        "inference:routing:write": "inference:routing:write";
+        "inference:providers:read": "inference:providers:read";
+        "inference:providers:write": "inference:providers:write";
+    }>>;
+    ownerAccountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+    applicationId: z.ZodString;
+    credentialId: z.ZodString;
+    environment: z.ZodEnum<{
+        development: "development";
+        staging: "staging";
+        production: "production";
+    }>;
+    lane: z.ZodEnum<{
+        machine_credential: "machine_credential";
+        service_token: "service_token";
+    }>;
+    applicationClass: z.ZodEnum<{
+        system: "system";
+        first_party: "first_party";
+        third_party: "third_party";
+        internal: "internal";
+    }>;
+    applicationIsInternal: z.ZodBoolean;
+}, z.core.$strict>], "authority">;
+export declare const kaanaIdentityAssertionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"identity">;
+    requestId: z.ZodString;
+    audience: z.ZodLiteral<"kaana.ai">;
+    requestSha256: z.ZodString;
+    issuedAt: z.ZodString;
+    expiresAt: z.ZodString;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        authority: z.ZodLiteral<"first_party">;
+        ownerAccountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+        applicationId: z.ZodString;
+        credentialId: z.ZodString;
+        environment: z.ZodEnum<{
+            development: "development";
+            staging: "staging";
+            production: "production";
+        }>;
+        lane: z.ZodEnum<{
+            machine_credential: "machine_credential";
+            service_token: "service_token";
+        }>;
+        applicationClass: z.ZodEnum<{
+            system: "system";
+            first_party: "first_party";
+            third_party: "third_party";
+            internal: "internal";
+        }>;
+        applicationIsInternal: z.ZodBoolean;
+    }, z.core.$strict>, z.ZodObject<{
+        authority: z.ZodLiteral<"external">;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "inference:invoke": "inference:invoke";
+            "inference:models:read": "inference:models:read";
+            "inference:usage:read": "inference:usage:read";
+            "inference:routing:read": "inference:routing:read";
+            "inference:routing:write": "inference:routing:write";
+            "inference:providers:read": "inference:providers:read";
+            "inference:providers:write": "inference:providers:write";
+        }>>;
+        ownerAccountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+        applicationId: z.ZodString;
+        credentialId: z.ZodString;
+        environment: z.ZodEnum<{
+            development: "development";
+            staging: "staging";
+            production: "production";
+        }>;
+        lane: z.ZodEnum<{
+            machine_credential: "machine_credential";
+            service_token: "service_token";
+        }>;
+        applicationClass: z.ZodEnum<{
+            system: "system";
+            first_party: "first_party";
+            third_party: "third_party";
+            internal: "internal";
+        }>;
+        applicationIsInternal: z.ZodBoolean;
+    }, z.core.$strict>], "authority">;
+    userId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "DelegatedUserId", "out">>;
+}, z.core.$strict>;
+export type KaanaIdentityRequest = z.infer<typeof kaanaIdentityRequestSchema>;
+export type KaanaIdentityPrincipal = z.infer<typeof kaanaIdentityPrincipalSchema>;
+export type KaanaIdentityAssertion = z.infer<typeof kaanaIdentityAssertionSchema>;

package/dist/internal/identity.js

@@ -0,0 +1,82 @@
+/** Identity facts only. Kaana owns admission, routing and economic policy. */
+import { z } from 'zod';
+import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
+import { delegatedUserIdSchema, inferenceEnvironmentSchema, inferenceTimestampSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, } from '../public/identifiers.js';
+import { inferenceScopeSchema } from './attribution.js';
+import { oxyAccountIdSchema } from './identifiers.js';
+export const IDENTITY_SIGNATURE_DOMAIN = 'oxy-kaana-identity:v1';
+export const IDENTITY_VALIDITY_WINDOW_MS = 60_000;
+export const OXY_KAANA_IDENTITIES_ENDPOINT = '/internal/kaana/v1/identities';
+/** The exact bytes of this request, not inference content, are signed by hash. */
+export const kaanaIdentityRequestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal('identity'),
+    requestId: requestIdSchema,
+    audience: z.literal('kaana.ai'),
+    credential: z.string().check(minUtf16Length(1)).check(maxUtf16Length(8192)),
+    /** Attribution only. Never proof of the person's identity or data authority. */
+    onBehalfOfUserId: delegatedUserIdSchema.optional(),
+})
+    .strict();
+export const kaanaIdentityLaneSchema = z.enum(['machine_credential', 'service_token']);
+export const kaanaIdentityApplicationClassSchema = z.enum([
+    'first_party',
+    'third_party',
+    'internal',
+    'system',
+]);
+const principalFields = {
+    ownerAccountId: oxyAccountIdSchema,
+    applicationId: oxyApplicationIdSchema,
+    credentialId: oxyCredentialIdSchema,
+    environment: inferenceEnvironmentSchema,
+    // Product sessions require their own identity-only verifier before enrollment.
+    lane: kaanaIdentityLaneSchema,
+    applicationClass: kaanaIdentityApplicationClassSchema,
+    applicationIsInternal: z.boolean(),
+};
+export const kaanaIdentityPrincipalSchema = z
+    .discriminatedUnion('authority', [
+    z.object({ ...principalFields, authority: z.literal('first_party') }).strict(),
+    z
+        .object({
+        ...principalFields,
+        authority: z.literal('external'),
+        scopes: z.array(inferenceScopeSchema),
+    })
+        .strict(),
+])
+    .superRefine((principal, ctx) => {
+    if (principal.authority === 'first_party' && principal.lane !== 'service_token') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['lane'],
+            message: 'First-party authority requires a workload service token',
+        });
+    }
+});
+export const kaanaIdentityAssertionSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal('identity'),
+    requestId: requestIdSchema,
+    audience: z.literal('kaana.ai'),
+    requestSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    issuedAt: inferenceTimestampSchema,
+    expiresAt: inferenceTimestampSchema,
+    principal: kaanaIdentityPrincipalSchema,
+    /** Attribution only, with the same meaning as onBehalfOfUserId. */
+    userId: delegatedUserIdSchema.optional(),
+})
+    .strict()
+    .superRefine((assertion, ctx) => {
+    const duration = Date.parse(assertion.expiresAt) - Date.parse(assertion.issuedAt);
+    if (!(duration > 0 && duration <= IDENTITY_VALIDITY_WINDOW_MS)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['expiresAt'],
+            message: 'Identity assertions are valid for at most 60 seconds',
+        });
+    }
+});

package/dist/internal/request.d.ts

@@ -341,6 +341,16 @@ export declare const inferenceRequestSchema: z.ZodObject<{
         }>;
         speed: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    image: z.ZodOptional<z.ZodObject<{
+        n: z.ZodOptional<z.ZodNumber>;
+        size: z.ZodOptional<z.ZodString>;
+        quality: z.ZodOptional<z.ZodString>;
+        style: z.ZodOptional<z.ZodString>;
+        responseFormat: z.ZodOptional<z.ZodEnum<{
+            url: "url";
+            b64_json: "b64_json";
+        }>>;
+    }, z.core.$strict>>;
     transcription: z.ZodOptional<z.ZodObject<{
         language: z.ZodOptional<z.ZodString>;
         prompt: z.ZodOptional<z.ZodString>;

package/dist/internal/request.js

@@ -8,7 +8,7 @@ import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { inferenceApiFormatSchema, inferenceModalitySchema } from '../public/catalogue.js';
 import { decisionInputSchema } from '../public/decisions.js';
 import { idempotencyKeySchema, inferenceTimestampSchema } from '../public/identifiers.js';
-import { inferenceAudioOutputParametersSchema, inferenceMessageSchema, inferenceReasoningSchema, inferenceSpeechParametersSchema, inferenceTranscriptionParametersSchema, responseFormatSchema, samplingParametersSchema, toolChoiceSchema, toolDefinitionSchema, } from '../public/messages.js';
+import { inferenceAudioOutputParametersSchema, inferenceMessageSchema, inferenceReasoningSchema, inferenceImageParametersSchema, inferenceSpeechParametersSchema, inferenceTranscriptionParametersSchema, responseFormatSchema, samplingParametersSchema, toolChoiceSchema, toolDefinitionSchema, } from '../public/messages.js';
 import { routingPolicyReferenceSchema } from '../public/policy.js';
 import { inferenceAttributionSchema } from './attribution.js';
 import { authorizedRouteSchema, routingTargetSchema } from './routing.js';
@@ -93,6 +93,8 @@ const inferenceRequestObjectSchema = z.object({
     /** Absent means the route's own default reasoning behaviour. */
     reasoning: inferenceReasoningSchema.optional(),
     speech: inferenceSpeechParametersSchema.optional(),
+    /** Text-to-image controls. Contract set 8.12.0. */
+    image: inferenceImageParametersSchema.optional(),
     /** File transcription parameters. Contract set 4.5.0. */
     transcription: inferenceTranscriptionParametersSchema.optional(),
     /** Spoken output from a conversational model. Contract set 3.2.0. */
@@ -168,6 +170,7 @@ export const inferenceRequestSchema = inferenceRequestObjectSchema.superRefine((
             request.responseFormat !== undefined ||
             request.reasoning !== undefined ||
             request.speech !== undefined ||
+            request.image !== undefined ||
             request.transcription !== undefined ||
             request.audioOutput !== undefined) {
             ctx.addIssue({
@@ -196,6 +199,16 @@ export const inferenceRequestSchema = inferenceRequestObjectSchema.superRefine((
             message: 'speech parameters require the audio_speech API format',
         });
     }
+    if (request.image !== undefined &&
+        (request.client.apiFormat !== 'images_generations' ||
+            request.modality !== 'image' ||
+            request.input.format !== 'text')) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['image'],
+            message: 'image parameters require the images_generations API format with image modality and text input',
+        });
+    }
     if (request.transcription !== undefined &&
         (request.client.apiFormat !== 'audio_transcriptions' ||
             request.modality !== 'audio' ||

package/dist/internal.d.ts

@@ -19,6 +19,7 @@ export * from './internal/embeddings.js';
 export * from './internal/errors.js';
 export * from './internal/grant.js';
 export * from './internal/identifiers.js';
+export * from './internal/identity.js';
 export * from './internal/realtime.js';
 export * from './internal/request.js';
 export * from './internal/routing.js';

package/dist/internal.js

@@ -19,6 +19,7 @@ export * from './internal/embeddings.js';
 export * from './internal/errors.js';
 export * from './internal/grant.js';
 export * from './internal/identifiers.js';
+export * from './internal/identity.js';
 export * from './internal/realtime.js';
 export * from './internal/request.js';
 export * from './internal/routing.js';

package/dist/public/messages.d.ts

@@ -343,6 +343,24 @@ export declare const inferenceSpeechParametersSchema: z.ZodObject<{
     }>;
     speed: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
+/**
+ * Parameters for text-to-image (contract set 8.12.0), preserved in the request.
+ * Each is the caller's own control, forwarded as named: an adapter whose
+ * provider takes none of them refuses the request rather than dropping it.
+ * `n` is how many images; `size`, `quality` and `style` are the provider's own
+ * vocabulary (each size/quality class is its own model reference in the
+ * catalogue, so none of them widens a hold).
+ */
+export declare const inferenceImageParametersSchema: z.ZodObject<{
+    n: z.ZodOptional<z.ZodNumber>;
+    size: z.ZodOptional<z.ZodString>;
+    quality: z.ZodOptional<z.ZodString>;
+    style: z.ZodOptional<z.ZodString>;
+    responseFormat: z.ZodOptional<z.ZodEnum<{
+        url: "url";
+        b64_json: "b64_json";
+    }>>;
+}, z.core.$strict>;
 /**
  * Parameters for a file transcription, preserved in the signed request
  * (contract set 4.5.0). `language` is the caller's statement of what is spoken,
@@ -386,6 +404,7 @@ export declare const inferenceAudioOutputParametersSchema: z.ZodObject<{
  * Moved from the Oxy edge (`packages/api/src/schemas/inferenceEdge.schemas.ts`).
  */
 export declare const requestLabelsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type InferenceImageParameters = z.infer<typeof inferenceImageParametersSchema>;
 export type InferenceSpeechParameters = z.infer<typeof inferenceSpeechParametersSchema>;
 export type InferenceTranscriptionParameters = z.infer<typeof inferenceTranscriptionParametersSchema>;
 export type InferenceAudioOutputParameters = z.infer<typeof inferenceAudioOutputParametersSchema>;

package/dist/public/messages.js

@@ -412,6 +412,23 @@ export const inferenceSpeechParametersSchema = z
     speed: z.number().min(0.25).max(4).optional(),
 })
     .strict();
+/**
+ * Parameters for text-to-image (contract set 8.12.0), preserved in the request.
+ * Each is the caller's own control, forwarded as named: an adapter whose
+ * provider takes none of them refuses the request rather than dropping it.
+ * `n` is how many images; `size`, `quality` and `style` are the provider's own
+ * vocabulary (each size/quality class is its own model reference in the
+ * catalogue, so none of them widens a hold).
+ */
+export const inferenceImageParametersSchema = z
+    .object({
+    n: z.number().int().min(1).max(10).optional(),
+    size: z.string().check(minUtf16Length(1)).check(maxUtf16Length(32)).optional(),
+    quality: z.string().check(minUtf16Length(1)).check(maxUtf16Length(32)).optional(),
+    style: z.string().check(minUtf16Length(1)).check(maxUtf16Length(32)).optional(),
+    responseFormat: z.enum(['url', 'b64_json']).optional(),
+})
+    .strict();
 /**
  * Parameters for a file transcription, preserved in the signed request
  * (contract set 4.5.0). `language` is the caller's statement of what is spoken,

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 = "8.11.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.13.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:
@@ -241,6 +241,19 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.11.0";
  * operation (`grantOperationSchema`, last member) and the public `POST /v1/rerank`
  * shapes (`rerankRequestSchema`, `rerankResponseSchema`). Kaana emits no `rerank`
  * operation and serves no route yet; Oxy supports the operation first.
+ *
+ * Contract set 8.12.0 is additive: the signed envelope's optional `image`
+ * member (`inferenceImageParametersSchema`: `n`, `size`, `quality`, `style`,
+ * `responseFormat`), which carries a text-to-image request's controls to the
+ * adapter instead of dropping them. It is valid only with the
+ * `images_generations` API format, image modality and text input. Nothing in
+ * 8.11.0 changes and the public request and response shapes are unchanged.
+ */
+/**
+ * Contract set 8.13.0 adds identity-only Oxy assertions under /internal, with a
+ * distinct signature domain and bounded request binding. Existing grants and
+ * public inference shapes are unchanged; publishing does not activate native
+ * economic authorization or enroll any customer.
  */
 /** The public API's one origin and version. */
 export declare const KAANA_API_BASE_URL = "https://kaana.ai/v1";

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 = '8.11.0';
+export const INFERENCE_CONTRACT_VERSION = '8.13.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:
@@ -241,6 +241,19 @@ export const INFERENCE_CONTRACT_VERSION = '8.11.0';
  * operation (`grantOperationSchema`, last member) and the public `POST /v1/rerank`
  * shapes (`rerankRequestSchema`, `rerankResponseSchema`). Kaana emits no `rerank`
  * operation and serves no route yet; Oxy supports the operation first.
+ *
+ * Contract set 8.12.0 is additive: the signed envelope's optional `image`
+ * member (`inferenceImageParametersSchema`: `n`, `size`, `quality`, `style`,
+ * `responseFormat`), which carries a text-to-image request's controls to the
+ * adapter instead of dropping them. It is valid only with the
+ * `images_generations` API format, image modality and text input. Nothing in
+ * 8.11.0 changes and the public request and response shapes are unchanged.
+ */
+/**
+ * Contract set 8.13.0 adds identity-only Oxy assertions under /internal, with a
+ * distinct signature domain and bounded request binding. Existing grants and
+ * public inference shapes are unchanged; publishing does not activate native
+ * economic authorization or enroll any customer.
  */
 /** The public API's one origin and version. */
 export const KAANA_API_BASE_URL = 'https://kaana.ai/v1';

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "8.11.0",
+    "version": "8.13.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": [
@@ -4311,6 +4311,39 @@
         "maxLength": 2048,
         "pattern": "^https:\\/\\/[^\\s]+$"
       },
+      "InferenceImageParameters": {
+        "type": "object",
+        "properties": {
+          "n": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10
+          },
+          "size": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 32
+          },
+          "quality": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 32
+          },
+          "style": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 32
+          },
+          "responseFormat": {
+            "type": "string",
+            "enum": [
+              "url",
+              "b64_json"
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
       "InferenceMessageRole": {
         "type": "string",
         "enum": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaana.ai/contracts",
-  "version": "8.11.0",
+  "version": "8.13.0",
   "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,