@xemahq/kernel-contracts 0.29.0 → 0.31.0

package/src/run-detail/lib/run-detail-dto.ts

@@ -0,0 +1,84 @@
+import { WorkflowRunStatus } from '../../workflow';
+
+import { RunOutcomeDto } from './run-outcome';
+import { RunPhaseRailDto } from './run-phase-rail';
+import { RunRevisionPayload } from './run-revision-state';
+import { WaitWindow } from './wait-windows';
+
+/**
+ * The single payload `GET /workflows/:slug/runs/:id/full` returns. Replaces
+ * the legacy `useRunSummary` + `useRunDescribe` + first-page `useRunHistory`
+ * + `useRunJobs` quad-query with one coalesced call.
+ *
+ * Conventions:
+ *   - Every nested list is bounded — the FE never asks for "all events".
+ *     Detail/history surfaces page through the timeline endpoint.
+ *   - Every closed-domain field uses an enum from this package or
+ *     `../../workflow`. No free-form strings except labels.
+ *   - The payload is shaped for the user-visible view, not internal
+ *     state. Internal Temporal IDs are exposed only in DEVELOPER mode.
+ *
+ * Wire envelope: this DTO is the `data` member of the standard envelope
+ *. The FE's envelope-assert util validates the
+ * shape end-to-end.
+ */
+export interface RunDetailDto {
+  readonly id: string;
+  readonly workflowSlug: string;
+  readonly workflowDisplayName: string;
+  readonly status: WorkflowRunStatus;
+  /** Initiator displayName — `null` for system-triggered runs (schedules, webhooks). */
+  readonly initiatorDisplayName: string | null;
+  readonly startedAt: string;
+  /** ISO-8601 when the run reached a terminal state, else `null`. */
+  readonly endedAt: string | null;
+  /** Engine ETA for in-flight runs. `null` when terminal or unknown. */
+  readonly etaAt: string | null;
+
+  readonly phaseRail: RunPhaseRailDto;
+  readonly waitWindows: readonly WaitWindow[];
+
+  /** What's actively running right now — feeds the Overview "Activity now" strip. */
+  readonly activityNow: readonly RunActivityNowDto[];
+
+  /** Last 6 events (coarse milestones). Click-through navigates to Developer mode. */
+  readonly recentTail: readonly RunRecentEventDto[];
+
+  /**
+   * Revision-state discriminator + payload (see {@link RunRevisionPayload}).
+   * Drives whether/which of the 3 revision UIs renders.
+   */
+  readonly revision: RunRevisionPayload;
+
+  /** Outcome strip for terminal runs. `null` for in-flight. */
+  readonly outcome: RunOutcomeDto | null;
+
+  /**
+   * One-line "what's blocking" callout for in-flight runs. Server-computed
+   * from waitWindows + escalation state. `null` when nothing is blocking.
+   */
+  readonly blockingSummary: string | null;
+}
+
+/**
+ * One row in the Overview "Activity now" strip — coarse "who is doing
+ * what right now". Updated via SSE incremental patches; one sentence
+ * per active job, no timestamps (they're current).
+ */
+export interface RunActivityNowDto {
+  readonly jobKey: string;
+  readonly agentDisplayName: string | null;
+  readonly summary: string;
+}
+
+/**
+ * One row in the Overview "Recent" tail — the last 6 coarse milestones
+ * (phase entered, deliverable emitted, agent paused, decision needed).
+ */
+export interface RunRecentEventDto {
+  readonly id: string;
+  readonly at: string;
+  readonly summary: string;
+  /** Optional deep-link anchor for the Developer-mode timeline. */
+  readonly developerAnchor: string | null;
+}

package/src/run-detail/lib/run-mode.ts

