@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/transcription-recordings.ts

@@ -1,162 +1,176 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-export const TranscriptionRecordingErrorCode = z.enum([
-  "permission_denied",
-  "not_supported",
-  "network",
-  "provider",
-  "policy_blocked",
-  "timeout",
-  "cancelled",
-  "unavailable",
-  "too_large",
-  "invalid_audio",
-  "unknown",
-]);
+export const TranscriptionRecordingErrorCode = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "permission_denied",
+    "not_supported",
+    "network",
+    "provider",
+    "policy_blocked",
+    "timeout",
+    "cancelled",
+    "unavailable",
+    "too_large",
+    "invalid_audio",
+    "unknown",
+    "insufficient_credits",
+    "allowance_exhausted",
+    "monthly_model_cost_limit",
+  ]),
+);
 export type TranscriptionRecordingErrorCode = z.infer<typeof TranscriptionRecordingErrorCode>;
 
-export const TranscriptionRecordingState = z.enum([
-  "uploading",
-  "segmenting",
-  "ready",
-  "transcribing",
-  "complete",
-  "failed",
-  "discarded",
-]);
+export const TranscriptionRecordingState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["uploading", "segmenting", "ready", "transcribing", "complete", "failed", "discarded"]),
+);
 export type TranscriptionRecordingState = z.infer<typeof TranscriptionRecordingState>;
 
-export const TranscriptionRecordingSegmentState = z.enum([
-  "preparing",
-  "pending",
-  "transcribing",
-  "complete",
-  "failed",
-]);
+export const TranscriptionRecordingSegmentState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["preparing", "pending", "transcribing", "complete", "failed"]),
+);
 export type TranscriptionRecordingSegmentState = z.infer<typeof TranscriptionRecordingSegmentState>;
 
-export const ClientResumableVoiceInputConfig = z
-  .object({
-    maxDurationSeconds: z
-      .number()
-      .int()
-      .positive()
-      .max(8 * 60 * 60),
-    maxSizeBytes: z
-      .number()
-      .int()
-      .positive()
-      .max(512 * 1024 * 1024),
-    maxChunkSizeBytes: z
-      .number()
-      .int()
-      .positive()
-      .max(25 * 1024 * 1024),
-    providerSegmentSeconds: z.number().int().positive().max(600),
-  })
-  .strict();
+export const ClientResumableVoiceInputConfig = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      maxDurationSeconds: z
+        .number()
+        .int()
+        .positive()
+        .max(8 * 60 * 60),
+      maxSizeBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(512 * 1024 * 1024),
+      maxChunkSizeBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(25 * 1024 * 1024),
+      providerSegmentSeconds: z.number().int().positive().max(600),
+    })
+    .strict(),
+);
 export type ClientResumableVoiceInputConfig = z.infer<typeof ClientResumableVoiceInputConfig>;
 
-export const CreateTranscriptionRecordingRequest = z
-  .object({
-    recordingId: z.string().uuid(),
-    mimeType: z.string().trim().min(1).max(128),
-  })
-  .strict();
+export const CreateTranscriptionRecordingRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      recordingId: z.string().uuid(),
+      mimeType: z.string().trim().min(1).max(128),
+    })
+    .strict(),
+);
 export type CreateTranscriptionRecordingRequest = z.infer<
   typeof CreateTranscriptionRecordingRequest
 >;
 
-export const FinalizeTranscriptionRecordingRequest = z
-  .object({
-    chunkCount: z.number().int().positive().max(100_000),
-    totalBytes: z
-      .number()
-      .int()
-      .positive()
-      .max(512 * 1024 * 1024),
-    totalDurationMilliseconds: z
-      .number()
-      .int()
-      .positive()
-      .max(8 * 60 * 60 * 1_000),
-  })
-  .strict();
+export const FinalizeTranscriptionRecordingRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      chunkCount: z.number().int().positive().max(100_000),
+      totalBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(512 * 1024 * 1024),
+      totalDurationMilliseconds: z
+        .number()
+        .int()
+        .positive()
+        .max(8 * 60 * 60 * 1_000),
+    })
+    .strict(),
+);
 export type FinalizeTranscriptionRecordingRequest = z.infer<
   typeof FinalizeTranscriptionRecordingRequest
 >;
 
-export const TranscriptionRecordingChunk = z
-  .object({
-    chunkNumber: z.number().int().nonnegative(),
-    byteLength: z.number().int().positive(),
-    sha256: z.string().regex(/^[0-9a-f]{64}$/),
-    startMilliseconds: z.number().int().nonnegative(),
-    durationMilliseconds: z.number().int().nonnegative(),
-    deduplicated: z.boolean(),
-  })
-  .strict();
+export const TranscriptionRecordingChunk = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      chunkNumber: z.number().int().nonnegative(),
+      byteLength: z.number().int().positive(),
+      sha256: z.string().regex(/^[0-9a-f]{64}$/),
+      startMilliseconds: z.number().int().nonnegative(),
+      durationMilliseconds: z.number().int().nonnegative(),
+      deduplicated: z.boolean(),
+    })
+    .strict(),
+);
 export type TranscriptionRecordingChunk = z.infer<typeof TranscriptionRecordingChunk>;
 
