@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/turn-serving-policy.ts

@@ -0,0 +1,167 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import { TurnExecutionPolicyV1 } from "./index";
+
+export const TURN_SERVING_POLICY_METADATA_KEY = "turnServingPolicyV1" as const;
+export const TURN_PENDING_SERVING_POLICY_METADATA_KEY = "turnPendingServingPolicyV1" as const;
+
+const ServingReason = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "initial",
+    "sticky",
+    "pinned",
+    "reselected_cold",
+    "failover_same_provider",
+    "failover_cross_provider",
+    "return_to_preferred",
+  ]),
+);
+
+/** One immutable serving receipt, not a replacement for the accepted policy.
+ * The lazy reference keeps the contracts barrel free of initialization cycles.
+ * Connection ids are references only; no credential material belongs here.
+ */
+export const TurnServingPolicyV1 = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      schemaVersion: z.literal(1),
+      policy: z.lazy(() => TurnExecutionPolicyV1),
+      executionGeneration: primitives.positiveInteger.max(Number.MAX_SAFE_INTEGER),
+      /** Selection reference; advisory until the generation is placed. */
+      connectionId: primitives.uuid,
+      reason: ServingReason,
+      /** Highest session history position at recording, including inactive rows.
+       * Fractional positions exist in historical compaction layouts. A revision
+       * applies strictly AFTER this boundary, never to the row at the boundary.
+       */
+      historyPosition: z.number().finite().nonnegative(),
+    })
+    .strict()
+    .superRefine((revision, context) => {
+      if (revision.policy.credentialRestriction !== undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["policy", "credentialRestriction"],
+          message: "Restricted policies cannot switch",
+        });
+      }
+      if (
+        revision.policy.billing.metering !== "external" ||
+        revision.policy.credentialSource.kind === "deployment"
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: ["policy", "billing"],
+          message: "Serving revisions require externally funded connected access",
+        });
+      }
+    }),
+);
+export type TurnServingPolicyV1 = z.infer<typeof TurnServingPolicyV1>;
+
+/** A recovery proposal, NOT provenance. Its history boundary is assigned only
+ * when a newer claimed generation commits a serving revision. C2 will stage it
+ * atomically with recovery using the transaction-local database helper.
+ */
+export const TurnPendingServingPolicyV1 = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      schemaVersion: z.literal(1),
+      sourceExecutionGeneration: primitives.positiveInteger.max(Number.MAX_SAFE_INTEGER),
+      sourceAttemptId: primitives.uuid,
+      policy: z.lazy(() => TurnExecutionPolicyV1),
+      connectionId: primitives.uuid,
+      reason: ServingReason,
+    })
+    .strict()
+    .superRefine((target, context) => {
+      const candidate = TurnServingPolicyV1.safeParse({
+        schemaVersion: 1,
+        policy: target.policy,
+        connectionId: target.connectionId,
+        reason: target.reason,
+        executionGeneration: target.sourceExecutionGeneration,
+        historyPosition: 0,
+      });
+      if (!candidate.success)
+        context.addIssue({ code: "custom", message: "Invalid pending serving selection" });
+    }),
+);
+export type TurnPendingServingPolicyV1 = z.infer<typeof TurnPendingServingPolicyV1>;
+
+export function readTurnPendingServingPolicyV1(
+  metadata: unknown,
+): TurnPendingServingPolicyV1 | null {
+  if (metadata === null || metadata === undefined) return null;
+  if (typeof metadata !== "object" || Array.isArray(metadata))
+    throw new Error("Malformed pending serving metadata");
+  if (!Object.prototype.hasOwnProperty.call(metadata, TURN_PENDING_SERVING_POLICY_METADATA_KEY))
+    return null;
+  const parsed = TurnPendingServingPolicyV1.safeParse(
+    (metadata as Record<string, unknown>)[TURN_PENDING_SERVING_POLICY_METADATA_KEY],
+  );
+  if (!parsed.success) throw new Error("Malformed pending serving policy");
+  return parsed.data;
+}
+
+const ServingRevisions = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(TurnServingPolicyV1)
+    .nonempty()
+    .superRefine((revisions, context) => {
+      for (let index = 1; index < revisions.length; index++) {
+        const previous = revisions[index - 1]!;
+        const current = revisions[index]!;
+        if (
+          current.executionGeneration <= previous.executionGeneration ||
+          current.historyPosition < previous.historyPosition
+        ) {
+          context.addIssue({
+            code: "custom",
+            path: [index],
+            message: "Serving revisions must advance generation and never move history backwards",
+          });
+        }
+      }
+    }),
+);
+
+export type TurnServingPolicyReadV1 =
+  | { kind: "absent" }
+  | { kind: "valid"; revisions: TurnServingPolicyV1[] };
+
+/** Only absence is legacy. Malformed present metadata fails closed, without
+ * reflecting untrusted values (which might contain credentials) into errors.
+ */
+export function readTurnServingPolicyV1(metadata: unknown): TurnServingPolicyReadV1 {
+  if (metadata === null || metadata === undefined) return { kind: "absent" };
+  if (typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new Error("Malformed turn serving policy metadata");
+  }
+  if (!Object.prototype.hasOwnProperty.call(metadata, TURN_SERVING_POLICY_METADATA_KEY))
+    return { kind: "absent" };
+  const parsed = ServingRevisions.safeParse(
+    (metadata as Record<string, unknown>)[TURN_SERVING_POLICY_METADATA_KEY],
+  );
+  if (!parsed.success) throw new Error("Malformed turn serving policy revisions");
+  return { kind: "valid", revisions: parsed.data };
+}
+
+/** D-39: the first receipt establishes the baseline. Reclaims, account-only
+ * rotations and reasoning changes do not spend the model/provider bound.
+ * Combine this with the all-provider refusal count at the recovery boundary.
+ */
+export function countTurnServingPolicyChangesV1(revisions: readonly TurnServingPolicyV1[]): number {
+  let count = 0;
+  for (let index = 1; index < revisions.length; index++) {
+    const previous = revisions[index - 1]!.policy;
+    const current = revisions[index]!.policy;
+    if (
+      previous.providerId !== current.providerId ||
+      previous.productModelId !== current.productModelId
+    )
+      count++;
+  }
+  return count;
+}

