@kaana.ai/contracts 0.0.0-stage → 4.3.0

package/dist/internal/credentialControl.js

@@ -0,0 +1,256 @@
+/**
+ * Signed customer-provider credential control (BYOK custody in Kaana).
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/providerConnection.ts`) by Kaana ADR 0002.
+ * The Console connection records (`providerConnectionSchema` and its
+ * validation and custody metadata) stay in `@oxy.so/contracts`.
+ */
+import { z } from 'zod';
+import { inferenceEnvironmentSchema, oxyApplicationIdSchema, PADDED_BASE64_PATTERN, } from '../public/identifiers.js';
+import { deploymentIdSchema, inferenceProviderSlugSchema } from './identifiers.js';
+/** Opaque reference minted by Kaana. It is not a KMS/Vault/SSM locator. */
+export const kaanaCredentialHandleSchema = z
+    .string()
+    .regex(/^kcred_[a-z2-7]{26}$/, 'a Kaana credential handle is kcred_ plus 26 base32 characters');
+/** Oxy-minted, case-sensitive replay identity for one exact Kaana mutation. */
+export const kaanaCredentialOperationIdSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{1,128}$/, 'a Kaana credential operation id is 1-128 opaque characters');
+export const kaanaCredentialOperationActionSchema = z.enum(['create', 'rotate', 'revoke']);
+/** Exact immutable Oxy identity repeated by both mutation and reconciliation. */
+export const kaanaCredentialIdentitySchema = z
+    .object({
+    provider: inferenceProviderSlugSchema,
+    ownerAccountId: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/),
+    connectionId: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/),
+    environment: inferenceEnvironmentSchema,
+})
+    .strict();
+const kaanaCredentialOperationActorSchema = z
+    .string()
+    .min(1)
+    .refine((value) => new TextEncoder().encode(value).byteLength <= 256 &&
+    value === value.trim() &&
+    !/[\r\n]/.test(value), {
+    message: 'a credential operation actor is one trimmed line of at most 256 bytes',
+});
+const base64Alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * Decode only enough of a strict base64 value to prove every output byte is
+ * visible ASCII. Keeping this implementation local avoids a Node Buffer or
+ * browser atob dependency in the universal contracts package.
+ */
+function isVisibleASCIIProviderCredential(value) {
+    const padding = value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0;
+    const decodedLength = (value.length / 4) * 3 - padding;
+    if (decodedLength < 1 || decodedLength > 4096)
+        return false;
+    for (let offset = 0, output = 0; offset < value.length; offset += 4, output += 3) {
+        const first = base64Alphabet.indexOf(value[offset] ?? '');
+        const second = base64Alphabet.indexOf(value[offset + 1] ?? '');
+        const third = value[offset + 2] === '=' ? 0 : base64Alphabet.indexOf(value[offset + 2] ?? '');
+        const fourth = value[offset + 3] === '=' ? 0 : base64Alphabet.indexOf(value[offset + 3] ?? '');
+        if (first < 0 || second < 0 || third < 0 || fourth < 0)
+            return false;
+        const finalQuartet = offset + 4 === value.length;
+        if (finalQuartet &&
+            ((padding === 2 && (second & 0x0f) !== 0) || (padding === 1 && (third & 0x03) !== 0))) {
+            return false;
+        }
+        const packed = (first << 18) | (second << 12) | (third << 6) | fourth;
+        const bytes = [(packed >> 16) & 0xff, (packed >> 8) & 0xff, packed & 0xff];
+        const count = Math.min(3, decodedLength - output);
+        for (let index = 0; index < count; index += 1) {
+            const byte = bytes[index];
+            if (byte === undefined || byte < 0x21 || byte > 0x7e)
+                return false;
+        }
+    }
+    return true;
+}
+const kaanaCredentialSecretBase64Schema = z
+    .string()
+    .min(1)
+    .max(8192)
+    .regex(PADDED_BASE64_PATTERN)
+    .refine(isVisibleASCIIProviderCredential, {
+    message: 'a decoded provider credential is 1-4096 visible ASCII bytes',
+});
+export const kaanaCredentialCreateMutationSchema = kaanaCredentialIdentitySchema
+    .extend({
+    schemaVersion: z.literal(1),
+    action: z.literal('create'),
+    operationId: kaanaCredentialOperationIdSchema,
+    operationActor: kaanaCredentialOperationActorSchema,
+    secretBase64: kaanaCredentialSecretBase64Schema,
+})
+    .strict();
+export const kaanaCredentialRotateMutationSchema = kaanaCredentialIdentitySchema
+    .extend({
+    schemaVersion: z.literal(1),
+    action: z.literal('rotate'),
+    operationId: kaanaCredentialOperationIdSchema,
+    operationActor: kaanaCredentialOperationActorSchema,
+    credentialHandle: kaanaCredentialHandleSchema,
+    expectedRevision: z
+        .number()
+        .int()
+        .positive()
+        .max(Number.MAX_SAFE_INTEGER - 1),
+    secretBase64: kaanaCredentialSecretBase64Schema,
+})
+    .strict();
+export const kaanaCredentialRevokeMutationSchema = kaanaCredentialIdentitySchema
+    .extend({
+    schemaVersion: z.literal(1),
+    action: z.literal('revoke'),
+    operationId: kaanaCredentialOperationIdSchema,
+    operationActor: kaanaCredentialOperationActorSchema,
+    credentialHandle: kaanaCredentialHandleSchema,
+    expectedRevision: z
+        .number()
+        .int()
+        .positive()
+        .max(Number.MAX_SAFE_INTEGER - 1),
+})
+    .strict();
+export const kaanaCredentialMutationSchema = z.discriminatedUnion('action', [
+    kaanaCredentialCreateMutationSchema,
+    kaanaCredentialRotateMutationSchema,
+    kaanaCredentialRevokeMutationSchema,
+]);
+export const kaanaCredentialCreateOutcomeRequestSchema = kaanaCredentialIdentitySchema
+    .extend({
+    schemaVersion: z.literal(1),
+    action: z.literal('create'),
+    operationId: kaanaCredentialOperationIdSchema,
+})
+    .strict();
+export const kaanaCredentialRotateOutcomeRequestSchema = kaanaCredentialIdentitySchema
+    .extend({
+    schemaVersion: z.literal(1),
+    action: z.literal('rotate'),
+    operationId: kaanaCredentialOperationIdSchema,
+    credentialHandle: kaanaCredentialHandleSchema,
+    expectedRevision: z
+        .number()
+        .int()
+        .positive()
+        .max(Number.MAX_SAFE_INTEGER - 1),
+})
+    .strict();
+export const kaanaCredentialRevokeOutcomeRequestSchema = kaanaCredentialIdentitySchema
+    .extend({
+    schemaVersion: z.literal(1),
+    action: z.literal('revoke'),
+    operationId: kaanaCredentialOperationIdSchema,
+    credentialHandle: kaanaCredentialHandleSchema,
+    expectedRevision: z
+        .number()
+        .int()
+        .positive()
+        .max(Number.MAX_SAFE_INTEGER - 1),
+})
+    .strict();
+export const kaanaCredentialOutcomeRequestSchema = z.discriminatedUnion('action', [
+    kaanaCredentialCreateOutcomeRequestSchema,
+    kaanaCredentialRotateOutcomeRequestSchema,
+    kaanaCredentialRevokeOutcomeRequestSchema,
+]);
+export const kaanaCredentialAppliedOutcomeSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    operationId: kaanaCredentialOperationIdSchema,
+    action: kaanaCredentialOperationActionSchema,
+    status: z.literal('applied'),
+    credentialHandle: kaanaCredentialHandleSchema,
+    revision: z.number().int().positive().safe(),
+})
+    .strict();
+export const kaanaCredentialConflictOutcomeSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    operationId: kaanaCredentialOperationIdSchema,
+    action: kaanaCredentialOperationActionSchema,
+    status: z.literal('conflict'),
+})
+    .strict();
+export const kaanaCredentialOutcomeSchema = z.discriminatedUnion('status', [
+    kaanaCredentialAppliedOutcomeSchema,
+    kaanaCredentialConflictOutcomeSchema,
+]);
+/**
+ * One separately authenticated check of a quarantined BYOK generation.
+ *
+ * This is deliberately not an inference request. It carries no prompt, user
+ * response, routing policy or billing principal, and it can select only one
+ * exact Kaana deployment plus one exact credential generation.
+ */
+export const kaanaCredentialValidationTaskSchema = kaanaCredentialIdentitySchema
+    .extend({
+    schemaVersion: z.literal(1),
+    operationId: kaanaCredentialOperationIdSchema,
+    applicationId: oxyApplicationIdSchema,
+    credentialHandle: kaanaCredentialHandleSchema,
+    credentialRevision: z.number().int().positive().safe(),
+    deploymentId: deploymentIdSchema,
+})
+    .strict();
+export const kaanaCredentialValidationOutcomeStateSchema = z.enum([
+    'pending',
+    'valid',
+    'invalid',
+    'inconclusive',
+]);
+export const kaanaCredentialValidationFailureCodeSchema = z.enum([
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'rate_limited',
+    'network',
+    'unknown',
+]);
+/**
+ * Durable result for one exact validation operation. `inconclusive` is a
+ * terminal answer about the attempt, never evidence that the credential is
+ * invalid; Oxy leaves the generation quarantined and may start a new exact
+ * operation. Kaana reports terminal outcomes through its service principal.
+ */
+export const kaanaCredentialValidationOutcomeSchema = kaanaCredentialValidationTaskSchema
+    .extend({
+    state: kaanaCredentialValidationOutcomeStateSchema,
+    failureCode: kaanaCredentialValidationFailureCodeSchema.optional(),
+})
+    .strict()
+    .superRefine((outcome, ctx) => {
+    if ((outcome.state === 'pending' || outcome.state === 'valid') &&
+        outcome.failureCode !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['failureCode'],
+            message: 'a valid credential validation carries no failure code',
+        });
+    }
+    if ((outcome.state === 'invalid' || outcome.state === 'inconclusive') &&
+        outcome.failureCode === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['failureCode'],
+            message: 'a failed credential validation must state its closed failure code',
+        });
+    }
+    if (outcome.state === 'invalid' && outcome.failureCode !== 'unauthorized') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['failureCode'],
+            message: 'only a provider authentication refusal proves invalidity',
+        });
+    }
+    if (outcome.state === 'inconclusive' && outcome.failureCode === 'unauthorized') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['failureCode'],
+            message: 'an explicit authentication refusal is invalid, not inconclusive',
+        });
+    }
+});

