@kaana.ai/contracts 0.0.0-stage → 4.3.0

package/dist/internal/scopedExecution.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Scoped execution (envelope v3).
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/scopedExecution.ts`) by Kaana ADR 0002.
+ */
+import { z } from 'zod';
+/** Explicit extension negotiation; never replaces the legacy 3.5 handshake. */
+export declare const SCOPED_EXECUTION_CONTRACT_VERSION: "3.6.0";
+/** Scoped only; normal envelope v2 and metadata 3.5 remain unchanged. */
+export declare const SCOPED_REQUEST_ENVELOPE_VERSION: 3;
+/** Restriction only: none of these identities grants catalogue eligibility. */
+export declare const scopedExecutionAudienceSchema: z.ZodObject<{
+    permitId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    fixtureSha256: z.ZodString;
+    expiresAt: z.ZodString;
+    principal: z.ZodObject<{
+        accountId: z.ZodString;
+        applicationId: z.ZodString;
+        credentialId: z.ZodString;
+        environment: z.ZodEnum<{
+            development: "development";
+            staging: "staging";
+            production: "production";
+        }>;
+    }, z.core.$strict>;
+    policy: z.ZodObject<{
+        routingPolicyId: z.ZodString;
+        policyVersion: z.ZodNumber;
+    }, z.core.$strict>;
+    deploymentId: z.ZodString;
+    provider: z.ZodString;
+    keyId: z.ZodString;
+    modelReference: z.ZodString;
+    upstreamModelId: z.ZodString;
+    priceVersionId: z.ZodString;
+    providerRateCardVersionId: z.ZodString;
+    providerSourceVersion: z.ZodString;
+    maxCostUsd: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
+}, z.core.$strict>;
+export declare const scopedExecutionSchema: z.ZodObject<{
+    permitId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    fixtureSha256: z.ZodString;
+    expiresAt: z.ZodString;
+    principal: z.ZodObject<{
+        accountId: z.ZodString;
+        applicationId: z.ZodString;
+        credentialId: z.ZodString;
+        environment: z.ZodEnum<{
+            development: "development";
+            staging: "staging";
+            production: "production";
+        }>;
+    }, z.core.$strict>;
+    policy: z.ZodObject<{
+        routingPolicyId: z.ZodString;
+        policyVersion: z.ZodNumber;
+    }, z.core.$strict>;
+    deploymentId: z.ZodString;
+    provider: z.ZodString;
+    keyId: z.ZodString;
+    modelReference: z.ZodString;
+    upstreamModelId: z.ZodString;
+    priceVersionId: z.ZodString;
+    providerRateCardVersionId: z.ZodString;
+    providerSourceVersion: z.ZodString;
+    maxCostUsd: z.core.$ZodBranded<z.ZodString, "ExactDecimal", "out">;
+    requestId: z.ZodString;
+    snapshotId: z.ZodString;
+    catalogueEvidenceHash: z.ZodString;
+}, z.core.$strict>;
+export type ScopedExecutionAudience = z.infer<typeof scopedExecutionAudienceSchema>;
+export type ScopedExecution = z.infer<typeof scopedExecutionSchema>;

package/dist/internal/scopedExecution.js

@@ -0,0 +1,61 @@
+/**
+ * Scoped execution (envelope v3).
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/scopedExecution.ts`) by Kaana ADR 0002.
+ */
+import { z } from 'zod';
+import { idempotencyKeySchema, inferenceEnvironmentSchema, modelReferenceSchema, requestIdSchema, } from '../public/identifiers.js';
+import { exactDecimalSchema } from '../public/money.js';
+import { deploymentIdSchema, inferenceProviderSlugSchema } from './identifiers.js';
+/** Explicit extension negotiation; never replaces the legacy 3.5 handshake. */
+export const SCOPED_EXECUTION_CONTRACT_VERSION = '3.6.0';
+/** Scoped only; normal envelope v2 and metadata 3.5 remain unchanged. */
+export const SCOPED_REQUEST_ENVELOPE_VERSION = 3;
+const identity = z.string().min(1).max(256);
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/);
+const maxCost = exactDecimalSchema.refine((value) => {
+    if (!exactDecimalSchema.safeParse(value).success)
+        return false;
+    const [whole, fraction = ''] = value.split('.');
+    const units = BigInt(whole) * 1000000000000n + BigInt(fraction.padEnd(12, '0'));
+    return units > 0n && units <= 10000000000n;
+}, 'scoped cost must be positive and at most 0.01 USD');
+/** Restriction only: none of these identities grants catalogue eligibility. */
+export const scopedExecutionAudienceSchema = z
+    .object({
+    permitId: identity,
+    idempotencyKey: idempotencyKeySchema,
+    fixtureSha256: sha256,
+    expiresAt: z.string().datetime(),
+    principal: z
+        .object({
+        accountId: identity,
+        applicationId: identity,
+        credentialId: identity,
+        environment: inferenceEnvironmentSchema,
+    })
+        .strict(),
+    policy: z
+        .object({
+        routingPolicyId: z.string().min(1).max(128),
+        policyVersion: z.number().int().positive().safe(),
+    })
+        .strict(),
+    deploymentId: deploymentIdSchema,
+    provider: inferenceProviderSlugSchema,
+    keyId: identity,
+    modelReference: modelReferenceSchema.refine((value) => value.includes('@'), 'must pin a revision'),
+    upstreamModelId: identity,
+    priceVersionId: identity,
+    providerRateCardVersionId: identity,
+    providerSourceVersion: identity,
+    maxCostUsd: maxCost,
+})
+    .strict();
+export const scopedExecutionSchema = scopedExecutionAudienceSchema
+    .extend({
+    requestId: requestIdSchema,
+    snapshotId: identity,
+    catalogueEvidenceHash: sha256,
+})
+    .strict();

