@kaana.ai/contracts 4.3.0 → 4.4.1

package/dist/internal/catalogue.d.ts

@@ -289,6 +289,34 @@ export declare const modelDeploymentSchema: z.ZodObject<{
     dedicatedCapacity: z.ZodBoolean;
     priceVersionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * The commercial facts Kaana publishes about ONE deployment on the descriptors
+ * it serves to Oxy (`POST /internal/v1/deployments/query` and
+ * `/internal/v1/models/query`), from the reviewed file
+ * `configs/deployment-commercial.json`. A deployment that is not sold carries
+ * no `commercial` at all, which is why the member is optional on the
+ * descriptor. New in contract set 4.4.0.
+ *
+ * `customer_byok` is the commercial basis of a `byok_only` route and of no
+ * other: the two say the same thing and may not disagree.
+ */
+export declare const deploymentCommercialSchema: z.ZodObject<{
+    availabilityScope: z.ZodEnum<{
+        platform_internal: "platform_internal";
+        public_payg: "public_payg";
+        enterprise: "enterprise";
+        byok_only: "byok_only";
+        oxy_hosted: "oxy_hosted";
+    }>;
+    commercialPermission: z.ZodEnum<{
+        standard_application_use: "standard_application_use";
+        public_resale_approved: "public_resale_approved";
+        wholesale_contract: "wholesale_contract";
+        customer_byok: "customer_byok";
+        open_weight_hosting: "open_weight_hosting";
+    }>;
+    dedicatedCapacity: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
 /** One candidate a profile may resolve to, and how strongly it is preferred. */
 export declare const routingProfileCandidateSchema: z.ZodObject<{
     modelReference: z.ZodString;
@@ -1019,6 +1047,7 @@ export type DeclaredModel = z.infer<typeof declaredModelSchema>;
 export type DeclaredCatalogue = z.infer<typeof declaredCatalogueSchema>;
 export type AvailabilityScope = z.infer<typeof availabilityScopeSchema>;
 export type CommercialPermission = z.infer<typeof commercialPermissionSchema>;
+export type DeploymentCommercial = z.infer<typeof deploymentCommercialSchema>;
 export type ModelPublisher = z.infer<typeof modelPublisherSchema>;
 export type CatalogueModel = z.infer<typeof catalogueModelSchema>;
 export type ModelRevision = z.infer<typeof modelRevisionSchema>;

package/dist/internal/catalogue.js

@@ -211,6 +211,46 @@ export const modelDeploymentSchema = z
         });
     }
 });