@@ -0,0 +1,65 @@
+import { WorkflowRunStatus, TERMINAL_WORKFLOW_RUN_STATUSES } from '../../workflow';
+
+/**
+ * The calm modes that replace the legacy 10-tab run detail.
+ *
+ * - `OVERVIEW` — coarse status + latest deliverables (links) + last 6
+ *   events. Default for running and terminal runs.
+ * - `WORK` — the question canvas + reply form. Default when the run has
+ *   a question waiting on the current user.
+ * - `OUTPUTS` — full deliverables surface. One sub-tab per artifact;
+ *   each sub-tab renders the artifact's CONTENT (markdown rendered as
+ *   an A4 page, code diff via the diff viewer, diagram via mermaid,
+ *   etc.) with a `Show raw` toggle that reveals the underlying artifact
+ *   JSON. Never the default — opened from the Overview deliverables
+ *   strip or directly via the mode switcher.
+ * - `DEVELOPER` — full activity console + Temporal history + Mounts /
+ *   Pending / Query diagnostic cards. Behind a user-pref + role gate.
+ *
+ * Mode-default selection is deterministic — see {@link selectDefaultRunMode}.
+ * Free-text strings are forbidden; consumers route on this enum.
+ */
+export enum RunMode {
+  OVERVIEW = 'overview',
+  WORK = 'work',
+  OUTPUTS = 'outputs',
+  DEVELOPER = 'developer',
+}
+
+/**
+ * Inputs the deterministic mode-default selector consumes. Keeping this
+ * narrow (no full RunDetailDto reference) lets callers pre-compute it
+ * without holding the whole run payload in scope.
+ */
+export interface RunModeSelectionInputs {
+  readonly status: WorkflowRunStatus;
+  readonly hasQuestionForCurrentUser: boolean;
+  /** User-pref override; wins if set. */
+  readonly userPreferredMode?: RunMode;
+}
+
+/**
+ * Deterministic mode-default rules:
+ *
+ *   status == waiting_on_human && hasQuestionForMe(runId)  → WORK
+ *   status terminal                                        → OVERVIEW
+ *   otherwise                                              → OVERVIEW
+ *   user pref override                                     → wins
+ *
+ * No timing, no probabilities, no fuzzy matching. The FE calls this once
+ * per render and routes accordingly; reverse calls are not supported.
+ */
+export function selectDefaultRunMode(input: RunModeSelectionInputs): RunMode {
+  if (input.userPreferredMode !== undefined) {
+    return input.userPreferredMode;
+  }
+  const isTerminal = TERMINAL_WORKFLOW_RUN_STATUSES.includes(input.status);
+  if (
+    !isTerminal &&
+    input.status === WorkflowRunStatus.WAITING_ON_HUMAN &&
+    input.hasQuestionForCurrentUser
+  ) {
+    return RunMode.WORK;
+  }
+  return RunMode.OVERVIEW;
+}

package/src/run-detail/lib/run-outcome.ts

@@ -0,0 +1,66 @@
+import { WorkflowRunStatus } from '../../workflow';
+
+/**
+ * Branch the FE outcome strip renders for a TERMINAL run. Mirrors the
+ * branch matrix for terminal runs.
+ *
+ * Every terminal run lands in exactly one branch — the engine sets it on
+ * the {@link RunDetailDto.outcome} field at run-end so the FE never has
+ * to re-derive from `status` + reason text.
+ */
+export enum RunOutcomeBranch {
+  SUCCEEDED = 'succeeded',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  ESCALATION_EXHAUSTED = 'escalation_exhausted',
+}
+
+/**
+ * What the user sees in the outcome card. Each branch's `actions` list
+ * is computed server-side (only valid CTAs leak into the wire) so the
+ * FE renders without policy logic.
+ *
+ * `summary` is one human sentence — never JSON. The FE displays it
+ * verbatim under the status header.
+ */
+export interface RunOutcomeDto {
+  readonly branch: RunOutcomeBranch;
+  readonly summary: string;
+  readonly actions: readonly RunOutcomeActionDto[];
+}
+
+/**
+ * A button rendered under the outcome card. Closed CTA enum — the FE
+ * fails-fast on unknown values rather than rendering a placeholder.
+ */
+export interface RunOutcomeActionDto {
+  readonly kind: RunOutcomeActionKind;
+  readonly label: string;
+  /** Optional href; if absent the action is dispatched to the engine via SDK. */
+  readonly href?: string;
+  /** Optional opaque payload the engine echoes on dispatch. */
+  readonly payload?: Readonly<Record<string, unknown>>;
+}
+
+export enum RunOutcomeActionKind {
+  RUN_AGAIN = 'run_again',
+  OPEN_IN_KB = 'open_in_kb',
+  REDO_FROM_PHASE = 'redo_from_phase',
+  OPEN_LAST_SUCCESSFUL_ARTIFACT = 'open_last_successful_artifact',
+  RESTART_WITH_SAME_INPUTS = 'restart_with_same_inputs',
+  ADJUST_ESCALATION_CHAIN = 'adjust_escalation_chain',
+}
+
+/**
+ * True iff a {@link WorkflowRunStatus} represents a terminal state that
+ * carries an outcome. Mirrors {@link TERMINAL_WORKFLOW_RUN_STATUSES} but
+ * rejects `ABORTED_FOR_MIGRATION` because that branch has no user-facing
+ * outcome card (it's an internal lifecycle event).
+ */
+export function isOutcomeBearingStatus(status: WorkflowRunStatus): boolean {
+  return (
+    status === WorkflowRunStatus.SUCCEEDED ||
+    status === WorkflowRunStatus.FAILED ||
+    status === WorkflowRunStatus.CANCELLED
+  );
+}

