@xemahq/kernel-contracts 0.29.0 → 0.30.0

package/src/output/lib/payload-schemas/diagram.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+
+/**
+ * Diagram-dialect enum. Closed today on `mermaid` only — the FE
+ * renderer pipeline can ingest mermaid via the existing
+ * `MarkdownView` mermaid block. Add new values here when a new
+ * dialect (drawio, plantuml, …) has a renderer wired.
+ */
+export enum DiagramDialect {
+  MERMAID = 'mermaid',
+}
+
+export const DiagramDialectSchema = z.nativeEnum(DiagramDialect);
+
+/**
+ * Payload shape for `OutputKind.DIAGRAM` artifacts — standalone
+ * diagrams emitted by architecture / requirements agents.
+ *
+ * Two valid shapes (mirroring how `xema/emit-artifact` producers
+ * actually emit today):
+ *
+ *   1. Inline source: `{ type: 'mermaid', source: '<mermaid src>' }`.
+ *   2. Markdown fallback: `{ body: '...mermaid block...' }` — when
+ *      the producer wrapped a mermaid fence in a markdown narrative.
+ *
+ * The FE `DiagramRenderer` reads `source` when present, else falls
+ * through to markdown rendering which itself supports mermaid.
+ */
+export const DiagramPayloadSchema = z
+  .object({
+    type: DiagramDialectSchema.optional(),
+    source: z.string().optional(),
+    body: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((value, ctx) => {
+    const hasSource = typeof value.source === 'string' && value.source.trim().length > 0;
+    const hasBody = typeof value.body === 'string' && value.body.trim().length > 0;
+    if (!hasSource && !hasBody) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'diagram payload must include either `source` or `body`.',
+      });
+    }
+    if (hasSource && value.type === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['type'],
+        message: 'diagram payload with `source` must declare `type` (e.g. `mermaid`).',
+      });
+    }
+  });
+
+export type DiagramPayload = z.infer<typeof DiagramPayloadSchema>;

package/src/output/lib/payload-schemas/external-blob.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+/**
+ * Payload shape for `OutputKind.EXTERNAL_BLOB` artifacts — images,
+ * PDFs, archives, and other binary content stored out-of-band in
+ * MinIO / S3.
+ *
+ * The `payload` itself is metadata about the external bytes. The
+ * actual bytes live behind `ArtifactVersion.pointer` (durable
+ * storage URI) and are streamed via the artifact-store's
+ * version-content endpoint, NOT carried inline.
+ *
+ * `contentType` (IANA media type) is required so the FE renderer
+ * can branch on preview mode (image / pdf / video / download).
+ * `size` is informational. `originalFilename` flows into the
+ * download affordance when present.
+ */
+export const ExternalBlobPayloadSchema = z
+  .object({
+    contentType: z
+      .string()
+      .min(1, 'external_blob.contentType must be a non-empty IANA media type'),
+    /** Byte count, when known. Producers without it may omit. */
+    size: z.number().nonnegative().int().optional(),
+    /** Original filename, used as the download attachment name. */
+    originalFilename: z.string().optional(),
+    /**
+     * Producer-supplied alt text for image-kind blobs (a11y) and
+     * for any future LLM-briefing path that needs a non-visual
+     * description.
+     */
+    altText: z.string().optional(),
+  })
+  .passthrough();
+
+export type ExternalBlobPayload = z.infer<typeof ExternalBlobPayloadSchema>;

package/src/output/lib/payload-schemas/index.ts

