@oxy.so/contracts 4.5.0 → 4.7.0

package/dist/cjs/inference/decisions.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decisionSuccessSchema = exports.decisionFailureSchema = exports.decisionResultSchema = exports.decisionAnswerSchema = exports.decisionRequestSchema = exports.decisionInputSchema = exports.decisionQuestionSchema = exports.decisionEffortSchema = void 0;
+exports.decisionInputBudget = decisionInputBudget;
+exports.decisionFitsGateway = decisionFitsGateway;
+exports.decisionAnswersMatch = decisionAnswersMatch;
+const zod_1 = require("zod");
+const errors_1 = require("./errors");
+const identifiers_1 = require("./identifiers");
+const money_1 = require("./money");
+const routingPolicy_1 = require("./routingPolicy");
+const usage_1 = require("./usage");
+const probability = zod_1.z.number().finite().min(0).max(1);
+const text = zod_1.z.string().min(1).max(65536);
+const id = zod_1.z.string().min(1).max(128);
+const tolerance = 1e-6;
+exports.decisionEffortSchema = zod_1.z.enum([
+    "instant",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+]);
+const common = { id, question: text, criteria: text.optional() };
+exports.decisionQuestionSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z
+        .object({
+        ...common,
+        kind: zod_1.z.literal("choice"),
+        options: zod_1.z.array(text).min(2).max(255),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...common,
+        kind: zod_1.z.literal("score"),
+        levels: zod_1.z.array(text).min(2).max(10),
+    })
+        .strict(),
+    zod_1.z.object({ ...common, kind: zod_1.z.literal("noul") }).strict(),
+]);
+const payloadFields = {
+    state: zod_1.z.string().max(65536),
+    instructions: text.optional(),
+    questions: zod_1.z.array(exports.decisionQuestionSchema).min(1).max(255),
+    effort: exports.decisionEffortSchema.optional(),
+};
+/**
+ * Conservative serialized input accounting, including escaping and structure.
+ * Measures both the normalized payload and the provider's structured-question
+ * representation. Common instructions repeat per question there. A 255-byte
+ * model identity and 4096-byte gateway-policy allowance bound adapter metadata.
+ * Kaana must also check its final serialized body before sending it.
+ */
+function decisionInputBudget(payload) {
+    const bytes = (value) => new TextEncoder().encode(JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`)).length;
+    const model = "x".repeat(255);
+    const measure = (questions) => {
+        const wireQuestions = Object.fromEntries(questions.map((q) => [q.id, {
+                type: q.kind,
+                instructions: {
+                    question: q.question,
+                    ...(payload.instructions === undefined ? {} : { instructions: payload.instructions }),
+                    ...(q.criteria === undefined ? {} : { criteria: q.criteria }),
+                },
+                ...(q.kind === "choice" ? { criteria: Object.fromEntries(q.options.map((label) => [label, null])) } :
+                    q.kind === "score" ? { criteria: q.levels } : {}),
+            }]));
+        return Math.max(bytes({ ...payload, model, questions }), bytes({ model, state: payload.state, questions: wireQuestions, ...(payload.effort === undefined ? {} : { effort: payload.effort }) }));
+    };
+    const total = measure(payload.questions);
+    return { total, context: Math.max(...payload.questions.map((q) => measure([q]))), gateway: total + 4096 };
+}
+/** OpenRouter's TOTAL limit is separate from direct state-plus-longest context. */
+function decisionFitsGateway(payload) {
+    return decisionInputBudget(payload).gateway <= 32000;
+}
+function validateInput(payload, ctx) {
+    if (new Set(payload.questions.map((q) => q.id)).size !==
+        payload.questions.length)
+        ctx.addIssue({
+            code: "custom",
+            path: ["questions"],
+            message: "Question IDs must be unique.",
+        });
+    for (const [index, question] of payload.questions.entries()) {
+        const labels = question.kind === "choice"
+            ? question.options
+            : question.kind === "score"
+                ? question.levels
+                : [];
+        if (new Set(labels).size !== labels.length)
+            ctx.addIssue({
+                code: "custom",
+                path: ["questions", index],
+                message: "Options and levels must be unique.",
+            });
+    }
+    const budget = decisionInputBudget(payload);
+    if (budget.total > 64000 || budget.context > 32000)
+        ctx.addIssue({
+            code: "custom",
+            path: ["state"],
+            message: "Decisions exceed the serialized 64000-byte total or 32000-byte per-question context budget.",
+        });
+}
+exports.decisionInputSchema = zod_1.z
+    .object(payloadFields)
+    .strict()
+    .superRefine(validateInput);
+exports.decisionRequestSchema = zod_1.z
+    .object({
+    model: identifiers_1.modelReferenceSchema.refine((model) => model.includes("@"), "Decisions require a revision-pinned model."),
+    ...payloadFields,
+})
+    .strict()
+    .superRefine(validateInput);
+exports.decisionAnswerSchema = zod_1.z
+    .discriminatedUnion("kind", [
+    zod_1.z
+        .object({
+        id,
+        kind: zod_1.z.literal("choice"),
+        /** Actual provider-selected option. Never reconstructed from probabilities. */
+        reply: text,
+        /** Provider-returned confidence, not a correctness probability. */
+        confidence: probability,
+        probabilities: zod_1.z.array(probability).min(2).max(255),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        id,
+        kind: zod_1.z.literal("score"),
+        /** Actual provider score. Kept separate from the validated expected index. */
+        reply: zod_1.z.number().finite().min(0).max(9),
+        confidence: probability,
+        mean: zod_1.z.number().finite().min(0).max(9),
+        distribution: zod_1.z.array(probability).min(2).max(10),
+    })
+        .strict(),
+    zod_1.z.object({ id, kind: zod_1.z.literal("noul"), probability }).strict(),
+])
+    .superRefine((answer, ctx) => {
+    if (answer.kind === "noul")
+        return;
+    if (answer.kind === "score" && Math.abs(answer.reply - answer.mean) > tolerance) {
+        ctx.addIssue({ code: "custom", path: ["reply"], message: "Provider score must match the expected level index." });
+    }
+    const distribution = answer.kind === "choice" ? answer.probabilities : answer.distribution;
+    if (Math.abs(distribution.reduce((sum, value) => sum + value, 0) - 1) >
+        tolerance)
+        ctx.addIssue({
+            code: "custom",
+            message: "Probabilities must sum to one.",
+        });
+    if (answer.kind === "score" &&
+        Math.abs(distribution.reduce((sum, value, index) => sum + index * value, 0) -
+            answer.mean) > tolerance)
+        ctx.addIssue({
+            code: "custom",
+            path: ["mean"],
+            message: "Mean must equal the expected zero-based level index.",
+        });
+});
+const resultFields = {
+    schemaVersion: zod_1.z.literal(1),
+    requestId: identifiers_1.requestIdSchema,
+    model: identifiers_1.modelReferenceSchema.refine((model) => model.includes("@"), "Decisions require an immutable model revision."),
+    data: zod_1.z.array(exports.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.",
+        });
+}
+exports.decisionResultSchema = zod_1.z
+    .object({ ...resultFields, usage: usage_1.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.
+ */
+exports.decisionFailureSchema = zod_1.z
+    .object({
+    schemaVersion: zod_1.z.literal(1),
+    requestId: identifiers_1.requestIdSchema,
+    error: errors_1.inferenceErrorSchema,
+    usage: usage_1.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." });
+    }
+});
+exports.decisionSuccessSchema = zod_1.z
+    .object({
+    ...resultFields,
+    usage: zod_1.z.array(money_1.usageQuantitySchema),
+    routingPolicy: routingPolicy_1.routingPolicyReferenceSchema,
+})
+    .strict()
+    .superRefine(uniqueAnswers);
+/** Bind output to the exact request. Provider order is not semantic. */
+function decisionAnswersMatch(input, answers) {
+    if (answers.length !== input.questions.length ||
+        new Set(answers.map((a) => a.id)).size !== answers.length)
+        return false;
+    return input.questions.every((question) => {
+        const answer = answers.find((candidate) => candidate.id === question.id);
+        if (!answer ||
+            !exports.decisionAnswerSchema.safeParse(answer).success ||
+            answer.kind !== question.kind)
+            return false;
+        if (question.kind === "choice" && answer.kind === "choice") {
+            const index = question.options.indexOf(answer.reply);
+            return question.options.length === answer.probabilities.length && index >= 0 &&
+                answer.probabilities[index] + tolerance >= Math.max(...answer.probabilities);
+        }
+        if (question.kind === "score" && answer.kind === "score")
+            return question.levels.length === answer.distribution.length;
+        return question.kind === "noul";
+    });
+}

package/dist/cjs/inference/request.js

@@ -26,6 +26,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.inferenceRequestSchema = exports.inferenceAudioOutputParametersSchema = exports.inferenceSpeechParametersSchema = exports.clientRequestMetadataSchema = exports.inferenceReasoningSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = void 0;
+const decisions_1 = require("./decisions");
 const zod_1 = require("zod");
 const attribution_1 = require("./attribution");
 const catalogue_1 = require("./catalogue");
@@ -198,6 +199,7 @@ exports.inferenceMessageSchema = zod_1.z
  * that both metering and provider translation depend on.
  */
 exports.inferenceInputSchema = zod_1.z.discriminatedUnion("format", [
+    zod_1.z.object({ format: zod_1.z.literal("decisions"), decisions: decisions_1.decisionInputSchema }).strict(),
     zod_1.z
         .object({
         format: zod_1.z.literal("messages"),
@@ -406,6 +408,17 @@ exports.inferenceRequestSchema = zod_1.z
     authorizedRoutes: zod_1.z.array(routingPolicy_1.authorizedRouteSchema).min(1).optional(),
 })
     .superRefine((request, ctx) => {
+    if (request.input.format === "decisions" || request.client.apiFormat === "decisions") {
+        const exactModel = request.target.kind === "model" && request.target.modelReference.includes('@');
+        const foreignRoute = request.authorizedRoutes?.some((route) => request.target.kind !== "model" || route.modelReference !== request.target.modelReference || route.substitution !== "same_model");
+        if (request.input.format !== "decisions" || request.client.apiFormat !== "decisions" ||
+            request.modality !== "text" || request.stream || !exactModel || foreignRoute ||
+            request.maxOutputTokens !== undefined || Object.keys(request.sampling).length > 0 ||
+            request.tools.length > 0 || request.toolChoice !== undefined || request.responseFormat !== undefined ||
+            request.reasoning !== undefined || request.speech !== undefined || request.audioOutput !== undefined) {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["input"], message: "Decisions require exact-model typed nonstreaming input without generation controls or model substitution." });
+        }
+    }
     const isSpeech = request.client.apiFormat === "audio_speech";
     if (isSpeech && request.speech !== undefined && (request.modality !== "audio" || request.input.format !== "text" || request.stream)) {
         ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["speech"], message: "speech requires audio modality, text input, parameters and non-streaming output" });

package/dist/cjs/inference/routingPolicy.js

@@ -34,6 +34,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.authorizedRouteSchema = exports.routingPolicyReferenceSchema = exports.routingPolicySchema = exports.routingFallbackPolicySchema = exports.routingPolicyScopeSchema = exports.routingTargetSchema = void 0;
+exports.effectiveSameModelDeployment = effectiveSameModelDeployment;
 const zod_1 = require("zod");
 const identifiers_1 = require("./identifiers");
 const providerConnection_1 = require("./providerConnection");
@@ -88,10 +89,26 @@ exports.routingPolicyScopeSchema = zod_1.z.discriminatedUnion("kind", [
 exports.routingFallbackPolicySchema = zod_1.z
     .object({
     disabled: zod_1.z.boolean(),
-    sameModelDeployment: zod_1.z.boolean(),
+    /**
+     * Same-model deployment failover. OPTIONAL since contract set 3.4.0, and
+     * absent means ON unless `disabled` is set: serving the same weights from
+     * another deployment of the same revision is an availability decision, not
+     * a substitution. A policy opts out with an explicit `false` (or
+     * `disabled: true`). See `effectiveSameModelDeployment`.
+     */
+    sameModelDeployment: zod_1.z.boolean().optional(),
     authorizedCrossModel: zod_1.z.array(identifiers_1.modelReferenceSchema).default([]),
 })
     .strict();
+/**
+ * Whether a fallback block authorizes same-model deployment failover: an
+ * explicit `sameModelDeployment` wins; absent means on unless `disabled`.
+ */
+function effectiveSameModelDeployment(fallback) {
+    if (fallback.disabled)
+        return false;
+    return fallback.sameModelDeployment ?? true;
+}
 /**
  * A versioned routing policy.
  *
@@ -131,6 +148,14 @@ exports.routingPolicySchema = zod_1.z
     allowedLicenseIds: zod_1.z.array(zod_1.z.string().min(1).max(128)).default([]),
     requireCommercialUseRights: zod_1.z.boolean(),
     fallback: exports.routingFallbackPolicySchema,
+    /**
+     * The routing profiles (power levels) this scope may target, by exact id
+     * (contract set 3.4.0). Empty means no restriction. A request naming a
+     * profile outside a non-empty list is refused with `policy_violation`, and
+     * `auto` only climbs to levels on the list. Concrete model targets are
+     * governed by the other controls, not by this list.
+     */
+    allowedRoutingProfileIds: zod_1.z.array(identifiers_1.routingProfileIdSchema).default([]),
     /** Whether the customer's own provider credentials may or must be used. */
     byokPreference: zod_1.z.enum(["disabled", "prefer", "require"]),
     /** Enterprise reserved capacity rather than shared endpoints. */
@@ -210,6 +235,25 @@ exports.routingPolicySchema = zod_1.z
             }
         }
     }
+    const allowedProfiles = policy.allowedRoutingProfileIds;
+    if (new Set(allowedProfiles).size !== allowedProfiles.length) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ["allowedRoutingProfileIds"],
+            message: "each routing profile is allowed at most once",
+        });
+    }
+    // A default the policy itself forbids would refuse every request that
+    // names no model — a policy that cannot serve its own default.
+    if (allowedProfiles.length > 0 &&
+        policy.defaultTarget?.kind === "routing_profile_id" &&
+        !allowedProfiles.includes(policy.defaultTarget.routingProfileId)) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ["defaultTarget", "routingProfileId"],
+            message: "the default routing profile must be one of allowedRoutingProfileIds",
+        });
+    }
 });
 /**
  * The reference a request records: which policy, at which of the customer's own

package/dist/cjs/inference/version.js

@@ -102,4 +102,4 @@ exports.INFERENCE_CONTRACT_VERSION = void 0;
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-exports.INFERENCE_CONTRACT_VERSION = '3.3.0';
+exports.INFERENCE_CONTRACT_VERSION = '3.5.0';