package/dist/internal/settlement.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Settlement: exactly once, from Kaana's measurement (Kaana ADR 0002,
+ * decision 3).
+ *
+ * When a granted request ends — success, error, cancellation or the close of a
+ * realtime session — Kaana writes the settlement into a durable outbox in its
+ * PostgreSQL, in the same transaction as its provider-cost events, and a worker
+ * delivers it to `POST https://api.oxy.so/internal/kaana/v1/settlements`,
+ * signed by Kaana under {@link SETTLEMENT_SIGNATURE_DOMAIN}. Oxy settles
+ * idempotently on `grantId` and reconciles by reading
+ * `GET https://kaana.ai/internal/v1/settlements?cursor=`. Units, never money:
+ * Oxy prices with the `priceVersionId` the grant admitted for the line served.
+ *
+ * New in contract set 4.0.0.
+ */
+import { z } from 'zod';
+/** The signature domain of a settlement, under Kaana's own settlement key. */
+export declare const SETTLEMENT_SIGNATURE_DOMAIN = "kaana-oxy-settlement:v1";
+/** One granted request's settlement, as the outbox delivers it. */
+export declare const settlementSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    settlementId: z.ZodString;
+    grantId: z.ZodString;
+    requestId: z.ZodString;
+    reservationId: z.ZodOptional<z.ZodString>;
+    meteredUsageId: z.ZodOptional<z.ZodString>;
+    servedStep: z.ZodOptional<z.ZodNumber>;
+    report: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<2>;
+        requestId: z.ZodString;
+        generationId: z.ZodOptional<z.ZodString>;
+        attribution: z.ZodObject<{
+            principal: z.ZodObject<{
+                billing: z.ZodObject<{
+                    accountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+                }, z.core.$strict>;
+                applicationId: z.ZodString;
+                credentialId: z.ZodString;
+                environment: z.ZodEnum<{
+                    development: "development";
+                    staging: "staging";
+                    production: "production";
+                }>;
+                inferenceScopes: 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";
+                }>>;
+            }, z.core.$strip>;
+            userId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "DelegatedUserId", "out">>;
+            requestId: z.ZodString;
+            generationId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        outcome: z.ZodEnum<{
+            cancelled: "cancelled";
+            completed: "completed";
+            partial: "partial";
+            failed: "failed";
+        }>;
+        units: z.ZodArray<z.ZodObject<{
+            unit: z.ZodEnum<{
+                input_tokens: "input_tokens";
+                cached_input_tokens: "cached_input_tokens";
+                output_tokens: "output_tokens";
+                reasoning_tokens: "reasoning_tokens";
+                requests: "requests";
+                images: "images";
+                audio_input_milliseconds: "audio_input_milliseconds";
+                audio_output_milliseconds: "audio_output_milliseconds";
+                video_milliseconds: "video_milliseconds";
+                characters: "characters";
+                embeddings: "embeddings";
+                audio_input_tokens: "audio_input_tokens";
+                cached_audio_input_tokens: "cached_audio_input_tokens";
+                audio_output_tokens: "audio_output_tokens";
+                session_milliseconds: "session_milliseconds";
+                input_transcription_milliseconds: "input_transcription_milliseconds";
+            }>;
+            quantity: z.ZodNumber;
+        }, z.core.$strict>>;
+        usageSource: z.ZodEnum<{
+            provider_reported: "provider_reported";
+            oxy_measured: "oxy_measured";
+            estimated: "estimated";
+        }>;
+        resolvedModelReference: z.ZodString;
+        servingProvider: z.ZodString;
+        deploymentId: z.ZodString;
+        routeSwitches: z.ZodNumber;
+        fundingTier: z.ZodOptional<z.ZodEnum<{
+            free: "free";
+            credit: "credit";
+            paid: "paid";
+        }>>;
+        startedAt: z.ZodString;
+        completedAt: z.ZodString;
+        timeToFirstTokenMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+/** Oxy's answer to a delivered settlement. A redelivery is `duplicate`, never a second charge. */
+export declare const settlementAcknowledgementSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    settlementId: z.ZodString;
+    status: z.ZodEnum<{
+        duplicate: "duplicate";
+        settled: "settled";
+    }>;
+}, z.core.$strict>;
+/** `GET /internal/v1/settlements?cursor=`: what Oxy reconciles against. */
+export declare const settlementPageSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        settlementId: z.ZodString;
+        grantId: z.ZodString;
+        requestId: z.ZodString;
+        reservationId: z.ZodOptional<z.ZodString>;
+        meteredUsageId: z.ZodOptional<z.ZodString>;
+        servedStep: z.ZodOptional<z.ZodNumber>;
+        report: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<2>;
+            requestId: z.ZodString;
+            generationId: z.ZodOptional<z.ZodString>;
+            attribution: z.ZodObject<{
+                principal: z.ZodObject<{
+                    billing: z.ZodObject<{
+                        accountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+                    }, z.core.$strict>;
+                    applicationId: z.ZodString;
+                    credentialId: z.ZodString;
+                    environment: z.ZodEnum<{
+                        development: "development";
+                        staging: "staging";
+                        production: "production";
+                    }>;
+                    inferenceScopes: 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";
+                    }>>;
+                }, z.core.$strip>;
+                userId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "DelegatedUserId", "out">>;
+                requestId: z.ZodString;
+                generationId: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            outcome: z.ZodEnum<{
+                cancelled: "cancelled";
+                completed: "completed";
+                partial: "partial";
+                failed: "failed";
+            }>;
+            units: z.ZodArray<z.ZodObject<{
+                unit: z.ZodEnum<{
+                    input_tokens: "input_tokens";
+                    cached_input_tokens: "cached_input_tokens";
+                    output_tokens: "output_tokens";
+                    reasoning_tokens: "reasoning_tokens";
+                    requests: "requests";
+                    images: "images";
+                    audio_input_milliseconds: "audio_input_milliseconds";
+                    audio_output_milliseconds: "audio_output_milliseconds";
+                    video_milliseconds: "video_milliseconds";
+                    characters: "characters";
+                    embeddings: "embeddings";
+                    audio_input_tokens: "audio_input_tokens";
+                    cached_audio_input_tokens: "cached_audio_input_tokens";
+                    audio_output_tokens: "audio_output_tokens";
+                    session_milliseconds: "session_milliseconds";
+                    input_transcription_milliseconds: "input_transcription_milliseconds";
+                }>;
+                quantity: z.ZodNumber;
+            }, z.core.$strict>>;
+            usageSource: z.ZodEnum<{
+                provider_reported: "provider_reported";
+                oxy_measured: "oxy_measured";
+                estimated: "estimated";
+            }>;
+            resolvedModelReference: z.ZodString;
+            servingProvider: z.ZodString;
+            deploymentId: z.ZodString;
+            routeSwitches: z.ZodNumber;
+            fundingTier: z.ZodOptional<z.ZodEnum<{
+                free: "free";
+                credit: "credit";
+                paid: "paid";
+            }>>;
+            startedAt: z.ZodString;
+            completedAt: z.ZodString;
+            timeToFirstTokenMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        createdAt: z.ZodString;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Settlement = z.infer<typeof settlementSchema>;
+export type SettlementAcknowledgement = z.infer<typeof settlementAcknowledgementSchema>;
+export type SettlementPage = z.infer<typeof settlementPageSchema>;