@@ -0,0 +1,133 @@
+import type { ZodTypeAny } from 'zod';
+
+import { CodeDiffPayloadSchema } from './code-diff';
+import { DecisionRecordPayloadSchema } from './decision-record';
+import { DiagramPayloadSchema } from './diagram';
+import { ExternalBlobPayloadSchema } from './external-blob';
+import { JsonPayloadPayloadSchema } from './json-payload';
+import { ManifestPayloadSchema } from './manifest';
+import { MarkdownDocPayloadSchema } from './markdown-doc';
+import { ReviewFindingsPayloadSchema } from './review-findings';
+import { JsonSchemaPayloadSchema } from './schema';
+import { TestReportPayloadSchema } from './test-report';
+
+import { OutputKind } from '../output-kind';
+
+export * from './code-diff';
+export * from './decision-record';
+export * from './diagram';
+export * from './external-blob';
+export * from './json-payload';
+export * from './manifest';
+export * from './markdown-doc';
+export * from './review-findings';
+export * from './schema';
+export * from './test-report';
+
+/**
+ * Registry mapping closed `OutputKind` → Zod schema for the matching
+ * artifact payload. Every kind that has a renderer also has a schema;
+ * `OutputKind.UNKNOWN` is intentionally absent — biome-supplied
+ * payloads we can't classify are NOT validated (they pass through to
+ * the `unknown` renderer's "Show raw" surface).
+ *
+ * Keeping the registry keyed on `OutputKind` rather than free-form
+ * `type` strings means: the `(type → OutputKind)` mapping is the single
+ * place biomes add new aliases; once a producer's `type` resolves to
+ * a known kind, validation kicks in automatically.
+ */
+export const OUTPUT_KIND_PAYLOAD_SCHEMAS: Readonly<
+  Partial<Record<OutputKind, ZodTypeAny>>
+> = {
+  [OutputKind.MARKDOWN_DOC]: MarkdownDocPayloadSchema,
+  [OutputKind.CODE_DIFF]: CodeDiffPayloadSchema,
+  [OutputKind.DECISION_RECORD]: DecisionRecordPayloadSchema,
+  [OutputKind.REVIEW_FINDINGS]: ReviewFindingsPayloadSchema,
+  [OutputKind.SCHEMA]: JsonSchemaPayloadSchema,
+  [OutputKind.MANIFEST]: ManifestPayloadSchema,
+  [OutputKind.TEST_REPORT]: TestReportPayloadSchema,
+  [OutputKind.DIAGRAM]: DiagramPayloadSchema,
+  [OutputKind.JSON_PAYLOAD]: JsonPayloadPayloadSchema,
+  [OutputKind.EXTERNAL_BLOB]: ExternalBlobPayloadSchema,
+};
+
+/**
+ * Closed mapping from producer-supplied `type` string (the
+ * `EmitArtifactDto.type` value) → `OutputKind` enum. This is the
+ * platform's authoritative `type → kind` table; the FE and BE both
+ * read from here. Biomes that ship new aliases for an existing kind
+ * extend this map via a biome-host extension point (future) or
+ * register a new OutputKind (kernel-level).
+ *
+ * Order is irrelevant — duplicate keys would be a build-time error
+ * in TS, and the map is frozen at module load.
+ */
+export const ARTIFACT_TYPE_TO_OUTPUT_KIND: Readonly<Record<string, OutputKind>> = {
+  // markdown_doc
+  document_page: OutputKind.MARKDOWN_DOC,
+  'markdown.doc': OutputKind.MARKDOWN_DOC,
+  'doc.markdown': OutputKind.MARKDOWN_DOC,
+  'requirements.doc': OutputKind.MARKDOWN_DOC,
+  'design.doc': OutputKind.MARKDOWN_DOC,
+  'spec.doc': OutputKind.MARKDOWN_DOC,
+  // code_diff
+  'code.diff': OutputKind.CODE_DIFF,
+  'src.diff': OutputKind.CODE_DIFF,
+  'patch.diff': OutputKind.CODE_DIFF,
+  // decision_record
+  'decision.record': OutputKind.DECISION_RECORD,
+  adr: OutputKind.DECISION_RECORD,
+  // review_findings
+  'review.findings': OutputKind.REVIEW_FINDINGS,
+  'review.report': OutputKind.REVIEW_FINDINGS,
+  'review.verdict': OutputKind.REVIEW_FINDINGS,
+  // schema
+  schema: OutputKind.SCHEMA,
+  'json.schema': OutputKind.SCHEMA,
+  // manifest
+  manifest: OutputKind.MANIFEST,
+  'workflow.manifest': OutputKind.MANIFEST,
+  'biome.manifest': OutputKind.MANIFEST,
+  // test_report
+  'test.report': OutputKind.TEST_REPORT,
+  'qa.report': OutputKind.TEST_REPORT,
+  // diagram
+  diagram: OutputKind.DIAGRAM,
+  mermaid: OutputKind.DIAGRAM,
+  // json_payload
+  endpoint_fetch_response: OutputKind.JSON_PAYLOAD,
+  structured_json: OutputKind.JSON_PAYLOAD,
+  'json.payload': OutputKind.JSON_PAYLOAD,
+  // external_blob
+  'image.png': OutputKind.EXTERNAL_BLOB,
+  'image.jpeg': OutputKind.EXTERNAL_BLOB,
+  'binary.blob': OutputKind.EXTERNAL_BLOB,
+};
+
+/**
+ * Resolve a producer-supplied `type` to the matching `OutputKind`.
+ * Returns `undefined` when no mapping exists — callers treat that as
+ * "biome-defined custom type" and skip schema validation, falling
+ * through to the `unknown` renderer downstream.
+ */
+export function outputKindForType(type: string): OutputKind | undefined {
+  return ARTIFACT_TYPE_TO_OUTPUT_KIND[type];
+}
+
+/**
+ * Resolve the Zod payload schema for a given `type` string, going
+ * through the `type → OutputKind → schema` chain. Returns
+ * `undefined` when the `type` is unknown OR when the kind has no
+ * registered schema (today only `OutputKind.UNKNOWN`).
+ *
+ * Callers (artifact-store-api's `EmitArtifactValidator`,
+ * future FE preview helpers) treat `undefined` as "pass through —
+ * no schema-level validation for this type". Biome extensibility is
+ * preserved: a custom `my-org.special-output` type that's not in the
+ * table simply isn't validated, exactly as today.
+ */
+export function payloadSchemaForType(type: string): ZodTypeAny | undefined {
+  const kind = outputKindForType(type);
+  if (kind === undefined) {return undefined;}
+  return OUTPUT_KIND_PAYLOAD_SCHEMAS[kind];
+}

