@xemahq/kernel-contracts 0.28.0 → 0.30.0

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),
+});

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

@@ -0,0 +1,79 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace image — manifest & variant types ──
+//
+// Strict types for per-org workspace image variants. The kernel never sees
+// a Dockerfile — variants are declared as a closed list of layer recipes
+// that the bake service translates into Buildah/BuildKit operations.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { WorkerRuntimeKind } from '../../worker-runtime';
+
+import type { ImageLayerKind, VariantStatus } from './enums';
+
+/**
+ * A single layer in a `WorkspaceImageManifest`. Closed discriminated
+ * union keyed by `kind`. Each kind has a strict payload — the bake
+ * service exhaustively `switch`es on `kind`.
+ *
+ * No `entrypoint` / `cmd` kind by design: the worker-runtime owns process
+ * lifecycle, not the org-authored image.
+ */
+export type ImageLayer =
+  | { readonly kind: ImageLayerKind.Apt; readonly packages: readonly string[] }
+  | { readonly kind: ImageLayerKind.Dnf; readonly packages: readonly string[] }
+  | { readonly kind: ImageLayerKind.Apk; readonly packages: readonly string[] }
+  | {
+      readonly kind: ImageLayerKind.Pip;
+      readonly packages: readonly string[];
+      readonly pythonVersion?: string;
+    }
+  | { readonly kind: ImageLayerKind.NpmGlobal; readonly packages: readonly string[] }
+  | { readonly kind: ImageLayerKind.Env; readonly vars: Readonly<Record<string, string>> }
+  | {
+      readonly kind: ImageLayerKind.File;
+      readonly path: string;
+      readonly contentBase64: string;
+      readonly mode?: number;
+    };
+
+/**
+ * A bake recipe. The manifest is the AUTHORATIVE input to the bake
+ * service; everything else on `WorkspaceImageVariant` is derived metadata.
+ *
+ * `workdir` is the working directory inside the resulting image; it
+ * defaults to the runtime's choice when omitted. No `entrypoint` field —
+ * the runtime owns process lifecycle.
+ */
+export interface WorkspaceImageManifest {
+  readonly layers: readonly ImageLayer[];
+  readonly workdir?: string;
+}
+
+/**
+ * Cross-service DTO for a baked variant. Mirrors the Prisma row in the
+ * workspace-image / bake service.
+ */
+export interface WorkspaceImageVariant {
+  readonly id: string;
+  readonly orgId: string;
+  readonly slug: string;
+  readonly description: string;
+  readonly runtimeKind: WorkerRuntimeKind;
+  /** Base image (registry/name:tag or digest) the manifest extends. */
+  readonly baseImage: string;
+  readonly manifest: WorkspaceImageManifest;
+  /** sha256 of `(manifest, baseImageDigest)` — see `computeContentHash`. */
+  readonly contentHash: string;
+  /** Pushed registry reference once `status = Ready`. */
+  readonly registryRef?: string;
+  readonly status: VariantStatus;
+  readonly isOrgDefault: boolean;
+  readonly autoRebake: boolean;
+  /** Regions in which this variant has been replicated. */
+  readonly regions: readonly string[];
+  /** Tail of the bake log; absent for `draft`. */
+  readonly buildLog?: string;
+  /** ISO-8601 timestamp; absent until first successful bake. */
+  readonly builtAt?: string;
+  readonly createdAt: string;
+}