package/src/usage-allowances.ts

@@ -1,25 +1,33 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 /** Credit amounts are integer USD micros (1 USD = 1,000,000), never floating-point dollars. */
-export const AllowanceCredits = z.number().int().nonnegative().safe();
-const Version = z.number().int().nonnegative().safe();
-const Timestamp = z.string().datetime({ offset: true });
-const OperationId = z
-  .string()
-  .min(1)
-  .max(256)
-  .refine(
-    (value) =>
-      value.trim().length > 0 &&
-      !value.includes("\0") &&
-      !/[\uD800-\uDFFF]/u.test(value) &&
-      new TextEncoder().encode(value).byteLength <= 256,
-  );
-const SubjectId = z
-  .string()
-  .min(1)
-  .max(1024)
-  .refine((value) => !value.includes("\0"));
+export const AllowanceCredits = /* @__PURE__ */ defineSchema(() =>
+  primitives.nonnegativeInteger.safe(),
+);
+const Version = /* @__PURE__ */ defineSchema(() => primitives.nonnegativeInteger.safe());
+const Timestamp = /* @__PURE__ */ defineSchema(() => primitives.string.datetime({ offset: true }));
+const OperationId = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(256)
+    .refine(
+      (value) =>
+        value.trim().length > 0 &&
+        !value.includes("\0") &&
+        !/[\uD800-\uDFFF]/u.test(value) &&
+        new TextEncoder().encode(value).byteLength <= 256,
+    ),
+);
+const SubjectId = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(1024)
+    .refine((value) => !value.includes("\0")),
+);
 
 /**
  * A share scales with the current workspace pool, including unexpired grants.
@@ -28,160 +36,228 @@ const SubjectId = z
  * happens before the next call, after actual usage is settled.
  * null removes the override and uses the workspace's memberDefault.
  */
-export const MemberAllowanceRule = z.union([
-  z.object({ share: z.number().finite().nonnegative() }).strict(),
-  z.object({ credits: AllowanceCredits }).strict(),
-  z.null(),
-]);
+export const MemberAllowanceRule = /* @__PURE__ */ defineSchema(() =>
+  z.union([
+    z.object({ share: z.number().finite().nonnegative() }).strict(),
+    z.object({ credits: AllowanceCredits }).strict(),
+    z.null(),
+  ]),
+);
 export type MemberAllowanceRule = z.infer<typeof MemberAllowanceRule>;
 
-export const MemberAllowanceDefault = z.union([
-  z.enum(["none", "equal_share"]),
-  z.object({ share: z.number().finite().nonnegative() }).strict(),
-  z.object({ credits: AllowanceCredits }).strict(),
-]);
+export const MemberAllowanceDefault = /* @__PURE__ */ defineSchema(() =>
+  z.union([
+    z.enum(["none", "equal_share"]),
+    z.object({ share: z.number().finite().nonnegative() }).strict(),
+    z.object({ credits: AllowanceCredits }).strict(),
+  ]),
+);
 export type MemberAllowanceDefault = z.infer<typeof MemberAllowanceDefault>;
 