package/src/output/lib/payload-schemas/json-payload.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+/**
+ * Payload shape for `OutputKind.JSON_PAYLOAD` artifacts — the
+ * deliberate "structured JSON without a more specific kind" bucket.
+ * Used today by `xema/http`, `xema/endpoint-fetch`, and any producer
+ * emitting an opaque JSON envelope.
+ *
+ * Permissive by design — the WHOLE payload IS the deliverable, no
+ * particular field is required. Validation just ensures it's an
+ * object (not a bare primitive); arrays masquerading as the root are
+ * also accepted via the union below.
+ */
+export const JsonPayloadPayloadSchema = z.union([
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()),
+]);
+
+export type JsonPayloadPayload = z.infer<typeof JsonPayloadPayloadSchema>;

package/src/output/lib/payload-schemas/manifest.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+
+/**
+ * One reference inside a manifest's `refs[]` — a pointer to a KB page,
+ * a backlog item, an emitted file, or any other tracked artifact the
+ * manifest summarises.
+ */
+export const ManifestRefSchema = z
+  .object({
+    /** Closed-ish set of ref kinds; producers may extend via .passthrough(). */
+    type: z.string().min(1),
+    id: z.string().min(1),
+    title: z.string().optional(),
+    /** Producer-defined verb describing what happened to the ref (created / modified / referenced / …). */
+    action: z.string().optional(),
+    /** File-system path for `file`-kind refs. */
+    path: z.string().optional(),
+  })
+  .passthrough();
+
+export type ManifestRef = z.infer<typeof ManifestRefSchema>;
+
+/**
+ * An inline diagram embedded in the manifest. Today only `mermaid`
+ * is supported; the FE renders via the existing mermaid pipeline in
+ * `MarkdownView`.
+ */
+export const ManifestDiagramSchema = z
+  .object({
+    key: z.string().min(1),
+    title: z.string().min(1),
+    type: z.literal('mermaid'),
+    source: z.string().min(1),
+  })
+  .passthrough();
+
+export type ManifestDiagram = z.infer<typeof ManifestDiagramSchema>;
+
+/**
+ * Payload shape for `OutputKind.MANIFEST` artifacts — phase summaries,
+ * workflow manifests, biome manifests, and any structured "summary
+ * with cross-references" document.
+ *
+ * Two render shapes the FE recognises:
+ *
+ *   1. Rich manifest: `{ schemaVersion, summary, refs[]?, diagrams[]? }`.
+ *      The FE renderer (`ManifestRenderer`, plus the legacy
+ *      `ArtifactContentViewer`) renders the summary as markdown with
+ *      phase + ref + diagram sidebars.
+ *   2. Plain YAML/JSON: `{ body: string }`. The renderer falls back
+ *      to monospaced text preserving indentation.
+ *
+ * `passthrough()` so the `schemaVersion` field — which is a producer-
+ * declared manifest version, distinct from the artifact-store's
+ * `EmitArtifactDto.schemaVersion` — flows through.
+ */
+export const ManifestPayloadSchema = z
+  .object({
+    schemaVersion: z.string().optional(),
+    summary: z.string().optional(),
+    refs: z.array(ManifestRefSchema).optional(),
+    diagrams: z.array(ManifestDiagramSchema).optional(),
+    body: z.string().optional(),
+    stageKey: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((value, ctx) => {
+    const hasSummary =
+      typeof value.summary === 'string' && value.summary.trim().length > 0;
+    const hasBody = typeof value.body === 'string' && value.body.trim().length > 0;
+    const hasRefs = Array.isArray(value.refs) && value.refs.length > 0;
+    if (!hasSummary && !hasBody && !hasRefs) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'manifest payload must include at least one of `summary`, `body`, or non-empty `refs[]`.',
+      });
+    }
+  });
+
+export type ManifestPayload = z.infer<typeof ManifestPayloadSchema>;