package/src/run-detail/lib/run-phase-rail.ts

@@ -0,0 +1,43 @@
+/**
+ * The phase rail shown at the top of every run-detail mode. Click any
+ * dot to filter the activity panel to that phase. The rail is a stable,
+ * compile-time-known sequence per workflow definition — the engine
+ * computes it once at run dispatch and freezes it on the run row so the
+ * FE doesn't have to re-derive from runtime activity.
+ */
+export interface RunPhaseRailDto {
+  readonly phases: readonly RunPhaseRailEntryDto[];
+  /**
+   * Index into `phases` of the currently-active phase. `null` when the
+   * run is terminal AND the last phase already completed (the rail
+   * renders fully filled).
+   */
+  readonly currentIndex: number | null;
+}
+
+export interface RunPhaseRailEntryDto {
+  readonly stageKey: string;
+  /** Display label — e.g. "Implementation", "Architecture review". */
+  readonly label: string;
+  readonly status: RunPhaseRailStatus;
+  /** ISO-8601 when the phase entered RUNNING. `null` if not yet started. */
+  readonly startedAt: string | null;
+  /** ISO-8601 when the phase reached a terminal state. `null` if still in flight. */
+  readonly endedAt: string | null;
+}
+
+/**
+ * Closed phase-rail status set. Distinct from {@link JobRunStatus} — a
+ * single phase rolls up many jobs and adds the WAITING / SKIPPED rail
+ * affordances the user sees. Maps from job status server-side; FE
+ * renders the icon+color directly off this enum.
+ */
+export enum RunPhaseRailStatus {
+  PENDING = 'pending',
+  RUNNING = 'running',
+  WAITING = 'waiting',
+  SUCCEEDED = 'succeeded',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  SKIPPED = 'skipped',
+}

package/src/run-detail/lib/run-revision-state.ts