-export const TranscriptionRecordingSegment = z
-  .object({
-    segmentNumber: z.number().int().nonnegative(),
-    state: TranscriptionRecordingSegmentState,
-    startMilliseconds: z.number().int().nonnegative(),
-    durationMilliseconds: z.number().int().positive(),
-    byteLength: z.number().int().positive(),
-    errorCode: TranscriptionRecordingErrorCode.nullable(),
-    retryable: z.boolean(),
-  })
-  .strict();
+export const TranscriptionRecordingSegment = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      segmentNumber: z.number().int().nonnegative(),
+      state: TranscriptionRecordingSegmentState,
+      startMilliseconds: z.number().int().nonnegative(),
+      durationMilliseconds: z.number().int().positive(),
+      byteLength: z.number().int().positive(),
+      errorCode: TranscriptionRecordingErrorCode.nullable(),
+      retryable: z.boolean(),
+    })
+    .strict(),
+);
 export type TranscriptionRecordingSegment = z.infer<typeof TranscriptionRecordingSegment>;
 
-export const TranscriptionRecording = z
-  .object({
-    id: z.string().uuid(),
-    workspaceId: z.string().uuid(),
-    mimeType: z.string().trim().min(1).max(128),
-    state: TranscriptionRecordingState,
-    nextChunkNumber: z.number().int().nonnegative(),
-    chunkCount: z.number().int().nonnegative(),
-    totalBytes: z.number().int().nonnegative(),
-    totalDurationMilliseconds: z.number().int().nonnegative(),
-    segmentCount: z.number().int().nonnegative(),
-    completedSegmentCount: z.number().int().nonnegative(),
-    transcriptText: z.string().max(1_000_000).nullable(),
-    languages: z.array(z.string().trim().min(1).max(64)).max(64),
-    errorCode: TranscriptionRecordingErrorCode.nullable(),
-    retryable: z.boolean(),
-    objectsCleaned: z.boolean(),
-    createdAt: z.string().datetime(),
-    updatedAt: z.string().datetime(),
-    expiresAt: z.string().datetime(),
-  })
-  .strict();
+export const TranscriptionRecording = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z.string().uuid(),
+      workspaceId: z.string().uuid(),
+      mimeType: z.string().trim().min(1).max(128),
+      state: TranscriptionRecordingState,
+      nextChunkNumber: z.number().int().nonnegative(),
+      chunkCount: z.number().int().nonnegative(),
+      totalBytes: z.number().int().nonnegative(),
+      totalDurationMilliseconds: z.number().int().nonnegative(),
+      segmentCount: z.number().int().nonnegative(),
+      completedSegmentCount: z.number().int().nonnegative(),
+      transcriptText: z.string().max(1_000_000).nullable(),
+      languages: z.array(z.string().trim().min(1).max(64)).max(64),
+      errorCode: TranscriptionRecordingErrorCode.nullable(),
+      retryable: z.boolean(),
+      objectsCleaned: z.boolean(),
+      createdAt: z.string().datetime(),
+      updatedAt: z.string().datetime(),
+      expiresAt: z.string().datetime(),
+    })
+    .strict(),
+);
 export type TranscriptionRecording = z.infer<typeof TranscriptionRecording>;
 
-export const TranscriptionRecordingResponse = z
-  .object({
-    recording: TranscriptionRecording,
-    segments: z.array(TranscriptionRecordingSegment).max(1_000),
-    retryAfterMilliseconds: z.number().int().positive().max(60_000).optional(),
-  })
-  .strict();
+export const TranscriptionRecordingResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      recording: TranscriptionRecording,
+      segments: z.array(TranscriptionRecordingSegment).max(1_000),
+      retryAfterMilliseconds: z.number().int().positive().max(60_000).optional(),
+    })
+    .strict(),
+);
 export type TranscriptionRecordingResponse = z.infer<typeof TranscriptionRecordingResponse>;
 
-export const TranscriptionRecordingListResponse = z
-  .object({
-    recordings: z.array(TranscriptionRecording).max(50),
-  })
-  .strict();
+export const TranscriptionRecordingListResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      recordings: z.array(TranscriptionRecording).max(50),
+    })
+    .strict(),
+);
 export type TranscriptionRecordingListResponse = z.infer<typeof TranscriptionRecordingListResponse>;
 
-export const UploadTranscriptionRecordingChunkResponse = z
-  .object({
-    recording: TranscriptionRecording,
-    chunk: TranscriptionRecordingChunk,
-  })
-  .strict();
+export const UploadTranscriptionRecordingChunkResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      recording: TranscriptionRecording,
+      chunk: TranscriptionRecordingChunk,
+    })
+    .strict(),
+);
 export type UploadTranscriptionRecordingChunkResponse = z.infer<
   typeof UploadTranscriptionRecordingChunkResponse
 >;

package/src/turn-serving-policy.ts

@@ -0,0 +1,166 @@
+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: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+      /** Selection reference; advisory until the generation is placed. */
+      connectionId: z.string().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: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+      sourceAttemptId: z.string().uuid(),
+      policy: z.lazy(() => TurnExecutionPolicyV1),
+      connectionId: z.string().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;
+}