-const Thresholds = z.array(z.number().finite().positive().max(1)).max(16);
+const Thresholds = /* @__PURE__ */ defineSchema(() =>
+  z.array(z.number().finite().positive().max(1)).max(16),
+);
+/**
+ * How model calls that spend no Opengeni credits count: subscription
+ * connections, workspace-owned keys and deployments without credit billing.
+ * "ignore" (the default) keeps the allowance credit-only. "list_price" counts
+ * each such call at its configured list-price estimate in USD micros and
+ * admits those turns against the allowance; calls without a list price are
+ * not counted.
+ */
+export const UnbilledUsageMetering = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["ignore", "list_price"]),
+);
+export type UnbilledUsageMetering = z.infer<typeof UnbilledUsageMetering>;
 /** Omitted threshold lists default to [0.8, 1]. Monthly boundaries are UTC. */
-export const WorkspaceAllowanceConfig = z
-  .object({
-    includedCredits: AllowanceCredits,
-    period: z.enum(["monthly", "none"]),
-    anchorDay: z.number().int().min(1).max(31).optional(),
-    memberDefault: MemberAllowanceDefault.optional(),
-    thresholds: z
-      .object({ workspace: Thresholds.optional(), member: Thresholds.optional() })
-      .strict()
-      .optional(),
-  })
-  .strict();
+export const WorkspaceAllowanceConfig = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      includedCredits: AllowanceCredits,
+      period: z.enum(["monthly", "none"]),
+      anchorDay: z.number().int().min(1).max(31).optional(),
+      memberDefault: MemberAllowanceDefault.optional(),
+      thresholds: z
+        .object({ workspace: Thresholds.optional(), member: Thresholds.optional() })
+        .strict()
+        .optional(),
+      unbilledUsage: UnbilledUsageMetering.optional(),
+    })
+    .strict(),
+);
 export type WorkspaceAllowanceConfig = z.infer<typeof WorkspaceAllowanceConfig>;
 
-export const WorkspaceAllowance = WorkspaceAllowanceConfig.extend({ version: Version.min(1) });
+export const WorkspaceAllowance = /* @__PURE__ */ defineSchema(() =>
+  WorkspaceAllowanceConfig.extend({ version: Version.min(1) }),
+);
 export type WorkspaceAllowance = z.infer<typeof WorkspaceAllowance>;
 /**
  * Lifecycle version survives clear. version=0 means never configured; a null
  * config with a positive version is cleared. Use this version for recreation.
  * The existing nullable configuration read remains unchanged.
  */
-export const WorkspaceAllowanceState = z
-  .object({ version: Version, config: WorkspaceAllowance.nullable() })
-  .strict()
-  .refine((state) => state.config === null || state.config.version === state.version, {
-    message: "Allowance configuration and lifecycle versions must match",
-    path: ["config", "version"],
-  });
+export const WorkspaceAllowanceState = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({ version: Version, config: WorkspaceAllowance.nullable() })
+    .strict()
+    .refine((state) => state.config === null || state.config.version === state.version, {
+      message: "Allowance configuration and lifecycle versions must match",
+      path: ["config", "version"],
+    }),
+);
 export type WorkspaceAllowanceState = z.infer<typeof WorkspaceAllowanceState>;
-export const SetWorkspaceAllowanceRequest = WorkspaceAllowanceConfig.extend({
-  expectedVersion: Version,
-});
+export const SetWorkspaceAllowanceRequest = /* @__PURE__ */ defineSchema(() =>
+  WorkspaceAllowanceConfig.extend({
+    expectedVersion: Version,
+  }),
+);
 export type SetWorkspaceAllowanceRequest = z.infer<typeof SetWorkspaceAllowanceRequest>;
 /** Reuse operationId and the exact expectedVersion to recover a lost clear
  * receipt. A later lifecycle change conflicts; read the state before deciding
  * on a new mutation, never guess a version or change it for a retry. */
-export const ClearWorkspaceAllowanceRequest = z
-  .object({ expectedVersion: Version.min(1), operationId: OperationId.optional() })
-  .strict();
+export const ClearWorkspaceAllowanceRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({ expectedVersion: Version.min(1), operationId: OperationId.optional() }).strict(),
+);
 export type ClearWorkspaceAllowanceRequest = z.infer<typeof ClearWorkspaceAllowanceRequest>;