@@ -0,0 +1,83 @@
+/**
+ * Three deliberately distinct revision UIs.
+ * The engine emits exactly one of these on the run detail payload; the
+ * FE renders the matching component (or nothing for `NONE`).
+ *
+ * - `REVISE` — purple checkpoint card embedded in the doc flow.
+ *   CTAs: "Approve & continue" | "Revise with feedback".
+ * - `MANUAL_OVERRIDE` — warning banner shown after auto-retries are
+ *   exhausted. CTAs: "Extend retries" | "Force approve" | "Reject run".
+ * - `REDO_FROM_PHASE` — terminal-only dropdown that re-dispatches from
+ *   a chosen earlier phase.
+ * - `NONE` — no revision UI; the run is progressing normally.
+ *
+ * Auto-retry status surfaces as a status pill in the run header, NOT
+ * its own revision-state value. Don't extend this enum to cover
+ * non-revision states.
+ */
+export enum RunRevisionState {
+  NONE = 'none',
+  REVISE = 'revise',
+  MANUAL_OVERRIDE = 'manual_override',
+  REDO_FROM_PHASE = 'redo_from_phase',
+}
+
+/**
+ * Per-state payload the FE needs to render the matching component. The
+ * engine includes whichever variant matches `state` and omits the rest.
+ *
+ * `NONE` carries no payload — the discriminator alone suffices.
+ */
+export type RunRevisionPayload =
+  | { readonly state: RunRevisionState.NONE }
+  | { readonly state: RunRevisionState.REVISE; readonly checkpoint: RunReviseCheckpointDto }
+  | {
+      readonly state: RunRevisionState.MANUAL_OVERRIDE;
+      readonly override: RunManualOverrideDto;
+    }
+  | {
+      readonly state: RunRevisionState.REDO_FROM_PHASE;
+      readonly redo: RunRedoFromPhaseDto;
+    };
+
+/** Payload for the purple checkpoint card. */
+export interface RunReviseCheckpointDto {
+  readonly checkpointId: string;
+  readonly stageKey: string;
+  readonly title: string;
+  /** Human-readable summary of what's being reviewed. */
+  readonly summary: string;
+  /** Reviewer findings to render inline alongside the canvas. */
+  readonly findings: readonly RunReviseFindingDto[];
+}
+
+export interface RunReviseFindingDto {
+  readonly id: string;
+  readonly severity: 'info' | 'minor' | 'major' | 'critical';
+  /** Optional file:line anchor — `null` if the finding is run-level. */
+  readonly anchor: string | null;
+  readonly message: string;
+}
+
+/** Payload for the manual-override banner (auto-retries exhausted). */
+export interface RunManualOverrideDto {
+  readonly retryCount: number;
+  readonly retryLimit: number;
+  readonly lastFailureReason: string;
+  /** When the engine is willing to attempt one more retry on demand. */
+  readonly canExtendRetries: boolean;
+}
+
+/** Payload for the redo-from-phase dropdown (terminal runs only). */
+export interface RunRedoFromPhaseDto {
+  readonly availablePhases: readonly RunRedoPhaseChoiceDto[];
+}
+
+export interface RunRedoPhaseChoiceDto {
+  readonly stageKey: string;
+  readonly label: string;
+  /** Whether the engine has the inputs needed to re-dispatch from here. */
+  readonly available: boolean;
+  /** Human-readable reason when `available === false`. */
+  readonly unavailableReason?: string;
+}

package/src/run-detail/lib/wait-windows.ts

@@ -0,0 +1,70 @@
+/**
+ * Single source of truth for "the run is waiting on X" math used by the
+ * RunHeaderTimebar, the run-list "what's blocking" inline text, and the
+ * Overview blocking callout.
+ *
+ * Three different surfaces used to compute these windows independently
+ * and could disagree by the
+ * second. They now share this util.
+ *
+ * All times are ISO-8601 strings on the wire; the helpers parse + return
+ * primitive ms numbers so callers stay framework-agnostic.
+ */
+
+export interface WaitWindow {
+  /** Inclusive start ISO-8601. */
+  readonly startedAt: string;
+  /** Exclusive end ISO-8601, or `null` if the wait is still open. */
+  readonly endedAt: string | null;
+  readonly reason: WaitReason;
+}
+
+/**
+ * Closed reason set. The user-visible label is rendered by the FE from
+ * this discriminator — never accept a free-form `reason` string from
+ * the wire.
+ */
+export enum WaitReason {
+  WAITING_ON_HUMAN = 'waiting_on_human',
+  WAITING_ON_AGENT = 'waiting_on_agent',
+  WAITING_ON_EXTERNAL = 'waiting_on_external',
+  WAITING_ON_DEPENDENCY = 'waiting_on_dependency',
+  WAITING_ON_QUOTA = 'waiting_on_quota',
+}
+
+/**
+ * Total wait duration (ms) summed across windows. Open windows count
+ * up to `nowMs`. Caller passes `nowMs` (test-injectable) — the lib
+ * never reads `Date.now()` on its own.
+ */
+export function totalWaitMs(windows: readonly WaitWindow[], nowMs: number): number {
+  let total = 0;
+  for (const w of windows) {
+    const start = Date.parse(w.startedAt);
+    const end = w.endedAt !== null ? Date.parse(w.endedAt) : nowMs;
+    if (Number.isFinite(start) && Number.isFinite(end) && end > start) {
+      total += end - start;
+    }
+  }
+  return total;
+}
+
+/**
+ * The currently-open wait window, if any. Returns the most recent open
+ * window (there should never be more than one open at a time, but if
+ * the engine emits overlapping waits we surface the most recent so the
+ * FE doesn't pick a stale reason).
+ */
+export function currentOpenWait(windows: readonly WaitWindow[]): WaitWindow | null {
+  let bestStart = -Infinity;
+  let bestWindow: WaitWindow | null = null;
+  for (const w of windows) {
+    if (w.endedAt !== null) continue;
+    const start = Date.parse(w.startedAt);
+    if (Number.isFinite(start) && start > bestStart) {
+      bestStart = start;
+      bestWindow = w;
+    }
+  }
+  return bestWindow;
+}