package/src/output/lib/payload-schemas/markdown-doc.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+/**
+ * Payload shape for `OutputKind.MARKDOWN_DOC` artifacts.
+ *
+ * The canonical document-page shape across the platform. Used by the
+ * deliverable harvester (one artifact per page), `xema/emit-artifact`
+ * with markdown content, requirements/design/spec agents, and KB-bound
+ * publications.
+ *
+ * `body` is the rendered narrative — markdown source. The FE renderer
+ * (`MarkdownDocRenderer`) reads `body` directly via
+ * `useArtifactContent.textViewOfPayload` and renders it through
+ * `MarkdownView` (react-markdown + remark-gfm + mermaid).
+ *
+ * `slug` and `parentSlug` are KB-publish hints; the publish-kb activity
+ * reads them when present, otherwise it derives slugs from the
+ * artifact's title + phase. They are NOT required at emit-time — a
+ * deliverable that's reviewed but never published has no slug.
+ *
+ * `.passthrough()` is intentional: producers may attach arbitrary
+ * extras (e.g. front-matter metadata, agent commentary) without the
+ * schema rejecting the emit.
+ */
+export const MarkdownDocPayloadSchema = z
+  .object({
+    body: z.string().min(1, 'markdown_doc.body must be non-empty'),
+    slug: z.string().optional(),
+    parentSlug: z.string().optional(),
+  })
+  .passthrough();
+
+export type MarkdownDocPayload = z.infer<typeof MarkdownDocPayloadSchema>;

package/src/output/lib/payload-schemas/review-findings.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+
+/**
+ * Closed severity enum for `ReviewFinding.severity`. Drives FE
+ * grouping + colouring in `ReviewFindingsRenderer`. `info` is
+ * commentary that doesn't gate a verdict; `minor` / `major` /
+ * `blocking` escalate.
+ */
+export enum ReviewFindingSeverity {
+  INFO = 'info',
+  MINOR = 'minor',
+  MAJOR = 'major',
+  BLOCKING = 'blocking',
+}
+
+export const ReviewFindingSeveritySchema = z.nativeEnum(ReviewFindingSeverity);
+
+/**
+ * A single finding inside a review-findings payload.
+ *
+ * `anchor` is a free-form string today (pre-W3C-anchor migration on
+ * REVIEW inquiries). Producers conventionally use shapes like
+ * `file:path:line` or `heading:slug`. A future tightening could
+ * promote this to a `WebAnnotationTarget` once the producer fleet
+ * is migrated, matching the inquiry-side anchor work.
+ */
+export const ReviewFindingSchema = z
+  .object({
+    severity: ReviewFindingSeveritySchema,
+    message: z.string().min(1, 'review_findings.findings[].message must be non-empty'),
+    anchor: z.string().optional(),
+  })
+  .passthrough();
+
+export type ReviewFinding = z.infer<typeof ReviewFindingSchema>;
+
+/**
+ * Payload shape for `OutputKind.REVIEW_FINDINGS` artifacts — emitted
+ * by reviewer agents inside `xema/review` iterations.
+ *
+ * Two valid shapes (the FE renderer detects both):
+ *
+ *   1. Structured: `findings: ReviewFinding[]` — preferred. Renders
+ *      as a severity-grouped table with anchors.
+ *   2. Legacy: `body: string` — markdown narrative of the review.
+ *      The renderer falls back to markdown rendering when `findings`
+ *      is absent.
+ *
+ * `verdict` + `summary` are optional rollups — the reviewer's
+ * top-line answer and a short paragraph framing the detailed
+ * findings.
+ */
+export const ReviewFindingsPayloadSchema = z
+  .object({
+    findings: z.array(ReviewFindingSchema).optional(),
+    verdict: z.enum(['approve', 'reject', 'abstain']).optional(),
+    summary: z.string().optional(),
+    body: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((value, ctx) => {
+    const hasFindings = Array.isArray(value.findings) && value.findings.length > 0;
+    const hasBody = typeof value.body === 'string' && value.body.trim().length > 0;
+    const hasSummary =
+      typeof value.summary === 'string' && value.summary.trim().length > 0;
+    if (!hasFindings && !hasBody && !hasSummary) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'review_findings payload must include at least one of `findings[]`, `summary`, or `body`.',
+      });
+    }
+  });
+
+export type ReviewFindingsPayload = z.infer<typeof ReviewFindingsPayloadSchema>;

