@oxy.so/contracts 4.7.0 → 4.8.0

package/dist/esm/index.js

@@ -184,3 +184,5 @@ export * from './notifications.js';
 export * from './email/messages.js';
 export * from './stickers.js';
 export { decisionEffortSchema, decisionQuestionSchema, decisionInputSchema, decisionRequestSchema, decisionAnswerSchema, decisionResultSchema, decisionSuccessSchema, decisionFailureSchema, decisionInputBudget, decisionFitsGateway, decisionAnswersMatch, } from './inference/decisions.js';
+export { SCOPED_EXECUTION_CONTRACT_VERSION, SCOPED_REQUEST_ENVELOPE_VERSION, scopedExecutionAudienceSchema, scopedExecutionSchema, canonicalScopedExecutionJson } from './inference/scopedExecution.js';
+export { scopedInferenceRequestSchema } from './inference/request.js';

package/dist/esm/inference/catalogue.js

@@ -1,3 +1,4 @@
+import { scopedExecutionAudienceSchema } from "./scopedExecution.js";
 /**
  * The canonical model catalogue.
  *
@@ -488,6 +489,8 @@ export const modelDeploymentSchema = z
     /** See `version.ts`: exchanged with the data plane on its own. */
     schemaVersion: z.literal(2),
     deploymentId: deploymentIdSchema,
+    /** Restrictive audience; never an eligibility approval. */
+    scopedExecution: scopedExecutionAudienceSchema.optional(),
     provider: inferenceProviderSlugSchema,
     /** Always revision-pinned: a deployment serves specific weights. */
     modelReference: modelReferenceSchema,

package/dist/esm/inference/request.js

@@ -25,6 +25,7 @@
  */
 import { decisionInputSchema } from './decisions.js';
 import { z } from "zod";
+import { scopedExecutionSchema, SCOPED_REQUEST_ENVELOPE_VERSION } from "./scopedExecution.js";
 import { inferenceAttributionSchema } from "./attribution.js";
 import { inferenceApiFormatSchema, inferenceModalitySchema, reasoningEffortSchema, } from "./catalogue.js";
 import { idempotencyKeySchema, inferenceTimestampSchema } from "./identifiers.js";
@@ -351,6 +352,8 @@ export const inferenceRequestSchema = z
     .object({
     /** See `version.ts`: this is the Oxy→data-plane request envelope. */
     schemaVersion: z.literal(2),
+    /** Recognized so v2 refuses rather than silently stripping a restriction. */
+    scopedExecution: scopedExecutionSchema.optional(),
     attribution: inferenceAttributionSchema,
     target: routingTargetSchema,
     modality: inferenceModalitySchema,
@@ -405,6 +408,8 @@ export const inferenceRequestSchema = z
     authorizedRoutes: z.array(authorizedRouteSchema).min(1).optional(),
 })
     .superRefine((request, ctx) => {
+    if (request.scopedExecution !== undefined)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["scopedExecution"], message: "Scoped execution requires envelope v3." });
     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");
@@ -534,3 +539,30 @@ export const inferenceRequestSchema = z
         });
     }
 });
+/** Explicit restrictive generation: old v2 receivers reject this version whole. */
+export const scopedInferenceRequestSchema = inferenceRequestSchema.innerType()
+    .extend({ schemaVersion: z.literal(SCOPED_REQUEST_ENVELOPE_VERSION), scopedExecution: scopedExecutionSchema })
+    .superRefine((request, ctx) => {
+    const { scopedExecution: scope, ...base } = request;
+    const legacy = inferenceRequestSchema.safeParse({ ...base, schemaVersion: 2 });
+    if (!legacy.success)
+        for (const issue of legacy.error.issues)
+            ctx.addIssue(issue);
+    const principal = request.attribution.principal;
+    const route = request.authorizedRoutes?.[0];
+    if (request.input.format !== "decisions" || request.client.apiFormat !== "decisions" ||
+        scope.requestId !== request.attribution.requestId ||
+        scope.idempotencyKey !== request.idempotencyKey ||
+        scope.principal.accountId !== principal.billing.accountId ||
+        scope.principal.applicationId !== principal.applicationId ||
+        scope.principal.credentialId !== principal.credentialId ||
+        scope.principal.environment !== principal.environment ||
+        scope.policy.routingPolicyId !== request.routingPolicy.routingPolicyId ||
+        scope.policy.policyVersion !== request.routingPolicy.policyVersion ||
+        request.authorizedRoutes?.length !== 1 || route?.customerProviderCredential !== undefined ||
+        route?.deploymentId !== scope.deploymentId || route?.provider !== scope.provider ||
+        route?.modelReference !== scope.modelReference ||
+        request.target.kind !== "model" || request.target.modelReference !== scope.modelReference) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["scopedExecution"], message: "Scoped execution must restrict the exact attributed decisions request and one platform route." });
+    }
+});

package/dist/esm/inference/scopedExecution.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { deploymentIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, inferenceProviderSlugSchema, modelReferenceSchema, requestIdSchema, } from "./identifiers.js";
+import { exactDecimalSchema } from "./money.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();
+/**
+ * Canonical JSON wire bytes: recursive UTF-16 key order, JSON string/number
+ * encoding, arrays in order, no whitespace. Hash the whole signed input, not a
+ * reparsed/defaulted decision. Reject non-JSON values rather than dropping them.
+ */
+export function canonicalScopedExecutionJson(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number" && Number.isFinite(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        const entries = Array.from(value, (entry, index) => {
+            if (!(index in value))
+                throw new Error("Scoped execution requires dense JSON arrays.");
+            return canonicalScopedExecutionJson(entry);
+        });
+        return `[${entries.join(",")}]`;
+    }
+    if (typeof value === "object" &&
+        value !== null &&
+        Object.getPrototypeOf(value) === Object.prototype) {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalScopedExecutionJson(value[key])}`);
+        return `{${entries.join(",")}}`;
+    }
+    throw new Error("Scoped execution requires JSON wire values.");
+}