package/dist/internal/decisions.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Kaana's typed decisions result and failure on the signed lane.
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/decisions.ts`) by Kaana ADR 0002.
+ */
+import { z } from 'zod';
+export declare const decisionResultSchema: z.ZodObject<{
+    usage: 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>;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    model: z.ZodString;
+    data: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"choice">;
+        reply: z.ZodString;
+        confidence: z.ZodNumber;
+        probabilities: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"score">;
+        reply: z.ZodNumber;
+        confidence: z.ZodNumber;
+        mean: z.ZodNumber;
+        distribution: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"noul">;
+        probability: z.ZodNumber;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>;
+/**
+ * Kaana's typed decisions failure. `usage` is present only when the provider
+ * measured something before failing; its absence means nothing was measured,
+ * never that the cost was zero. A failure carrying usage did execute.
+ */
+export declare const decisionFailureSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    error: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        code: z.ZodEnum<{
+            invalid_request: "invalid_request";
+            authentication_failed: "authentication_failed";
+            permission_denied: "permission_denied";
+            insufficient_scope: "insufficient_scope";
+            model_not_found: "model_not_found";
+            unsupported_modality: "unsupported_modality";
+            context_length_exceeded: "context_length_exceeded";
+            request_too_large: "request_too_large";
+            output_limit_exceeded: "output_limit_exceeded";
+            idempotency_conflict: "idempotency_conflict";
+            insufficient_balance: "insufficient_balance";
+            spending_limit_exceeded: "spending_limit_exceeded";
+            quota_exceeded: "quota_exceeded";
+            byok_credential_invalid: "byok_credential_invalid";
+            policy_violation: "policy_violation";
+            commercial_permission_denied: "commercial_permission_denied";
+            no_route_available: "no_route_available";
+            upstream_content_filtered: "upstream_content_filtered";
+            cancelled: "cancelled";
+            rate_limited: "rate_limited";
+            provider_error: "provider_error";
+            provider_timeout: "provider_timeout";
+            provider_overloaded: "provider_overloaded";
+            service_unavailable: "service_unavailable";
+            internal_error: "internal_error";
+            deployment_unavailable: "deployment_unavailable";
+            provider_credential_invalid: "provider_credential_invalid";
+            provider_billing_refused: "provider_billing_refused";
+        }>;
+        message: z.ZodString;
+        retryable: z.ZodBoolean;
+        requestId: z.ZodString;
+        retryAfterMs: z.ZodOptional<z.ZodNumber>;
+        param: z.ZodOptional<z.ZodString>;
+        upstreamCategory: z.ZodOptional<z.ZodEnum<{
+            rate_limit: "rate_limit";
+            quota: "quota";
+            timeout: "timeout";
+            overloaded: "overloaded";
+            server_error: "server_error";
+            content_filter: "content_filter";
+            invalid_request: "invalid_request";
+            authentication: "authentication";
+            unknown: "unknown";
+        }>>;
+        providerError: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            status: z.ZodOptional<z.ZodNumber>;
+            code: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strip>;
+    usage: z.ZodOptional<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>>;
+}, z.core.$strict>;
+export type DecisionResult = z.infer<typeof decisionResultSchema>;
+export type DecisionFailure = z.infer<typeof decisionFailureSchema>;

package/dist/internal/decisions.js

@@ -0,0 +1,69 @@
+/**
+ * Kaana's typed decisions result and failure on the signed lane.
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/decisions.ts`) by Kaana ADR 0002.
+ */
+import { z } from 'zod';
+import { decisionAnswerSchema } from '../public/decisions.js';
+import { modelReferenceSchema, requestIdSchema } from '../public/identifiers.js';
+import { inferenceErrorSchema } from './errors.js';
+import { normalizedUsageReportSchema } from './usage.js';
+const resultFields = {
+    schemaVersion: z.literal(1),
+    requestId: requestIdSchema,
+    model: modelReferenceSchema.refine((model) => model.includes('@'), 'Decisions require an immutable model revision.'),
+    data: z.array(decisionAnswerSchema).min(1).max(255),
+};
+function uniqueAnswers(result, ctx) {
+    if (new Set(result.data.map((answer) => answer.id)).size !== result.data.length)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['data'],
+            message: 'Answer IDs must be unique.',
+        });
+}
+export const decisionResultSchema = z
+    .object({ ...resultFields, usage: normalizedUsageReportSchema })
+    .strict()
+    .superRefine(uniqueAnswers)
+    .superRefine((result, ctx) => {
+    if (result.usage.requestId !== result.requestId ||
+        result.usage.resolvedModelReference !== result.model ||
+        result.usage.outcome !== 'completed') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['usage'],
+            message: 'Decision usage must describe this completed request and immutable model.',
+        });
+    }
+});
+/**
+ * Kaana's typed decisions failure. `usage` is present only when the provider
+ * measured something before failing; its absence means nothing was measured,
+ * never that the cost was zero. A failure carrying usage did execute.
+ */
+export const decisionFailureSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    requestId: requestIdSchema,
+    error: inferenceErrorSchema,
+    usage: normalizedUsageReportSchema.optional(),
+})
+    .strict()
+    .superRefine((failure, ctx) => {
+    if (failure.error.requestId !== failure.requestId) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['error', 'requestId'],
+            message: 'The error must answer this request.',
+        });
+    }
+    if (failure.usage !== undefined &&
+        (failure.usage.requestId !== failure.requestId || failure.usage.outcome === 'completed')) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['usage'],
+            message: 'Failure usage must describe this request and an incomplete outcome.',
+        });
+    }
+});