package/src/workspace-image/index.ts

@@ -0,0 +1,13 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace Image Contracts — Barrel Export ──
+//
+// Kernel (Layer 1) contracts for per-org workspace image variants. Pure
+// types, closed enums, zod schemas, plus the deterministic content-hash
+// helper used to identify a variant from its declarative manifest +
+// base-image digest. Zero NestJS, zero Prisma.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/enums';
+export * from './lib/types';
+export * from './lib/hash';
+export * from './lib/schemas';

package/src/workspace-image/lib/enums.ts

@@ -0,0 +1,38 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace image — closed-domain enums ──
+//
+// Closed sets backing the per-org workspace image variants described in
+// the ImageLayerKind enumerates every layer recipe the kernel
+// understands; VariantStatus enumerates the bake lifecycle.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Closed set of layer-recipe kinds. Each kind has a strict TypeScript
+ * payload shape (see `ImageLayer` in `types.ts`).
+ *
+ * IMPORTANT: there is no `entrypoint` / `cmd` kind — the entrypoint is
+ * owned by the worker-runtime, never by an org-supplied recipe.
+ */
+export enum ImageLayerKind {
+  Apt = 'apt',
+  Dnf = 'dnf',
+  Apk = 'apk',
+  Pip = 'pip',
+  NpmGlobal = 'npm-global',
+  Env = 'env',
+  File = 'file',
+}
+
+/**
+ * Lifecycle of a single image variant. `draft` is editable in the UI;
+ * `building` is the active bake; `ready` is mountable by workers;
+ * `failed` retains the build log for debugging; `archived` keeps the row
+ * for history but disallows new use.
+ */
+export enum VariantStatus {
+  Draft = 'draft',
+  Building = 'building',
+  Ready = 'ready',
+  Failed = 'failed',
+  Archived = 'archived',
+}

package/src/workspace-image/lib/hash.ts