package/src/output/lib/payload-schemas/schema.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/**
+ * Payload shape for `OutputKind.SCHEMA` artifacts — JSON Schema
+ * documents declared by agents.
+ *
+ * The payload IS the JSON Schema document. We don't dictate which
+ * dialect (Draft 07, 2020-12, OpenAPI) — the validator we use
+ * downstream picks based on the document's own `$schema` field.
+ * Minimum check: it must be a non-empty object.
+ *
+ * The FE `SchemaRenderer` reads the payload directly via
+ * `useArtifactContent.payload` (NOT `content`) and renders the
+ * schema as a typed tree.
+ */
+export const JsonSchemaPayloadSchema = z
+  .record(z.string(), z.unknown())
+  .refine((v) => Object.keys(v).length > 0, {
+    message: 'schema payload must be a non-empty JSON Schema document.',
+  });
+
+export type JsonSchemaPayload = z.infer<typeof JsonSchemaPayloadSchema>;

package/src/output/lib/payload-schemas/test-report.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+/**
+ * Outcome of a single test in a test-report payload. Closed enum
+ * because the FE renders each state with distinctive iconography.
+ */
+export enum TestOutcome {
+  PASSED = 'passed',
+  FAILED = 'failed',
+  SKIPPED = 'skipped',
+  ERRORED = 'errored',
+}
+
+export const TestOutcomeSchema = z.nativeEnum(TestOutcome);
+
+export const TestCaseSchema = z
+  .object({
+    name: z.string().min(1),
+    outcome: TestOutcomeSchema,
+    /** Duration in milliseconds; producers without timing data omit. */
+    durationMs: z.number().nonnegative().optional(),
+    /** Failure / error message for FAILED + ERRORED outcomes. */
+    message: z.string().optional(),
+    /** Optional path to the file under test (e.g. `src/auth.test.ts`). */
+    file: z.string().optional(),
+  })
+  .passthrough();
+
+export type TestCase = z.infer<typeof TestCaseSchema>;
+
+/**
+ * Payload shape for `OutputKind.TEST_REPORT` artifacts.
+ *
+ * `tests[]` is the per-case detail; the rollup counters
+ * (`passed`, `failed`, `skipped`, `errored`) are derived from
+ * `tests[]` when present but may be supplied directly when the
+ * producer only has aggregate numbers.
+ *
+ * `body` is the legacy markdown fallback (same pattern as other
+ * markdown-bearing kinds).
+ */
+export const TestReportPayloadSchema = z
+  .object({
+    tests: z.array(TestCaseSchema).optional(),
+    passed: z.number().nonnegative().int().optional(),
+    failed: z.number().nonnegative().int().optional(),
+    skipped: z.number().nonnegative().int().optional(),
+    errored: z.number().nonnegative().int().optional(),
+    summary: z.string().optional(),
+    body: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((value, ctx) => {
+    const hasTests = Array.isArray(value.tests) && value.tests.length > 0;
+    const hasCounters =
+      typeof value.passed === 'number' ||
+      typeof value.failed === 'number' ||
+      typeof value.skipped === 'number';
+    const hasBody = typeof value.body === 'string' && value.body.trim().length > 0;
+    if (!hasTests && !hasCounters && !hasBody) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'test_report payload must include at least one of `tests[]`, the rollup counters, or `body`.',
+      });
+    }
+  });
+
+export type TestReportPayload = z.infer<typeof TestReportPayloadSchema>;

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