-export const ClearWorkspaceAllowanceResponse = z.object({ version: Version.min(1) }).strict();
+export const ClearWorkspaceAllowanceResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ version: Version.min(1) }).strict(),
+);
 export type ClearWorkspaceAllowanceResponse = z.infer<typeof ClearWorkspaceAllowanceResponse>;
 
 /** Reuse the operationId and exact request to recover an uncertain grant response. */
-export const GrantWorkspaceCreditsRequest = z
-  .object({
-    operationId: OperationId,
-    credits: AllowanceCredits.positive(),
-    expiresAt: Timestamp.nullable().optional(),
-  })
-  .strict();
+export const GrantWorkspaceCreditsRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: OperationId,
+      credits: AllowanceCredits.positive(),
+      expiresAt: Timestamp.nullable().optional(),
+    })
+    .strict(),
+);
 export type GrantWorkspaceCreditsRequest = z.infer<typeof GrantWorkspaceCreditsRequest>;
-export const WorkspaceCreditGrant = GrantWorkspaceCreditsRequest.extend({
-  remaining: AllowanceCredits,
-  expiresAt: Timestamp.nullable(),
-});
+export const WorkspaceCreditGrant = /* @__PURE__ */ defineSchema(() =>
+  GrantWorkspaceCreditsRequest.extend({
+    remaining: AllowanceCredits,
+    expiresAt: Timestamp.nullable(),
+  }),
+);
 export type WorkspaceCreditGrant = z.infer<typeof WorkspaceCreditGrant>;
 
-export const SetMemberAllowanceRequest = z
-  .object({
-    rule: MemberAllowanceRule,
-    expectedVersion: Version,
-  })
-  .strict();
+export const SetMemberAllowanceRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      rule: MemberAllowanceRule,
+      expectedVersion: Version,
+    })
+    .strict(),
+);
 export type SetMemberAllowanceRequest = z.infer<typeof SetMemberAllowanceRequest>;
-export const MemberAllowance = z
-  .object({
-    subjectId: SubjectId,
-    rule: MemberAllowanceRule,
-    version: Version,
-  })
-  .strict();
+export const MemberAllowance = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      subjectId: SubjectId,
+      rule: MemberAllowanceRule,
+      version: Version,
+    })
+    .strict(),
+);
 export type MemberAllowance = z.infer<typeof MemberAllowance>;
 
-export const UsageAllowancePeriod = z.union([
-  z.literal("current"),
-  z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/),
-]);
+export const UsageAllowancePeriod = /* @__PURE__ */ defineSchema(() =>
+  z.union([z.literal("current"), primitives.string.regex(/^\d{4}-(0[1-9]|1[0-2])$/)]),
+);
 export type UsageAllowancePeriod = z.infer<typeof UsageAllowancePeriod>;
-export const GetUsageRequest = z
-  .object({
-    period: UsageAllowancePeriod.optional(),
-    limit: z.number().int().min(1).max(200).optional(),
-    cursor: z.string().min(1).max(2048).optional(),
-  })
-  .strict();
+export const GetUsageRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      period: UsageAllowancePeriod.optional(),
+      limit: z.number().int().min(1).max(200).optional(),
+      cursor: z.string().min(1).max(2048).optional(),
+    })
+    .strict(),
+);
 export type GetUsageRequest = z.infer<typeof GetUsageRequest>;
-export const GetMyUsageRequest = GetUsageRequest.pick({ period: true });
+export const GetMyUsageRequest = /* @__PURE__ */ defineSchema(() =>
+  GetUsageRequest.pick({ period: true }),
+);
 export type GetMyUsageRequest = z.infer<typeof GetMyUsageRequest>;
 
-export const UsageAllowanceStatus = z.enum(["ok", "warning", "exhausted"]);
+export const UsageAllowanceStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["ok", "warning", "exhausted"]),
+);
 export type UsageAllowanceStatus = z.infer<typeof UsageAllowanceStatus>;
-export const UsageAllowanceWindow = z
-  .object({
-    start: Timestamp.nullable(),
-    end: Timestamp.nullable(),
-  })
-  .strict();
+export const UsageAllowanceWindow = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      start: Timestamp.nullable(),
+      end: Timestamp.nullable(),
+    })
+    .strict(),
+);
 export type UsageAllowanceWindow = z.infer<typeof UsageAllowanceWindow>;
