@oxy.so/contracts 4.11.0 → 4.12.0

package/dist/esm/index.js

@@ -119,7 +119,9 @@ oxyAccountIdSchema, delegatedUserIdSchema, oxyApplicationIdSchema, oxyCredential
 // Wire primitives
 inferenceTimestampSchema, inferenceDateSchema, inferenceHttpsUrlSchema, sha256DigestSchema, 
 // Catalogue references
-publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileIdSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers.js';
+publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileIdSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, 
+// The economic tier Oxy bounds a route by and Kaana reports (ADR 0038)
+inferenceFundingTierSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers.js';
 export { 
 // Exact money and metered units — never floats, units never money.
 currencyCodeSchema, INFERENCE_MONEY_SCALE, exactDecimalSchema, moneySchema, USAGE_UNITS, usageUnitSchema, USAGE_SOURCES, usageSourceSchema, usageQuantitySchema, unitPriceSchema, } from './inference/money.js';

package/dist/esm/inference/identifiers.js

@@ -221,3 +221,16 @@ export const inferenceRegionSchema = z
  * this constant exists to be checked against.
  */
 export const RESERVED_ALIA_PUBLISHER = 'alia';
+/**
+ * The economic tier of the provider capacity that funds a request, in the
+ * order Kaana spends it: `free` (costs nothing), `credit` (a promotional or
+ * trial grant, or a prepaid balance), `paid` (ordinary metered spend).
+ *
+ * Kaana owns provider keys, their economics and which key serves (Oxy ADR
+ * 0038, Kaana ADR 0001); Oxy owns what a customer may spend. The tier is the
+ * one economic fact the two exchange: Oxy BOUNDS a route by it
+ * (`maxFundingTier`), and Kaana REPORTS the tier that served
+ * (`normalizedUsageReportSchema.fundingTier`). No key id, label or price
+ * travels with it.
+ */
+export const inferenceFundingTierSchema = z.enum(['free', 'credit', 'paid']);

package/dist/esm/inference/routingPolicy.js

@@ -32,7 +32,7 @@
  * docs/adr/0017-authorized-routes-in-the-envelope.md, issue #972 workstream 6.
  */
 import { z } from "zod";
-import { deploymentIdSchema, inferenceProviderSlugSchema, inferenceRegionSchema, inferenceTimestampSchema, modelReferenceSchema, oxyAccountIdSchema, oxyApplicationIdSchema, routingProfileIdSchema, } from "./identifiers.js";
+import { deploymentIdSchema, inferenceProviderSlugSchema, inferenceFundingTierSchema, inferenceRegionSchema, inferenceTimestampSchema, modelReferenceSchema, oxyAccountIdSchema, oxyApplicationIdSchema, routingProfileIdSchema, } from "./identifiers.js";
 import { kaanaCredentialHandleSchema } from "./providerConnection.js";
 import { exactDecimalSchema, currencyCodeSchema, unitPriceSchema, } from "./money.js";
 /**
@@ -291,6 +291,16 @@ const authorizedRouteFields = {
     modelReference: modelReferenceSchema,
     provider: inferenceProviderSlugSchema,
     regions: z.array(inferenceRegionSchema),
+    /**
+     * The dearest funding tier the data plane may spend on this route. Absent
+     * means no ceiling. Present, the data plane walks only provider keys whose
+     * STATED tier is at or below it — a key whose economics nobody stated is
+     * never admitted — and refuses the route rather than fall through to a
+     * dearer key. It is how Oxy authorizes a route only while credit funds it
+     * (Alia Pro and Ultra spend credits only, ADR 0038). Meaningless with a
+     * customer credential, which the provider bills to the customer.
+     */
+    maxFundingTier: inferenceFundingTierSchema.optional(),
     /**
      * Exact customer credential binding. Absence means a platform credential;
      * presence names the immutable Kaana generation this route may use.
@@ -345,6 +355,13 @@ export const authorizedRouteSchema = z
         .strict(),
 ])
     .superRefine((route, ctx) => {
+    if (route.maxFundingTier !== undefined && route.customerProviderCredential !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['maxFundingTier'],
+            message: 'a funding ceiling bounds platform keys; a customer credential is billed to the customer',
+        });
+    }
     // Same rule as `modelDeploymentSchema`: a route serves specific weights. An
     // unpinned entry would leave the data plane choosing a revision, which is
     // the one substitution the customer never authorized by naming a model.

package/dist/esm/inference/usage.js

@@ -30,7 +30,7 @@
  */
 import { z } from 'zod';
 import { inferenceAttributionSchema } from './attribution.js';
-import { deploymentIdSchema, generationIdSchema, idempotencyKeySchema, inferenceProviderSlugSchema, inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from './identifiers.js';
+import { deploymentIdSchema, generationIdSchema, idempotencyKeySchema, inferenceFundingTierSchema, inferenceProviderSlugSchema, inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from './identifiers.js';
 import { currencyCodeSchema, exactDecimalSchema, usageQuantitySchema, usageSourceSchema, } from './money.js';
 import { priceSnapshotSchema } from './priceVersion.js';
 /* -------------------------------------------------------------------------- */
@@ -170,6 +170,14 @@ export const normalizedUsageReportSchema = z
     deploymentId: deploymentIdSchema,
     /** How many allowed route switches occurred while serving this request. */
     routeSwitches: z.number().int().nonnegative().max(100),
+    /**
+     * The funding tier of the platform key that served the final attempt, as
+     * the data plane states it (ADR 0038). Absent when the key's economics
+     * were never stated, when a customer credential served, or when nothing
+     * was served. Oxy reads it to account for what the request cost the
+     * platform; it is never a key identity and never reaches a customer.
+     */
+    fundingTier: inferenceFundingTierSchema.optional(),
     startedAt: inferenceTimestampSchema,
     completedAt: inferenceTimestampSchema,
     timeToFirstTokenMs: z.number().int().nonnegative().safe().optional(),

package/dist/esm/inference/version.js

@@ -99,4 +99,4 @@
  * 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 = '3.5.0';
+export const INFERENCE_CONTRACT_VERSION = '3.8.0';