package/dist/internal/economics.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How a grant is treated economically.
+ *
+ * The treatment is decided by Oxy from the AUTHENTICATED application, its
+ * environment and lane, against a versioned policy; nothing a caller sends can
+ * select it, so it appears only on the signed grant, never on a public request.
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/economics.ts`) by Kaana
+ * ADR 0002, which adds `platform_fee_only` (decision 4: a BYOK request, billed
+ * by the provider to the customer, on which Oxy charges only its fee; until now
+ * a receipt flag). Cost-centre usage and the metered generation read model stay
+ * in `@oxy.so/contracts`.
+ */
+import { z } from 'zod';
+/**
+ * - `commercial` — the default: reserve, settle, refund.
+ * - `internal_metered` — a product relationship Oxy configured (Alia on Kaana,
+ *   the Jev classifier): no hold and no receipt, usage still recorded.
+ * - `platform_fee_only` — BYOK: the provider bills the customer's own account.
+ */
+export declare const INFERENCE_ECONOMIC_TREATMENTS: readonly ["commercial", "internal_metered", "platform_fee_only"];
+export declare const inferenceEconomicTreatmentSchema: z.ZodEnum<{
+    commercial: "commercial";
+    internal_metered: "internal_metered";
+    platform_fee_only: "platform_fee_only";
+}>;
+export type InferenceEconomicTreatment = z.infer<typeof inferenceEconomicTreatmentSchema>;

package/dist/internal/economics.js

@@ -0,0 +1,26 @@
+/**
+ * How a grant is treated economically.
+ *
+ * The treatment is decided by Oxy from the AUTHENTICATED application, its
+ * environment and lane, against a versioned policy; nothing a caller sends can
+ * select it, so it appears only on the signed grant, never on a public request.
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/economics.ts`) by Kaana
+ * ADR 0002, which adds `platform_fee_only` (decision 4: a BYOK request, billed
+ * by the provider to the customer, on which Oxy charges only its fee; until now
+ * a receipt flag). Cost-centre usage and the metered generation read model stay
+ * in `@oxy.so/contracts`.
+ */
+import { z } from 'zod';
+/**
+ * - `commercial` — the default: reserve, settle, refund.
+ * - `internal_metered` — a product relationship Oxy configured (Alia on Kaana,
+ *   the Jev classifier): no hold and no receipt, usage still recorded.
+ * - `platform_fee_only` — BYOK: the provider bills the customer's own account.
+ */
+export const INFERENCE_ECONOMIC_TREATMENTS = [
+    'commercial',
+    'internal_metered',
+    'platform_fee_only',
+];
+export const inferenceEconomicTreatmentSchema = z.enum(INFERENCE_ECONOMIC_TREATMENTS);