package/dist/internal/settlement.js

@@ -0,0 +1,71 @@
+/**
+ * Settlement: exactly once, from Kaana's measurement (Kaana ADR 0002,
+ * decision 3).
+ *
+ * When a granted request ends — success, error, cancellation or the close of a
+ * realtime session — Kaana writes the settlement into a durable outbox in its
+ * PostgreSQL, in the same transaction as its provider-cost events, and a worker
+ * delivers it to `POST https://api.oxy.so/internal/kaana/v1/settlements`,
+ * signed by Kaana under {@link SETTLEMENT_SIGNATURE_DOMAIN}. Oxy settles
+ * idempotently on `grantId` and reconciles by reading
+ * `GET https://kaana.ai/internal/v1/settlements?cursor=`. Units, never money:
+ * Oxy prices with the `priceVersionId` the grant admitted for the line served.
+ *
+ * New in contract set 4.0.0.
+ */
+import { z } from 'zod';
+import { inferenceTimestampSchema, requestIdSchema } from '../public/identifiers.js';
+import { normalizedUsageReportSchema } from './usage.js';
+/** The signature domain of a settlement, under Kaana's own settlement key. */
+export const SETTLEMENT_SIGNATURE_DOMAIN = 'kaana-oxy-settlement:v1';
+/** One granted request's settlement, as the outbox delivers it. */
+export const settlementSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    /** The outbox row; stable across redeliveries. */
+    settlementId: z.string().min(1).max(128),
+    /** The idempotency key of the settlement: one grant settles once. */
+    grantId: z.string().min(1).max(128),
+    requestId: requestIdSchema,
+    /** The grant's hold, when it had one. */
+    reservationId: z.string().min(1).max(128).optional(),
+    /** The grant's capacity slot, when it claimed one; settling releases it. */
+    meteredUsageId: z.string().min(1).max(128).optional(),
+    /** The step that served, by position in the grant. Absent when nothing was served. */
+    servedStep: z.number().int().nonnegative().max(7).optional(),
+    report: normalizedUsageReportSchema,
+    createdAt: inferenceTimestampSchema,
+})
+    .strict()
+    .superRefine((settlement, ctx) => {
+    if (settlement.report.requestId !== settlement.requestId) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['report', 'requestId'],
+            message: 'the report settles this request',
+        });
+    }
+    if (settlement.report.outcome === 'completed' && settlement.servedStep === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['servedStep'],
+            message: 'a completed request was served by a step of its grant',
+        });
+    }
+});
+/** Oxy's answer to a delivered settlement. A redelivery is `duplicate`, never a second charge. */
+export const settlementAcknowledgementSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    settlementId: z.string().min(1).max(128),
+    status: z.enum(['settled', 'duplicate']),
+})
+    .strict();
+/** `GET /internal/v1/settlements?cursor=`: what Oxy reconciles against. */
+export const settlementPageSchema = z
+    .object({
+    data: z.array(settlementSchema),
+    /** Absent on the last page. */
+    nextCursor: z.string().min(1).max(512).optional(),
+})
+    .strict();