@opengeni/contracts 0.40.0 → 0.44.1

package/src/video-generation.ts

@@ -0,0 +1,394 @@
+import { z } from "zod";
+import {
+  GENERATED_VIDEO_MAX_BYTES,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
+  RetainedArtifactReferenceSchema,
+} from "./retained-output";
+
+export const VIDEO_GENERATION_SCHEMA_VERSION = 1 as const;
+export const SEEDANCE_2_5_MODEL_ID = "bytedance/seedance-2.5" as const;
+
+export const VideoGenerationSourceMode = z.enum([
+  "text",
+  "first_frame",
+  "first_and_last_frames",
+  "image_reference",
+  "video_reference",
+]);
+export type VideoGenerationSourceMode = z.infer<typeof VideoGenerationSourceMode>;
+
+export const VideoGenerationResolution = z.enum(["480p", "720p"]);
+export type VideoGenerationResolution = z.infer<typeof VideoGenerationResolution>;
+
+export const VideoGenerationFundingSource = z.enum(["opengeni_credits", "workspace_gateway"]);
+export type VideoGenerationFundingSource = z.infer<typeof VideoGenerationFundingSource>;
+
+export const VideoGenerationAspectRatio = z.enum([
+  "16:9",
+  "4:3",
+  "1:1",
+  "3:4",
+  "9:16",
+  "21:9",
+  "adaptive",
+]);
+export type VideoGenerationAspectRatio = z.infer<typeof VideoGenerationAspectRatio>;
+
+const SandboxVideoReferencePath = z
+  .string()
+  .min(1)
+  .max(1_024)
+  .refine((value) => value.startsWith("/workspace/"), {
+    message: "video references must use an absolute /workspace path",
+  });
+
+export const VideoGenerationSource = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("text") }).strict(),
+  z
+    .object({
+      mode: z.literal("first_frame"),
+      imagePath: SandboxVideoReferencePath,
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("first_and_last_frames"),
+      firstFramePath: SandboxVideoReferencePath,
+      lastFramePath: SandboxVideoReferencePath,
+    })
+    .strict()
+    .refine((value) => value.firstFramePath !== value.lastFramePath, {
+      path: ["lastFramePath"],
+      message: "first and last frame paths must differ",
+    }),
+  z
+    .object({
+      mode: z.literal("image_reference"),
+      imagePath: SandboxVideoReferencePath,
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("video_reference"),
+      videoPath: SandboxVideoReferencePath,
+    })
+    .strict(),
+]);
+export type VideoGenerationSource = z.infer<typeof VideoGenerationSource>;
+
+/** Stable provider-neutral function-tool input. Dynamic capability facts never enter this schema. */
+export const GenerateVideoToolInput = z
+  .object({
+    prompt: z
+      .string()
+      .min(1)
+      .max(32_000)
+      .refine((value) => value.trim().length > 0),
+    modelId: z.string().min(1).max(256).optional(),
+    source: VideoGenerationSource.optional(),
+    durationSeconds: z.number().int().min(4).max(30).optional(),
+    aspectRatio: VideoGenerationAspectRatio.optional(),
+    resolution: VideoGenerationResolution.optional(),
+    generateAudio: z.boolean().optional(),
+  })
+  .strict();
+export type GenerateVideoToolInput = z.infer<typeof GenerateVideoToolInput>;
+
+export const GetVideoGenerationCapabilitiesToolInput = z.object({}).strict();
+export type GetVideoGenerationCapabilitiesToolInput = z.infer<
+  typeof GetVideoGenerationCapabilitiesToolInput
+>;
+
+export const VideoGenerationModelCapability = z
+  .object({
+    modelId: z.string().min(1).max(256),
+    label: z.string().min(1).max(128),
+    providerLabel: z.string().min(1).max(128),
+    sourceModes: z.array(VideoGenerationSourceMode).min(1).max(5),
+    resolutions: z.array(VideoGenerationResolution).min(1).max(2),
+    aspectRatios: z.array(VideoGenerationAspectRatio).min(1).max(7),
+    duration: z
+      .object({
+        minSeconds: z.number().int().positive(),
+        maxSeconds: z.number().int().positive(),
+        stepSeconds: z.number().int().positive(),
+      })
+      .strict()
+      .refine((value) => value.maxSeconds >= value.minSeconds),
+    supportsAudio: z.boolean(),
+  })
+  .strict();
+export type VideoGenerationModelCapability = z.infer<typeof VideoGenerationModelCapability>;
+
+export const VideoGenerationCapabilities = z
+  .object({
+    schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+    capabilityRevision: z.string().min(1).max(128),
+    defaultModelId: z.string().min(1).max(256),
+    models: z.array(VideoGenerationModelCapability).min(1).max(16),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const ids = new Set(value.models.map((model) => model.modelId));
+    if (ids.size !== value.models.length) {
+      ctx.addIssue({ code: "custom", path: ["models"], message: "model ids must be unique" });
+    }
+    if (!ids.has(value.defaultModelId)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["defaultModelId"],
+        message: "default model must be present in the enabled model list",
+      });
+    }
+  });
+export type VideoGenerationCapabilities = z.infer<typeof VideoGenerationCapabilities>;
+
+export const VideoGenerationPolicy = z
+  .object({
+    schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+    revision: z.number().int().nonnegative().safe(),
+    fundingSource: VideoGenerationFundingSource,
+    enabledModelIds: z.array(z.string().min(1).max(256)).max(16),
+    defaultModelId: z.string().min(1).max(256).nullable(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const ids = new Set(value.enabledModelIds);
+    if (ids.size !== value.enabledModelIds.length) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["enabledModelIds"],
+        message: "enabled model ids must be unique",
+      });
+    }
+    if (value.defaultModelId !== null && !ids.has(value.defaultModelId)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["defaultModelId"],
+        message: "default model must be enabled",
+      });
+    }
+  });
+export type VideoGenerationPolicy = z.infer<typeof VideoGenerationPolicy>;
+
+export const UpdateVideoGenerationPolicyRequest = z
+  .object({
+    expectedRevision: z.number().int().nonnegative().safe(),
+    fundingSource: VideoGenerationFundingSource,
+    enabledModelIds: z.array(z.string().min(1).max(256)).max(16),
+    defaultModelId: z.string().min(1).max(256).nullable(),
+  })
+  .strict();
+export type UpdateVideoGenerationPolicyRequest = z.infer<typeof UpdateVideoGenerationPolicyRequest>;
+
+export const VideoGenerationFundingOption = z
+  .object({
+    source: VideoGenerationFundingSource,
+    label: z.string().min(1).max(128),
+    description: z.string().min(1).max(256),
+    available: z.boolean(),
+    unavailableReason: z.string().min(1).max(256).nullable(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.available !== (value.unavailableReason === null)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["unavailableReason"],
+        message: "available funding options cannot have an unavailable reason",
+      });
+    }
+  });
+export type VideoGenerationFundingOption = z.infer<typeof VideoGenerationFundingOption>;
+
+export const WorkspaceVideoGenerationSettings = z
+  .object({
+    schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+    policy: VideoGenerationPolicy,
+    fundingOptions: z.array(VideoGenerationFundingOption).length(2),
+    availableModels: z.array(VideoGenerationModelCapability).max(16),
+    capabilities: VideoGenerationCapabilities.nullable(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (
+      new Set(value.fundingOptions.map((option) => option.source)).size !== 2 ||
+      !value.fundingOptions.some((option) => option.source === "opengeni_credits") ||
+      !value.fundingOptions.some((option) => option.source === "workspace_gateway")
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["fundingOptions"],
+        message: "both funding sources must be described exactly once",
+      });
+    }
+    const selected = value.fundingOptions.find(
+      (option) => option.source === value.policy.fundingSource,
+    );
+    if (!selected) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["fundingOptions"],
+        message: "the selected funding source must be described",
+      });
+    } else if (!selected.available && value.capabilities !== null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["capabilities"],
+        message: "unavailable funding cannot expose executable capabilities",
+      });
+    }
+  });
+export type WorkspaceVideoGenerationSettings = z.infer<typeof WorkspaceVideoGenerationSettings>;
+
+export const VideoGenerationAcceptedReceipt = z
+  .object({
+    schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+    status: z.literal("accepted"),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type VideoGenerationAcceptedReceipt = z.infer<typeof VideoGenerationAcceptedReceipt>;
+
+export const GeneratedVideoFacts = z
+  .object({
+    durationSeconds: z.number().positive().max(120),
+    width: z.number().int().positive().max(8_192),
+    height: z.number().int().positive().max(8_192),
+    fps: z.number().positive().max(120),
+    hasAudio: z.boolean(),
+    videoCodec: z.literal("h264"),
+    audioCodec: z.literal("aac").nullable(),
+  })
+  .strict();
+export type GeneratedVideoFacts = z.infer<typeof GeneratedVideoFacts>;
+
+export const GeneratedVideoReceipt = z
+  .object({
+    type: z.literal("generated_video"),
+    schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+    operationId: z.string().uuid(),
+    artifact: RetainedArtifactReferenceSchema,
+    video: GeneratedVideoFacts,
+    sandboxPath: z
+      .string()
+      .max(256)
+      .regex(
+        /^\/workspace\/generated-videos\/generated-video-[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.mp4$/,
+      ),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (
+      value.artifact.kind !== "generated_video" ||
+      value.artifact.contentType !== "video/mp4" ||
+      value.artifact.originalBytes <= 0 ||
+      value.artifact.originalBytes > GENERATED_VIDEO_MAX_BYTES ||
+      value.artifact.retention.policy !== "workspace_file" ||
+      value.artifact.retrieval.maxRangeBytes !== RETAINED_OUTPUT_MAX_PAGE_BYTES
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["artifact"],
+        message: "generated-video artifact metadata is invalid",
+      });
+    }
+    if (
+      value.artifact.dimensions?.width !== value.video.width ||
+      value.artifact.dimensions?.height !== value.video.height
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["video"],
+        message: "video dimensions must match the retained artifact",
+      });
+    }
+    if (
+      value.sandboxPath !==
+      `/workspace/generated-videos/generated-video-${value.artifact.artifactId}.mp4`
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["sandboxPath"],
+        message: "generated-video sandbox path does not match its artifact",
+      });
+    }
+  });
+export type GeneratedVideoReceipt = z.infer<typeof GeneratedVideoReceipt>;
+
+export const VideoGenerationTerminalFailureStatus = z.enum([
+  "provider_failed",
+  "retention_failed",
+  "cancelled_before_submit",
+  "outcome_unknown",
+]);
+export type VideoGenerationTerminalFailureStatus = z.infer<
+  typeof VideoGenerationTerminalFailureStatus
+>;
+
+export const MediaGenerationResult = z.discriminatedUnion("status", [
+  z
+    .object({
+      type: z.literal("media_generation_result"),
+      schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+      status: z.literal("ready"),
+      operationId: z.string().uuid(),
+      receipt: GeneratedVideoReceipt,
+    })
+    .strict()
+    .refine((value) => value.receipt.operationId === value.operationId, {
+      path: ["receipt", "operationId"],
+      message: "terminal receipt must match its operation",
+    }),
+  z
+    .object({
+      type: z.literal("media_generation_result"),
+      schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+      status: VideoGenerationTerminalFailureStatus,
+      operationId: z.string().uuid(),
+      boundedPublicReason: z.string().min(1).max(1_000),
+    })
+    .strict(),
+]);
+export type MediaGenerationResult = z.infer<typeof MediaGenerationResult>;
+
+export const VideoGenerationPublicStatus = z.enum([
+  "preparing",
+  "prepared",
+  "accepted",
+  "provider_started",
+  "retaining",
+  "completed",
+  "provider_failed",
+  "cancelled_before_submit",
+  "outcome_unknown",
+  "retention_failed",
+]);
+export type VideoGenerationPublicStatus = z.infer<typeof VideoGenerationPublicStatus>;
+
+export const VideoGenerationOperationSummary = z
+  .object({
+    schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+    operationId: z.string().uuid(),
+    modelId: z.string().min(1).max(256),
+    status: VideoGenerationPublicStatus,
+    createdAt: z.string().datetime({ offset: true }),
+    updatedAt: z.string().datetime({ offset: true }),
+    terminal: MediaGenerationResult.nullable(),
+  })
+  .strict();
+export type VideoGenerationOperationSummary = z.infer<typeof VideoGenerationOperationSummary>;
+
+export const VideoArtifactPlaybackSource = z
+  .object({
+    schemaVersion: z.literal(VIDEO_GENERATION_SCHEMA_VERSION),
+    artifactId: z.string().uuid(),
+    url: z.string().url().max(8_192),
+    expiresAt: z.string().datetime({ offset: true }),
+    contentType: z.literal("video/mp4"),
+    sizeBytes: z.number().int().positive().max(GENERATED_VIDEO_MAX_BYTES),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    acceptRanges: z.literal("bytes"),
+  })
+  .strict();
+export type VideoArtifactPlaybackSource = z.infer<typeof VideoArtifactPlaybackSource>;