-const Usage = z.object({
-  limit: AllowanceCredits.nullable(),
-  used: AllowanceCredits,
-  remaining: z.number().int().safe().nullable(),
-  /** Display this ratio rather than raw USD micros in human-facing products. */
-  fraction: z.number().finite().nonnegative().nullable(),
-  status: UsageAllowanceStatus,
-  resetsAt: Timestamp.nullable(),
-});
-export const WorkspaceAllowanceUsage = Usage.extend({
-  includedCredits: AllowanceCredits,
-  grantsRemaining: AllowanceCredits,
-}).strict();
+const Usage = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    limit: AllowanceCredits.nullable(),
+    used: AllowanceCredits,
+    remaining: z.number().int().safe().nullable(),
+    /** Display this ratio rather than raw USD micros in human-facing products. */
+    fraction: z.number().finite().nonnegative().nullable(),
+    status: UsageAllowanceStatus,
+    resetsAt: Timestamp.nullable(),
+  }),
+);
+export const WorkspaceAllowanceUsage = /* @__PURE__ */ defineSchema(() =>
+  Usage.extend({
+    includedCredits: AllowanceCredits,
+    grantsRemaining: AllowanceCredits,
+  }).strict(),
+);
 export type WorkspaceAllowanceUsage = z.infer<typeof WorkspaceAllowanceUsage>;
-export const MemberAllowanceUsage = Usage.extend({
-  subjectId: SubjectId,
-  externalIdentity: z.object({ source: z.string(), externalId: z.string() }).strict().nullable(),
-  rule: MemberAllowanceRule,
-  version: Version,
-}).strict();
+export const MemberAllowanceUsage = /* @__PURE__ */ defineSchema(() =>
+  Usage.extend({
+    subjectId: SubjectId,
+    externalIdentity: z
+      .object({ source: primitives.string, externalId: primitives.string })
+      .strict()
+      .nullable(),
+    rule: MemberAllowanceRule,
+    version: Version,
+  }).strict(),
+);
 export type MemberAllowanceUsage = z.infer<typeof MemberAllowanceUsage>;
 /** /usage/me returns only the authenticated subject's member row, never the roster. */
-export const WorkspaceUsageResponse = z
-  .object({
-    period: UsageAllowanceWindow,
-    workspace: WorkspaceAllowanceUsage,
-    members: z.array(MemberAllowanceUsage),
-    nextCursor: z.string().nullable(),
-  })
-  .strict();
+export const WorkspaceUsageResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      /**
+       * The unit of every amount (`limit`, `used`, `remaining`,
+       * `includedCredits`, `grantsRemaining`): integer USD micros, 1 USD =
+       * 1,000,000. Absent from servers that predate it; the unit is the same.
+       */
+      unit: z.literal("usd_micros").optional(),
+      /**
+       * The window the counters cover. Without a configured budget this is
+       * still the calendar month (UTC) being counted; null when the window
+       * is unknown (a past month with no recorded history) or lifetime.
+       */
+      period: UsageAllowanceWindow,
+      workspace: WorkspaceAllowanceUsage,
+      members: z.array(MemberAllowanceUsage),
+      nextCursor: primitives.nullableString,
+    })
+    .strict(),
+);
 export type WorkspaceUsageResponse = z.infer<typeof WorkspaceUsageResponse>;
 
-export const AllowanceExhaustedRefusal = z
-  .object({
-    code: z.literal("allowance_exhausted"),
-    scope: z.enum(["workspace", "member"]),
-    resetsAt: Timestamp.nullable(),
-    subjectId: SubjectId.optional(),
-    message: z.string(),
-  })
-  .strict();
+export const AllowanceExhaustedRefusal = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      code: z.literal("allowance_exhausted"),
+      scope: z.enum(["workspace", "member"]),
+      resetsAt: Timestamp.nullable(),
+      subjectId: SubjectId.optional(),
+      message: primitives.string,
+    })
+    .strict(),
+);
 export type AllowanceExhaustedRefusal = z.infer<typeof AllowanceExhaustedRefusal>;

package/src/values.ts

@@ -0,0 +1,25 @@
+/**
+ * Small runtime helpers shared across packages. Dependency-free and safe in
+ * browsers, React Native, workers and servers, so any package can import
+ * `@opengeni/contracts/values` without pulling in zod or Node built-ins.
+ */
+
+/** A non-null object that is not an array. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** An `Error`'s message, or the value converted to a string. */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Lowercase hex SHA-256 of bytes, or of a string's UTF-8 encoding, with Web Crypto. */
+export async function sha256Hex(data: string | Uint8Array): Promise<string> {
+  // A copy hands Web Crypto a plain ArrayBuffer even for views over shared memory.
+  const bytes =
+    typeof data === "string" ? new TextEncoder().encode(data) : new Uint8Array(data.byteLength);
+  if (typeof data !== "string") bytes.set(data);
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}