+/**
+ * The commercial facts Kaana publishes about ONE deployment on the descriptors
+ * it serves to Oxy (`POST /internal/v1/deployments/query` and
+ * `/internal/v1/models/query`), from the reviewed file
+ * `configs/deployment-commercial.json`. A deployment that is not sold carries
+ * no `commercial` at all, which is why the member is optional on the
+ * descriptor. New in contract set 4.4.0.
+ *
+ * `customer_byok` is the commercial basis of a `byok_only` route and of no
+ * other: the two say the same thing and may not disagree.
+ */
+export const deploymentCommercialSchema = z
+    .object({
+    availabilityScope: availabilityScopeSchema,
+    commercialPermission: commercialPermissionSchema,
+    /** Reserved capacity for one enterprise account; absent means shared. */
+    dedicatedCapacity: z.boolean().optional(),
+})
+    .strict()
+    .superRefine((commercial, ctx) => {
+    const byokScope = commercial.availabilityScope === 'byok_only';
+    const byokPermission = commercial.commercialPermission === 'customer_byok';
+    if (byokScope !== byokPermission) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['commercialPermission'],
+            message: 'customer_byok is the permission of a byok_only route, and only of it',
+        });
+    }
+    if (commercial.availabilityScope === 'public_payg' &&
+        commercial.commercialPermission !== 'public_resale_approved' &&
+        commercial.commercialPermission !== 'wholesale_contract' &&
+        commercial.commercialPermission !== 'open_weight_hosting') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['commercialPermission'],
+            message: 'a public pay-as-you-go route requires an approved resale permission',
+        });
+    }
+});
 /** One candidate a profile may resolve to, and how strongly it is preferred. */
 export const routingProfileCandidateSchema = z
     .object({

package/dist/internal/grant.d.ts

@@ -303,6 +303,7 @@ export declare const grantStepLimitsSchema: z.ZodObject<{
     prohibitTrainingOnCustomerData: z.ZodBoolean;
     allowedLicenseIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
     requireCommercialUseRights: z.ZodBoolean;
+    sameModelFailover: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
 /**
  * One step: a target and its limits. Kaana tries the steps IN ORDER and moves
@@ -349,6 +350,7 @@ export declare const grantStepSchema: z.ZodObject<{
         prohibitTrainingOnCustomerData: z.ZodBoolean;
         allowedLicenseIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
         requireCommercialUseRights: z.ZodBoolean;
+        sameModelFailover: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>;
 }, z.core.$strict>;
 /**
@@ -474,6 +476,7 @@ export declare const grantSchema: z.ZodObject<{
             prohibitTrainingOnCustomerData: z.ZodBoolean;
             allowedLicenseIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
             requireCommercialUseRights: z.ZodBoolean;
+            sameModelFailover: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>;
     }, z.core.$strict>>;
     exactRoute: z.ZodOptional<z.ZodObject<{

package/dist/internal/grant.js

@@ -240,6 +240,14 @@ export const grantStepLimitsSchema = z
     prohibitTrainingOnCustomerData: z.boolean(),
     allowedLicenseIds: z.array(z.string().min(1).max(128)).default([]),
     requireCommercialUseRights: z.boolean(),
+    /**
+     * Whether Kaana may fail over, inside this step, between providers (and
+     * keys) serving the SAME admitted line. `false` serves each admitted line
+     * with exactly one provider and one key: the cheapest admissible one, with
+     * no move to another provider of the line within the step. Absent means
+     * `true`. New in contract set 4.4.0.
+     */
+    sameModelFailover: z.boolean().default(true),
 })
     .strict()
     .superRefine((limits, ctx) => {

package/dist/internal/settlement.d.ts

@@ -111,6 +111,21 @@ export declare const settlementAcknowledgementSchema: z.ZodObject<{
         settled: "settled";
     }>;
 }, z.core.$strict>;
+/**
+ * The signature domain of Oxy's reconciliation read, under the Oxy edge key
+ * (`KAANA_EDGE_PUBLIC_KEYS`). New in package 4.4.1; Kaana has verified under it
+ * since contract set 4.2.0.
+ */
+export declare const SETTLEMENT_READ_SIGNATURE_DOMAIN = "oxy-kaana-settlement-read:v1";
+/** Where Oxy reads the outbox, on `https://kaana.ai`. */
+export declare const SETTLEMENT_READ_PATH = "/internal/v1/settlements";
+/**
+ * The query string of a reconciliation read, without its `?`: both what Oxy
+ * sends and the exact bytes it signs. Kaana verifies the raw query and nothing
+ * else — the path is fixed by the domain — so signing `path?query`, or encoding
+ * the cursor differently from what is sent, is refused as unsigned.
+ */
+export declare function settlementReadQuery(cursor: string | null): string;
 /** `GET /internal/v1/settlements?cursor=`: what Oxy reconciles against. */
 export declare const settlementPageSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{

package/dist/internal/settlement.js

@@ -61,6 +61,23 @@ export const settlementAcknowledgementSchema = z
     status: z.enum(['settled', 'duplicate']),
 })
     .strict();
+/**
+ * The signature domain of Oxy's reconciliation read, under the Oxy edge key
+ * (`KAANA_EDGE_PUBLIC_KEYS`). New in package 4.4.1; Kaana has verified under it
+ * since contract set 4.2.0.
+ */
+export const SETTLEMENT_READ_SIGNATURE_DOMAIN = 'oxy-kaana-settlement-read:v1';
+/** Where Oxy reads the outbox, on `https://kaana.ai`. */
+export const SETTLEMENT_READ_PATH = '/internal/v1/settlements';
+/**
+ * The query string of a reconciliation read, without its `?`: both what Oxy
+ * sends and the exact bytes it signs. Kaana verifies the raw query and nothing
+ * else — the path is fixed by the domain — so signing `path?query`, or encoding
+ * the cursor differently from what is sent, is refused as unsigned.
+ */
+export function settlementReadQuery(cursor) {
+    return cursor === null ? '' : `cursor=${encodeURIComponent(cursor)}`;
+}
 /** `GET /internal/v1/settlements?cursor=`: what Oxy reconciles against. */
 export const settlementPageSchema = z
     .object({

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 = "4.3.0";
+export declare const INFERENCE_CONTRACT_VERSION = "4.4.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:
@@ -128,6 +128,13 @@ export declare const INFERENCE_CONTRACT_VERSION = "4.3.0";
  * Kaana declares (identity, licence, data policy, capabilities and the list
  * price per unit), carried to Oxy as `declaredCatalogue` on the signed
  * `GET /internal/v1/models`. Nothing in 4.2.0 changes.
+ *
+ * Contract set 4.4.0 (Kaana ADR 0002, amendment 2026-10-15) is additive: the
+ * internal `deploymentCommercialSchema`, the optional `commercial` member of
+ * every deployment descriptor Kaana serves (availability scope, commercial
+ * permission, dedicated capacity), and `sameModelFailover` on
+ * `grantStepLimitsSchema` (default `true`: what 4.3.0 did). Nothing in 4.3.0
+ * changes.
  */
 /** 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 = '4.3.0';
+export const INFERENCE_CONTRACT_VERSION = '4.4.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:
@@ -128,6 +128,13 @@ export const INFERENCE_CONTRACT_VERSION = '4.3.0';
  * Kaana declares (identity, licence, data policy, capabilities and the list
  * price per unit), carried to Oxy as `declaredCatalogue` on the signed
  * `GET /internal/v1/models`. Nothing in 4.2.0 changes.
+ *
+ * Contract set 4.4.0 (Kaana ADR 0002, amendment 2026-10-15) is additive: the
+ * internal `deploymentCommercialSchema`, the optional `commercial` member of
+ * every deployment descriptor Kaana serves (availability scope, commercial
+ * permission, dedicated capacity), and `sameModelFailover` on
+ * `grantStepLimitsSchema` (default `true`: what 4.3.0 did). Nothing in 4.3.0
+ * changes.
  */
 /** 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": "4.3.0",
+    "version": "4.4.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": [

package/package.json

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