package/src/workspace-learning-policy.ts

@@ -0,0 +1,233 @@
+import { z } from "zod";
+
+export const WORKSPACE_LEARNING_POLICY_MAX_SOURCE_OVERRIDES = 256;
+export const WORKSPACE_LEARNING_POLICY_SOURCE_KIND_MAX_CHARS = 96;
+export const WORKSPACE_LEARNING_POLICY_SOURCE_ID_MAX_CHARS = 1_024;
+export const WORKSPACE_LEARNING_POLICY_REASON_MAX_CHARS = 4_096;
+export const WORKSPACE_LEARNING_POLICY_DEFAULT_OFF_REVISION_ID =
+  "workspace-learning-policy:default-off:v1";
+
+export const WorkspaceLearningMode = z.enum(["off", "suggest", "automatic"]);
+export type WorkspaceLearningMode = z.infer<typeof WorkspaceLearningMode>;
+
+export const WorkspaceLearningOverrideMode = z.enum(["inherit", "off", "suggest", "automatic"]);
+export type WorkspaceLearningOverrideMode = z.infer<typeof WorkspaceLearningOverrideMode>;
+
+export function normalizeWorkspaceLearningSourceKind(value: string): string {
+  return value.normalize("NFKC").trim().toLowerCase().replace(/\s+/gu, "-").replace(/-+/g, "-");
+}
+
+export const WorkspaceLearningSourceKind = z
+  .string()
+  .transform(normalizeWorkspaceLearningSourceKind)
+  .pipe(
+    z
+      .string()
+      .min(1)
+      .max(WORKSPACE_LEARNING_POLICY_SOURCE_KIND_MAX_CHARS)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+  );
+export type WorkspaceLearningSourceKind = z.infer<typeof WorkspaceLearningSourceKind>;
+
+export const WorkspaceLearningSourceId = z
+  .string()
+  .min(1)
+  .max(WORKSPACE_LEARNING_POLICY_SOURCE_ID_MAX_CHARS)
+  .refine(
+    (value) => value.trim() === value,
+    "learning source ids must not contain edge whitespace",
+  );
+export type WorkspaceLearningSourceId = z.infer<typeof WorkspaceLearningSourceId>;
+
+export const WorkspaceLearningSourceRef = z.object({
+  kind: WorkspaceLearningSourceKind,
+  id: WorkspaceLearningSourceId,
+});
+export type WorkspaceLearningSourceRef = z.infer<typeof WorkspaceLearningSourceRef>;
+
+export const WorkspaceLearningSourceOverrideInput = WorkspaceLearningSourceRef.extend({
+  mode: WorkspaceLearningOverrideMode,
+});
+export type WorkspaceLearningSourceOverrideInput = z.infer<
+  typeof WorkspaceLearningSourceOverrideInput
+>;
+
+export const WorkspaceLearningSourceOverride = WorkspaceLearningSourceRef.extend({
+  mode: WorkspaceLearningMode,
+});
+export type WorkspaceLearningSourceOverride = z.infer<typeof WorkspaceLearningSourceOverride>;
+
+export const WorkspaceLearningSourceOverrides = z
+  .array(WorkspaceLearningSourceOverride)
+  .max(WORKSPACE_LEARNING_POLICY_MAX_SOURCE_OVERRIDES);
+export type WorkspaceLearningSourceOverrides = z.infer<typeof WorkspaceLearningSourceOverrides>;
+
+export function workspaceLearningSourceKey(source: WorkspaceLearningSourceRef): string {
+  return `${source.kind}\u0000${source.id}`;
+}
+
+function compareUtf8(left: string, right: string): number {
+  const encoder = new TextEncoder();
+  const leftBytes = encoder.encode(left);
+  const rightBytes = encoder.encode(right);
+  const length = Math.min(leftBytes.length, rightBytes.length);
+  for (let index = 0; index < length; index += 1) {
+    if (leftBytes[index] !== rightBytes[index]) return leftBytes[index]! - rightBytes[index]!;
+  }
+  return leftBytes.length - rightBytes.length;
+}
+
+/**
+ * Canonicalize caller input before hashing or persistence. `inherit` is a
+ * request-only reset operation: inherited entries are deliberately absent from
+ * immutable revisions so the persisted policy stays sparse and transparent.
+ */
+export function canonicalizeWorkspaceLearningSourceOverrides(
+  input: readonly WorkspaceLearningSourceOverrideInput[],
+): WorkspaceLearningSourceOverride[] {
+  if (input.length > WORKSPACE_LEARNING_POLICY_MAX_SOURCE_OVERRIDES) {
+    throw new Error(
+      `workspace learning policy supports at most ${WORKSPACE_LEARNING_POLICY_MAX_SOURCE_OVERRIDES} source overrides`,
+    );
+  }
+  const seen = new Set<string>();
+  const canonical: WorkspaceLearningSourceOverride[] = [];
+  for (const candidate of input) {
+    const parsed = WorkspaceLearningSourceOverrideInput.parse(candidate);
+    const key = workspaceLearningSourceKey(parsed);
+    if (seen.has(key)) {
+      throw new Error(`duplicate workspace learning source override: ${parsed.kind}/${parsed.id}`);
+    }
+    seen.add(key);
+    if (parsed.mode !== "inherit") canonical.push(parsed as WorkspaceLearningSourceOverride);
+  }
+  canonical.sort((left, right) => {
+    const kindOrder = compareUtf8(left.kind, right.kind);
+    return kindOrder === 0 ? compareUtf8(left.id, right.id) : kindOrder;
+  });
+  return WorkspaceLearningSourceOverrides.parse(canonical);
+}
+
+const revisionIdentityShape = {
+  id: z.string().uuid(),
+  revision: z.number().int().positive(),
+  policyHash: z.string().regex(/^[0-9a-f]{64}$/),
+};
+
+export const WorkspaceLearningPolicyRevisionIdentity = z.object(revisionIdentityShape);
+export type WorkspaceLearningPolicyRevisionIdentity = z.infer<
+  typeof WorkspaceLearningPolicyRevisionIdentity
+>;
+
+export const WorkspaceLearningPolicyRevision = z.object({
+  ...revisionIdentityShape,
+  operationId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  workspaceMode: WorkspaceLearningMode,
+  sourceOverrides: WorkspaceLearningSourceOverrides,
+  supersedesRevisionId: z.string().uuid().nullable(),
+  createdBySubjectId: z.string().min(1),
+  createdAt: z.string().datetime(),
+});
+export type WorkspaceLearningPolicyRevision = z.infer<typeof WorkspaceLearningPolicyRevision>;
+
+export const WorkspaceLearningPolicyHead = z.object({
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  revisionId: z.string().uuid(),
+  revision: z.number().int().positive(),
+  policyHash: z.string().regex(/^[0-9a-f]{64}$/),
+  activationVersion: z.number().int().positive(),
+  activatedAt: z.string().datetime(),
+});
+export type WorkspaceLearningPolicyHead = z.infer<typeof WorkspaceLearningPolicyHead>;
+
+export const WorkspaceLearningPolicyActivationType = z.enum(["activate", "rollback"]);
+export type WorkspaceLearningPolicyActivationType = z.infer<
+  typeof WorkspaceLearningPolicyActivationType
+>;
+
+export const WorkspaceLearningPolicyActivationEvent = z.object({
+  id: z.string().uuid(),
+  operationId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  type: WorkspaceLearningPolicyActivationType,
+  activationVersion: z.number().int().positive(),
+  oldRevision: WorkspaceLearningPolicyRevisionIdentity.nullable(),
+  newRevision: WorkspaceLearningPolicyRevisionIdentity,
+  actorSubjectId: z.string().min(1),
+  reason: z.string().min(1).max(WORKSPACE_LEARNING_POLICY_REASON_MAX_CHARS),
+  createdAt: z.string().datetime(),
+});
+export type WorkspaceLearningPolicyActivationEvent = z.infer<
+  typeof WorkspaceLearningPolicyActivationEvent
+>;
+
+export const WorkspaceLearningPolicySnapshot = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sessionId: z.string().uuid(),
+  turnId: z.string().uuid(),
+  attemptId: z.string().uuid(),
+  executionGeneration: z.number().int().positive(),
+  revision: WorkspaceLearningPolicyRevisionIdentity.nullable(),
+  activationVersion: z.number().int().nonnegative(),
+  activatedAt: z.string().datetime().nullable(),
+  workspaceMode: WorkspaceLearningMode,
+  sourceOverrides: WorkspaceLearningSourceOverrides,
+  snapshotHash: z.string().regex(/^[0-9a-f]{64}$/),
+  createdAt: z.string().datetime(),
+});
+export type WorkspaceLearningPolicySnapshot = z.infer<typeof WorkspaceLearningPolicySnapshot>;
+
+export const WorkspaceLearningPolicyRouterContext = z.object({
+  mode: WorkspaceLearningMode,
+  snapshotId: z.string().uuid(),
+  revisionId: z.string().min(1).max(512),
+});
+export type WorkspaceLearningPolicyRouterContext = z.infer<
+  typeof WorkspaceLearningPolicyRouterContext
+>;
+
+export const WorkspaceLearningPolicyEffectiveMode = WorkspaceLearningPolicyRouterContext.extend({
+  inherited: z.boolean(),
+  source: WorkspaceLearningSourceRef,
+  policyRevision: WorkspaceLearningPolicyRevisionIdentity.nullable(),
+  activationVersion: z.number().int().nonnegative(),
+  snapshotHash: z.string().regex(/^[0-9a-f]{64}$/),
+});
+export type WorkspaceLearningPolicyEffectiveMode = z.infer<
+  typeof WorkspaceLearningPolicyEffectiveMode
+>;
+
+/** Stable router seam: resolve only from an immutable accepted-attempt snapshot. */
+export function resolveWorkspaceLearningPolicyEffectiveMode(
+  snapshot: WorkspaceLearningPolicySnapshot,
+  source: WorkspaceLearningSourceRef,
+): WorkspaceLearningPolicyEffectiveMode {
+  const parsedSnapshot = WorkspaceLearningPolicySnapshot.parse(snapshot);
+  const parsedSource = WorkspaceLearningSourceRef.parse(source);
+  const override = parsedSnapshot.sourceOverrides.find(
+    (candidate) => candidate.kind === parsedSource.kind && candidate.id === parsedSource.id,
+  );
+  return WorkspaceLearningPolicyEffectiveMode.parse({
+    mode: override?.mode ?? parsedSnapshot.workspaceMode,
+    inherited: override === undefined,
+    source: parsedSource,
+    policyRevision: parsedSnapshot.revision,
+    activationVersion: parsedSnapshot.activationVersion,
+    snapshotId: parsedSnapshot.id,
+    revisionId: parsedSnapshot.revision?.id ?? WORKSPACE_LEARNING_POLICY_DEFAULT_OFF_REVISION_ID,
+    snapshotHash: parsedSnapshot.snapshotHash,
+  });
+}
+
+/** Exact provider-neutral context consumed by the canonical durable-learning router. */
+export function workspaceLearningPolicyRouterContext(
+  effectiveMode: WorkspaceLearningPolicyEffectiveMode,
+): WorkspaceLearningPolicyRouterContext {
+  return WorkspaceLearningPolicyRouterContext.parse(effectiveMode);
+}