@@ -0,0 +1,95 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace image — deterministic content hash ──
+//
+// Given a `WorkspaceImageManifest` plus the resolved base-image digest,
+// produce a stable sha256 used as the variant's content identity. Two
+// inputs that differ only in JSON formatting MUST hash to the same value;
+// two inputs that differ semantically MUST NOT collide.
+//
+// Strategy:
+//   1. Canonicalize: recursively sort object keys; arrays keep their
+//      authored order (order is semantically meaningful — `apt install`
+//      ordering can change layer caching and image size).
+//   2. JSON.stringify the canonical form (no whitespace, stable key order).
+//   3. sha256 over the concatenation `canonicalManifest + '\n' + digest`.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { createHash } from 'node:crypto';
+
+import type { WorkspaceImageManifest } from './types';
+
+type CanonicalJson =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly CanonicalJson[]
+  | { readonly [key: string]: CanonicalJson };
+
+/**
+ * Recursively produce a canonical, order-stable JSON-compatible value:
+ *
+ * - Objects: keys sorted lexicographically. `undefined` values dropped
+ *   (mirrors `JSON.stringify`'s default and avoids two inputs differing
+ *   only by an explicit `undefined` hashing differently).
+ * - Arrays: order is preserved (semantically meaningful in image layers).
+ * - Primitives & null: pass through.
+ *
+ * Throws on values JSON cannot represent (functions, symbols, bigint,
+ * circular refs) — fail-fast per the project's constitution.
+ */
+function canonicalize(value: unknown, seen: WeakSet<object> = new WeakSet()): CanonicalJson {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === 'string' || t === 'boolean') {
+    return value as CanonicalJson;
+  }
+  if (t === 'number') {
+    if (!Number.isFinite(value as number)) {
+      throw new Error('canonicalize: non-finite number is not JSON-representable');
+    }
+    return value as number;
+  }
+  if (t === 'undefined') {
+    // Will be dropped by the object pass; encountering it at the root or
+    // inside an array indicates a programmer error.
+    throw new Error('canonicalize: undefined is not JSON-representable');
+  }
+  if (t === 'bigint' || t === 'function' || t === 'symbol') {
+    throw new Error(`canonicalize: ${t} is not JSON-representable`);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) throw new Error('canonicalize: circular reference');
+    seen.add(value);
+    return value.map((entry) => canonicalize(entry, seen));
+  }
+  // Plain object.
+  if (seen.has(value as object)) throw new Error('canonicalize: circular reference');
+  seen.add(value as object);
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const out: Record<string, CanonicalJson> = {};
+  for (const [k, v] of entries) {
+    out[k] = canonicalize(v, seen);
+  }
+  return out;
+}
+
+/**
+ * Compute the canonical content hash of a workspace image variant. The
+ * `baseImageDigest` MUST be the resolved digest of the base image at
+ * bake-time (not a mutable tag) — otherwise a tag drift would silently
+ * invalidate the hash.
+ */
+export function computeContentHash(
+  manifest: WorkspaceImageManifest,
+  baseImageDigest: string,
+): string {
+  if (!baseImageDigest || typeof baseImageDigest !== 'string') {
+    throw new Error('computeContentHash: baseImageDigest is required');
+  }
+  const canonical = canonicalize(manifest);
+  const serialized = JSON.stringify(canonical);
+  return createHash('sha256').update(`${serialized}\n${baseImageDigest}`).digest('hex');
+}

package/src/workspace-image/lib/schemas.ts

@@ -0,0 +1,63 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace image — zod schemas ──
+//
+// Runtime validators mirroring the enums and DTOs. Used by the bake
+// service when persisting authored manifests and by the frontend when
+// editing them in the Studio.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+import { workerRuntimeKindSchema } from '../../worker-runtime';
+
+import { ImageLayerKind, VariantStatus } from './enums';
+
+export const imageLayerKindSchema = z.nativeEnum(ImageLayerKind);
+export const variantStatusSchema = z.nativeEnum(VariantStatus);
+
+const packagesArray = z.array(z.string().min(1));
+
+export const imageLayerSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal(ImageLayerKind.Apt), packages: packagesArray }),
+  z.object({ kind: z.literal(ImageLayerKind.Dnf), packages: packagesArray }),
+  z.object({ kind: z.literal(ImageLayerKind.Apk), packages: packagesArray }),
+  z.object({
+    kind: z.literal(ImageLayerKind.Pip),
+    packages: packagesArray,
+    pythonVersion: z.string().min(1).optional(),
+  }),
+  z.object({ kind: z.literal(ImageLayerKind.NpmGlobal), packages: packagesArray }),
+  z.object({
+    kind: z.literal(ImageLayerKind.Env),
+    vars: z.record(z.string().min(1), z.string()),
+  }),
+  z.object({
+    kind: z.literal(ImageLayerKind.File),
+    path: z.string().min(1),
+    contentBase64: z.string().min(1),
+    mode: z.number().int().nonnegative().optional(),
+  }),
+]);
+
+export const workspaceImageManifestSchema = z.object({
+  layers: z.array(imageLayerSchema),
+  workdir: z.string().min(1).optional(),
+});
+
+export const workspaceImageVariantSchema = z.object({
+  id: z.string().min(1),
+  orgId: z.string().min(1),
+  slug: z.string().min(1),
+  description: z.string(),
+  runtimeKind: workerRuntimeKindSchema,
+  baseImage: z.string().min(1),
+  manifest: workspaceImageManifestSchema,
+  contentHash: z.string().min(1),
+  registryRef: z.string().min(1).optional(),
+  status: variantStatusSchema,
+  isOrgDefault: z.boolean(),
+  autoRebake: z.boolean(),
+  regions: z.array(z.string().min(1)),
+  buildLog: z.string().optional(),
+  builtAt: z.string().min(1).optional(),
+  createdAt: z.string().min(1),
+});